Create a client

Create an XMTP client that connects your agent to the XMTP network. The client handles authentication, encryption, and message delivery. Your agent's logic (brain) is separate. The client just gives it the ability to send and receive messages.

A signer links the client to an EOA or SCW wallet, which serves as your agent's identity on the network.

Create an EOA signer

Node

import { Agent, createSigner, createUser } from '@xmtp/agent-sdk';
 
// Replace with your own wallet key and encryption key
const walletKey = '0xprivateKey';
const db_encryptionKey = '0xencryptionKey';
 
// Option 1: Create a local user + signer
const user = createUser(walletKey);
const dbEncryptionKey = Buffer.from(db_encryptionKey).toString('hex');
 
const agent = await Agent.create(signer, {
  env: 'dev', // or 'production'
  dbEncryptionKey, // save it for later
});

Environment variables

The XMTP Agent SDK allows you to use environment variables (process.env) for easier configuration without modifying code.

Available variables:

Variable	Purpose	Example
`XMTP_WALLET_KEY`	Private key for wallet	`XMTP_WALLET_KEY=0x1234...abcd`
`XMTP_ENV`	XMTP network environment (`local`, `dev`, or `production`)	`XMTP_ENV=dev` or `XMTP_ENV=production`
`XMTP_DB_ENCRYPTION_KEY`	Database encryption key for the local database (32 bytes, hex)	`XMTP_DB_ENCRYPTION_KEY=0xabcd...1234`

Using environment variables, you can connect your agent to XMTP in just a few lines of code:

Generate random keys

Node

import { generatePrivateKey } from 'viem';
import { getRandomValues } from 'node:crypto';
 
const walletKey = generatePrivateKey();
const encryptionKeyHex = getRandomValues(new Uint8Array(32));
 
console.log(`Wallet key: ${walletKey}`);
console.log(`Encryption key: ${encryptionKeyHex}`);

Use this script to generate random XMTP keys:

yarn gen:keys

Running the command will append keys to your existing .env file.

Use environment variables

Node

// Load variables from .env file
process.loadEnvFile('.env');
 
// Connect to XMTP using environment variables
const agent = await Agent.createFromEnv();

Configuration options

You can configure an XMTP client with these options passed to Agent.create:

Node

/**
 * Specify which XMTP environment to connect to. (default: `dev`)
 */
env?: 'local' | 'dev' | 'production';
/**
 * Add a client app version identifier that's included with API requests.
 * Production apps are strongly encouraged to set this value.
 *
 * You can use the following format: `appVersion: 'AGENT_NAME/AGENT_VERSION'`.
 * For example, `appVersion: 'alix/2.x'`
 *
 * If you have an agent and an app, it's best to distinguish them from each other by
 * adding `-agent` and `-app` to the names. For example:
 * - Agent: `appVersion: 'alix-agent/2.x'`
 * - App: `appVersion: 'alix-app/3.x'`
 *
 * Setting this value provides telemetry that shows which agents are using the
 * XMTP client SDK. This information can help XMTP core developers provide you with agent
 * support, especially around communicating important SDK updates, including
 * deprecations and required upgrades.
 */
appVersion?: string;
/**
 * apiUrl can be used to override the `env` flag and connect to a
 * specific endpoint
 */
apiUrl?: string;
/**
 * Path to the local DB
 *
 * There are 4 value types that can be used to specify the database path:
 *
 * - `undefined` (or excluded from the client options)
 *    The database will be created in the current working directory and is based on
 *    the XMTP environment and client inbox ID.
 *    Example: `xmtp-dev-<inbox-id>.db3`
 *
 * - `null`
 *    No database will be created and all data will be lost once the client disconnects.
 *
 * - `string`
 *    The given path will be used to create the database.
 *    Example: `./my-db.db3`
 *
 * - `function`
 *    A callback function that receives the inbox ID and returns a string path.
 *    Example: `(inboxId) => string`
 */
dbPath?: string | null | ((inboxId: string) => string);
/**
 * Encryption key for the local DB
 */
dbEncryptionKey?: Uint8Array;
/**
 * Allow configuring codecs for additional content types
 */
codecs?: ContentCodec[];
/**
 * Enable structured JSON logging
 */
structuredLogging?: boolean;
/**
 * Logging level
 */
loggingLevel?: LogLevel;

Create a smart contract wallet (SCW) signer

When working with smart contract wallets, you can connect your agent to XMTP using the wallet's seed or private key:

Node

import { Agent, createSigner, createUser } from '@xmtp/agent-sdk';
 
const walletData = await initializeWallet('wallet.json');
/* Create the signer using viem and parse the encryption key for the local db */
const user = createUser(walletData.seed as `0x${string}`);
const signer = createSigner(user);
 
// Connect to XMTP with SCW signer
const agent = await Agent.create(signer);
 
/* Add your own business logic here */