Update xmtp agent guide (#33)

* Add yarn integrity file and update chat agent guide

* Add package-lock.json for consistent dependency management

* Remove unused package lock and yarn integrity files

* Add link to Cursor Rules for better agent guidance

* Switch package manager from yarn to npm for consistency

---------

Co-authored-by: fabrizio guespe <fabrizioguespe@Fabri-M3-2.local>

Author: humanagent

docs/wallet-app/guides/chat-agents.mdx

@@ -19,7 +19,7 @@ Real Examples:
 
 • AI Trading Companion: Message "buy $100 ETH when it hits $3,000" and your agent executes trades 24/7 while you sleep.
 
-• Travel Planning Bot: "Book flight LAX to NYC under $300" and get instant booking with crypto payments, all in your group chat
+• Travel Planning Agent: "Book flight LAX to NYC under $300" and get instant booking with crypto payments, all in your group chat
 
 • Coinbase Wallet & XMTP are combining AI, crypto, and mini apps with secure messaging – to unlock use-cases never before possible. Secure group chats & DMs are the new surface area for developers.
 
@@ -28,7 +28,7 @@ Real Examples:
 This guide will walk you through creating, testing, and deploying your first XMTP messaging agent. By the end, you'll have a fully functional agent that can send and receive messages on the XMTP messaging network.
 
 **Prerequisites**  
-• Node.js (v16 or higher)  
+• Node.js (v20 or higher)  
 • Git  
 • A code editor  
 • Basic knowledge of JavaScript/TypeScript
@@ -37,109 +37,116 @@ This guide will walk you through creating, testing, and deploying your first XMT
 
 - [Getting Started with XMTP (Video)](https://www.youtube.com/watch?v=djRLnWUvwIA)
 - [Building Agents on XMTP](https://github.com/ephemeraHQ/xmtp-agent-examples)
+- [Cursor Rules](https://github.com/ephemeraHQ/xmtp-agent-examples/blob/main/.cursor/rules/xmtp.md)
 - [XMTP Documentation](https://docs.xmtp.org/)
-- [Coinbase AgentKit](https://github.com/coinbase/agentkit)
-- [Coinbase Developer Platform](https://docs.cdp.coinbase.com/)
 - [Faucets](https://portal.cdp.coinbase.com/products/faucet)
-- [OnchainKit](https://onchainkit.xyz/)
 
 **STEP 1: SET UP YOUR DEVELOPMENT ENVIRONMENT**
 
-Clone the XMTP Bot Starter Template:
+Clone the XMTP Agent Examples Repository:
 
-```javascript
-git clone https://github.com/xmtp/bot-starter
-cd bot-starter
+```bash
+git clone https://github.com/ephemeraHQ/xmtp-agent-examples.git
+cd xmtp-agent-examples
 ```
 
-Alternative: create from scratch:
+**STEP 2: INSTALL DEPENDENCIES**
 
-```javascript
-mkdir my-xmtp-bot
-cd my-xmtp-bot
-npm init -y
+Install all required packages:
+
+```bash
+npm
 ```
 
-**STEP 2: INSTALL DEPENDENCIES**
+**STEP 3: GENERATE KEYS FOR YOUR AGENT**
 
-Install the required XMTP SDK and other dependencies:
+Run the key generation script to create your agent's wallet:
 
-```javascript
-npm install @xmtp/xmtp-js ethers dotenv
+```bash
+npm gen:keys
 ```
 
-For TypeScript support (recommended):
+This creates a .env file with:
 
-```javascript
-npm install -D typescript @types/node ts-node
+```bash
+WALLET_KEY=0x... # Your agent's private key
+ENCRYPTION_KEY=... # Encryption key for local database
+XMTP_ENV=dev # Environment (local, dev, production)
 ```
 
-**STEP 3: GENERATE KEYS FOR YOUR BOT**
+**STEP 4: WRITE YOUR AGENT LOGIC**
 
-Run the key generation script to create your bot's wallet:
+Create a basic agent that responds to messages:
 
 ```javascript
-npm run gen:keys
+// import the xmtp sdk
+import { Client, type XmtpEnv, type Signer } from "@xmtp/node-sdk";
+
+// encryption key, must be consistent across runs
+const encryptionKey: Uint8Array = ...;
+const signer: Signer = ...;
+const env: XmtpEnv = "dev";
+
+// create the client
+const client = await Client.create(signer, {encryptionKey, env });
+// sync the client to get the latest messages
+await client.conversations.sync();
+
+// listen to all messages
+const stream = await client.conversations.streamAllMessages();
+for await (const message of  stream) {
+  // ignore messages from the agent
+  if (message?.senderInboxId === client.inboxId ) continue;
+  // get the conversation by id
+  const conversation = await client.conversations.getConversationById(message.conversationId);
+  // send a message from the agent
+  await conversation.send("gm");
+}
 ```
 
-This creates a .env file with:
+Then run your agent:
 
-```javascript
-XMTP_ENV=dev
-PRIVATE_KEY=0x... (Your bot's private key)
-PUBLIC_ADDRESS=0x... (Your bot's public address)
+```bash
+npm dev
 ```
 
-IMPORTANT:  
-• Keep your PRIVATE_KEY secure and never commit it to version control  
-• Start with XMTP_ENV=dev for testing  
-• Switch to XMTP_ENV=production when ready to go live
-
-**STEP 4: WRITE YOUR BOT LOGIC**
-
-Create a basic bot that responds to messages:
-
-```javascript
-// bot.js
-import { Client } from '@xmtp/xmtp-js'
-import { Wallet } from 'ethers'
-
-const wallet = new Wallet(process.env.PRIVATE_KEY)
-const xmtp = await Client.create(wallet, { env: process.env.XMTP_ENV })
+### Getting the address of a user
 
-// Listen for new conversations
-for await (const conversation of await xmtp.conversations.stream()) {
-  console.log(`New conversation started with ${conversation.peerAddress}`)
+Each user has a unique inboxId for retrieving their associated addresses (identifiers). One inboxId can have multiple identifiers like passkeys or EVM wallet addresses.
 
-  // Listen for messages in this conversation
-  for await (const message of await conversation.streamMessages()) {
-    if (message.senderAddress === xmtp.address) continue // Skip own messages
+```tsx
+const inboxState = await client.preferences.inboxStateFromInboxIds([
+  message.senderInboxId,
+]);
+const addressFromInboxId = inboxState[0].identifiers[0].identifier;
+```
 
-    console.log(`Received: ${message.content}`)
+You can also explore example implementations in the `/examples` folder, including:
 
-    // Simple echo bot response
-    await conversation.send(`You said: ${message.content}`)
-  }
-}
+- [xmtp-gm](https://github.com/ephemeraHQ/xmtp-agent-examples/tree/main/examples/xmtp-gm): A simple agent that replies to all text messages with "gm".
+- [xmtp-gpt](https://github.com/ephemeraHQ/xmtp-agent-examples/tree/main/examples/xmtp-gpt): An example using GPT API's to answer messages.
+- [xmtp-nft-gated-group](https://github.com/ephemeraHQ/xmtp-agent-examples/tree/main/examples/xmtp-nft-gated-group): Add members to a group based on an NFT
+- [xmtp-coinbase-agentkit](https://github.com/ephemeraHQ/xmtp-agent-examples/tree/main/examples/xmtp-coinbase-agentkit): Agent that uses a CDP for gassless USDC on base
+- [xmtp-transactions](https://github.com/ephemeraHQ/xmtp-agent-examples/tree/main/examples/xmtp-transactions): Use XMTP content types to send transactions
+- [xmtp-smart-wallet](https://github.com/ephemeraHQ/xmtp-agent-examples/tree/main/examples/xmtp-smart-wallet): Agent that uses a smart wallet to send messages
 
-```
 
-**STEP 5: TEST YOUR BOT**
+**STEP 5: TEST YOUR AGENT**
 
 **Development Testing**
 
-1\. Start your bot:
+1\. Start your agent:
 
 ```javascript
-npm start
+npm dev
 ```
 
 2\. Test on [xmtp.chat:](https://xmtp.chat/conversations)  
 • Go to https://xmtp.chat  
 • Connect your personal wallet  
 • Switch to Dev environment in settings  
-• Start a new conversation with your bot's public address (from .env)  
-• Send a test message and verify the bot responds
+• Start a new conversation with your agent's public address (from .env)  
+• Send a test message and verify the agent responds
 
 **Production Testing**
 
@@ -152,36 +159,37 @@ XMTP_ENV=production
 2\. Test on Coinbase Wallet:  
 • Open Coinbase Wallet mobile app  
 • Go to messaging  
-• Start conversation with your bot's address  
+• Start conversation with your agent's address  
 • Verify functionality
 
-**STEP 6: GET A BASENAME FOR YOUR BOT**
+**STEP 6: GET A BASENAME FOR YOUR AGENT**
 
-Give your bot a human-readable name:
+Give your agent a human-readable name:
 
-**1\. Import bot wallet to Coinbase Wallet extension:**  
+**1\. Import agent wallet to Coinbase Wallet extension:**  
 • Install Coinbase Wallet browser extension  
-• Import using your bot's private key
+• Import using your agent's private key
 
 **2\. Purchase a basename:**  
 • Visit https://base.org/names  
-• Connect your bot's wallet  
-• Search and purchase your desired basename (e.g., mybot.base.eth)  
+• Connect your agent's wallet  
+• Search and purchase your desired basename (e.g., myagent.base.eth)  
 • Set as primary name
 
 **3\. Verify setup:**  
-• Your bot can now be reached via the basename instead of the long address  
-• Users can message mybot.base.eth instead of 0x123...
+• Your agent can now be reached via the basename instead of the long address  
+• Users can message myagent.base.eth instead of 0x123...
 
-**STEP 7: DEPLOY YOUR BOT**
+**STEP 7: DEPLOY YOUR AGENT**
 
 **Option 1: Railway (Recommended)**
 
 • Visit https://railway.app  
 • Connect your GitHub repository  
 • Add environment variables in Railway dashboard:  
  \- XMTP_ENV=production  
- \- PRIVATE_KEY=your_bot_private_key  
+ \- WALLET_KEY=your_agent_private_key  
+ \- ENCRYPTION_KEY=your_agent_encryption_key
 • Deploy and monitor logs
 
 **Option 2: Other Platforms**  
@@ -193,22 +201,34 @@ Heroku, Vercel, or any Node.js hosting platform:
 **STEP 8: MONITOR AND MAINTAIN**
 
 **Best Practices**  
-1\. Logging: Add comprehensive logging to track bot activity  
+1\. Logging: Add comprehensive logging to track agent activity  
 2\. Error Handling: Implement try-catch blocks for network issues  
-3\. Rate Limiting: Respect XMTP rate limits in your bot logic  
+3\. Rate Limiting: Respect XMTP rate limits in your agent logic  
 4\. Security: Never expose private keys; use environment variables
 
 **Monitoring**  
-Add to your bot for basic monitoring:
+
+Add to your agent for basic monitoring:
 
 ```javascript
-- console.log(\`Bot started. Address: ${xmtp.address}\`)
-- console.log(\`Environment: ${process.env.XMTP_ENV}\`)
-- console.log(\`Listening for messages...\`)
+const inboxState = await client.preferences.inboxState();
+const address = inboxState.identifiers[0].identifier;
+const inboxId = client.inboxId;
+const installationId = client.installationId;
+const conversations = await client.conversations.list();
+
+console.log(`
+✓ XMTP Client:
+• InboxId: ${inboxId}
+• Address: ${address}
+• Conversations: ${conversations.length}
+• Installations: ${inboxState.installations.length}
+• InstallationId: ${installationId}
+• Network: ${process.env.XMTP_ENV}`);
 ```
 
 ## Getting featured
 
-Fill out the form [here](https://app.deform.cc/form/52b71db4-bfa2-4ef5-a954-76c66250bdd2/?page_number=0) to submit your agent for review. If approved, your bot will be featured in Coinbase Wallet. You will hear back from us within 5 business days.
+Fill out the form [here](https://app.deform.cc/form/52b71db4-bfa2-4ef5-a954-76c66250bdd2/?page_number=0) to submit your agent for review. If approved, your agent will be featured in Coinbase Wallet. You will hear back from us within 5 business days.
 
 Need help or have feature requests? Visit [https://community.xmtp.org/](https://community.xmtp.org/)