Skip to main content

​
Overview

The xmtp_api crate provides the core trait definitions and client wrapper for XMTP API implementations. It defines the XmtpApi trait that combines MLS (Messaging Layer Security) client functionality with identity management.

​
Source Location

crates/xmtp_api/src/lib.rs

​
XmtpApi Trait

The XmtpApi trait is the primary interface for XMTP API clients. It’s a composite trait that requires implementations to support both:
  • XmtpMlsClient - MLS delivery service operations
  • XmtpIdentityClient - Identity service operations
pub trait XmtpApi
where
    Self: XmtpMlsClient + XmtpIdentityClient,
{
}

​
XmtpMlsClient

Represents the backend API required for an MLS Delivery Service to be compatible with XMTP.

​
Methods

Key Package Management
  • upload_key_package(request: UploadKeyPackageRequest) -> Result<(), Self::Error>
  • fetch_key_packages(request: FetchKeyPackagesRequest) -> Result<FetchKeyPackagesResponse, Self::Error>
Message Operations
  • send_group_messages(request: SendGroupMessagesRequest) -> Result<(), Self::Error>
  • send_welcome_messages(request: SendWelcomeMessagesRequest) -> Result<(), Self::Error>
  • query_group_messages(group_id: GroupId) -> Result<Vec<GroupMessage>, Self::Error>
  • query_latest_group_message(group_id: GroupId) -> Result<Option<GroupMessage>, Self::Error>
  • query_welcome_messages(installation_key: InstallationId) -> Result<Vec<WelcomeMessage>, Self::Error>
Commit Log Operations
  • publish_commit_log(request: BatchPublishCommitLogRequest) -> Result<(), Self::Error>
  • query_commit_log(request: BatchQueryCommitLogRequest) -> Result<BatchQueryCommitLogResponse, Self::Error>
  • get_newest_group_message(request: GetNewestGroupMessageRequest) -> Result<Vec<Option<GroupMessageMetadata>>, Self::Error>

​
XmtpIdentityClient

Represents the backend API required for the XMTP Identity Service as described in XIP-46 Multi-Wallet Identity.

​
Methods

  • publish_identity_update(request: PublishIdentityUpdateRequest) -> Result<PublishIdentityUpdateResponse, Self::Error>
  • get_identity_updates_v2(request: GetIdentityUpdatesV2Request) -> Result<GetIdentityUpdatesV2Response, Self::Error>
  • get_inbox_ids(request: GetInboxIdsRequest) -> Result<GetInboxIdsResponse, Self::Error>
  • verify_smart_contract_wallet_signatures(request: VerifySmartContractWalletSignaturesRequest) -> Result<VerifySmartContractWalletSignaturesResponse, Self::Error>

​
XmtpMlsStreams

Provides streaming support for MLS operations.

​
Methods

  • subscribe_group_messages(group_ids: &[&GroupId]) -> Result<Self::GroupMessageStream, Self::Error>
  • subscribe_group_messages_with_cursors(groups_with_cursors: &TopicCursor) -> Result<Self::GroupMessageStream, Self::Error>
  • subscribe_welcome_messages(installations: &[&InstallationId]) -> Result<Self::WelcomeMessageStream, Self::Error>

​
ApiClientWrapper

A generic wrapper that provides retry logic and context to any API client implementation. 
pub struct ApiClientWrapper<ApiClient> {
    pub api_client: ApiClient,
    pub(crate) retry_strategy: Arc<Retry<ExponentialBackoff>>,
    pub(crate) inbox_id: Option<String>,
}

​
Methods

Constructor 
pub fn new(api_client: ApiClient, retry_strategy: Retry<ExponentialBackoff>) -> Self
Map Function 
pub fn map<F, NewApiClient>(self, f: F) -> ApiClientWrapper<NewApiClient>
where
    F: FnOnce(ApiClient) -> NewApiClient
Transforms the wrapped API client using a mapping function. Attach Inbox ID 
pub fn attach_inbox_id(&mut self, inbox_id: Option<String>)
Attaches an inbox_id context to tracing logs for debugging purposes.

​
Error Types

​
ApiError

pub enum ApiError {
    Api(Box<dyn RetryableError>),
    MismatchedKeyPackages {
        key_packages: usize,
        installation_keys: usize,
    },
    ProtoConversion(xmtp_proto::ConversionError),
}
The ApiError type erases the specific API implementation error (HTTP or gRPC) and implements RetryableError to support automatic retry logic.

​
Retry Strategies

The strategies module provides pre-configured retry strategies: 
pub fn exponential_cooldown() -> Retry<ExponentialBackoff>
Returns a retry strategy with exponential backoff for handling transient failures.

​
Type Aliases

pub type Result<T> = std::result::Result<T, ApiError>;
pub type BoxedXmtpApi<Error> = Box<dyn BoxableXmtpApi<Error>>;
pub type ArcedXmtpApi<Error> = Arc<dyn BoxableXmtpApi<Error>>;
  • xmtp_api_grpc - gRPC implementation of the XmtpApi trait
  • xmtp_api_d14n - Decentralized API implementation
  • xmtp_proto - Protocol buffer definitions

Build docs developers (and LLMs) love

Get started for freeTalk to us