XMTP

https://github.com/xmtp/docs-xmtp-org
Admin
XMTP is the Extensible Message Transport Protocol, an open and extensible protocol for secure and...
Tokens:345,729
Snippets:2,509
Trust Score:9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Quickstart: XMTP Android SDK setup and usage

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/sdks/android.mdx

Complete quickstart example showing how to create a signer, initialize the XMTP client, create groups, send messages, and list/stream/sync conversations. Requires an EOA or SCW signer and a 32-byte database encryption key.

```Kotlin
// 1. Create an EOA or SCW signer.
// Details depend on your app's wallet implementation.
class EOAWallet : SigningKey {
    override val publicIdentity: PublicIdentity
        get() = PublicIdentity(IdentityKind.ETHEREUM, key.publicAddress)
    override val type: SignerType
        get() = SignerType.EOA
    override suspend fun sign(message: String): SignedData {
        return SignedData(key.sign(message = message))
    }
}

// 2. Create the XMTP client
val client = Client.create(
    account = SigningKey,
    options = ClientOptions(
        ClientOptions.Api(XMTPEnvironment.PRODUCTION, true),
        appContext = ApplicationContext(),
        dbEncryptionKey = keyBytes // 32 bytes
    )
)

// 3. Start conversations
val group = client.conversations.newGroup(inboxIds = listOf(bo.inboxId, caro.inboxId))
val groupWithMeta = client.conversations.newGroup(
    inboxIds = listOf(bo.inboxId, caro.inboxId),
    permissionLevel = GroupPermissionPreconfiguration.ALL_MEMBERS,
    name = "The Group Name",
    imageUrl = "www.groupImage.com",
    description = "The description of the group"
)

// 4. Send messages
val dm = client.conversations.findOrCreateDm(recipientInboxId)
dm.send(text = "Hello world")
group.send(text = "Hello everyone")

// 5. List, stream, and sync
// List existing conversations
val conversations = client.conversations.list()
val filteredConversations = client.conversations.list(consentState = ConsentState.ALLOWED)
// Stream all new conversations and new messages from allowed conversations
client.conversations.streamAllMessages(consentStates = listOf(ConsentState.ALLOWED)).collect {
    // Received a message
}
// Sync all new welcomes, preference updates, conversations,
// and messages from allowed conversations
client.conversations.syncAll(consentStates = ConsentState.ALLOWED)
```

--------------------------------

### Swift: XMTP iOS SDK quickstart

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/sdks/ios.mdx

Complete quickstart example showing how to create a signer, create the XMTP client, start conversations, send messages, and list/stream/sync conversations. Uses the XMTP iOS SDK.

```swift
// 1. Create an EOA or SCW signer
// Details depend on your app's wallet implementation.
public struct EOAWallet: SigningKey {
    public var identity: PublicIdentity {
        return PublicIdentity(kind: .ethereum, identifier: key.publicAddress)
    }
    public var type: SignerType { .EOA }
    public func sign(message: String) async throws -> SignedData {
        return SignedData(try await key.sign(message: message))
    }
}

// 2. Create the XMTP client
let client = try await Client.create(
    account: SigningKey,
    options: ClientOptions.init(
        api: .init(env: .production, isSecure: true),
        dbEncryptionKey: keyBytes // 32 bytes
    )
)

// 3. Start conversations
let group = try await client.conversations.newGroup([bo.inboxId, caro.inboxId])
let groupWithMeta = try await client.conversations.newGroup([bo.inboxId, caro.inboxId],
    permissionLevel: .admin_only,
    name: "The Group Name",
    imageUrl: "www.groupImage.com",
    description: "The description of the group"
)

// 4. Send messages
let dm = try await client.conversations.findOrCreateDm(with: recipientInboxId)
try await dm.send(content: "Hello world")
try await group.send(content: "Hello everyone")

// 5. List, stream, and sync
// List existing conversations
let conversations = try await client.conversations.list()
let filteredConversations = try await client.conversations.list(consentState: .allowed)
// Stream new messages
for await message in try await client.conversations.streamAllMessages(type: /* OPTIONAL .dms, .groups, .all */, consentState: [.allowed]) {
    // Received a message
}
// Sync all new welcomes, preference updates, conversations,
// and messages from allowed conversations
try await client.conversations.syncAllConversations(consentState: [.allowed])
```

