Build Your Own: XMTP Agent Examples for Node.js

Unlock the power of decentralized messaging with XMTP agents. This guide provides practical examples and clear steps to get you started building your own XMTP agents using Node.js. Let's dive in!

Why Build with XMTP?

XMTP offers a unique approach to secure and private communication:

• End-to-End Encryption: Your data is safe, both during transmission and when stored.
• Open-Source and Trustless: Built on the MLS protocol, it replaces central authorities with cryptographic proofs.
• Enhanced Privacy: Enjoy anonymous or pseudonymous usage with minimal metadata tracking.
• Decentralized Network: No single point of failure means reliable and continuous operation.
• Multi-Agent Communication: Enable secure communication between multiple agents and humans.

Quickstart: Setting Up Your XMTP Agent Environment

Ready to start building? Here's what you need:

• Node.js: Version 20 or higher is required.
• Yarn: Version 4 or higher.
• Docker: Optional, for running a local network.

Environment Variables

Create a .env file in your project directory and add the following:

• WALLET_KEY: Your private key.
• ENCRYPTION_KEY: An encryption key for your local database.
• XMTP_ENV: Set to dev, local, or production.

Generate XMTP Keys:

Use the command yarn gen:keys to create random XMTP keys. Caution: This command appends to your existing .env file.

Running Your Agent

1. Clone the Repository:

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

   Copy

2. Navigate to the Directory:

   cd xmtp-agent-examples
   

   Copy

3. Install Packages:

   yarn
   

   Copy

4. Generate Keys (Optional):

   yarn gen:keys
   

   Copy

5. Run the Example:

   yarn dev
   

   Copy

Local Network Setup (Optional)

Run your agent on a local network for testing and development. This requires Docker. Follow these steps:

1. Install Docker.
2. Start the XMTP Service and Database (refer to the repository's documentation for specific commands).
3. Update .env: Change the XMTP_ENV variable to local.

Deploying Your Agent

For a hassle-free deployment, refer to the guide for deploying the agent on Railway.

Basic Usage: XMTP Agent Code Snippet

This example shows how to initialize an XMTP listener and send messages using the XMTP Node SDK, use it as a guide in your journey to create your own Node.js XMTP Agent.

// 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";
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 Exciting XMTP Agent Examples

Dive into these examples to inspire your XMTP-powered projects:

• xmtp-gm: Responds to all text messages with "gm."
• xmtp-gpt: Uses GPT APIs to intelligently answer messages, creating a conversational agent.
• xmtp-nft-gated-group: Add members to a group based on NFT ownership, enabling gated communities.
• xmtp-coinbase-agentkit: Uses a CDP for gasless USDC on Base, streamlining transactions.
• xmtp-transaction-content-type: Sends transactions using XMTP content types for clear communication.
• xmtp-gaia: Another example using a CDP for gasless USDC on Base, showcasing different approaches.
• xmtp-stream-restart: Restarts the message stream upon errors, ensuring reliability.
• xmtp-smart-wallet: Employs a smart wallet to send messages, enhancing security and control.
• xmtp-multiple-clients: Runs parallel agents, both listening and sending messages, for complex operations.
• xmtp-attachment-content-type: An agent for sending images, expanding communication possibilities.
• xmtp-queue-dual-client: Uses two clients to send and receive messages, optimizing performance.

Standalone XMTP Agent Examples

These projects exist outside the main repository and offer diverse implementation scenarios:

• gm-bot: A simple bot that replies to every message with "gm," a classic example.
• xmtp-mini-app: A mini-app interacting with a group, demonstrating XMTP integration in applications.
• xmtp-group-toss: Uses a group to toss a coin, showcasing random selection within XMTP.

Interact Using the Web Inbox

Test and interact with the XMTP network using the official web inbox, xmtp.chat.

By exploring these XMTP Agent examples and following the setup guide, you'll be well-equipped to build innovative and secure messaging solutions. Remember to check related long-tail terms such as "build XMTP bots" and "secure messaging with XMTP" for more ideas and inspiration.