Chat Agents in Coinbase Wallet
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 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:
STEP 2: INSTALL DEPENDENCIES
Install all required packages:
STEP 3: GENERATE KEYS FOR YOUR AGENT
Run the key generation script to create your agent’s wallet:
This creates a .env file with:
STEP 4: WRITE YOUR AGENT LOGIC
Create a basic agent that responds to messages:
Then run your agent:
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.
You can also explore example implementations in the /examples
folder, including:
- xmtp-gm: A simple agent that replies to all text messages with “gm”.
- xmtp-gpt: An example using GPT API’s to answer messages.
- xmtp-nft-gated-group: Add members to a group based on an NFT
- xmtp-coinbase-agentkit: Agent that uses a CDP for gassless USDC on base
- xmtp-transactions: Use XMTP content types to send transactions
- xmtp-smart-wallet: Agent that uses a smart wallet to send messages
STEP 5: TEST YOUR AGENT
Development Testing
- Start your agent:
- 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
- Update environment:
- 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
- Logging: Add comprehensive logging to track agent activity
- Error Handling: Implement try-catch blocks for network issues
- Rate Limiting: Respect XMTP rate limits in your agent logic
- Security: Never expose private keys; use environment variables
Monitoring
Add to your agent for basic monitoring:
Content types
Coinbase Wallet supports various XMTP content types for rich messaging capabilities. This document outlines all supported content types, including custom types for Quick Actions and Intent.
XMTP uses content types to define the structure and meaning of message types.
We’ll outline the standard and custom XMTP content types you can utilize in your agent.
XMTP Content Types
Text Messages
- Content Type:
xmtp.org/text:1.0
- Purpose: Basic text messaging
- Usage: Default for plain text
Attachments
- Content Type:
xmtp.org/attachment:1.0
- Purpose: File attachments (inline)
- Usage: Send files directly in messages
Remote Static Attachments
- Content Type:
xmtp.org/remoteStaticAttachment:1.0
- Purpose: Remote file attachments via URLs
- Usage: Reduce message size
Reactions
- Content Type:
xmtp.org/reaction:1.0
- Purpose: Emoji reactions
- Usage: React to messages with emojis
- Note: Does not trigger read receipts
Replies
- Content Type:
xmtp.org/reply:1.0
- Purpose: Threaded conversations
- Usage: Reply to specific messages
Group Management
- Content Types:
xmtp.org/group_membership_change:1.0
xmtp.org/group_updated:1.0
- Purpose: Membership & group metadata updates
- Usage: Automatic system messages
Read Receipts
- Content Type:
xmtp.org/readReceipt:1.0
- Purpose: Read confirmations
- Usage: Sent automatically
Transactions (Wallet Send Calls)
- Content Type:
xmtp.org/walletSendCalls:1.0
- Purpose: Request wallet actions from users
Transaction Receipts
- Content Type:
xmtp.org/transactionReference:1.0
- Purpose: Share blockchain transaction info
Coinbase Wallet Content Types
There are content types developed by the Coinbase Wallet team for agents in Coinbase Wallet. Other XMTP clients may not support these content types.
Quick Actions (coinbase.com/actions:1.0)
Purpose: Present interactive buttons in a message
Structure:
Validation Rules:
id
,description
are requiredactions
must be 1–10 items with unique IDs- Style must be one of:
primary
,secondary
,danger
Fallback:
Example: Payment Options
Intent (coinbase.com/intent:1.0)
Purpose: User expresses choice from Quick Actions
Structure:
Validation Rules:
id
,actionId
required- Must match corresponding Actions
metadata
is optional,<10KB
Fallback:
Example: Intent Message
Best practices
- Always validate content structures
- Provide fallbacks for unsupported clients
- Test across client versions
- Limit message and metadata size
- Follow XIP-67
Your agent should respond to both direct messages and group chat messages (if applicable).
For direct messages, it should automatically respond.
We recommend reacting to messages with an emoji (like 👀 or ⌛) to indicate the message was received, while the response is processing.
For group chat messages, agents should only respond if they are mentioned with the ”@” symbol and the agent’s name. (example “@bankr”), OR if the user replies directly to a message from the agent (using the reply content type).
Getting featured
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/