Skip to content

Quickstart

Send your first XMTP message and get a reply from an agent in under 5 minutes.

This quickstart connects your app to a "gm" agent running on the XMTP dev network. You send a message, the agent replies "gm".

Install the CLI

npm install -g @xmtp/cli

Generate your keys

xmtp init

This creates a wallet key, database encryption key, and saves them to ~/.xmtp/.env:

XMTP_WALLET_KEY=0x...
XMTP_DB_ENCRYPTION_KEY=...
XMTP_ENV=dev

Check your client

xmtp client info

You should see your address, inbox ID, and connection status.

Start a conversation with the gm agent

xmtp conversations create-dm 0xf9244662f952d6ef83bd0719ddb5a27fbb2fe1bc

Copy the id from the output — you'll need it for the next steps.

Send a message

Replace <id> with the conversation id from the previous step.

xmtp conversation send-text <id> "gm"

Check for the reply

xmtp conversation messages <id> --sync

You should see your message and the agent's reply:

senderInboxId   content  sentAt
--------------  -------  -------------------
a1b2c3d4e5f6…   gm       2026-02-20 12:00:00
f6e5d4c3b2a1…   gm       2026-02-20 12:00:01

Try it now

Click each step to run it right here in your browser. No setup required.

Try the CLI

Type XMTP CLI commands directly in your browser. Same commands you'd use with npx @xmtp/cli.

Run it locally

Scaffold a project

npm create vite@latest my-xmtp-app -- --template vanilla-ts
cd my-xmtp-app
npm install @xmtp/browser-sdk viem

Replace src/main.ts

Delete the contents of src/main.ts and replace with:

import { Client, IdentifierKind } from "@xmtp/browser-sdk";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
import { toBytes } from "viem";
 
// The "gm" agent on the dev network
const AGENT_ADDRESS = "0xf9244662f952d6ef83bd0719ddb5a27fbb2fe1bc";
 
const output = document.getElementById("output")!;
function log(msg: string) {
  output.textContent += msg + "\n";
}
 
async function main() {
  log("Creating ephemeral wallet...");
 
  // Generate a throwaway wallet — no MetaMask needed
  const key = generatePrivateKey();
  const account = privateKeyToAccount(key);
 
  // Create a signer for XMTP
  const signer = {
    type: "EOA" as const,
    getIdentifier: () => ({
      identifier: account.address.toLowerCase(),
      identifierKind: IdentifierKind.Ethereum,
    }),
    signMessage: async (message: string) => {
      const signature = await account.signMessage({ message });
      return toBytes(signature);
    },
  };
 
  log("Connecting to XMTP dev network...");
 
  // Create client with in-memory database (no OPFS needed)
  const client = await Client.create(signer, {
    env: "dev",
    dbPath: null,
  });
 
  log(`Connected as ${account.address}`);
  log(`Creating conversation with gm agent...`);
 
  // Create a DM with the gm agent
  const dm = await client.conversations.createDmWithIdentifier({
    identifier: AGENT_ADDRESS,
    identifierKind: IdentifierKind.Ethereum,
  });
 
  // Start streaming messages before sending
  const stream = await dm.stream();
 
  // Send a message
  await dm.sendText("gm");
  log(`You: gm`);
  log(`Waiting for reply...`);
 
  // Listen for the agent's reply
  for await (const message of stream) {
    if (message?.senderInboxId !== client.inboxId) {
      log(`Agent: ${message?.content}`);
      break;
    }
  }
 
  log(`\nDone! You just sent and received an XMTP message.`);
}
 
main().catch((e) => log(`Error: ${e.message}`));

Update index.html

Replace the contents of the <body> tag in index.html:

<body>
  <pre id="output"></pre>
  <script type="module" src="/src/main.ts"></script>
</body>

Run it

npm run dev

Open the URL shown in your terminal (usually http://localhost:5173). You should see:

Creating ephemeral wallet...
Connecting to XMTP dev network...
Connected as 0x...
Creating conversation with gm agent...
You: gm
Waiting for reply...
Agent: gm
 
Done! You just sent and received an XMTP message.

Node SDK

Coming soon.

React Native SDK

Coming soon.

Android SDK

Coming soon.

iOS SDK

Coming soon.