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.

  • Why agents?
  • Getting started with XMTP
  • Getting featured in Coinbase Wallet

​
Why agents?

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.

Real Examples:

• Smart Payment Assistant: Text “split dinner $200 4 ways” and everyone gets paid instantly with sub-cent fees, no app switching or Venmo delays.

• AI Trading Companion: Message “buy 100ETHwhenithits100 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

• 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.

​
Getting started

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)
• Git
• A code editor
• Basic knowledge of JavaScript/TypeScript

Resources

STEP 1: SET UP YOUR DEVELOPMENT ENVIRONMENT

Clone the XMTP Bot Starter Template:

git clone https://github.com/xmtp/bot-starter
cd bot-starter

Alternative: create from scratch:

mkdir my-xmtp-bot
cd my-xmtp-bot
npm init -y

STEP 2: INSTALL DEPENDENCIES

Install the required XMTP SDK and other dependencies:

npm install @xmtp/xmtp-js ethers dotenv

For TypeScript support (recommended):

npm install -D typescript @types/node ts-node

STEP 3: GENERATE KEYS FOR YOUR BOT

Run the key generation script to create your bot’s wallet:

npm run gen:keys

This creates a .env file with:

XMTP_ENV=dev
PRIVATE_KEY=0x... (Your bot's private key)
PUBLIC_ADDRESS=0x... (Your bot's public address)

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:

// 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 })

// Listen for new conversations
for await (const conversation of await xmtp.conversations.stream()) {
  console.log(`New conversation started with ${conversation.peerAddress}`)

  // Listen for messages in this conversation
  for await (const message of await conversation.streamMessages()) {
    if (message.senderAddress === xmtp.address) continue // Skip own messages

    console.log(`Received: ${message.content}`)

    // Simple echo bot response
    await conversation.send(`You said: ${message.content}`)
  }
}

STEP 5: TEST YOUR BOT

Development Testing

1. Start your bot:

npm start

2. Test on xmtp.chat:
• 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

Production Testing

1. Update environment:

XMTP_ENV=production

2. Test on Coinbase Wallet:
• Open Coinbase Wallet mobile app
• Go to messaging
• Start conversation with your bot’s address
• Verify functionality

STEP 6: GET A BASENAME FOR YOUR BOT

Give your bot a human-readable name:

1. Import bot wallet to Coinbase Wallet extension:
• Install Coinbase Wallet browser extension
• Import using your bot’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)
• 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…

STEP 7: DEPLOY YOUR BOT

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
• Deploy and monitor logs

Option 2: Other Platforms
Heroku, Vercel, or any Node.js hosting platform:
• Ensure your package.json has the correct start script
• Set environment variables in your hosting platform
• Deploy your repository

STEP 8: MONITOR AND MAINTAIN

Best Practices
1. Logging: Add comprehensive logging to track bot activity
2. Error Handling: Implement try-catch blocks for network issues
3. Rate Limiting: Respect XMTP rate limits in your bot logic
4. Security: Never expose private keys; use environment variables

Monitoring
Add to your bot for basic monitoring:

- console.log(\`Bot started. Address: ${xmtp.address}\`)
- console.log(\`Environment: ${process.env.XMTP_ENV}\`)
- console.log(\`Listening for messages...\`)

Fill out the form here 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.

Need help or have feature requests? Visit https://community.xmtp.org/