|
| 1 | +# Chat Agents in Coinbase Wallet |
| 2 | + |
| 3 | +This guide will cover how you can get started building messaging agents for Coinbase Wallet, using XMTP, a decentralized messaging protocol. Discover a fast, easy way to build and get distribution in Coinbase Wallet. |
| 4 | + |
| 5 | +- Why agents? |
| 6 | +- Getting started with XMTP |
| 7 | +- Getting featured in Coinbase Wallet |
| 8 | + |
| 9 | +## Why agents? |
| 10 | + |
| 11 | +Messaging is the largest use-case in the world, but it’s more than just conversations—it’s a secure, programmable channel for financial and social innovation. When combined with the onchain capabilities of Coinbase Wallet, builders have a new surface area to build 10X better messaging experiences not currently possible on legacy platforms like WhatsApp or Messenger. |
| 12 | + |
| 13 | +Real Examples: |
| 14 | + |
| 15 | +• Smart Payment Assistant: Text "split dinner $200 4 ways" and everyone gets paid instantly with sub-cent fees, no app switching or Venmo delays. |
| 16 | + |
| 17 | +• AI Trading Companion: Message "buy $100 ETH when it hits $3,000" and your agent executes trades 24/7 while you sleep. |
| 18 | + |
| 19 | +• Travel Planning Bot: "Book flight LAX to NYC under $300" and get instant booking with crypto payments, all in your group chat |
| 20 | + |
| 21 | +• 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. |
| 22 | + |
| 23 | +## Getting started |
| 24 | + |
| 25 | +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. |
| 26 | + |
| 27 | +**Prerequisites** |
| 28 | +• Node.js (v16 or higher) |
| 29 | +• Git |
| 30 | +• A code editor |
| 31 | +• Basic knowledge of JavaScript/TypeScript |
| 32 | + |
| 33 | +**Resources** |
| 34 | + |
| 35 | +- [Getting Started with XMTP (Video)](https://www.youtube.com/watch?v=djRLnWUvwIA) |
| 36 | +- [Building Agents on XMTP](https://github.com/ephemeraHQ/xmtp-agent-examples) |
| 37 | +- [XMTP Documentation](https://docs.xmtp.org/) |
| 38 | +- [Coinbase AgentKit](https://github.com/coinbase/agentkit) |
| 39 | +- [Coinbase Developer Platform](https://docs.cdp.coinbase.com/) |
| 40 | +- [Faucets](https://portal.cdp.coinbase.com/products/faucet) |
| 41 | +- [OnchainKit](https://onchainkit.xyz/) |
| 42 | + |
| 43 | +**STEP 1: SET UP YOUR DEVELOPMENT ENVIRONMENT** |
| 44 | + |
| 45 | +Clone the XMTP Bot Starter Template: |
| 46 | + |
| 47 | +```javascript |
| 48 | +git clone https://github.com/xmtp/bot-starter |
| 49 | +cd bot-starter |
| 50 | +``` |
| 51 | + |
| 52 | +Alternative: create from scratch: |
| 53 | + |
| 54 | +```javascript |
| 55 | +mkdir my-xmtp-bot |
| 56 | +cd my-xmtp-bot |
| 57 | +npm init -y |
| 58 | +``` |
| 59 | + |
| 60 | +**STEP 2: INSTALL DEPENDENCIES** |
| 61 | + |
| 62 | +Install the required XMTP SDK and other dependencies: |
| 63 | + |
| 64 | +```javascript |
| 65 | +npm install @xmtp/xmtp-js ethers dotenv |
| 66 | +``` |
| 67 | + |
| 68 | +For TypeScript support (recommended): |
| 69 | + |
| 70 | +```javascript |
| 71 | +npm install -D typescript @types/node ts-node |
| 72 | +``` |
| 73 | + |
| 74 | +**STEP 3: GENERATE KEYS FOR YOUR BOT** |
| 75 | + |
| 76 | +Run the key generation script to create your bot's wallet: |
| 77 | + |
| 78 | +```javascript |
| 79 | +npm run gen:keys |
| 80 | +``` |
| 81 | + |
| 82 | +This creates a .env file with: |
| 83 | + |
| 84 | +```javascript |
| 85 | +XMTP_ENV=dev |
| 86 | +PRIVATE_KEY=0x... (Your bot's private key) |
| 87 | +PUBLIC_ADDRESS=0x... (Your bot's public address) |
| 88 | +``` |
| 89 | + |
| 90 | +IMPORTANT: |
| 91 | +• Keep your PRIVATE_KEY secure and never commit it to version control |
| 92 | +• Start with XMTP_ENV=dev for testing |
| 93 | +• Switch to XMTP_ENV=production when ready to go live |
| 94 | + |
| 95 | +**STEP 4: WRITE YOUR BOT LOGIC** |
| 96 | + |
| 97 | +Create a basic bot that responds to messages: |
| 98 | + |
| 99 | +```javascript |
| 100 | +// bot.js |
| 101 | +import { Client } from '@xmtp/xmtp-js' |
| 102 | +import { Wallet } from 'ethers' |
| 103 | + |
| 104 | +const wallet = new Wallet(process.env.PRIVATE_KEY) |
| 105 | +const xmtp = await Client.create(wallet, { env: process.env.XMTP_ENV }) |
| 106 | + |
| 107 | +// Listen for new conversations |
| 108 | +for await (const conversation of await xmtp.conversations.stream()) { |
| 109 | + console.log(`New conversation started with ${conversation.peerAddress}`) |
| 110 | + |
| 111 | + // Listen for messages in this conversation |
| 112 | + for await (const message of await conversation.streamMessages()) { |
| 113 | + if (message.senderAddress === xmtp.address) continue // Skip own messages |
| 114 | + |
| 115 | + console.log(`Received: ${message.content}`) |
| 116 | + |
| 117 | + // Simple echo bot response |
| 118 | + await conversation.send(`You said: ${message.content}`) |
| 119 | + } |
| 120 | +} |
| 121 | + |
| 122 | +``` |
| 123 | + |
| 124 | +**STEP 5: TEST YOUR BOT** |
| 125 | + |
| 126 | +**Development Testing** |
| 127 | + |
| 128 | +1\. Start your bot: |
| 129 | + |
| 130 | +```javascript |
| 131 | +npm start |
| 132 | +``` |
| 133 | + |
| 134 | +2\. Test on [xmtp.chat:](https://xmtp.chat/conversations) |
| 135 | +• Go to https://xmtp.chat |
| 136 | +• Connect your personal wallet |
| 137 | +• Switch to Dev environment in settings |
| 138 | +• Start a new conversation with your bot's public address (from .env) |
| 139 | +• Send a test message and verify the bot responds |
| 140 | + |
| 141 | +**Production Testing** |
| 142 | + |
| 143 | +1\. Update environment: |
| 144 | + |
| 145 | +```javascript |
| 146 | +XMTP_ENV=production |
| 147 | +``` |
| 148 | + |
| 149 | +2\. Test on Coinbase Wallet: |
| 150 | +• Open Coinbase Wallet mobile app |
| 151 | +• Go to messaging |
| 152 | +• Start conversation with your bot's address |
| 153 | +• Verify functionality |
| 154 | + |
| 155 | +**STEP 6: GET A BASENAME FOR YOUR BOT** |
| 156 | + |
| 157 | +Give your bot a human-readable name: |
| 158 | + |
| 159 | +**1\. Import bot wallet to Coinbase Wallet extension:** |
| 160 | +• Install Coinbase Wallet browser extension |
| 161 | +• Import using your bot's private key |
| 162 | + |
| 163 | +**2\. Purchase a basename:** |
| 164 | +• Visit https://base.org/names |
| 165 | +• Connect your bot's wallet |
| 166 | +• Search and purchase your desired basename (e.g., mybot.base.eth) |
| 167 | +• Set as primary name |
| 168 | + |
| 169 | +**3\. Verify setup:** |
| 170 | +• Your bot can now be reached via the basename instead of the long address |
| 171 | +• Users can message mybot.base.eth instead of 0x123... |
| 172 | + |
| 173 | +**STEP 7: DEPLOY YOUR BOT** |
| 174 | + |
| 175 | +**Option 1: Railway (Recommended)** |
| 176 | + |
| 177 | +• Visit https://railway.app |
| 178 | +• Connect your GitHub repository |
| 179 | +• Add environment variables in Railway dashboard: |
| 180 | + \- XMTP_ENV=production |
| 181 | + \- PRIVATE_KEY=your_bot_private_key |
| 182 | +• Deploy and monitor logs |
| 183 | + |
| 184 | +**Option 2: Other Platforms** |
| 185 | +Heroku, Vercel, or any Node.js hosting platform: |
| 186 | +• Ensure your package.json has the correct start script |
| 187 | +• Set environment variables in your hosting platform |
| 188 | +• Deploy your repository |
| 189 | + |
| 190 | +**STEP 8: MONITOR AND MAINTAIN** |
| 191 | + |
| 192 | +**Best Practices** |
| 193 | +1\. Logging: Add comprehensive logging to track bot activity |
| 194 | +2\. Error Handling: Implement try-catch blocks for network issues |
| 195 | +3\. Rate Limiting: Respect XMTP rate limits in your bot logic |
| 196 | +4\. Security: Never expose private keys; use environment variables |
| 197 | + |
| 198 | +**Monitoring** |
| 199 | +Add to your bot for basic monitoring: |
| 200 | + |
| 201 | +```javascript |
| 202 | +- console.log(\`Bot started. Address: ${xmtp.address}\`) |
| 203 | +- console.log(\`Environment: ${process.env.XMTP_ENV}\`) |
| 204 | +- console.log(\`Listening for messages...\`) |
| 205 | +``` |
| 206 | + |
| 207 | +## Getting featured |
| 208 | + |
| 209 | +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. |
| 210 | + |
| 211 | +Need help or have feature requests? Visit [https://community.xmtp.org/](https://community.xmtp.org/) |
0 commit comments