Build Your Own XMTP Agent: A Practical Guide with Examples

Want to automate messaging or build intelligent bots? This guide dives into building XMTP agents, offering practical examples to get you started quickly. Learn how to leverage the power of decentralized communication for enhanced privacy and control.

Why Use XMTP for Your Agents?

XMTP isn't just another messaging protocol. It offers key benefits for agent development:

• End-to-End Encryption: Secure your agent's communications, protecting sensitive data in transit and at rest.
• Open-Source & Trustless: Built on the MLS protocol, XMTP ensures transparency and cryptographic proof, eliminating reliance on centralized authorities.
• Privacy & Metadata Protection: XMTP enables anonymous or pseudonymous agent operation, minimizing tracked metadata.
• Decentralized Network: Enjoy uninterrupted agent operation with a peer-to-peer network, removing single points of failure.
• Multi-Agent Communication: Facilitate confidential communication between multiple agents and humans. This is powered by MLS group chats.

Setting Up Your XMTP Agent Development Environment

Before diving into code, ensure your environment is ready using these steps:

1. Install Prerequisites: Node.js v20+, Yarn v4+, and Docker (optional for local network setup).

2. Clone the Example Repository: Grab the code examples by running: git clone https://github.com/ephemeraHQ/xmtp-agent-examples.git Then, navigate to the directory using cd xmtp-agent-examples.

3. Install Dependencies: Run yarn to install all necessary packages.

4. Configure Environment Variables: Create a .env file with the following variables:

   • WALLET_KEY: The private key of your agent's wallet.
   • ENCRYPTION_KEY: An encryption key for the local database.
   • XMTP_ENV: Set to dev, local, or production depending on your target environment.

   Warning: You can generate random keys using yarn gen:keys, but be cautious as this will append to your existing .env file.

Running Your First XMTP Agent Example

With your environment set up, let's run a basic XMTP agent example:

1. Start the Agent: Execute yarn dev to launch the chosen example.
2. Local Network (Optional): Use Docker to host the XMTP service and database locally for isolated testing.
3. Networking: Remember to update your .env file to use correct networking, should you choose that option.

Basic Usage: Initializing the XMTP Listener and Sending Messages

Here's a code snippet demonstrating how to initialize the XMTP listener and send messages:

 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";
 async function main () {
    const client = await Client. create ( signer, encryptionKey, { env});
    await client. conversations. sync ();
    const stream = await client. conversations. streamAllMessages ();
    for await ( const message of stream) {
        // ignore messages from the agent
        if ( message?. senderInboxId === client. inboxId) {
            continue;
        }
        const conversation = await client. conversations. getConversationById ( message. conversationId);
        // send a message from the agent
        await conversation. send ( "gm");
    }
 }
 main (). catch ( console. error);

Explore XMTP Agent Examples: Real-World Applications

The repository offers several agent examples showcasing different functionalities:

• xmtp-gm: Responds to all messages with "gm". The basis for many bots.
• xmtp-gpt: Integrates with GPT APIs to intelligently answer messages. Perfect for customer service applications.
• xmtp-nft-gated-group: Manages group membership based on NFT ownership. Useful for building exclusive communities.
• xmtp-coinbase-agentkit: Uses a CDP for gasless USDC on Base, allowing for fast transactions.
• xmtp-transaction-content-type: Shows how to send transactions using XMTP content types.
• xmtp-stream-restart: Automatically restarts the message stream on errors.
• xmtp-smart-wallet: Uses a smart wallet for sending messages.
• xmtp-multiple-clients: Enables parallel agents to listen and send messages.
• xmtp-attachment-content-type: Sends images as attachments.
• xmtp-queue-dual-client: Uses two XMTP clients for message sending and receiving.

Standalone XMTP Agent Examples for Inspiration

These projects, outside the main repository, demonstrate real-world XMTP agent use cases:

• gm-bot: A simple bot that replies to every message with "gm."
• xmtp-mini-app: A basic mini-app that interacts with an XMTP group.
• xmtp-group-toss: An agent that uses a group to "toss" a coin.

Deploy Your XMTP Agent: A Quick Guide

Ready to launch your agent? A deployment guide for Railway is available.

Interact with the XMTP Network

Use xmtp.chat, the official web inbox for developers, to interact with your deployed XMTP agent and the XMTP network. Experiment and explore the possibilities!