XMTP

Build secure messaging into your app.

XMTP is an open protocol for end-to-end encrypted direct messages and group conversations. Use it to add chat to your mobile or web app, connect people with agents from other apps, or connect agents to agents.

This repository contains the shared Rust implementation, a ready to deploy messaging backend, and SDKs for browsers, Node.js, Android, iOS, and agents. The SDKs handle message encryption, identity, group state, and local storage so you can focus on your app.

Documentation · SDK source · Example apps · Contributing

Why use XMTP

• Security built on MLS. Messaging Layer Security provides end-to-end encryption, forward secrecy, and post-compromise security. XMTP provides protection against harvest now, decrypt later (HNDL) attacks, where messages are stored today for a future quantum computer to try to decrypt. SQLCipher is officially supported for encrypting native client databases at rest. See the security model.

• Private groups and profiles. Conversation members can manage membership and permissions without the server operator seeing either. Keep group metadata and member profiles encrypted, with configurable fields and permissions. See the group guide.

• Private keys are first class identities. Create an account with a cryptographic private key. The identity registry provides an immutable ledger of all keys added to or removed from accounts. Clients verify signed updates, and your app keeps the private key. See the identity model.

• Rich messages. Use standard content types for replies, reactions, and attachments. Add custom content types for your app. XMTP supports remote attachments for encrypted files. See the content type guide.

• One stack across platforms. Build with Browser or Node SDKs and Android and iOS native SDKs. XMTP includes a ready to deploy messaging backend.

XMTP powers messaging in products from Coinbase, World, and Zora. The XMTP ecosystem includes 4,500+ developers and 1,700+ production miniapps.

XMTP supports tens of thousands of active conversations for a single user. Explore the SDK performance suite and database conversation benchmark for the measured workloads. See benchmark commands to run them.

Start building an app

This README uses the version 8 release candidate, 8.0.0-rc2, for the SDKs and messaging backend. Choose your platform below and follow the installation guide to get started. App developers can use the SDK packages directly.

Use an existing backend or run the messaging backend. For a Node.js app, install the SDK in your app project:

npm install --save-exact @xmtp/node-sdk@8.0.0-rc2

Follow the chat app quickstart to create a signer and client with a 32-byte database encryption key. Create a conversation with a registered recipient's inbox ID. Send a message and receive it with the other client. Use the same backend for both clients.

For an agent, use the Agent quickstart. It covers key setup, a text handler, and testing the agent. For a browser or mobile app, use the chat app quickstart and select your platform.

See Create a client for backend and storage settings.

SDKs and packages

Each version 8 RC SDK has source, an installation guide, and an API reference.

SDK	Language	Source	Documentation	Package
Browser	TypeScript	Source	Install · API	npm — @xmtp/browser-sdk
Node	TypeScript	Source	Install · API	npm — @xmtp/node-sdk
Agent	TypeScript	Source	Guide · API	npm — @xmtp/agent-sdk
Android	Kotlin	Source	Install · API	Maven Central — org.xmtp:android
iOS	Swift	Source	Install · API	Swift Package Manager · CocoaPods — XMTP

Explore the examples

• Web chat: Run a browser client against your backend.

• Android Messenger: Test messaging and debug the Android SDK.

• iOS examples: Build a mobile client with the local Swift package.

• Agent demos: Explore message handlers and app-specific behavior.

For more Agent SDK examples, see XMTP Agent Examples.

Getting started working in this repo

The local setup uses Nix to provide pinned development tools. The setup script below targets macOS, with Apple Silicon as the primary platform. Install and start Docker for test services.

1. Clone the repository and create a branch for your change.

   git clone https://github.com/xmtp/libxmtp.git
   cd libxmtp
   git switch -c my-change

2. Set up Nix and the binary cache. Follow the script prompts.

   ./dev/nix-up

3. Start the backend and check the workspace.

   dev/nix-shell 'just backend up'
   dev/nix-shell 'just check'
   dev/nix-shell 'just test'

4. Run the shared checks. Then run the build and tests listed in the guide for the directory you changed.

   dev/nix-shell 'just lint'

just test covers the default Rust workspace members and excludes backend database tests. Run those tests with dev/nix-shell 'just backend test'. Run the dev tool tests with dev/nix-shell 'just test dev' after a change under dev/, nix/, or .github/. Use each SDK's guide for platform builds and tests. Run dev/nix-shell 'just' to list the available tasks.

To run the full backend and web example:

dev/nix-shell 'just backend up'
dev/nix-shell 'just backend status'
dev/nix-shell 'just install-js'
dev/nix-shell 'just web-chat dev'

Open the URL printed by the app. See the web chat guide for connection settings. Use the addresses printed by backend status; worktrees have separate port blocks. See the backend guide for configuration and service details.

Find your way around

Path	Contents
sdks	Public SDK source and platform packages
crates	Shared Rust code for messaging, identity, storage, and cryptography
apps/backend	Ready to deploy messaging backend
apps	Example apps, command-line tools, and developer tools
docs/specs	Behavior specifications
docs	Setup, operations, and SDK guides

Contribute

See DEVELOPMENT.md for dependency changes, test logging, coverage, and benchmark commands.

Start with CONTRIBUTING.md and AGENTS.md. Read the instructions in the directory you change. Check the specifications for the relevant behavior.

Open an issue for a bug or to discuss a substantial change. Branch from main and target your pull request at main. Explain what changed and how you checked it. Include a test that detects the bug when you fix behavior, and show that the test fails without the fix.

For help building an app, see the debugging guide or open an issue. For the protocol's security properties, see the security documentation.

License

MIT.