lnbot 0.5.0

# ln.bot

[![crates.io](https://img.shields.io/crates/v/lnbot.svg)](https://crates.io/crates/lnbot)
[![docs.rs](https://docs.rs/lnbot/badge.svg)](https://docs.rs/lnbot)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

**The official Rust SDK for [ln.bot](https://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.

```rust
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](https://www.npmjs.com/package/@lnbot/sdk)**, **[Python SDK](https://pypi.org/project/lnbot/)**, **[Go SDK](https://pkg.go.dev/github.com/lnbotdev/go-sdk)**, **[CLI](https://ln.bot/docs)**, and **[MCP server](https://ln.bot/docs)**.

---

## Install

Add to your `Cargo.toml`:

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

---

## Quick start

### Create a wallet

```rust
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

```rust
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)

```rust
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

```rust
use lnbot::CreatePaymentRequest;

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

### Check balance

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

---

## L402 paywalls

```rust
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

```rust
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

```rust
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](https://ln.bot)

## Links

- [ln.bot](https://ln.bot) — website
- [Documentation](https://ln.bot/docs)
- [GitHub](https://github.com/lnbotdev)
- [docs.rs](https://docs.rs/lnbot)
- [crates.io](https://crates.io/crates/lnbot)

## Other SDKs

- [TypeScript SDK](https://github.com/lnbotdev/typescript-sdk) · [npm](https://www.npmjs.com/package/@lnbot/sdk)
- [Python SDK](https://github.com/lnbotdev/python-sdk) · [pypi](https://pypi.org/project/lnbot/)
- [Go SDK](https://github.com/lnbotdev/go-sdk) · [pkg.go.dev](https://pkg.go.dev/github.com/lnbotdev/go-sdk)

## License

MIT