XMTP agent examples

This repository provides examples of agents that use the XMTP network. These agents are built with the XMTP Node SDK.

🎥 Watch Vibe coding secure agents with XMTP for a quickstart guide to building with these example agents.

Why build agents with 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.

Example agents

• 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 gasless USDC on base
• xmtp-transactions: Allow transactions between users and agents.
• xmtp-gaia: Agent that uses a CDP for gasless USDC on base
• xmtp-smart-wallet: Agent that uses a smart wallet to send messages
• xmtp-attachments: Agent that sends images
• xmtp-revoke-installations: Script that revokes excess installations
• xmtp-queue-dual-client: Agent that uses two clients to send and receive messages
• xmtp-multiple-workers: Agent that uses multiple workers to send and receive messages
• xmtp-group-welcome: Sends a welcome message when its added and to new members

Run example agents

Prerequisites

• Node.js v20 or higher
• Yarn v4 or higher
• Docker (to run a local XMTP network, optional)

Cursor rules

See these Cursor rules for vibe coding agents with XMTP using best practices.

Set environment variables

To run an example 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 by running:

yarn gen:keys

Warning

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

Run an example 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

Optional: Run a local XMTP network

dev and production networks are hosted by XMTP, while you can run your own local network.

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

4. Try out the example agents using xmtp.chat, the official web inbox for developers.

   

Build your own agent

To learn how to build your own production-grade agent with XMTP, see Tutorial: Build an agent.