Skip to content

FAQ about XMTP agents

Get answers to frequently asked questions about building agents with XMTP.

Platform and compatibility

What chains does XMTP support?

XMTP agents work with EOAs and SCWs on Ethereum and Ethereum L2s. Because messages are stored off-chain, agents are interoperable across EVM chains.

Supported chains: Ethereum, Base, Arbitrum, Optimism, Polygon, and other EVM-compatible networks.

What languages and libraries can I use?

Development setup

Should I use dbPath: null for development?

Not recommended. Using dbPath: null creates a new installation on every restart, quickly hitting the 10-installation limit (within ~30 minutes of development).

Recommended approach:
  • Use persistent database paths for development
  • Ideal setup: 2 installations (local + production), leaving 8 for testing
  • Only use dbPath: null for fire-and-forget or temporary agents

Database management

What files need to be backed up?

Back up these SQLite files for persistent storage:

  • {env}-{description}.db3 - Main database
  • {env}-{description}.db3-shm - Shared memory
  • {env}-{description}.db3-wal - Write-ahead log
  • {env}-{description}.db3.sqlcipher_salt - Encryption salt

Example for production: production-xmtp.db3, production-xmtp.db3-shm, etc.

How much storage should I provision?

Rough estimate: 1GB ≈ 15,000 conversations. Plan based on your expected volume.

What data is stored in the database?

  • All messages and conversations
  • Conversation state and encryption keys
  • Group membership and metadata

Can I clear database data without deleting files?

Not currently possible from SDKs. XMTP is developing database management tools (XIP-70).

What happens when I delete/wipe the database?

File deletion:
  • Creates fresh database with new installation
  • Messages continue streaming normally
  • Works unless you've hit the 10-installation limit
Database wipe (once XIP-70 tools are available):
  • Agent loses access to existing groups
  • Regains group access when receiving new messages
  • All local message history is lost

Installation limits and troubleshooting

What is the installation limit?

Each inbox has a maximum of 10 installations. Creating a new installation beyond this limit will fail.

How do I recover from hitting the limit?

Currently:

  • Use a different client/signer to create new agents
  • No built-in method to revoke old installations
  • Automatic revocation tools are planned for future releases

Messages and content

What content types can agents send?

Text, reactions, replies, attachments, and transaction requests. See Content types for details.

Are there message size limits?

Yes, messages are limited to just under 1MB. For larger content, use remote attachments.

Are there any messaging costs?

No messaging fees currently. Messages are stored off-chain on the XMTP network.

Domains

How do I register a domain for my agent?

1. Register a new ENS domain

  1. Go to https://app.ens.domains/
  2. Search for your desired name (e.g., "myagent.eth")
  3. If available, click "Request to register" → Complete registration (requires ETH for registration + gas fees)
  4. Wait ~1 minute for registration to complete

2. Create agent wallet in MetaMask

  1. Open MetaMask → Account selector → "Add account or hardware wallet" → "Add a new account"
  2. Name it (e.g., "Agent Wallet") → Create
  3. Click three dots → "Account details" → "Show private key" → enter password → copy and save private key
  4. Copy the wallet address

3. Link ENS domain to agent wallet

  1. Go to https://app.ens.domains/yourdomain.eth
  2. Click "Edit profile" → Under "ETH Address" → paste agent wallet address → Save
  3. Sign the transaction

4. Set as primary name

  1. Switch MetaMask to the agent wallet account
  2. Go to https://app.ens.domains/
  3. Click "My account" → Find your domain → Click "Set as primary name"
  4. Sign the transaction

5. Transfer ownership (optional)

  1. Switch back to owner account in MetaMask
  2. On the ENS page, click "Transfer" → paste agent address → sign transaction
  3. Agent now owns the domain (can update records using private key)

Result: Your agent can now use the private key to control the wallet/domain, reverse resolution works (address → name), and people can send funds to yourdomain.eth

Framework integration

Does XMTP work with ElizaOS?

Yes! XMTP has official ElizaOS support through the @elizaos/plugin-xmtp plugin, enabling secure, decentralized, and end-to-end encrypted messaging for ElizaOS agents.

Installation

pnpm add @elizaos/plugin-xmtp
# or
elizaos add plugins @elizaos/plugin-xmtp

Environment variables

  • WALLET_KEY - Private key of the wallet
  • XMTP_SIGNER_TYPE - Signer type (SCW or EOA)
  • XMTP_SCW_CHAIN_ID - (Optional) Chain ID for smart contract wallet
  • XMTP_ENV - (Optional) XMTP environment (dev, local, production)

Benefits of XMTP + ElizaOS

  • End-to-end encrypted agent communication
  • Decentralized messaging without single points of failure
  • Multi-agent, multi-human confidential group chats
  • Privacy and metadata protection

Can I contribute to XMTP integrations?

Absolutely! We welcome contributions to improve XMTP agent integrations:

  • ElizaOS plugin: Contribute to the official plugin-xmtp repository
  • Agent SDK: Help improve the core XMTP Agent SDK
  • Documentation: Submit improvements to agent documentation and examples
  • Community: Share your agent projects and help others in XMTP Discord

Identity and profile management

How do I create separate XMTP inboxes for multiple Lens profiles owned by the same address?

Each Lens profile needs its own XMTP identity to have a separate inbox. XMTP doesn't support linking multiple identities to a single owner address.

The challenge

  • One wallet address can own multiple Lens profiles
  • XMTP identity creation uses the profile owner's address
  • You want each Lens profile to have its own unique inbox

The solution

  • Each Lens profile must have its own XMTP identity
  • This means each profile needs its own private key/wallet
  • You cannot have multiple XMTP identities linked to one owner address

Example use case

If you have 3 Lens profiles on one address and want separate inboxes for each, you'll need 3 different XMTP identities (each with their own private key), not 3 profiles sharing one XMTP identity.

Security

Has XMTP been audited?

Yes. NCC Group completed a security assessment of LibXMTP and its MLS implementation in December 2024. See: Public Report: XMTP MLS Implementation Review