Quickstart

This guide will walk you through the essential steps to integrate LibXMTP into your application and send your first encrypted message.

Prerequisites

Before you begin, make sure you have:

A supported development environment (Node.js 22+, iOS/macOS, Android, or modern browser)
An Ethereum wallet address for identity authentication
Basic familiarity with async/await patterns

Quick start steps

Install the library

Choose your platform and install LibXMTP using your package manager.

Node.js
iOS
Android
WASM

npm install @xmtp/node-bindings

Add LibXMTP to your Package.swift:

dependencies: [
  .package(url: "https://github.com/xmtp/libxmtp", from: "1.9.0")
]

Or add it via Xcode: File > Add Package Dependencies

Add to your build.gradle:

dependencies {
  implementation("org.xmtp:android:1.9.0")
}

npm

npm install @xmtp/wasm-bindings

WASM bindings require browser support for OPFS or ephemeral storage.

Create a client

Initialize an XMTP client with your wallet credentials.

Node.js
Swift
Kotlin

import { Client } from '@xmtp/node-bindings'

// Create a client with wallet authentication
const client = await Client.create(
  accountAddress,
  {
    env: 'production',
    dbPath: './xmtp.db'
  }
)

console.log('Client created with Inbox ID:', client.inboxId())

import XMTPiOS

// Create client with wallet
let client = try await Client.create(
  account: wallet,
  options: .init(
    api: .init(env: .production),
    dbEncryptionKey: encryptionKey
  )
)

print("Client created with Inbox ID: \(client.inboxId)")

import org.xmtp.android.library.Client

// Create client
val client = Client().create(
  account = wallet,
  options = ClientOptions(
    api = ClientOptions.Api(
      env = XMTPEnvironment.PRODUCTION
    )
  )
)

println("Client created with Inbox ID: ${client.inboxId}")

The client manages your local database, identity state, and network connections. Each client is bound to a single Inbox ID and Installation ID.

On first run, the client will register your installation with the XMTP network. This requires a wallet signature to prove ownership.

Create or join a group

Start a new conversation or sync existing groups from the network.

Node.js
Swift
Kotlin

// Sync existing groups from the network
await client.conversations.sync()

// Create a new group
const group = await client.conversations.createGroup(
  [member1Address, member2Address],
  {
    groupName: "Team Discussion",
    groupImageUrl: "https://example.com/avatar.png",
    groupDescription: "Our project coordination channel"
  }
)

console.log('Group created:', group.id())

// List all conversations
const groups = await client.conversations.list()
console.log(`You have ${groups.length} conversations`)

// Sync existing groups
try await client.conversations.sync()

// Create a new group
let group = try await client.conversations.newGroup(
  with: [member1Address, member2Address],
  permissions: .allMembers,
  name: "Team Discussion",
  imageUrlSquare: "https://example.com/avatar.png"
)

print("Group created: \(group.id)")

// Sync existing groups
client.conversations.sync()

// Create a new group
val group = client.conversations.newGroup(
  listOf(member1Address, member2Address),
  permissions = GroupPermissions.ALL_MEMBERS,
  name = "Team Discussion",
  imageUrlSquare = "https://example.com/avatar.png"
)

println("Group created: ${group.id}")

Send and receive messages

Exchange end-to-end encrypted messages with group members.

Node.js
Swift
Kotlin

// Send a text message
await group.send("Hello, team! 👋")

// Send with optimistic sending (returns before confirmed)
await group.send("Quick update", { sendOptimistically: true })

// Query recent messages
const messages = await group.findMessages({ limit: 10 })
messages.forEach(msg => {
  console.log(`${msg.senderInboxId}: ${msg.content}`)
})

// Stream new messages in real-time
const stream = await group.streamMessages()
for await (const message of stream) {
  console.log('New message:', message.content)
}

// Send a message
try await group.send(content: "Hello, team! 👋")

// Query messages
let messages = try await group.messages(limit: 10)
for message in messages {
  print("\(message.senderInboxId): \(message.body)")
}

// Stream new messages
for try await message in group.streamMessages() {
  print("New message: \(message.body)")
}

// Send a message
group.send("Hello, team! 👋")

// Query messages
val messages = group.messages(limit = 10)
messages.forEach { message ->
  println("${message.senderInboxId}: ${message.body}")
}

// Stream new messages
group.streamMessages().collect { message ->
  println("New message: ${message.body}")
}

Example message output