--------------------------------

### Quickstart: Create client, start conversation, send messages, and sync

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/sdks/node.mdx

This example shows the core steps to use the XMTP Node SDK: create a signer, create a client, start a group conversation, send a text message, and list/stream/sync conversations. It includes comments for each step.

```tsx
// 1. Create an EOA or SCW signer.
// Details depend on your app's wallet implementation.
import type { Signer, Identifier, IdentifierKind } from '@xmtp/node-sdk';

const signer: Signer = {
  type: 'EOA',
  getIdentifier: () => ({
    identifier: '0x...', // Ethereum address as the identifier
    identifierKind: IdentifierKind.Ethereum,
  }),
  signMessage: async (message: string): Uint8Array => {
    // typically, signing methods return a hex string
    // this string must be converted to bytes and returned in this function
  },
};

// 2. Create the XMTP client
import { Client } from '@xmtp/node-sdk';
import { getRandomValues } from 'node:crypto';

const dbEncryptionKey = getRandomValues(new Uint8Array(32));
const client = await Client.create(signer, { dbEncryptionKey });

// 3. Start a new conversation
const group = await client.conversations.createGroup(
  [bo.inboxId, caro.inboxId],
  createGroupOptions /* optional */
);

// 4. Send messages
await group.sendText('Hello everyone');

// 5. List, stream, and sync
// List existing conversations
const allConversations = await client.conversations.list({
  consentStates: [ConsentState.Allowed],
});
// Stream new messages
const stream = await client.conversations.streamAllMessages({
  consentStates: [ConsentState.Allowed],
  onValue: (message) => {
    console.log('New message:', message);
  },
  onError: (error) => {
    console.error(error);
  },
});

// Or use for-await loop
for await (const message of stream) {
  // Received a message
  console.log('New message:', message);
}
// Sync all new welcomes, preference updates, conversations,
// and messages from allowed conversations
await client.conversations.syncAll(['allowed']);
```

--------------------------------

### React Native quickstart: signer, client, conversations, messages, and sync

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/sdks/react-native.mdx

Complete quickstart example for the XMTP React Native SDK. It shows how to convert an EOA to a signer, create a client with production environment and encryption key, start group conversations with optional metadata, send direct and group messages, and list, stream, and sync conversations. Note that the signer creation depends on your app's wallet implementation.

```tsx
// 1. Create an EOA or SCW signer.
// Details depend on your app's wallet implementation.
export function convertEOAToSigner(eoaAccount: EOAAccount): Signer {
  return {
    getIdentifier: async () =>
      new PublicIdentity(eoaAccount.address, 'ETHEREUM'),
    getChainId: () => undefined,
    getBlockNumber: () => undefined,
    signerType: () => 'EOA',
    signMessage: async (message: string) => ({
      signature: await eoaAccount.signMessage(message),
    }),
  };
}

// 2. Create the XMTP client
const client = Client.create(signer, {
  env: 'production',
  dbEncryptionKey: keyBytes, // 32 bytes
});

// 3. Start conversations
const group = await client.conversations.newGroup([bo.inboxId, caro.inboxId]);
const groupWithMeta = await client.conversations.newGroup(
  [bo.inboxId, caro.inboxId],
  {
    name: 'The Group Name',
    imageUrl: 'www.groupImage.com',
    description: 'The description of the group',
    permissionLevel: 'admin_only',
    appData: JSON.stringify({ theme: 'dark' }), // Custom app data
  }
);

// 4. Send messages
const dm = await client.conversations.findOrCreateDm(recipientInboxId);
await dm.send('Hello world');
await group.send('Hello everyone');

// 5. List, stream, and sync
// List existing conversations
await client.conversations.list(['allowed']);
// Stream new messages
await client.conversations.streamAllMessages(
  async (message: DecodedMessage<any>) => {
    // Received a message
  },
  { consentState: ['allowed'] }
);
// Sync all new welcomes, preference updates, conversations,
// and messages from allowed conversations
await client.conversations.syncAllConversations(['allowed']);
```

