Skip to content

Update xmtp agent guide #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
soheimam merged 5 commits into from
Jun 23, 2025
Merged

Update xmtp agent guide #33

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a13bf22
Add yarn integrity file and update chat agent guide
Jun 19, 2025
5b8c822
Add package-lock.json for consistent dependency management
Jun 19, 2025
669a28c
Remove unused package lock and yarn integrity files
Jun 19, 2025
3cbf93a
Add link to Cursor Rules for better agent guidance
Jun 19, 2025
60c3b0a
Switch package manager from yarn to npm for consistency
Jun 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 100 additions & 80 deletions docs/wallet-app/guides/chat-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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**

Expand All @@ -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**
Expand All @@ -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/)