xmtp

Unofficial Python client SDKs for the XMTP network.

Primary goal: feature parity with xmtp-js.

This is a community project that mirrors the structure and interfaces of the official xmtp-js SDK, adapted for Python.

What's inside?

SDKs

• python-sdk: XMTP client SDK for Python
• agent-sdk: XMTP agent SDK for Python (event-driven, middleware-powered)

Content types

• content-type-primitives: Primitives for building custom XMTP content types
• content-type-group-updated: Content type for group update messages
• content-type-reaction: Content type for reactions to messages
• content-type-read-receipt: Content type for read receipts
• content-type-remote-attachment: Content type for file attachments stored off-network
• content-type-reply: Content type for direct replies to messages
• content-type-text: Content type for plain text messages
• content-type-transaction-reference: Content type for on-chain transaction references
• content-type-markdown: Content type for markdown-formatted messages
• content-type-wallet-send-calls: Content type for wallet transaction requests

Requirements

• Python 3.10+
• libxmtp bindings >= 1.7.0-r3

Installation

pip install xmtp

This installs the client SDK, agent SDK, and built-in content types in one package. xmtp pins xmtp-bindings to the same package version; mismatched installs fail startup compatibility checks with an actionable error.

Install from GitHub main

pip install "xmtp @ git+https://github.com/pierce403/xmtp-py.git@main"

From source (dev)

Clone the repo and install into a virtualenv. Install the bindings first so the local editable package can resolve them:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

pip install -e bindings/python
pip install -e ".[dev]"

Quick start

Agent SDK (recommended)

import asyncio
import xmtp

from xmtp_agent import Agent
from xmtp_agent.name_resolver import create_name_resolver
from xmtp_agent.user import create_user, create_signer
from xmtp.types import ClientOptions

recipient = "deanpierce.eth"


async def main() -> None:
    # Create a user and signer
    user = create_user()
    signer = create_signer(user)

    # Create the agent
    agent = await Agent.create(
        signer,
        ClientOptions(
            env="production",
            disable_history_sync=True,
            db_path=None,
        ),
    )

    # Resolve the recipient and send a message
    resolver = create_name_resolver()
    address = await resolver(recipient)
    if address is None:
        raise ValueError(f'Could not resolve address for "{recipient}"')

    dm = await agent.client.conversations.new_dm(address)
    await dm.send(f"Hello from xmtp-py {xmtp.__version__}")


if __name__ == "__main__":
    asyncio.run(main())

Python SDK (client)

import asyncio
import xmtp

from xmtp import Client
from xmtp.signers import create_signer
from xmtp.types import ClientOptions
from xmtp_agent.name_resolver import create_name_resolver

recipient = "deanpierce.eth"


async def main() -> None:
    signer = create_signer(private_key)
    client = await Client.create(
        signer,
        ClientOptions(
            env="production",
            disable_history_sync=True,
        ),
    )

    resolver = create_name_resolver()
    address = await resolver(recipient)
    if address is None:
        raise ValueError(f'Could not resolve address for "{recipient}"')

    dm = await client.conversations.new_dm(address)
    await dm.send(f"Hello from xmtp-py {xmtp.__version__}")


if __name__ == "__main__":
    asyncio.run(main())

Key management tips

• create_user() generates an in-memory key; persist the private key yourself if you want a stable inbox across restarts.
• Prefer XMTP_WALLET_KEY in environment variables or a secrets manager; never commit it to git.
• Use a stable db_path and keep the database directory between runs. Losing the database creates a new installation and can hit installation limits.
• XMTP_DB_ENCRYPTION_KEY is optional. Set it only when you intentionally use an encrypted local database, then keep it stable.
• For production, wrap a hardware wallet or KMS signer by implementing the Signer protocol instead of storing raw keys.

Local database workflows

By default, db_path="auto" stores xmtp-<env>-<inbox_id>.db3 in the current working directory. SQLite may also create .db3-wal and .db3-shm sidecar files; treat all three as one installation.

For disposable development runs, point XMTP_DB_DIRECTORY or ClientOptions.db_path at a dev-only directory. To wipe a dev install, stop the agent and delete the matching .db3, .db3-wal, and .db3-shm files for that inbox.

For production, preserve the wallet key, database file, sidecar files, and optional encryption key together. Moving only the wallet key without the database creates another installation.

Configuration & troubleshooting

History sync is disabled by default. To enable it, pass disable_history_sync=False (and optionally history_sync_url) in ClientOptions, or set XMTP_HISTORY_SYNC_URL.

Endpoint overrides via env:

• XMTP_ENV, XMTP_API_URL, XMTP_HISTORY_SYNC_URL, XMTP_GATEWAY_HOST
• XMTP_DISABLE_HISTORY_SYNC=1 to force identity calls through the primary API
• XMTP_RUST_LOG to override Rust logging (defaults to off)

Common issues:

• Missing libxmtpv3.so: install will build it automatically, but you need Rust (cargo) and git. See bindings/python/README.md for overrides. If no prebuilt wheels are available, pip install xmtp will fall back to a source build.
• History sync gRPC errors: leave history sync disabled, or set XMTP_DISABLE_HISTORY_SYNC=1. To re-enable, pass disable_history_sync=False (and optionally history_sync_url) in ClientOptions.
• Gateway host errors: gateway_host is an advanced setting; only set it when you have a gateway that supports XMTP gRPC.
• Noisy Rust logs: set XMTP_RUST_LOG=error or pass rust_log="error" in ClientOptions.

LibXMTP bindings

This SDK uses libxmtp Python bindings for core XMTP functionality including cryptography, networking, and protocol implementation.

Minimum version: 1.7.0-r3

Runtime version metadata is exposed as xmtp.__version__, xmtp.__bindings_version__, and xmtp_bindings.__version__.

Documentation

• XMTP Documentation
• Build an XMTP Agent

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache 2.0