Lightning Network

bitpilot provides Lightning (L2) support through two main classes:

LightningWallet — channel management, invoice creation, and payment
L402Client — automatic HTTP 402 invoice payment for pay-per-request APIs

Install


pip install bitpilot[lightning]   # LightningWallet + L402Client
pip install bitpilot[l402]        # L402Client only (no gRPC)

LightningWallet

Connect to LND


from bitpilot.lightning import LightningWallet

ln = LightningWallet.from_lnd(
    macaroon_path="~/.lnd/data/chain/bitcoin/testnet/admin.macaroon",
    tls_cert_path="~/.lnd/tls.cert",
    host="localhost:10009",
)

Connect to CLN


ln = LightningWallet.from_cln(socket_path="/path/to/lightning-rpc")

Both constructors validate credentials and verify connectivity at init time. Invalid config raises LightningConfigError; auth failures raise LightningAuthError.

Operations


invoice = await ln.create_invoice(amount_sats=1000, memo="test")
payment = await ln.pay_invoice(bolt11="lnbc...")
balance = await ln.get_balance()
channels = await ln.list_channels()

Models

Model	Key Fields
`LightningInvoice`	`payment_hash`, `bolt11`, `amount_sats`, `status`, `preimage`
`LightningPayment`	`payment_hash`, `bolt11`, `amount_sats`, `fee_sats`, `status`
`LightningBalance`	`local_balance_sats`, `remote_balance_sats`, `total_channels`
`LightningChannel`	`channel_id`, `capacity_sats`, `local_balance_sats`, `status`

L402Client

Auto-pays HTTP 402 challenges and retries the request with proof-of-payment headers.


from bitpilot.lightning import LightningWallet, L402Client

ln = LightningWallet.from_lnd(...)

async with L402Client(ln) as client:
    response = await client.get("https://api.example.com/data")
    response.raise_for_status()
    print(response.json())

Parameters

Parameter	Default	Description
`max_fee_sats`	`100`	Maximum fee allowed per L402 payment
`auto_pay_methods`	`{"GET", "HEAD", "OPTIONS"}`	HTTP methods that auto-pay
`client`	`None`	Custom `httpx.AsyncClient` (optional)

Challenge Extraction

The client parses L402 challenges from:

WWW-Authenticate header (standard)
x-l402 header
JSON response body

Exceptions

L402Error — base class
L402ProtocolError — HTTP 402 response missing a valid challenge
L402PaymentError — invoice payment or preimage extraction failed

Lightning Exceptions

LightningError — base class for all Lightning errors
LightningConfigError — invalid LND/CLN configuration
LightningAuthError — authentication or connectivity failure