ln.bot

The official Rust SDK for ln.bot — Bitcoin for AI Agents.

Give your AI agents, apps, and services access to Bitcoin over the Lightning Network. Create wallets, send and receive sats, and get real-time payment notifications.

use lnbot::{LnBot, CreateInvoiceRequest};

let client = LnBot::new("key_...");
let invoice = client.invoices().create(
    &CreateInvoiceRequest::new(1000).memo("Coffee"),
).await?;

ln.bot also ships a TypeScript SDK, Python SDK, Go SDK, CLI, and MCP server.

---

Install

Add to your Cargo.toml:

[dependencies]
lnbot = "0.1"
tokio = { version = "1", features = ["full"] }

---

Quick start

Create a wallet

use lnbot::{LnBot, CreateWalletRequest};

let client = LnBot::unauthenticated();
let wallet = client.wallets().create(&CreateWalletRequest {
    name: Some("my-agent".into()),
}).await?;

println!("{}", wallet.primary_key);
println!("{}", wallet.address);

Receive sats

use lnbot::{LnBot, CreateInvoiceRequest};

let client = LnBot::new(&wallet.primary_key);
let invoice = client.invoices().create(
    &CreateInvoiceRequest::new(1000).memo("Payment for task #42"),
).await?;
println!("{}", invoice.bolt11);

Wait for payment (SSE)

use futures_util::StreamExt;
use lnbot::InvoiceEventType;

let mut stream = client.invoices().watch(invoice.number, None);
while let Some(event) = stream.next().await {
    let event = event?;
    if event.event == InvoiceEventType::Settled {
        println!("Paid!");
    }
}

Send sats

use lnbot::CreatePaymentRequest;

client.payments().create(
    &CreatePaymentRequest::new("alice@ln.bot").amount(500),
).await?;

Check balance

let wallet = client.wallets().current().await?;
println!("{} sats available", wallet.available);

---

L402 paywalls

use lnbot::{CreateL402ChallengeRequest, PayL402Request, VerifyL402Request};

// Create a challenge (server side)
let challenge = client.l402().create_challenge(&CreateL402ChallengeRequest {
    amount: 100,
    description: Some("API access".into()),
    expiry_seconds: Some(3600),
    caveats: None,
}).await?;

// Pay the challenge (client side)
let result = client.l402().pay(&PayL402Request {
    www_authenticate: challenge.www_authenticate,
    max_fee: None, reference: None, wait: None, timeout: None,
}).await?;

// Verify a token (server side, stateless)
let v = client.l402().verify(&VerifyL402Request {
    authorization: result.authorization.unwrap(),
}).await?;
println!("{}", v.valid);

Error handling

use lnbot::LnBotError;

match client.invoices().get(999).await {
    Ok(invoice) => println!("{:?}", invoice),
    Err(LnBotError::NotFound { body }) => eprintln!("not found: {}", body),
    Err(LnBotError::BadRequest { body }) => eprintln!("bad request: {}", body),
    Err(LnBotError::Conflict { body }) => eprintln!("conflict: {}", body),
    Err(e) => eprintln!("error: {}", e),
}

Configuration

use lnbot::LnBot;

let client = LnBot::new("key_...")
    .with_base_url("https://api.ln.bot");

---

Features

• Async-first — built on reqwest + tokio
• Strongly typed — every request/response is a Rust struct with serde derives
• Typed enums — InvoiceStatus, PaymentStatus, TransactionType are real enums, not strings
• SSE streaming — watch returns a Stream of typed events
• Typed errors — LnBotError enum with BadRequest, NotFound, Conflict variants
• Forward-compatible — #[non_exhaustive] and #[serde(other)] for safe API evolution

Requirements

• Rust 2021 edition
• Get your API key at ln.bot

Links

• ln.bot — website
• Documentation
• GitHub
• docs.rs
• crates.io

Other SDKs

• TypeScript SDK · npm
• Python SDK · pypi
• Go SDK · pkg.go.dev

License

MIT