ln.bot-csharp

The official .NET 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.

using LnBot;
using LnBot.Models;

using var client = new LnBotClient("uk_...");
var w = client.Wallet("wal_...");

var invoice = await w.Invoices.CreateAsync(new CreateInvoiceRequest
{
    Amount = 1000,
    Memo = "Coffee",
});

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

---

Install

dotnet add package LnBot

---

Quick start

Register an account

using LnBot;

using var client = new LnBotClient();
var account = await client.RegisterAsync();
Console.WriteLine(account.PrimaryKey);
Console.WriteLine(account.RecoveryPassphrase);

Create a wallet

using var client = new LnBotClient(account.PrimaryKey);
var wallet = await client.Wallets.CreateAsync();
Console.WriteLine(wallet.WalletId);

Receive sats

var w = client.Wallet(wallet.WalletId);

var invoice = await w.Invoices.CreateAsync(new CreateInvoiceRequest
{
    Amount = 1000,
    Memo = "Payment for task #42",
});
Console.WriteLine(invoice.Bolt11);

Wait for payment (SSE)

await foreach (var evt in w.Invoices.WatchAsync(invoice.Number))
{
    if (evt.Event == "settled")
    {
        Console.WriteLine("Paid!");
        break;
    }
}

Send sats

var payment = await w.Payments.CreateAsync(new CreatePaymentRequest
{
    Target = "alice@ln.bot",
    Amount = 500,
});

Check balance

var info = await w.GetAsync();
Console.WriteLine($"{info.Available} sats available");

---

Wallet-scoped API

All wallet operations go through a WalletScope obtained via client.Wallet(walletId):

var w = client.Wallet("wal_abc123");

// Wallet info
var info = await w.GetAsync();
await w.UpdateAsync(new UpdateWalletRequest { Name = "production" });

// Sub-resources
w.Key          // Wallet key management (wk_ keys)
w.Invoices     // Create, list, get, watch invoices
w.Payments     // Send, list, get, watch, resolve payments
w.Addresses    // Create, list, delete, transfer Lightning addresses
w.Transactions // List transaction history
w.Webhooks     // Create, list, delete webhook endpoints
w.Events       // Real-time SSE event stream
w.L402         // L402 paywall authentication

Account-level operations stay on the client:

await client.RegisterAsync();          // Register new account
await client.MeAsync();               // Get authenticated identity
await client.Wallets.CreateAsync();    // Create wallet
await client.Wallets.ListAsync();      // List wallets
await client.Keys.RotateAsync(0);     // Rotate account key

---

Error handling

using LnBot.Exceptions;

try
{
    var info = await w.GetAsync();
}
catch (NotFoundException ex)
{
    Console.WriteLine($"Not found: {ex.Message}");
}
catch (BadRequestException ex)
{
    Console.WriteLine($"Bad request: {ex.Message}");
}
catch (ConflictException ex)
{
    Console.WriteLine($"Conflict: {ex.Message}");
}
catch (LnBotException ex)
{
    Console.WriteLine($"API error {ex.StatusCode}: {ex.Message}");
}

Configuration

using var client = new LnBotClient("uk_...", new LnBotClientOptions
{
    BaseUrl = "https://api.ln.bot",
    Timeout = TimeSpan.FromSeconds(30),
});

Or bring your own HttpClient:

var httpClient = new HttpClient();
using var client = new LnBotClient("uk_...", new LnBotClientOptions
{
    HttpClient = httpClient,
});

---

L402 paywalls

var w = client.Wallet("wal_...");

// Create a challenge (server side)
var challenge = await w.L402.CreateChallengeAsync(new CreateL402ChallengeRequest
{
    Amount = 100,
    Description = "API access",
    ExpirySeconds = 3600,
});

// Pay the challenge (client side)
var result = await w.L402.PayAsync(new PayL402Request
{
    WwwAuthenticate = challenge.WwwAuthenticate,
});

// Verify a token (server side, stateless)
var v = await w.L402.VerifyAsync(new VerifyL402Request
{
    Authorization = result.Authorization!,
});

---

Features

• Zero dependencies — System.Net.Http + System.Text.Json only
• Wallet-scoped API — client.Wallet(id) returns a typed scope with all sub-resources
• Async-first — every method returns Task<T> with CancellationToken support
• Typed exceptions — BadRequestException, NotFoundException, ConflictException, UnauthorizedException, ForbiddenException
• SSE support — WatchAsync returns IAsyncEnumerable<T> for real-time events
• Nullable reference types — fully annotated

Requirements

• .NET 8.0+
• Get your API key at ln.bot

Links

• ln.bot — website
• Documentation
• GitHub
• NuGet

Other SDKs

• TypeScript SDK · npm
• Python SDK · pypi
• Go SDK · pkg.go.dev
• Rust SDK · crates.io · docs.rs

License

MIT