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.

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.