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="key_...")
invoice = ln.invoices.create(amount=1000, memo="Coffee")
ln.payments.create(target="alice@ln.bot", amount=500)
ln.bot also ships a TypeScript SDK, Go SDK, Rust SDK, CLI, and MCP server.
from lnbot import LnBot
ln = LnBot()
wallet = ln.wallets.create(name="my-agent")
print(wallet.primary_key) # your API key
print(wallet.address) # your Lightning address
print(wallet.recovery_passphrase) # back this up!
ln = LnBot(api_key=wallet.primary_key)
invoice = ln.invoices.create(amount=1000, memo="Payment for task #42")
print(invoice.bolt11)
for event in ln.invoices.watch(invoice.number):
if event.event == "settled":
print("Paid!")ln.payments.create(target="alice@ln.bot", amount=500)
ln.payments.create(target="lnbc10u1p...")
wallet = ln.wallets.current()
print(f"{wallet.available} sats available")
Every method has an async equivalent via AsyncLnBot:
from lnbot import AsyncLnBot
async with AsyncLnBot(api_key="key_...") as ln:
wallet = await ln.wallets.current()
invoice = await ln.invoices.create(amount=1000)
async for event in ln.invoices.watch(invoice.number):
if event.event == "settled":
print("Paid!")
from lnbot import LnBot, BadRequestError, UnauthorizedError, NotFoundError, ConflictError, LnBotError
try:
ln.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)from lnbot import LnBot
ln = LnBot(
api_key="key_...", # 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.
Monetize APIs with Lightning-native authentication:
# Create a challenge (server side)
challenge = ln.l402.create_challenge(amount=100, description="API access", expiry_seconds=3600)
# Pay the challenge (client side)
result = ln.l402.pay(www_authenticate=challenge.www_authenticate)
# Verify a token (server side, stateless)
v = ln.l402.verify(authorization=result.authorization)
print(v.valid)
| Method |
Description |
ln.wallets.create(name=) |
Create a new wallet (no auth required) |
ln.wallets.current() |
Get current wallet info and balance |
ln.wallets.update(name=) |
Update wallet name |
| Method |
Description |
ln.invoices.create(amount=, memo=, reference=) |
Create a BOLT11 invoice |
ln.invoices.list(limit=, after=) |
List invoices |
ln.invoices.get(number) |
Get invoice by number |
ln.invoices.watch(number, timeout=) |
SSE stream for settlement/expiry |
| Method |
Description |
ln.payments.create(target=, amount=, ...) |
Send sats to a Lightning address or BOLT11 invoice |
ln.payments.list(limit=, after=) |
List payments |
ln.payments.get(number) |
Get payment by number |
| Method |
Description |
ln.addresses.create(address=) |
Create a random or vanity Lightning address |
ln.addresses.list() |
List all addresses |
ln.addresses.delete(address) |
Delete an address |
ln.addresses.transfer(address, target_wallet_key=) |
Transfer address to another wallet |
| Method |
Description |
ln.transactions.list(limit=, after=) |
List credit and debit transactions |
| Method |
Description |
ln.webhooks.create(url=) |
Register a webhook endpoint (max 10) |
ln.webhooks.list() |
List all webhooks |
ln.webhooks.delete(webhook_id) |
Delete a webhook |
| Method |
Description |
ln.keys.rotate(slot) |
Rotate a key (0 = primary, 1 = secondary) |
| Method |
Description |
ln.l402.create_challenge(amount=, ...) |
Create an L402 challenge (invoice + macaroon) |
ln.l402.verify(authorization=) |
Verify an L402 token (stateless) |
ln.l402.pay(www_authenticate=, ...) |
Pay an L402 challenge, get Authorization header |
| Method |
Description |
ln.backup.recovery() |
Generate 12-word BIP-39 recovery passphrase |
ln.backup.passkey_begin() |
Start passkey backup (WebAuthn) |
ln.backup.passkey_complete(session_id=, attestation=) |
Complete passkey backup |
ln.restore.recovery(passphrase=) |
Restore wallet with recovery passphrase |
ln.restore.passkey_begin() |
Start passkey restore (WebAuthn) |
ln.restore.passkey_complete(session_id=, assertion=) |
Complete passkey restore |
- Python 3.10+
- Get your API key at ln.bot
MIT
