Skip to content

Rust Quickstart

The Lexe Rust SDK is our most advanced SDK, ideal for building secure, reliable, high-performance applications.

Install

cargo add lexe

Configure credentials

The Rust SDK authenticates with one of the following:

  1. Client credentials: scoped and revocable, well-suited for controlling your own existing wallet, or for building applications with limited access to other people's wallets, including charging for services via pull payments.
  2. Root seed: the master secret of a Lexe wallet, used to create new wallets.

See the Authentication page for more details.

Control an existing wallet (client credentials)

Get client credentials from the Lexe mobile app

  1. Download the Lexe mobile app (iOS, Android)
  2. Menu > "Client credentials" > "Create credentials"
  3. Copy the credentials string

If you're running a service that helps manage your users' wallets, you can collect your users' client credentials using a web form or similar.

Set LEXE_CLIENT_CREDENTIALS in your environment

export LEXE_CLIENT_CREDENTIALS="eyJsZXhlX2F1dGhfdG9rZ...TA0In0"

A .env file loaded with dotenvy is also common.

Example: Instantiating a LexeWallet from client credentials.

use lexe::{
    config::WalletEnvConfig,
    types::auth::{ClientCredentials, CredentialsRef},
    wallet::LexeWallet,
};

let env_config = WalletEnvConfig::mainnet();

let cc_string = std::env::var("LEXE_CLIENT_CREDENTIALS")?;
let cc = ClientCredentials::from_string(&cc_string)?;
let credentials = CredentialsRef::from(&cc);

let wallet = LexeWallet::load_or_fresh(env_config, credentials, None)?;

// Ensure the node is running the latest enclave version
wallet.provision(credentials).await?;

Create a new wallet (root seed)

Generate a fresh RootSeed, sign up with Lexe, and provision a Lightning node. The seed is persisted to ~/.lexe/seedphrase.txt and auto-loaded on subsequent runs.

Example: Instantiating a LexeWallet from a root seed.

use lexe::{
    config::WalletEnvConfig,
    types::auth::{CredentialsRef, RootSeed},
    wallet::LexeWallet,
};

// Create a wallet config for mainnet (or testnet3() for testing)
let env_config = WalletEnvConfig::mainnet();

// Load root seed from ~/.lexe, or create a fresh one
let is_new_seed;
let root_seed = match RootSeed::read(&env_config.wallet_env)? {
    Some(seed) => {
        is_new_seed = false;
        seed
    }
    None => {
        is_new_seed = true;
        RootSeed::generate()
    }
};
let credentials = CredentialsRef::from(&root_seed);

// Load or create wallet (data stored in ~/.lexe)
let wallet =
    LexeWallet::load_or_fresh(env_config.clone(), credentials, None)?;

if is_new_seed {
    // Signup with Lexe and provision the node (idempotent)
    let partner_pk = None;
    wallet.signup(&root_seed, partner_pk).await?;
    // Persist the seed at ~/.lexe/seedphrase.txt for subsequent runs.
    root_seed.write(&env_config.wallet_env)?;
} else {
    // Ensure provisioned to latest trusted release
    wallet.provision(credentials).await?;
}

Using the LexeWallet

Continuing from either example above, you can use the wallet instance to create invoices, send payments, and more:

Example: Common LexeWallet operations.

use std::str::FromStr;

use lexe::types::{
    bitcoin::{Amount, Invoice},
    command::{CreateInvoiceRequest, PayInvoiceRequest},
};

// Get node info
let node_info = wallet.node_info().await?;
println!("Balance: {} sats", node_info.balance);

// Create a Lightning invoice
let invoice_req = CreateInvoiceRequest {
    expiration_secs: Some(3600),
    amount: Some(Amount::from_sats_u32(5_000)),
    description: Some("Initial deposit".to_string()),
    ..Default::default()
};
let invoice_resp = wallet.create_invoice(invoice_req).await?;

// Pay an invoice
let invoice = Invoice::from_str("lnbc1pjlue...")?;
let pay_req = PayInvoiceRequest {
    invoice,
    fallback_amount: None,
    personal_note: Some("Open-source donation".to_string()),
};
let pay_resp = wallet.pay_invoice(pay_req).await?;

// Sync payments from the node
let summary = wallet.sync_payments().await?;
println!("Synced {} new payments", summary.num_new);

Runnable example

See the rust-example for a complete, runnable example showing how to:

  • Set up a Tokio runtime, dotenvy, and the Lexe tracing logger
  • Load credentials from LEXE_CLIENT_CREDENTIALS, LEXE_ROOT_SEED, or a seedphrase file at ~/.lexe
  • Initialize a LexeWallet and provision the node to the latest version
  • Query node info, sync payments, and create Lightning invoices