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 [email protected]
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