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".

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.