Python SDK

Install

pip install bolthub

Minimal dependencies. Only one runtime dependency (httpx). No other third-party packages in your supply chain.

Quick start

from bolthub import L402Client, LndWallet

wallet = LndWallet(
    host="https://your-lnd-node:8080",
    macaroon="0201036c6e...",
)

client = L402Client(wallet, budget_sats=10_000)

resp = client.get(
    "https://acme.gw.bolthub.ai/v1/market-data",
    params={"symbol": "BTC"},
)
data = resp.json()

Wallet adapters

LND

from bolthub import LndWallet

wallet = LndWallet(
    host="https://your-lnd-node:8080",
    macaroon="admin-macaroon-hex",
    timeout_seconds=30,
)

NWC (Nostr Wallet Connect)

NwcWallet takes a callable that receives a BOLT11 invoice and must return the preimage as a hex string. Plug in any NWC library you already use to handle the payment:

from bolthub import NwcWallet

# pay_fn receives the BOLT11 invoice string and returns the preimage hex
def pay(bolt11: str) -> str:
    preimage = my_nwc_client.pay_invoice(bolt11)
    return preimage

wallet = NwcWallet(pay_fn=pay)

LNbits

from bolthub import LnbitsWallet

wallet = LnbitsWallet(
    url="https://lnbits.example.com",
    admin_key="your-admin-key",
)

Phoenixd

Use PhoenixdWallet when your agent pays via an existing Phoenixd HTTP API. Prefer LndWallet with the bolthub Node Launcher or your own LND for new setups.

from bolthub import PhoenixdWallet

wallet = PhoenixdWallet(
    url="http://localhost:9740",
    password="your-phoenixd-password",
    timeout_seconds=35,
)

Custom wallet

Implement the WalletAdapter protocol:

class MyWallet:
    def pay_invoice(self, bolt11: str) -> str:
        preimage = my_payment_logic(bolt11)
        return preimage

Budget guards

client = L402Client(
    wallet,
    max_per_request_sats=100,  # reject invoices over 100 sats
    budget_sats=10_000,         # total spending cap
)

print(client.total_spent)       # sats spent so far
print(client.remaining_budget)  # sats remaining

Python SDK

On this page