Creating Clients

Learn how to create and initialize LibXMTP clients using ClientBuilder

The Client is the primary interface for interacting with the XMTP network. This guide shows you how to create and configure clients using the ClientBuilder pattern.

Overview

Each client instance is bound to:

• A single Inbox ID (user identity)
• A single Installation ID (device/app instance)
• A local SQLite database for storage

If you need to operate with a different Inbox ID or Installation ID, create a new client with a new database.

Basic Client Creation

ClientBuilder Configuration

The ClientBuilder supports extensive configuration:

Storage Configuration

use xmtp_db::EncryptedMessageStore;

// With custom database
let db = EncryptedMessageStore::new(
    StorageOption::Persistent(db_path),
    Some(encryption_key),  // Optional encryption
)?;

client_builder.store(db)

See Database Encryption for encryption details.

Device Sync Configuration

use xmtp_mls::builder::DeviceSyncMode;

// Enable device sync (default)
client_builder.device_sync_worker_mode(DeviceSyncMode::Enabled)

// Disable device sync
client_builder.device_sync_worker_mode(DeviceSyncMode::Disabled)

Version Information

use xmtp_mls::utils::VersionInfo;

client_builder.version(VersionInfo {
    version: "1.0.0".to_string(),
})

Offline Mode

// Build client offline (no network calls)
let client = client_builder
    .with_allow_offline(Some(true))
    .build_offline()?;  // Synchronous build

Smart Contract Verifier

use xmtp_id::scw_verifier::HttpSmartContractWalletVerifier;

// Custom verifier for smart contract wallets
let verifier = HttpSmartContractWalletVerifier::new(rpc_urls);
client_builder.with_scw_verifier(verifier)

Client Properties

Rust

// Get inbox and installation IDs
let inbox_id = client.inbox_id();
let installation_id = client.installation_public_key();

// Check registration status
if client.identity().is_ready() {
    println!("Client is registered and ready");
}

// Get database connection
let db = client.db();

Identity States

A client’s identity can be in one of three states:

1. Not Registered - Installation keys generated but not associated with an inbox
2. Registered but Not Ready - Identity update created but not published to network
3. Ready - Fully registered and operational

// Check if identity is ready
if !client.identity().is_ready() {
    // Must call register_identity() first
    return Err(IdentityError::UninitializedIdentity);
}

Operations like creating groups or sending messages will fail if the identity is not ready. Always call register_identity() before performing group operations.

Multi-Device Support

Multiple installations can share the same inbox:

// Create second installation for same inbox
let client2 = Client::builder(IdentityStrategy::CreateIfNotFound(
    same_account_address,
    nonce,
    None,
))
.api_clients(api_client, sync_api_client)
.store(different_db_path)  // Different database!
.default_mls_store()?
.with_remote_verifier()?
.build()
.await?;

// Associate with existing inbox
let signature_request = client2.add_identifier_signature_request();
// ... sign and apply

Best Practices

Error Handling

Common errors when building clients:

use xmtp_mls::builder::ClientBuilderError;

match client_builder.build().await {
    Ok(client) => { /* success */ }
    Err(ClientBuilderError::MissingParameter { parameter }) => {
        eprintln!("Missing required parameter: {}", parameter);
    }
    Err(ClientBuilderError::StorageError(e)) => {
        eprintln!("Database error: {}", e);
    }
    Err(ClientBuilderError::Identity(e)) => {
        eprintln!("Identity error: {}", e);
    }
    Err(e) => {
        eprintln!("Build failed: {}", e);
    }
}

Next Steps

Managing Groups

Create and manage group conversations

Database Encryption

Secure your local database with SQLCipher