# Build with XMTP

> XMTP is a secure and decentralized protocol for building communication platforms for the next phase of the internet.

## Docs

- [Privacy policy](/privacy): `docs.xmtp.org` does not use cookies and does not collect any personal data or personally-identifiable information (PII).
- [Terms of service](/terms): Our content licensing policies are based on those of the [Google Developer](https://developers.google.com/site-policies) website.
- [Page not found](/*): This page may have been moved, renamed, or removed. Our docs are actively maintained, so URLs occasionally change.
- [Cursors with XMTP](/protocol/cursors): This document explains the concept of **cursors** as they relate to message synchronization on the XMTP network. Cursors are a fundamental part of how XMTP clients efficiently fetch new messages and maintain state, particularly with the `sync()` family of functions.
- [Envelope types with XMTP](/protocol/envelope-types): This document covers **envelope types** that clients can publish to XMTP APIs. These are the top-level message structures that can be sent and received through the XMTP network. This information is primarily useful for:
- [Epochs with XMTP](/protocol/epochs): With XMTP, each [commit](/protocol/envelope-types#commit-messages) starts a new epoch, which represents the current cryptographic state of a group chat.
- [Identity model with XMTP](/protocol/identity): XMTP's identity model includes an inbox ID and its associated identities and installations.
- [Intents with XMTP](/protocol/intents): Intents provide an internal state machine, or "bookkeeping" mechanism, for reliably applying changes to XMTP group chat states, even when the process encounters retries, crashes, race conditions, or ordering issues.
- [XMTP protocol overview](/protocol/overview): XMTP is a decentralized messaging protocol that enables secure, end-to-end encrypted communication between any identities that can produce a verifiable cryptographic signature.
- [Messaging security properties with XMTP](/protocol/security): XMTP delivers end-to-end encrypted 1:1 and group chat using the following resources:
- [Wallet signatures with XMTP](/protocol/signatures): Learn about the types of wallet address signatures you might be prompted to provide when using apps built with XMTP. These signatures are always made with a specific wallet address controlled by your wallet.
- [Topics with XMTP](/protocol/topics): This document describes the concept of **topics** on the XMTP network. Topics are used to address and route [envelopes](/protocol/envelope-types), forming the backbone of the XMTP pub/sub messaging system.
- [XMTP Improvement Proposals (XIPs)](/protocol/xips): An XIP is a design document that proposes a new feature or improvement for XMTP or its processes or environment.
- [FAQ about the XMTP network](/network/faq): A testnet of the decentralized XMTP network was launched in early December 2024.
- [XMTP Testnet nodes](/network/network-nodes): For real-time statuses of nodes in the XMTP Testnet, see [XMTP Node Status](https://status.testnet.xmtp-partners.xyz/).
- [Run an XMTP network node](/network/run-a-node): To start, the XMTP Network operates with a limited set of curated node operators to ensure maximum performance and censorship resistance.
The [XMTP Testnet](/network/network-nodes) is powered by registered node operators running [xmtpd](https://github.com/xmtp/xmtpd), XMTP daemon software. xmtpd will also power Mainnet.
- [Get started with funding an app or agent to send messages with XMTP](/fund-agents-apps/get-started): Mainnet of the decentralized XMTP Network is expected to launch in early 2026.
- [Glossary for funding an app or agent to send messages with XMTP](/fund-agents-apps/glossary): Total amount of USDC allocated to pay for messaging and gas fees for a registered payer wallet. This includes:
- [Update your app or agent to use an XMTP SDK with Gateway Service support](/fund-agents-apps/update-sdk): Once [Testnet- and Mainnet-compatible XMTP SDKs are delivered](/fund-agents-apps/get-started#key-milestones-and-actions), you can update your app or agent to a compatible SDK version that includes helpers that enable it to communicate with your XMTP Gateway Service.
- [Understand and calculate XMTP fees](/fund-agents-apps/calculate-fees): Use this guide to understand XMTP fees and how to calculate estimated XMTP fees for an app or agent.
- [Fund an app or agent to send messages with XMTP](/fund-agents-apps/fund-your-app): Use this guide to learn how to use the XMTP Funding Portal to fund an app or agent to send messages with XMTP. You can also use the portal to view usage and current and projected fees.
- [Run your XMTP Gateway Service](/fund-agents-apps/run-gateway): An XMTP Gateway Service is a proxy that pays for and forwards messages to the XMTP Broadcast Network on behalf of your users. Think of it as your app or agent's payment gateway for messaging.
- [Debug your chat app](/chat-apps/debug-your-app): This document covers tools and features available for debugging apps built with XMTP, including stress testing, group chat diagnostics, logging, and network monitoring capabilities.
- [Use signatures with XMTP](/chat-apps/use-signatures): With XMTP, you can use various types of signatures to sign and verify payloads.
- [Support user consent preferences to provide spam-free chats](/chat-apps/user-consent/support-user-consent): Use the following methods to provide users with control over their messaging experience, ensuring their chats are tailored to their preferences and spam-free.
- [Understand how user consent preferences support spam-free chats](/chat-apps/user-consent/user-consent): In any open and permissionless messaging ecosystem, spam is an inevitable reality, and XMTP is no exception.
- [Get started with the XMTP Android SDK](/chat-apps/sdks/android): Use the [XMTP Android SDK](https://github.com/xmtp/xmtp-android) to build secure, private, and decentralized messaging into your Android app.
- [Get started with the XMTP Browser SDK](/chat-apps/sdks/browser): Use the [XMTP Browser SDK](https://github.com/xmtp/xmtp-js/tree/main/sdks/browser-sdk) to build web-based apps, tools, and experiences with secure, private, and decentralized messaging.
- [Get started with the XMTP iOS SDK](/chat-apps/sdks/ios): Use the [XMTP iOS SDK](https://github.com/xmtp/xmtp-ios) to build secure, private, and decentralized messaging into your iOS app.
- [Get started with the XMTP Node SDK](/chat-apps/sdks/node): Use the [XMTP Node SDK](https://github.com/xmtp/xmtp-js/tree/main/sdks/node-sdk) to build agents and other server-side applications that interact with the XMTP network.
- [Get started with the XMTP React Native SDK](/chat-apps/sdks/react-native): Use the [XMTP React Native SDK](https://github.com/xmtp/xmtp-react-native) to build secure, private, and decentralized messaging into your cross-platform mobile app.
- [Try push notifications with the Android example XMTP app](/chat-apps/push-notifs/android-pn): This guide describes how to set up push notifications for the [XMTP Android example app](https://github.com/xmtp/xmtp-android/tree/main/example) built with the [xmtp-android SDK](https://github.com/xmtp/xmtp-android) using Firebase Cloud Messaging (FCM) and a custom notification server.
- [Try push notifications with the iOS example XMTP app](/chat-apps/push-notifs/ios-pn): This guide describes how to set up push notifications for the [XMTP iOS example app](https://github.com/xmtp/xmtp-ios/tree/main/XMTPiOSExample) built with the [xmtp-ios SDK](https://github.com/xmtp/xmtp-ios) using Firebase Cloud Messaging (FCM) and a custom notification server.
- [Run a push notification server for an app built with XMTP](/chat-apps/push-notifs/pn-server): This guide supplements the [core instructions](https://github.com/xmtp/example-notification-server-go/blob/np/export-kotlin-proto-code/README.md#local-setup) provided in the `example-notification-server-go` repository. The guide aims to address some common setup misconceptions and issues.
- [Support push notifications](/chat-apps/push-notifs/push-notifs): With XMTP, you can enable real-time push notifications to keep users updated on new conversations and messages.
- [Understand push notifications with XMTP](/chat-apps/push-notifs/understand-push-notifs): With XMTP, you can enable real-time push notifications to keep users updated on new conversations and messages.
- [Support archive-based backups](/chat-apps/list-stream-sync/archive-backups): Support archive-based backups to give your users an easy and durable way to back up their XMTP conversations, messages, and consent preferences from one app installation and import them into another.
- [Enable history sync for apps built with XMTP](/chat-apps/list-stream-sync/history-sync): Enable the history sync feature to give your users a way to sync an archive (decrypted historical data) from an existing app installation to a new app installation.
- [List messages](/chat-apps/list-stream-sync/list-messages): Query messages from a conversation using filters including time ranges, delivery status, and content types. You can either retrieve the full message list or just get a message count for efficiency.
- [List conversations](/chat-apps/list-stream-sync/list): Get a list of existing group chat and DM conversations in the local database.
- [Stream conversations and messages](/chat-apps/list-stream-sync/stream): Listens to the network for new group chats and DMs. Whenever a new conversation starts, it triggers the provided callback function with a [`ConversationContainer` object](/chat-apps/core-messaging/create-conversations#conversation-union-type). This allows the client to immediately respond to any new group chats or DMs initiated by other users.
- [Sync conversations and messages](/chat-apps/list-stream-sync/sync-and-syncall): This video provides a walkthrough of key concepts required to implement syncing correctly.
- [Sync preferences](/chat-apps/list-stream-sync/sync-preferences): You can sync the following preference-related information across multiple existing app installations:
- [Get dev support for building with XMTP](/chat-apps/intro/dev-support): Building with XMTP and need help or think you've found a bug?
- [FAQ about XMTP](/chat-apps/intro/faq): Get answers to the most frequently asked questions about XMTP.
- [Get started building with XMTP](/chat-apps/intro/get-started): XMTP (Extensible Message Transport Protocol) is the largest and most secure decentralized messaging network. XMTP is open and permissionless, empowering any developer to build end-to-end encrypted 1:1, group, and agent messaging experiences, and more.
- [Build a quickstart chat app](/chat-apps/intro/quickstart): Follow this tutorial to build a quickstart chat app with XMTP.
- [What is XMTP?](/chat-apps/intro/what-is-xmtp): XMTP (Extensible Message Transport Protocol) is an open protocol and decentralized network for secure, end-to-end encrypted messaging. It enables developers to build messaging experiences where users own their identity, conversations, and data.
- [Why build with XMTP?](/chat-apps/intro/why-xmtp): Build with XMTP to:
- [Extend the XMTP identity model](/chat-apps/core-messaging/extend-id-model): XMTP is designed with a flexible identity model that can be extended over time without introducing breaking changes for existing apps.
- [Create an XMTP client](/chat-apps/core-messaging/create-a-client): Create an XMTP client that can use the signing capabilities provided by the [signer](/chat-apps/core-messaging/create-a-signer). This signer links the client to the appropriate EOA or SCW.
- [Create a signer](/chat-apps/core-messaging/create-a-signer): To connect to XMTP, your app needs a **signer**, an object that identifies a user and can sign messages on their behalf. Under the hood, XMTP uses [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) signatures on the **secp256k1** curve.
- [Create conversations](/chat-apps/core-messaging/create-conversations): The first step to creating a conversation is to verify that participants' identities are reachable on XMTP. The `canMessage` method checks each identity's compatibility, returning a response indicating whether each identity can receive messages.
- [Delete messages](/chat-apps/core-messaging/delete-messages): A user can delete messages they sent in a DM or group chat. In a group chat, the super admin role can delete any message in the group.
- [Support disappearing messages](/chat-apps/core-messaging/disappearing-messages): Disappearing messages are messages that are intended to be visible to users for only a short period of time. After the message expiration time passes, the messages are removed from the UI and deleted from local storage so the messages are no longer accessible to conversation participants.
- [Manage group chat metadata](/chat-apps/core-messaging/group-metadata): Group chats can have metadata, like names, descriptions, and images. Metadata can help users more easily identify their group chats. You can set group chat metadata when [creating a group chat](/chat-apps/core-messaging/create-conversations), and get and update metadata using these methods.
- [Manage group permissions](/chat-apps/core-messaging/group-permissions): Robust group chat permissions are key to providing users with a friendly and safe group chat experience.
- [Manage XMTP inboxes, identities, and installations](/chat-apps/core-messaging/manage-inboxes): With XMTP, a user can have one or more **inboxes** they use to access their messages. An inbox ID is a stable identifier for a user's messaging identity and is used as the destination for messages in direct message and group conversations. It is derived from the public key material in their key package.
- [Observe rate limits](/chat-apps/core-messaging/rate-limits): XMTP enforces separate rate limits for read and write operations per client per rolling 5-minute window:
- [Send messages](/chat-apps/core-messaging/send-messages): Once you have the group chat or DM conversation, you can send messages in the conversation.
- [Support group chat invite links](/chat-apps/core-messaging/support-group-invite-links): This document provides suggested paths you might take to provide XMTP group chat invite links in your app. These are just proposals and the actual implementation direction and details are specific to your app and your goals.
- [Support actions in your app built with XMTP](/chat-apps/content-types/actions): Use the actions content type to send interactive messages with selectable options. Actions enable users to choose from a list of predefined options, making it easy to build interactive experiences like polls, confirmations, or multi-step workflows.
- [Support attachments in your app built with XMTP](/chat-apps/content-types/attachments): Use the remote attachment, multiple remote attachments, or attachment content type to support attachments in your app.
- [Understand content types with XMTP](/chat-apps/content-types/content-types): When you build an app with XMTP, all messages are encoded with a content type to ensure that an XMTP client knows how to encode and decode messages, ensuring interoperability and consistent display of messages across apps.
- [Build custom content types](/chat-apps/content-types/custom): Any developer building with XMTP can create a custom content type and immediately start using it in their app. Unlike a standard content type, use of a custom content type doesn't require prerequisite formal adoption through the XRC and XIP processes.
- [Use fallback text for content type compatibility](/chat-apps/content-types/fallback): When building with XMTP, you can't know in advance whether a recipient's app will support a given content type, especially a [custom one](/chat-apps/content-types/custom). Likewise, your own app might receive messages with content types it doesn't support.
- [Support intents in your app built with XMTP](/chat-apps/content-types/intents): Use the intent content type to respond to [action messages](/chat-apps/content-types/actions). An intent represents a user's selection from an actions message, enabling interactive workflows within conversations.
- [Support reactions in your app built with XMTP](/chat-apps/content-types/reactions): Use the reaction content type to support reactions in your app. A reaction is a quick and often emoji-based way to respond to a message. Reactions are usually limited to a predefined set of emojis or symbols provided by the chat app.
- [Support read receipts in your app built with XMTP](/chat-apps/content-types/read-receipts): Use the read receipt content type to support read receipts in your app. A read receipt is a `timestamp` that indicates when a message was read. It is sent as a message and can be used to calculate the time since the last message was read.
- [Support replies in your app built with XMTP](/chat-apps/content-types/replies): Use the reply content type to support quote replies in your app. A reply is a method to directly respond to a specific message in a conversation. Users can select and reply to a particular message instead of sending a new one.
- [Support onchain transaction references in your app built with XMTP](/chat-apps/content-types/transaction-refs): This package provides an XMTP content type to support onchain transaction references. It is a reference to an onchain transaction sent as a message. This content type facilitates sharing transaction hashes or IDs, thereby providing a direct link to onchain activities. Transaction references serve to display transaction details, facilitating the sharing of onchain activities, such as token transfers, between users.
- [Support onchain transactions in your app built with XMTP](/chat-apps/content-types/transactions): This content type supports sending transactions to a wallet for execution.
- [Build XMTP agents](/agents/get-started/build-an-agent): Use the [XMTP Agent SDK](https://www.npmjs.com/package/@xmtp/agent-sdk) to build agents that interact with the XMTP network.
- [FAQ about XMTP agents](/agents/get-started/faq): Get answers to frequently asked questions about building agents with XMTP.
- [Build XMTP agents](/agents/get-started/intro): XMTP agents are autonomous programs that can participate in secure, end-to-end encrypted conversations on the XMTP network. Build agents that interact with humans and other agents across any XMTP-powered app.
- [Follow agent security best practices](/agents/deploy/agent-security): For an agent to function—whether it's answering questions, executing commands, or providing automated responses—it must be able to read the conversation to understand what's being asked, and write messages to respond.
- [Debug an agent](/agents/deploy/debug-agents): You can debug and interact with your agent using [xmtp.chat](https://xmtp.chat), the official web chat app for developers.
- [Deploy an agent](/agents/deploy/deploy-agent): This section covers how to deploy an agent using [Railway](https://railway.app/)—a platform many developers prefer for quickly and easily deploying agents. While this tutorial focuses on Railway, you can use any hosting provider that supports Node.js and environment variables.
- [Process management](/agents/deploy/pm2-process-management): XMTP SDKs have a few guardrails in place to prevent crashes. However, it's difficult to guarantee 100% uptime for long-running processes. For that reason, we recommend using a process manager like [PM2](https://pm2.io/) to ensure proper restart behavior and logging.
- [Observe rate limits](/agents/deploy/rate-limits): XMTP enforces separate rate limits for read and write operations per client per rolling 5-minute window:
- [Send actions and handle intents](/agents/content-types/actions): Actions let your agent send a message with tappable buttons. When the user picks one, the agent gets an intent event with the selected button's ID. This works well for confirmations, payment flows, menu navigation, and polls.
- [Support attachments with your agent built with XMTP](/agents/content-types/attachments): The Agent SDK package provides an XMTP content type (`RemoteAttachmentCodec`) to support sending file attachments through conversations.
- [Understand content types with XMTP](/agents/content-types/content-types): When you build an agent with XMTP, all messages are encoded with a content type to ensure that an XMTP client knows how to encode and decode messages, ensuring interoperability and consistent display of messages across apps.
- [Stream group updates with XMTP](/agents/content-types/group-updates): Stream group metadata changes (name, description, members) in real-time using the `group_updated` native content type. Group updates allow you to monitor changes to group conversations including member additions/removals, name changes, and description updates.
- [Support markdown with your agent built with XMTP](/agents/content-types/markdown): Use the markdown content type to send rich formatted text messages with your agent. Markdown allows you to include headers, lists, tables, code blocks, and other formatting elements to create more engaging and structured messages.
- [Support reactions with your agent built with XMTP](/agents/content-types/reactions): Use the reaction content type to support reactions with your agent. A reaction is a quick and often emoji-based way to respond to a message. Reactions are usually limited to a predefined set of emojis or symbols provided by the chat app.
- [Support replies with your agent built with XMTP](/agents/content-types/replies): Use the reply content type to support quote replies with your agent. A reply is a method to directly respond to a specific message in a conversation. Users can select and reply to a particular message instead of sending a new one.
- [Support onchain transaction references with your agent built with XMTP](/agents/content-types/transaction-refs): This package provides an XMTP content type to support onchain transaction references. It is a reference to an onchain transaction sent as a message. This content type facilitates sharing transaction hashes or IDs, thereby providing a direct link to onchain activities. Transaction references serve to display transaction details, facilitating the sharing of onchain activities, such as token transfers, between users.
- [Support onchain transactions with your agent built with XMTP](/agents/content-types/transactions): This package provides an XMTP content type to support sending transactions to a wallet for execution.
- [Context and helpers](/agents/concepts/context): Every XMTP agent event handler receives a rich `MessageContext` object that provides access to the message, conversation, client, and powerful helper methods. This context makes it easy to build responsive agents without repetitive boilerplate code.
- [Event-driven architecture](/agents/concepts/event-driven): Subscribe only to what you need using Node’s `EventEmitter` interface. Events you can listen for:
- [Built‑in filters](/agents/concepts/filters): Instead of manually checking every incoming message, you can use the provided filters.
- [Create an XMTP client](/agents/concepts/identity): Create an XMTP client that can use the signing capabilities provided by the [signer](/chat-apps/core-messaging/create-a-signer). This signer links the client to the appropriate Externally Owned Account (EOA) or Smart Contract Wallet (SCW).
- [Middleware support](/agents/concepts/middleware): Extend your agent with custom business logic using middleware. Compose cross-cutting behavior like routing, telemetry, rate limiting, analytics, and feature flags, or plug in your own.
- [Create an XMTP agent](/agents/build-agents/create-a-client): Create an XMTP agent that can use the signing capabilities provided by the [signer](/chat-apps/core-messaging/create-a-signer). This signer links the agent to the appropriate EOA or SCW.
- [Create conversations](/agents/build-agents/create-conversations): With your agent, you can create a new conversation, whether it's a group chat or direct message (DM).
- [Understand group permissions](/agents/build-agents/group-permissions): The group permissions system controls what actions different members can take in a group chat. This guide explains how the system works conceptually. For practical code examples of managing roles and permissions, see [Manage group chats](/agents/build-agents/groups).
- [Manage group chats](/agents/build-agents/groups): Group chats can have metadata like names, descriptions, and images to help users identify them. You can set metadata when [creating a group chat](/agents/build-agents/create-conversations) or update it later.
- [Manage agent local database files and installations](/agents/build-agents/local-database): Each XMTP agent installation maintains its own local database containing message history, conversation state, and cryptographic material. When you delete this database (or use an in-memory database), you create a new installation that counts toward your [installation limits](/chat-apps/core-messaging/manage-inboxes#inbox-update-and-installation-limits).
- [Stream conversations and messages](/agents/build-agents/stream): With the agent-sdk, you can listen for different types of messages using event handlers. The agent automatically handles streaming and provides simple event-based APIs.