agent-bitcoin 27.1.1

Lightning Bitcoin payments for autonomous AI Agents

A Python SDK and Merchant endpoint that enables autonomous AI agents to transact via Lightning Network payments with Bitcoin final settlement.

Features

• Autonomous AI agent swarms
• Agent-to-Agent Lightning Network payments
• Agent-to-Merchant Lightning Network payments
• Bitcoin final settlement layer
• Python SDK for autonomous AI agent swarms
• Nostr Unique ID's for agents
• AI models for agents (Grok, Ollama)

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.

L402 tool suites

Paid JSON on Aperture :8081. Unpaid calls return 402; finance/Nostr paths are typically 100 sats (l402_pay.py --price 100). Not a public catalog (operator /32). Agent guide: docs/l402-tools.md. Operators: docs/l402-aperture.md.

Bitcoin (L1 fee / fullness / FX; skip if Lightning-only): GET /paid/finance/mempool-feerate — on-chain sat/vB fee bands; mempool-backlog — mempool tx count and fullness; fee-for-vsize — total fee for vbyte size; confirm-target — wait window to sat/vB; btc-usd — BTC/USD pass-through mark.

Lightning (decode → preflight → path-hint → pay): POST /paid/finance/ln-invoice-decode — inspect BOLT11 amount and dest; ln-invoice-preflight — allow/reject invoice policy reasons; ln-path-fee-hint — AWS LND QueryRoutes fee hint.

Nostr (local, no relay): POST /paid/nostr/event-verify — check NIP-01 id and sig; npub-decode — bech32 npub/note to hex (nsec rejected); zap-receipt-inspect — inspect kind-9735 zap receipt.

Demo files (/paid/hello, PDFs, PNG) are 1,000 sats. Lab host: http://3.90.159.146:8081 (allowlisted).

Remote client (known host)

Not “anyone with the URL.” A known client machine can pay Aperture with their LND (not our Mac wallet, not AWS invoice LND). Prefer a private channel; the operator admits their egress /32 on 8081 and 9735. Pack: docs/l402-client-pack.md. Ubuntu CLI: docs/l402-client-pack-script.md (examples/client-pack/).

Agent demos (swarm)

Two-agent and eight-agent swarms negotiate who pays one L402 GET (hash default, optional fee-sats puzzle). Live pay is from the Mac LND, not AWS self-pay. examples/swarm_l402.md, examples/swarm_l402_8.md.

LLM gate (--resolve llm-gate, two-agent only): each role votes YES/NO with Grok; YES voters use the hash tie-break; 0 YES → no L402. Requires XAI_API_KEY in the environment (never commit it). Do not pass --no-llm. Run Alice in one Mac terminal and Bob in another (same exports; start Alice then Bob). The script POSTs path-hint for you (no --method POST flag). Vote reason is logged locally, not sent to AWS.

export XAI_API_KEY=
export NOSTR_PASSPHRASE=

Mock (no Lightning):

# Terminal A
./examples/swarm_l402.sh --role alice --resolve llm-gate --offline-bus
# Terminal B
./examples/swarm_l402.sh --role bob --resolve llm-gate --offline-bus

Live (Mac pays AWS, 100 sats):

export LND_NETWORK=mainnet
export LND_CONTAINER=agent-bitcoin-lnd-mainnet
export LND_TRANSPORT=docker
export AGENT_BITCOIN_ALLOW_MAINNET=1
export AGENT_BITCOIN_ALLOW_AUTOPAY=1
# Terminal A
./examples/swarm_l402.sh --role alice --resolve llm-gate --price 100 \
  --url http://3.90.159.146:8081/paid/finance/ln-path-fee-hint
# Terminal B
./examples/swarm_l402.sh --role bob --resolve llm-gate --price 100 \
  --url http://3.90.159.146:8081/paid/finance/ln-path-fee-hint

Forced YES (test only — skip Grok; do not default):

export SWARM_LLM_FORCE_VOTE=YES
# both terminals, then the same alice/bob commands as mock (`--offline-bus`)
# or live (URL + LND exports above)

Nostr (agent identity)

Lightning invoice/pay and L402 finance tools do not require Nostr. Paid local checks (event-verify, npub-decode, zap-receipt-inspect) are in the L402 Nostr suite at 100 sats. Install the extra with uv sync --extra nostr or pip install 'agent-bitcoin[nostr]' (prefer Python 3.12). Details: docs/nostr-agent-identity.md, docs/nwc-automatic-wallets.md, SDK.md.

• Agents get a unique ID. Each agent is assigned a unique cryptographic secp256k1 keypair (npub & nsec), esentially, a unique ID. Agents in an agent swarm can easily and uniquely identify one another via their public npub. Agents never share or expose their private encrypted secret nsec.

• Agents communicate with Nostr events. Agents within agent swarms communicate with one-another via Nostr cryptographically signed events. Every accepted event must verify an agents ID, signature and pubkey. Events with sensitive payloads (i.e. invoices, etc.) are encrypted.

• Agents use Nostr relays. Agents publish signed events once. If one relay dies or censors, events simply move to another relay. Thus, agents use redundant and reliable communication channels to exchange events.

• Agents can use Nostr encryption. Agents can choose encrypted events for sensitive information. Encryption hides the inside of a message so a Nostr relay can store and forward it without reading invoices, prompts or agent state. Signing still proves which agent sent a message.

• Agents use Nostr for discovery. Agents can find one-another by publishing a signed “I can do X” event. Nostr relays find matching agents for that event. There is no need for a central directory.

Installation

From github repo source

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

From PyPI

pip install agent-bitcoin==27.0.0

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

More operator, lab, and swarm docs live under docs/ and examples/.

AI models

Currently, you may choose default Grok or Ollama models for Agent-to-Agent payments or Agent-to-Merchant payments.

Agent-to-Agent Lightning Network payments: Grok or Ollama model
Example: examples/agent-to-agent-pay.md

Agent-to-Merchant Lightning Network payments: Grok or Ollama model
Example: examples/agent-to-merchant-pay.md

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