--------------------------------

### Start local XMTP network with dev/up

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/deploy/debug-agents.mdx

Run this command to start the XMTP service and database locally. Requires Docker to be installed first.

```bash
./dev/up
```

--------------------------------

### Quickstart: Create client, group, send messages, list, stream, and sync

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/sdks/browser.mdx

TypeScript example showing the core XMTP Browser SDK workflow: create a signer, create a client, create a group, send a text message, list conversations, stream messages, and sync. Note that dbEncryptionKey is not used for encryption in browser environments.

```tsx
// 1. Create an EOA or SCW signer.
// Details depend on your app's wallet implementation.
import type { Signer, Identifier } from '@xmtp/browser-sdk';
import { IdentifierKind } from '@xmtp/browser-sdk';

const signer: Signer = {
  type: 'EOA',
  getIdentifier: () => ({
    identifier: '0x...', // Ethereum address as the identifier
    identifierKind: IdentifierKind.Ethereum,
  }),
  signMessage: async (message: string): Uint8Array => {
    // typically, signing methods return a hex string
    // this string must be converted to bytes and returned in this function
  },
};

// 2. Create the XMTP client
import { Client } from '@xmtp/browser-sdk';
const client = await Client.create(signer, {
  // Note: dbEncryptionKey is not used for encryption in browser environments
});

// 3. Start conversations
const group = await client.conversations.createGroup(
  [bo.inboxId, caro.inboxId],
  createGroupOptions /* optional */
);

// 4. Send messages
await group.sendText('Hello everyone');

// 5. List, stream, and sync
// List existing conversations
const allConversations = await client.conversations.list({
  consentStates: [ConsentState.Allowed],
});
const allGroups = await client.conversations.listGroups({
  consentStates: [ConsentState.Allowed],
});
const allDms = await client.conversations.listDms({
  consentStates: [ConsentState.Allowed],
});
// Stream new messages
const stream = await client.conversations.streamAllMessages({
  consentStates: [ConsentState.Allowed],
  onValue: (message) => {
    console.log('New message:', message);
  },
  onError: (error) => {
    console.error(error);
  },
});

// Or use for-await loop
for await (const message of stream) {
  console.log('New message:', message);
}
// Sync all new welcomes, preference updates, conversations,
// and messages from allowed conversations
await client.conversations.syncAll(['allowed']);
```

--------------------------------

### Install Go with Homebrew

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/push-notifs/pn-server.mdx

Installs Go via Homebrew. If you see 'Error: go 1.17.2 is already installed', Go is already installed.

```bash
brew install go
```

--------------------------------

### Create an XMTP agent that responds to text messages

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/get-started/build-an-agent.mdx

Example agent that creates an Agent from environment variables, listens for text messages, replies with a greeting, and logs its address and test URL on start. Requires a .env file with the XMTP environment variables.

```ts
import { Agent, getTestUrl } from '@xmtp/agent-sdk';

// 2. Spin up the agent
const agent = await Agent.createFromEnv();

// 3. Respond to text messages
agent.on('text', async (ctx) => {
  await ctx.conversation.sendText('Hello from my XMTP Agent! 👋');
});

// 4. Log when we're ready
agent.on('start', () => {
  console.log(`Waiting for messages...`);
  console.log(`Address: ${agent.address}`);
  console.log(`🔗 ${getTestUrl(agent.client)}`);
});

await agent.start();
```

--------------------------------

### Install PM2 with pnpm

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-agents.txt

Install PM2 as a dependency using pnpm.

```bash
pnpm add pm2
```

--------------------------------

### Install PM2 with yarn

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-agents.txt

Install PM2 as a dependency using yarn.

```bash
yarn add pm2
```

--------------------------------

### Client address and test URL

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/concepts/context.mdx

