Table of Contents

• Table of Contents
• Features
• Installation
• Getting Started
  • Step 1: Create your Keystore File
  • Step 2: Write Your Code
• Running Examples
• Examples Index
• Error Handling
• License

Features

• Complete: Supports most APIs for Mixin Network and Mixin Messenger.
• Secure: All API requests are automatically signed with JWT.
• Idiomatic Rust: Designed to be asynchronous from the ground up using tokio.
• Developer Friendly: Provides clear error handling and a simple, function-based API.

Installation

Add the following to your Cargo.toml:

[dependencies]
mixin-sdk-rs = { git = "https://github.com/lixvyang/mixin-sdk-rs" }
tokio = { version = "1", features = ["full"] }

Getting Started

Follow these two simple steps to start using the SDK.

Step 1: Create your Keystore File

It is highly recommended to manage your bot's credentials using a keystore.json file instead of hardcoding them. Create a file named keystore.json with the following structure:

{
  "app_id": "YOUR_USER_ID",
  "session_id": "YOUR_SESSION_ID",
  "session_private_key": "YOUR_PRIVATE_KEY",
  "server_public_key": "YOUR_SERVER_PUBLIC_KEY",
  "spend_private_key": "YOUR_SPEND_PRIVATE_KEY"
}

Security Note: Make sure to add this file to your .gitignore to prevent committing your secrets to version control.

Step 2: Write Your Code

Now you can load the SafeUser from your keystore and make API calls.

use mixin_sdk_rs::safe::SafeUser;
use mixin_sdk_rs::user;
use mixin_sdk_rs::error::Error;

#[tokio::main]
async fn main() -> Result<(), Error> {
    // 1. Set the environment variable to point to your keystore file.
    std::env::set_var("TEST_KEYSTORE_PATH", "/path/to/your/keystore.json");

    // 2. Load the user credentials from the keystore.
    let user = SafeUser::new_from_env()?;

    // 3. Call the API.
    println!("Fetching user profile...");
    let me = user::request_user_me(&user).await?;

    println!("Success! User ID: {}", me.user_id);
    if let Some(name) = me.full_name {
        println!("Full Name: {}", name);
    }

    Ok(())
}

Running Examples

The /examples directory contains various usage examples. You can run any example using cargo run.

For instance, to run the get_me.rs example:

1. Make sure you have created your keystore.json file.
2. Set the environment variable.

   export TEST_KEYSTORE_PATH="/path/to/your/keystore.json"
   

3. Run the example.

   cargo run --example get_me --all-features
   

Examples Index

All examples expect TEST_KEYSTORE_PATH unless noted otherwise.

• get_me: Fetch /safe/me
• register_safe_user: Register Safe user with spend key (requires a fresh user)
• send_message: Send a plain text message (requires RECIPIENT_ID)
• create_group: Create a group conversation (requires PARTICIPANT_IDS, optional GROUP_NAME/GROUP_ANNOUNCEMENT)
• list_outputs: List unspent outputs
• create_address: Create a withdrawal address (requires ASSET_ID, DESTINATION, optional ADDRESS_LABEL/ADDRESS_TAG)
• create_withdrawal: Create a withdrawal (requires ADDRESS_ID, AMOUNT, FEE, optional MEMO/TRACE_ID)

Example commands:

export TEST_KEYSTORE_PATH="/path/to/keystore.json"

cargo run --example get_me --all-features
cargo run --example register_safe_user --all-features

export RECIPIENT_ID="target-user-id"
cargo run --example send_message --all-features

export PARTICIPANT_IDS="user-id-1,user-id-2"
export GROUP_NAME="Rust SDK Group"
export GROUP_ANNOUNCEMENT="Hello"
cargo run --example create_group --all-features

cargo run --example list_outputs --all-features

export ASSET_ID="asset-id"
export DESTINATION="destination"
export ADDRESS_LABEL="Rust SDK"
export ADDRESS_TAG=""
cargo run --example create_address --all-features

export ADDRESS_ID="address-id"
export AMOUNT="1"
export FEE="0.001"
export MEMO="memo"
export TRACE_ID="trace-id"
cargo run --example create_withdrawal --all-features

Error Handling

All API functions return a Result<T, mixin_sdk_rs::error::Error>. You can match on the Error enum to handle different failure scenarios.

// ... inside an async function
if let Err(err) = user::request_user_me(&user).await {
    match err {
        mixin_sdk_rs::error::Error::Api(e) => {
            // Error returned by the Mixin API
            eprintln!("[API Error] Code: {}, Description: {}", e.code, e.description);
            if e.code == 401 {
                eprintln!("=> Unauthorized. Please check your credentials.");
            }
        }
        mixin_sdk_rs::error::Error::Request(e) => {
            // Error from the underlying HTTP client (e.g., network issues)
            eprintln!("[Network Error] {}", e);
        }
        mixin_sdk_rs::error::Error::Json(e) => {
            // Error during JSON serialization/deserialization
            eprintln!("[Serialization Error] {}", e);
        }
        _ => {
            // Other kinds of errors
            eprintln!("[An unexpected error occurred] {}", err);
        }
    }
}

License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.