Skip to main content
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.

​
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 install
STEP 3: GENERATE KEYS FOR YOUR AGENT Run the key generation script to create your agent’s wallet: 
npm run gen:keys
This creates a .env file with: 
XMTP_WALLET_KEY=0x... # Your agent's private key
XMTP_DB_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 { Agent, getTestUrl } from "@xmtp/agent-sdk";

// 2. Spin up the agent
const agent = await Agent.createFromEnv({
  env: "dev", // or 'production' for base app
});

// 3. Respond to text messages
agent.on("text", async (ctx) => {
  await ctx.sendText("Hello from my XMTP Agent! 👋");
});

// 4. Log when we're ready
agent.on("start", () => {
  console.log(`We are online: ${getTestUrl(agent)}`);
});

await agent.start();
Then run your agent: 
npm run 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. 
agent.on("text", async (ctx) => {
  const message = ctx.message.content;
  const senderAddress = ctx.getSenderAddress();
});
You can also explore example implementations in the /examples folder, including: STEP 5: TEST YOUR AGENT Development Testing
  1. Start your agent:
npm run dev
  1. 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; // for base app
  1. Test on Base App:
    • Open Base App 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 Base App extension:
• Install Base App 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
- XMTP_WALLET_KEY=your_agent_private_key
- XMTP_DB_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
⌘I