Use agent.address to get the agent's address and getTestUrl(agent.client) to get a test URL. The example logs both in the 'start' event.

```typescript
import { getTestUrl } from '@xmtp/agent-sdk';

agent.on('start', () => {
  console.log(`Waiting for messages...`);
  console.log(`Address: ${agent.address}`);
  console.log(`🔗 ${getTestUrl(agent.client)}`);
});
```

--------------------------------

### Get client address with getClientAddress()

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/concepts/context.mdx

Use ctx.getClientAddress() to get the Ethereum address of your agent. The example logs it.

```typescript
agent.on('text', async (ctx) => {
  const agentAddress = ctx.getClientAddress();
  console.log(`Agent address: ${agentAddress}`);
});
```

--------------------------------

### Run example notification server with FCM

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/push-notifs/android-pn.mdx

Set up the example notification server: first store the FCM credentials JSON in a shell variable, then run the server with the required flags including the XMTP listener, API, database connection, and FCM configuration.

```bash
YOURFCMJSON=$(cat /path/to/FCMCredentials.json)
```

```bash
dev/run \
--xmtp-listener-tls \
--xmtp-listener \
--api \
-x "grpc.production.xmtp.network:443" \
-d "postgres://postgres:xmtp@localhost:25432/postgres?sslmode=disable" \
--fcm-enabled \
--fcm-credentials-json=$YOURFCMJSON \
--fcm-project-id="YOURFCMPROJECTID"
```

--------------------------------

### GET /groupJoinRequest/:id - Example request

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/core-messaging/support-group-invite-links.mdx

HTTP GET request to check the status of a group join request.

```html
GET /groupJoinRequest/hijklmn
```

--------------------------------

### Install XMTP SDK and key generation libraries

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/intro/quickstart.mdx

Moves into the project directory and installs the XMTP browser SDK and key generation libraries.

```bash
cd my-xmtp-app
npm install @xmtp/browser-sdk @noble/curves @noble/hashes
```

--------------------------------

### Get consent state of an individual in a group chat

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/user-consent/support-user-consent.mdx

Use the client's getConsentState method with ConsentEntityType.InboxId to retrieve the consent state for a specific inbox ID. The Browser and Node examples use the respective SDKs. The React Native, Kotlin, and Swift examples show two approaches: getting consent directly on the member and getting consent from the inboxId.

```js
import { ConsentEntityType } from '@xmtp/browser-sdk';

const inboxConsentState = await client.getConsentState(
  ConsentEntityType.InboxId,
  inboxId
);
```

```js
import { ConsentEntityType } from '@xmtp/node-sdk';

const inboxConsentState = await client.getConsentState(
  ConsentEntityType.InboxId,
  inboxId
);
```

```tsx
// Get consent directly on the member
const memberConsentStates = (await group.members()).map((member) =>
  member.consentState()
);

// Get consent from the inboxId
const inboxConsentState = await client.preferences.inboxIdConsentState(inboxId);
```

```kotlin
// Get consent directly on the member
val memberConsentStates = group.members().map { it.consentState }

// Get consent from the inboxId
val inboxConsentState = client.preferences.inboxIdState(inboxId)
```

```swift
// Get consent directly on the member
let memberConsentStates = try await group.members.map(\.consentState)

// Get consent from the inboxId
let inboxConsentState = try await client.preferences.inboxIdState(inboxId: inboxId)
```

--------------------------------

### Install @xmtp/browser-sdk with bun

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-chat-apps.txt

Install the XMTP Browser SDK as a dependency using bun.

```bash
bun i @xmtp/browser-sdk
```

--------------------------------

### Preview static build with npm run preview

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/README.md

Starts a local server to view the static website content generated in the dist directory, opening it at http://localhost:4173/ in the default browser. Changes to markdown files are not reflected in this static build.

```bash
$ npm run preview
```

--------------------------------

### Message history: get all and recent messages

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/concepts/context.mdx

Use ctx.conversation.messages() to get all messages, then slice the last 10 to get recent messages. The example logs each message's sender inbox ID and content.

