Create an XMTP client

Create an XMTP client that can use the signing capabilities provided by the signer. This signer links the client to the appropriate EOA or SCW.

🎥 walkthrough: Create a client

This video provides a walkthrough of creating a client, covering the key ideas discussed in this doc. After watching, feel free to continue reading for more details.

Create a client

Browser

import { Client, type Signer } from "@xmtp/browser-sdk";
 
// create a signer
const signer: Signer = { /* ... */ };
 
/**
 * The database encryption key is optional but strongly recommended for
 * secure local storage of the database.
 *
 * This value must be consistent when creating a client with an existing
 * database.
 */
const dbEncryptionKey = window.crypto.getRandomValues(new Uint8Array(32));
 
const client = await Client.create(
  signer,
  // client options
  {
    dbEncryptionKey,
  },
);

When an app first calls Client.create(), a client creates a local database to manage messaging between the app and the network. In subsequent calls, it loads the existing database. The database is encrypted using the key provided when creating the client.

To learn more about database operations, see the XMTP MLS protocol spec.

Configure an XMTP client

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

Browser

import type { ContentCodec } from "@xmtp/content-type-primitives";
 
type ClientOptions = {
  /**
   * Specify which XMTP environment to connect to. (default: `dev`)
   */
  env?: "local" | "dev" | "production";
  /**
   * apiUrl can be used to override the `env` flag and connect to a
   * specific endpoint
   */
  apiUrl?: string;
  /**
   * historySyncUrl can be used to override the `env` flag and connect to a
   * specific endpoint for syncing history
   */
  historySyncUrl?: string;
  /**
   * Allow configuring codecs for additional content types
   */
  codecs?: ContentCodec[];
  /**
   * Path to the local DB
   */
  dbPath?: string;
  /**
   * Encryption key for the local DB
   */
  dbEncryptionKey?: Uint8Array;
  /**
   * Enable structured JSON logging
   */
  structuredLogging?: boolean;
  /**
   * Enable performance metrics
   */
  performanceLogging?: boolean;
  /**
   * Logging level
   */
  loggingLevel?: "off" | "error" | "warn" | "info" | "debug" | "trace";
  /**
   * Disable automatic registration when creating a client
   */
  disableAutoRegister?: boolean;
};

XMTP network environments

XMTP provides developer and production network environments. These networks are completely separate and not interchangeable.

For example, an XMTP identity on the developer network is completely distinct from the XMTP identity on the production network, as are the messages associated with these identities. In addition, XMTP identities and messages created on the developer network can't be accessed from or moved to the production network, and vice versa.

The production network is configured to store messages indefinitely. XMTP may occasionally delete messages and identities from the developer network, and will provide advance notice in the XMTP Community Forums.

You can also use a local network to have a client communicate with an XMTP node you are running locally.

During development, it's highly recommended to use a local network environment for speed and reliability.

Build an existing client

Build, or resume, an existing client that's logged in and has an existing local database.

Browser

import { Client, type Identifier } from "@xmtp/browser-sdk";
 
const identifier: Identifier = {
  identifier: "0x1234567890abcdef1234567890abcdef12345678",
  identifierKind: "Ethereum",
};
const client = await Client.build(identifier, options);

Log out a client

When you log a user out of your app, you can give them the option to delete their local database.

Browser

/**
 * The Browser SDK client does not currently support deleting the local database.
 */
 
// this method only terminates the client's associated web worker
client.close();