lnbot 1.0.0

Official Python SDK for LnBot — Bitcoin for AI Agents. Send and receive sats over Lightning with a few lines of code.

ln.bot

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

from lnbot import LnBot

ln = LnBot(api_key="uk_...")
w = ln.wallet("wal_...")

invoice = w.invoices.create(amount=1000, memo="Coffee")

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

---

Install

pip install lnbot

---

Quick start

Register an account

from lnbot import LnBot

ln = LnBot()
account = ln.register()
print(account.primary_key)
print(account.recovery_passphrase)

Create a wallet

ln = LnBot(api_key=account.primary_key)
wallet = ln.wallets.create()
print(wallet.wallet_id)

Receive sats

w = ln.wallet(wallet.wallet_id)

invoice = w.invoices.create(amount=1000, memo="Payment for task #42")
print(invoice.bolt11)

Wait for payment (SSE)

for event in w.invoices.watch(invoice.number):
    if event.event == "settled":
        print("Paid!")
        break

Send sats

w.payments.create(target="[e-mail]", amount=500)

Check balance

info = w.get()
print(f"{info.available} sats available")

---

Wallet-scoped API

All wallet operations go through a Wallet handle obtained via ln.wallet(wallet_id):

w = ln.wallet("wal_abc123")

# Wallet info
info = w.get()
w.update(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:

ln.register()                       # Register new account
ln.me()                             # Get authenticated identity
ln.wallets.create()                 # Create wallet
ln.wallets.list()                   # List wallets
ln.keys.rotate(0)                   # Rotate account key
ln.invoices.create_for_wallet(...)  # Public invoice by wallet ID
ln.invoices.create_for_address(...) # Public invoice by address

---

Async support

Every method has an async equivalent via AsyncLnBot:

from lnbot import AsyncLnBot

async with AsyncLnBot(api_key="uk_...") as ln:
    w = ln.wallet("wal_...")
    info = await w.get()
    invoice = await w.invoices.create(amount=1000)

    async for event in w.invoices.watch(invoice.number):
        if event.event == "settled":
            print("Paid!")
            break

---

Error handling

from lnbot import LnBot, BadRequestError, UnauthorizedError, NotFoundError, ConflictError, LnBotError

try:
    w.payments.create(target="invalid", amount=100)
except BadRequestError:
    ...  # 400
except UnauthorizedError:
    ...  # 401
except NotFoundError:
    ...  # 404
except ConflictError:
    ...  # 409
except LnBotError as e:
    print(e.status, e.body)

Configuration

from lnbot import LnBot

ln = LnBot(
    api_key="uk_...",                 # or set LNBOT_API_KEY env var
    base_url="https://api.ln.bot",    # optional — this is the default
    timeout=30.0,                     # optional — request timeout in seconds
)

The API key can also be provided via the LNBOT_API_KEY environment variable. If both are provided, the constructor argument takes precedence.

---

L402 paywalls

w = ln.wallet("wal_...")

# Create a challenge (server side)
challenge = w.l402.create_challenge(amount=100, description="API access", expiry_seconds=3600)

# Pay the challenge (client side)
result = w.l402.pay(www_authenticate=challenge.www_authenticate)

# Verify a token (server side, stateless)
v = w.l402.verify(authorization=result.authorization)
print(v.valid)

---

Features

• Zero extra dependencies — only httpx
• Wallet-scoped API — ln.wallet(id) returns a typed scope with all sub-resources
• Sync + async — LnBot and AsyncLnBot with identical APIs
• Typed exceptions — BadRequestError, NotFoundError, ConflictError, UnauthorizedError, ForbiddenError
• SSE support — watch() returns an iterator/async iterator for real-time events
• Dataclass responses — all responses are frozen dataclasses

Requirements

• Python 3.10+
• Get your API key at ln.bot

Links

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

Other SDKs

• TypeScript SDK · npm
• C# SDK · NuGet
• Go SDK · pkg.go.dev
• Rust SDK · crates.io · docs.rs

License

MIT