```typescript
agent.on('text', async (ctx) => {
  // Get all messages
  const messages = await ctx.conversation.messages();
  console.log(`Total messages: ${messages.length}`);

  // Get recent messages
  const recentMessages = messages.slice(-10);

  for (const msg of recentMessages) {
    console.log(`${msg.senderInboxId}: ${msg.content}`);
  }
});
```

--------------------------------

### Get a Welcome message topic ID

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-chat-apps.txt

Get the topic identifier for an app installation to listen for push notifications about new group chat or DM conversations.

```APIDOC
## Get a Welcome message topic ID

### Description
Get the topic identifier for an app installation. This topic ID tells your app where to listen on the network for push notifications about any new group chat or DM conversations.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
None

### Request Example
```tsx [React Native]
alix.welcomeTopic()
```

```kotlin [Kotlin]
Topic.userWelcome(client.installationId).description
```

```swift [Swift]
Topic.userWelcome(client.installationId).description
```

### Response
#### Success Response
- **topic** (string) - The topic identifier for the app installation.

#### Response Example
```
/xmtp/mls/1/w-$installationId/proto
```

```

--------------------------------

### Build the server with ./dev/build

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/push-notifs/pn-server.mdx

Builds the server. If you encounter Go-related errors like missing `go.sum` entries, use the suggested `go get` or `go mod download` commands. Ignore warnings about `//go:build comment without // +build comment` as they are future deprecation warnings.

```bash
./dev/build
```

--------------------------------

### Get sender address with getSenderAddress()

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/concepts/context.mdx

Use ctx.getSenderAddress() to get the Ethereum address of the message sender. The example logs it and uses it for authorization by comparing to a hardcoded address.

```typescript
agent.on('text', async (ctx) => {
  const senderAddress = await ctx.getSenderAddress();
  console.log(`Message from: ${senderAddress}`);

  // Use for authorization
  if (senderAddress === '0x1234...') {
    await ctx.sendTextReply('Hello, admin!');
  }
});
```

--------------------------------

### Install @xmtp/node-sdk with bun

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-chat-apps.txt

Install the XMTP Node SDK as a dependency using bun.

```bash
bun i @xmtp/node-sdk
```

--------------------------------

### GET /groupInvite/:id - Example request

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/core-messaging/support-group-invite-links.mdx

HTTP GET request to retrieve invite information for generating a landing page. The :id is the invite identifier, e.g., abcdefg.

```html
GET /groupInvite/abcdefg
```

--------------------------------

### Connect to XMTP with Agent.createFromEnv()

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/get-started/connect-to-xmtp.mdx

Imports the Agent class from the XMTP Agent SDK and creates an agent instance using createFromEnv(). This function reads XMTP_WALLET_KEY, XMTP_DB_ENCRYPTION_KEY, and XMTP_ENV from process.env, normalizes key formats, sets up the client, and registers the agent's identity on the network if needed. The agent must be started at least once before its address can receive messages.

```tsx
import { Agent } from "@xmtp/agent-sdk";

// ---------------------------------------------------------------------------
// THE MESSAGING RAILS: XMTP Agent SDK
// ---------------------------------------------------------------------------

// createFromEnv() reads XMTP_WALLET_KEY, XMTP_DB_ENCRYPTION_KEY, and XMTP_ENV
// from process.env and handles all key format normalization automatically.
const agent = await Agent.createFromEnv();
```

--------------------------------

### Get network debug information and statistics (Swift)

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/debug/debug-your-app.mdx

Swift example showing how to get network debug information, access aggregated and individual statistics, and clear all statistics.

```swift
// Get network debug information
let debugInfo = client.debugInformation

// Get aggregated statistics
print(debugInfo.aggregateStatistics)

// Access individual API statistics
print("Uploads: \(debugInfo.apiStatistics.uploadKeyPackage)")
print("Fetches: \(debugInfo.apiStatistics.fetchKeyPackage)")

// Clear all statistics
try await client.debugInformation.clearAllStatistics()
```

--------------------------------

### Install canvas library

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/content-types/attachments.mdx

