Developer quickstart for XMTP

This document provides a developer quickstart, followed by more detailed guidance for getting started building with XMTP.

Need to send a test message? Message the XMTP message bot at gm.xmtp.eth (0x937C0d4a6294cdfa575de17382c7076b579DC176) to get an immediate automated reply.

Install an SDK

To start with XMTP, install an XMTP client SDK:

yarn install @xmtp/xmtp-js

Quickstart

Here's a quick overview of the core concepts and lines of code needed to build with XMTP.

import { Client } from "@xmtp/xmtp-js";
import { Wallet } from "ethers";
 
// You'll want to replace this with a wallet from your application
const signer = Wallet.createRandom();
// Create the client with your wallet. This will connect to the XMTP development network by default
const xmtp = await Client.create(signer, { env: "dev" });
// Start a conversation with XMTP
const conversation = await xmtp.conversations.newConversation(
  "0x3F11b27F323b62B159D2642964fa27C46C841897",
);
// Load all messages in the conversation
const messages = await conversation.messages();
// Send a message
await conversation.send("gm");
// Listen for new messages in the conversation
for await (const message of await conversation.streamMessages()) {
  console.log(`[${message.senderAddress}]: ${message.content}`);
}

Get started

This section provides more detailed guidance for getting started with XMTP. The examples use the XMTP JavaScript SDK (xmtp-js).

You might also be interested in exploring this Replit: JavaScript live code example

Install required packages

yarn install @xmtp/xmtp-js ethers@5.7.0

Import libraries

Import the xmtp-js client SDK and ethers library into your project:

const { Wallet } = require("ethers");
const { Client } = require("@xmtp/xmtp-js");

Initialize a wallet

When we initialize a wallet, we create an instance of a wallet that the XMTP client will use to sign messages and transactions. In this code sample, a random wallet is generated for demo purposes. In your real code, you should use the user's actual wallet instead of generating a random one.

// You'll want to replace this with a wallet from your application
const wallet = Wallet.createRandom();
console.log("Wallet address: " + wallet.address);
//eg. Wallet address 0xd8dA6BF26964aF9D7eEd9e03E53415D37

Create a client

To create a client, you need to pass in a wallet that implements the Signer interface. This is a requirement because the XMTP client uses the wallet to sign messages and verify the sender's identity. When you create a client, you can set client parameters, including which network environment (env) the client should connect to.

const xmtp = await Client.create(signer, { env: "dev" });
console.log("Client created", xmtp.address);
//eg. Client created 0xd8dA6BF26964aF9D7eEd9e03E53415D37

Check if the recipient address is XMTP enabled

For a user to send a message to a recipient, the recipient address must have XMTP enabled. This means the recipient must have already started an XMTP client at least once and consequently advertised their key bundle on the network.

You can check if a recipient address is XMTP enabled by calling client.canMessage and including the recipient address.

//Message this XMTP message bot to get an immediate automated reply:
//gm.xmtp.eth (0x937C0d4a6294cdfa575de17382c7076b579DC176) env:production
const WALLET_TO = "0x20B572bE48527a770479744AeC6fE5644F97678B";
const isOnProdNetwork = await xmtp.canMessage(WALLET_TO);
console.log("Can message: " + isOnProdNetwork);
//eg. Can message: true

Start a conversation

You can create a conversation between the sender and any XMTP-enabled address. Currently, XMTP supports Ethereum Virtual Machine (EVM) wallet addresses only. With XMTP, a conversation is the context in which users send messages.

const conversation = await xmtp.conversations.newConversation(WALLET_TO);
console.log("Conversation created", conversation);
//eg. Conversation created: {Object}

Send a message

const message = await conversation.send("gm");
console.log("Message sent", message);
//eg. Message sent: {Object}

Stream messages

To receive new messages in real-time for all of a user's conversations, use streamAllMessages. This method streams all new messages from any sender across all conversations the user is involved in.

for await (const message of await xmtp.conversations.streamAllMessages()) {
  console.log(`New message from ${message.senderAddress}: ${message.content}`);
}
//eg. New message from 0xd8dA6BF26964aF9D7eEd9e03E53415D37: gm