agent-bitcoin 26.2.0

Lightning Bitcoin payments for autonomous AI Agents

A lightweight Python SDK that enables AI agents to send and receive Lightning/Bitcoin payments.

Features

• Simple, agent-friendly API (create_client)
• Create and pay Lightning invoices (payee creates, payer pays)
• Explicit invoice quotes for independent agents (create_invoice_quote / pay_invoice_quote) — one BOLT11 for the requested amount
• LND transports: docker lncli (lab default) or gRPC + macaroon (docs/lnd-client.md)
• Networks: regtest (default), signet, testnet; mainnet only with explicit latch
• Pydantic models and structured errors
• Optional LLM payment decision agent (PAY / REJECT / CONFIRM — never executes pays)
• Balance checks (Lightning and on-chain)
• Operator tooling: dual-node health, SCB backup, daily ops (docs/index.md)
• Optional Aperture L402 HTTP gateway (regtest PoC; Mac pays AWS :8081) — docs/l402-aperture.md

Roles: payee and payer

Either physical node (AWS agent LND or Mac counterparty LND) can act as payee or payer depending on who creates the invoice.

Payment amounts

There is no platform / transaction fee. A requested payment of X sats creates and pays a BOLT11 for exactly X. Lightning routing fees (the fee_limit_sats / routing_fee_limit_sats cap) are separate and still apply when paying.

For independent agents, prefer create_invoice_quote so the payer sees amount_sats / total_cost_sats without shared env. Details: SDK.md.

There is no collect_transaction_fee / POST /send-fee. Mainnet pays stay latch-gated — see docs/mainnet-pilot.md.

Installation

From PyPI

pip install agent-bitcoin

From source

git clone https://github.com/gpu7/agent-bitcoin.git
cd agent-bitcoin
uv sync

More detail (optional LangChain / Grok / Ollama deps): SDK.md.

Quick start

from agent_bitcoin import create_client

client = create_client()

# Payee: invoice + explicit quote for independent payers
quote = client.create_invoice_quote(memo="Test payment", amount_sats=2000)
# quote.payment_request, amount_sats, total_cost_sats (equals amount)

# Payer: validate / decision inputs, then pay Lightning amount
inputs = client.build_payer_decision_inputs(quote, routing_fee_limit_sats=200)
if inputs.quote_valid:
    result = client.pay_invoice_quote(quote, routing_fee_limit_sats=200)
    if result.success:
        print(f"Paid {result.amount} sats (LN); total_cost was {quote.total_cost_sats}")

Bare create_invoice / pay_invoice remain available for simple lab flows.

Configure LND via env (LND_NETWORK, LND_TRANSPORT=docker|grpc, container or gRPC cert/macaroon). Full API → SDK.md. Regtest operators → docs/backend.md. Signet operators → docs/signet.md.

Security

Agent-Bitcoin is developed with security in mind:

• Secrets stay out of the repository — API keys, wallet material, and host credentials are configured via environment and local ops practice, not committed source
• Least privilege for network and node access (admin/API/RPC not left open to the whole internet in operator deployments)
• Conservative defaults for payment amounts and fees (see SDK.md)
• Authenticated payment APIs — backend balance/invoice/pay routes require an API key when deployed
• Bounded autonomous payment decisions — hard amount limits in code before any LLM approval
• Mainnet kill switches — e.g. AGENT_BITCOIN_ALLOW_MAINNET, AGENT_BITCOIN_ALLOW_AUTOPAY, daily spend caps
• Operator health checks — dual-node signet health, backups (docs/daily-ops-signet.md, docs/security-hardening.md)
• Regtest / signet first for lab work; mainnet is never the implicit default (pilot ops complete under ≤50k dual-node — docs/mainnet-pilot.md)

Report vulnerabilities privately — see SECURITY.md. Do not open public issues for security reports.

Documentation

Repository

• GitHub: https://github.com/gpu7/agent-bitcoin
• PyPI: https://pypi.org/project/agent-bitcoin/

License

MIT License — see LICENSE.

Support

Richard Casey richardcaseyhpc@protonmail.com +1 970-980-5975