Install the canvas library to programmatically create a PNG image.

```bash
npm install canvas
```

--------------------------------

### Install Docker and Docker Compose with Homebrew

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/push-notifs/pn-server.mdx

Installs Docker, Docker Compose, and Docker credential desktop via Homebrew. Requires Docker Desktop to be running afterward.

```bash
brew install docker docker-compose docker-credential-desktop
```

--------------------------------

### Get network debug information and statistics (Kotlin)

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/debug/debug-your-app.mdx

Kotlin example showing how to get network debug information, access aggregated and individual statistics, and clear all statistics.

```kotlin
// Get network debug information
val debugInfo = client.debugInformation

// Get aggregated statistics
println(debugInfo.aggregateStatistics)

// Access individual API statistics
println("Uploads: ${debugInfo.apiStatistics.uploadKeyPackage}")
println("Fetches: ${debugInfo.apiStatistics.fetchKeyPackage}")

// Clear all statistics
client.debugInformation.clearAllStatistics()
```

--------------------------------

### Install @xmtp/browser-sdk with pnpm

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-chat-apps.txt

Install the XMTP Browser SDK as a dependency using pnpm.

```bash
pnpm i @xmtp/browser-sdk
```

--------------------------------

### GET /groupJoinRequest/:id - Example response

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/core-messaging/support-group-invite-links.mdx

JSON response for the GET request, showing the join request status and an optional reason. Possible statuses are approved, rejected, and pending.

```json
{
 id: "hijklmn",
 status: "approved"// Possible statuses ("approved", "rejected", "pending")
 reason: null // Allow the system to pass a reason back to the client
}
```

--------------------------------

### Send a sync request (Browser/Node)

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-chat-apps.txt

Sends a request to other installations to sync conversations and messages. Call after creating a client on a new installation. The custom options example uses archiveElements and a serverUrl.

```JavaScript
// With default options
await client.sendSyncRequest();

// With custom options
await client.sendSyncRequest(
  { archiveElements: ["consent"] },            // options
  "https://your-history-sync-server.example.com/" // serverUrl
);
```

```JavaScript
// With default options
await client.sendSyncRequest();

// With custom options
await client.sendSyncRequest(
  { archiveElements: ["consent"] },            // options
  "https://your-history-sync-server.example.com/" // serverUrl
);
```

--------------------------------

### Run the server with ./dev/run --xmtp-listener --api

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/push-notifs/pn-server.mdx

Starts both the `worker` and `api` services. The `worker` listens for new messages on the XMTP network and sends push notifications; the `api` service handles HTTP/gRPC requests. Requires sourcing the `.env` file first.

```bash
./dev/up
```

```bash
source .env
./dev/run --xmtp-listener --api
```

--------------------------------

### Get network debug information and statistics (React Native)

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/debug/debug-your-app.mdx

React Native example showing how to get network debug information, access aggregated and individual statistics, and clear all statistics.

```tsx
// Get network debug information
const debugInfo = await client.debugInformation.getNetworkDebugInformation();

// Get aggregated statistics as formatted string
console.log(debugInfo.aggregateStatistics);

// Access individual API statistics
console.log('Uploads:', debugInfo.apiStatistics.uploadKeyPackage);
console.log('Fetches:', debugInfo.apiStatistics.fetchKeyPackage);
console.log('Sent messages:', debugInfo.apiStatistics.sendGroupMessages);

// Access identity statistics
console.log('Identity updates:', debugInfo.identityStatistics.publishIdentityUpdate);
console.log('Inbox ID lookups:', debugInfo.identityStatistics.getInboxIds);

// Clear all statistics
await client.debugInformation.clearAllStatistics();
```

--------------------------------

### Install @xmtp/browser-sdk with npm

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-chat-apps.txt

Install the XMTP Browser SDK as a dependency using npm.

```bash
npm i @xmtp/browser-sdk
```

--------------------------------

### Install @xmtp/browser-sdk with yarn

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-chat-apps.txt

Install the XMTP Browser SDK as a dependency using yarn.

