XMTP agent examples

This repository contains examples of agents that use the XMTP network.

Why XMTP?

• End-to-end & compliant: Data is encrypted in transit and at rest, meeting strict security and regulatory standards.
• Open-source & trustless: Built on top of the MLS protocol, it replaces trust in centralized certificate authorities with cryptographic proofs.
• Privacy & metadata protection: Offers anonymous usage through SDKs and pseudonymous usage with nodes tracking minimum metadata.
• Decentralized: Operates on a peer-to-peer network, eliminating single points of failure and ensuring continued operation even if some nodes go offline.
• Multi-agent: Allows confidential communication between multiple agents and humans through MLS group chats.

Getting started

Tip

See XMTP's cursor rules for vibe coding agents and best practices.

Requirements

• Node.js v20 or higher
• Yarn v4 or higher
• Docker (optional, for local network)

Environment variables

To run your XMTP agent, you must create a .env file with the following variables:

WALLET_KEY= # the private key of the wallet
ENCRYPTION_KEY= # encryption key for the local database
XMTP_ENV=dev # local, dev, production

You can generate random xmtp keys with the following command:

yarn gen:keys

Warning

Running the gen:keys command will append keys to your existing .env file.

Run the agent

# git clone repo
git clone https://github.com/ephemeraHQ/xmtp-agent-examples.git
# go to the folder
cd xmtp-agent-examples
# install packages
yarn
# generate random xmtp keys (optional)
yarn gen:keys
# run the example
yarn dev

Work in local network

dev and production networks are hosted by XMTP, while local network is hosted by yourself.

• 1. Install docker
• 2. Start the XMTP service and database

./dev/up

• 3. Change the .env file to use the local network

XMTP_ENV = local

Deployment

We have a guide for deploying the agent on Railway.

Basic usage

These are the steps to initialize the XMTP listener and send 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";

async function main() {
  const client = await Client.create(signer, encryptionKey, { env });
  await client.conversations.sync();
  const stream = client.conversations.streamAllMessages();
  for await (const message of await 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);

Examples

• xmtp-gm: A simple agent that replies to all text messages with "gm".
• xmtp-gpt: An example using GPT API's to answer messages.e
• 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-transaction-content-type: Use XMTP content types to send transactions
• xmtp-group-toss: Agent that uses a group to toss a coin
• xmtp-gaia: Agent that uses a CDP for gassless USDC on base
• xmtp-smart-wallet: Agent that uses a smart wallet to send messages

Web inbox

Interact with the XMTP network using xmtp.chat, the official web inbox for developers.