{
  "id": "msg_abc123...",
  "senderInboxId": "0x1234abcd...",
  "senderInstallationId": "install_xyz789...",
  "content": "Hello, team! 👋",
  "sentAtNs": 1234567890000000,
  "kind": "application",
  "deliveryStatus": "published",
  "contentType": {
    "authorityId": "xmtp.org",
    "typeId": "text",
    "versionMajor": 1,
    "versionMinor": 0
  }
}

Next steps

Now that you have LibXMTP running, explore more advanced features:

Managing groups

Add members, update metadata, and configure permissions

Content types

Send reactions, replies, attachments, and custom content

Permissions & policies

Configure who can add members, send messages, and update groups

Consent management

Block unwanted conversations and manage spam

Common patterns

Creating a direct message (DM)

Direct messages are 1:1 conversations with exactly two members:

const dm = await client.conversations.createDm(otherAddress)
await dm.send("Hey! Want to collaborate on this?")

Handling errors

Always wrap LibXMTP operations in try-catch blocks:

try {
  const group = await client.conversations.createGroup([address1, address2])
  await group.send("Welcome!")
} catch (error) {
  if (error.message.includes('not registered')) {
    console.error('One or more addresses are not XMTP users')
  } else {
    console.error('Failed to create group:', error)
  }
}

Syncing conversations

Regularly sync to stay updated with network changes:

// Sync all conversations
await client.conversations.sync()

// Sync a specific group
await group.sync()

Troubleshooting

Client creation fails with 'signature required'

The first time a client is created, you need to provide a wallet signature to register your installation. Make sure your wallet is properly initialized and can sign messages.See Creating Clients for detailed registration flows.

Messages not appearing immediately

Messages may take a few seconds to propagate through the network. Use group.sync() to manually fetch new messages, or set up a message stream for real-time updates.

Database permission errors

Make sure the dbPath directory exists and is writable by your application. On mobile platforms, use the app’s documents directory.

Member not found errors when creating groups

Users must have an active XMTP installation to be added to groups. They need to have created a client at least once. Check that addresses are valid XMTP users with client.canMessage([address]).

Complete example

Here’s a complete Node.js example that ties everything together:

import { Client } from '@xmtp/node-bindings'

async function main() {
  // Create client
  const client = await Client.create(
    process.env.WALLET_ADDRESS,
    {
      env: 'production',
      dbPath: './my-xmtp-db.db3'
    }
  )
  
  console.log('✅ Client created:', client.inboxId())
  
  // Sync existing conversations
  await client.conversations.sync()
  console.log('✅ Synced conversations')
  
  // Create a group
  const group = await client.conversations.createGroup(
    [process.env.MEMBER_1, process.env.MEMBER_2],
    {
      groupName: "My First Group",
      groupDescription: "Learning LibXMTP"
    }
  )
  
  console.log('✅ Group created:', group.id())
  
  // Send a message
  await group.send("Hello from LibXMTP! 🚀")
  console.log('✅ Message sent')
  
  // Read messages
  const messages = await group.findMessages({ limit: 5 })
  console.log(`📬 Found ${messages.length} messages:`)
  messages.forEach(msg => {
    console.log(`  - ${msg.senderInboxId.slice(0, 10)}...: ${msg.content}`)
  })
  
  // Start streaming new messages
  console.log('👂 Listening for new messages...')
  const stream = await group.streamMessages()
  for await (const message of stream) {
    console.log(`💬 New message from ${message.senderInboxId.slice(0, 10)}...: ${message.content}`)
  }
}

main().catch(console.error)

Resources

Installation Guide - Platform-specific setup instructions
Core Concepts - Understand LibXMTP’s architecture
API Reference - Complete API documentation
GitHub Repository - Source code and examples

Getting Started

Core Concepts

Guides

Language Bindings

Security

Development

Prerequisites

Quick start steps

Next steps

Managing groups

Content types

Permissions & policies

Consent management

Common patterns

Creating a direct message (DM)

Handling errors

Syncing conversations

Troubleshooting

Complete example

Resources

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Language Bindings

Security

Development

​Prerequisites

​Quick start steps

​Next steps

Managing groups

Content types

Permissions & policies

Consent management

​Common patterns

​Creating a direct message (DM)

​Handling errors

​Syncing conversations

​Troubleshooting

​Complete example

​Resources

Build docs developers (and LLMs) love

Prerequisites

Quick start steps

Next steps

Common patterns

Creating a direct message (DM)

Handling errors

Syncing conversations

Troubleshooting

Complete example

Resources