```bash
yarn add @xmtp/browser-sdk
```

--------------------------------

### Sample response: InboxState JSON

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/core-messaging/manage-inboxes.mdx

Example JSON response showing the structure of an InboxState object, including recoveryIdentity, identities, installations, and inboxId. Note that PASSKEY kind is not yet supported and is provided as an example only.

```json
InboxState
{
  "recoveryIdentity": "string",
  "identities": [
    {
      "kind": "ETHEREUM",
      "identifier": "string",
      "relyingPartner": "string"
    },
    {
      "kind": "PASSKEY",  // not yet supported; provided as an example only.
      "identifier": "string",
      "relyingPartner": "string"
    }
  ],
  "installations": ["string"],
  "inboxId": "string"
}
```

--------------------------------

### Get a Welcome message topic ID (React Native)

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/push-notifs/push-notifs.mdx

Use alix.welcomeTopic() to get the topic ID for an app installation, which listens for push notifications about new group chats or DMs. The response format is /xmtp/mls/1/w-$installationId/proto.

```tsx
// Request
alix.welcomeTopic()

// Response
/xmtp/mls/1/w-$installationId/proto
```

--------------------------------

### Install @xmtp/agent-sdk with npm, pnpm, yarn, or bun

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/get-started/build-an-agent.mdx

Install the @xmtp/agent-sdk package using your preferred package manager: npm, pnpm, yarn, or bun. Choose the command that matches your environment.

```bash
npm i @xmtp/agent-sdk
```

```bash
pnpm i @xmtp/agent-sdk
```

```bash
yarn add @xmtp/agent-sdk
```

```bash
bun i @xmtp/agent-sdk
```

--------------------------------

### Scaffold project directory and initialize git

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/get-started/connect-to-xmtp.mdx

Creates a new directory for the agent project and initializes a git repository.

```bash
mkdir my-xmtp-agent
cd my-xmtp-agent
git init
```

--------------------------------

### Fetch inbox ID by identifier

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/concepts/context.mdx

Use ctx.client.fetchInboxIdByIdentifier() to get an inbox ID from an identifier. The example uses IdentifierKind.Ethereum and a targetAddress variable.

```typescript
const inboxId = await ctx.client.fetchInboxIdByIdentifier({
  identifier: targetAddress,
  identifierKind: IdentifierKind.Ethereum,
});
```

--------------------------------

### Import Anthropic SDK and initialize client

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/agents/get-started/connect-to-xmtp.mdx

Sets up the Anthropic SDK client. The SDK automatically reads the ANTHROPIC_API_KEY from the environment, so no explicit configuration is needed.

```tsx
import "dotenv/config";
import Anthropic from "@anthropic-ai/sdk";

// ---------------------------------------------------------------------------
// THE BRAIN: Your logic (i.e., AI or rules engine)
// ---------------------------------------------------------------------------

const anthropic = new Anthropic();
```

--------------------------------

### Sync preferences using client.preferences.sync()

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/list-stream-sync/sync-preferences.mdx

This example shows how to synchronize preferences (consent preferences and HMAC keys) across app installations in a preferences group. It also syncs welcomes to ensure you have all potential new installations before syncing. A lighter-weight alternative to using syncAll.

```js
await client.preferences.sync();
```

```js
await client.preferences.sync();
```

```tsx
await client.preferences.sync();
```

```kotlin
client.preferences.sync()
```

```swift
try await client.preferences.sync()
```

--------------------------------

### Create Vite project with vanilla template

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/pages/chat-apps/intro/quickstart.mdx

Creates a new Vite project using the vanilla template. When prompted to install with npm and start now, select No.

```bash
npm create vite@latest my-xmtp-app -- --template vanilla
```

--------------------------------

### Install @xmtp/node-sdk with pnpm

Source: https://github.com/xmtp/docs-xmtp-org/blob/main/docs/public/llms/llms-chat-apps.txt

Install the XMTP Node SDK as a dependency using pnpm.

```bash
pnpm i @xmtp/node-sdk
```
Tokens:
Raw