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

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

Resources

STEP 1: SET UP YOUR DEVELOPMENT ENVIRONMENT

Clone the XMTP Agent Examples Repository:

git clone https://github.com/ephemeraHQ/xmtp-agent-examples.git
cd xmtp-agent-examples

STEP 2: INSTALL DEPENDENCIES

Install all required packages:

npm

STEP 3: GENERATE KEYS FOR YOUR AGENT

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

npm gen:keys

This creates a .env file with:

WALLET_KEY=0x... # Your agent's private key
ENCRYPTION_KEY=... # Encryption key for local database
XMTP_ENV=dev # Environment (local, dev, production)

STEP 4: WRITE YOUR AGENT LOGIC

Create a basic agent that responds to messages:

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

Then run your agent:

npm dev

​
Getting the address of a user

Each user has a unique inboxId for retrieving their associated addresses (identifiers). One inboxId can have multiple identifiers like passkeys or EVM wallet addresses.

const inboxState = await client.preferences.inboxStateFromInboxIds([
  message.senderInboxId,
]);
const addressFromInboxId = inboxState[0].identifiers[0].identifier;

You can also explore example implementations in the /examples folder, including:

STEP 5: TEST YOUR AGENT

Development Testing

1. Start your agent:

npm dev

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 agent’s public address (from .env)
• Send a test message and verify the agent 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 agent’s address
• Verify functionality

STEP 6: GET A BASENAME FOR YOUR AGENT

Give your agent a human-readable name:

1. Import agent wallet to Coinbase Wallet extension:
• Install Coinbase Wallet browser extension
• Import using your agent’s private key

2. Purchase a basename:
• Visit https://base.org/names
• Connect your agent’s wallet
• Search and purchase your desired basename (e.g., myagent.base.eth)
• Set as primary name

3. Verify setup:
• 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 AGENT

Option 1: Railway (Recommended)

• Visit https://railway.app
• Connect your GitHub repository
• Add environment variables in Railway dashboard:
- XMTP_ENV=production
- WALLET_KEY=your_agent_private_key
- ENCRYPTION_KEY=your_agent_encryption_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 agent activity
2. Error Handling: Implement try-catch blocks for network issues
3. Rate Limiting: Respect XMTP rate limits in your agent logic
4. Security: Never expose private keys; use environment variables

Monitoring

Add to your agent for basic monitoring:

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}`);

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