# btc402: paid Bitcoin node data (x402 + Lightning + UnyKorn chain registry)

Layers: pruned Bitcoin Core 31.1 node (data) -> `btc_x402.py` (x402 per-call + Lightning API keys/plans)
-> the UnyKorn chain (chain.unykorn.ai) registry for offers and hashed payment-verification records.

## Files
- `btc_x402.py`: server (stdlib). `python3 btc_x402.py`
- `lightning.py`: LND REST / LNbits invoices, SQLite ledger, API keys, plans
- `registry.py`: offer manifest + verification records (local `registry.jsonl`; optional HMAC-signed POST to `REGISTRY_URL`)
- `btc_wallet.sh`: node receiving wallet (setup/address/balance/watch/withdraw). Its bech32 address = `BTC_PAY_TO` (sats rail on-chain destination). x402 `PAY_TO` stays an EVM Base USDC address.
- `btc402.env.example`: config; copy to `btc402.env`, chmod 600
- `index.html`: project site

## Endpoints
| Method | Path | Notes |
|---|---|---|
| GET | /health, /offer | free |
| GET | /blockcount, /feeestimate | `X-PAYMENT` (x402, 0.001 USDC) or `Authorization: Bearer <key>` (1 sat or plan quota) |
| POST | /keys | new API key (only hash stored) |
| POST | /topup `{key,sats}` | BOLT11 invoice |
| GET | /topup/<payment_hash> | poll, credits once on settlement |
| POST | /subscribe `{key,plan}` | basic 5,000 sats / pro 20,000 sats per 30 days |

## Status / pending
- FACILITATOR_URL and PAY_TO must be set before x402 calls can settle.
- Lightning backend credentials (LNbits invoice key or LND invoice macaroon) are not configured.
- Registry API: https://registry.unykorn.org (Cloudflare Worker `unykorn-registry`, KV, source `registry_worker.js`). It stores HMAC-verified records. These are not on-chain writes yet. chain.unykorn.ai remains read-only, and on-chain anchoring is pending.
- x402 facilitator: Coinbase CDP (`FACILITATOR_AUTH=cdp`, `CDP_KEY_FILE`). JWT auth is in `btc_x402.py` and needs `cryptography`.
- Lightning: phoenixd (`LN_BACKEND=phoenixd`) on 127.0.0.1:9740, using the limited-access password. On the first incoming payment, phoenixd opens a channel automatically and deducts the on-chain plus service fee (several thousand sats), so very small first top-ups can be absorbed or rejected.
- Earlier note: chain.unykorn.ai exposes only a website + read-only `/api/live`, `/api/site`; RPC POST answers "read only". Records are kept locally until a write endpoint is confirmed.

## Security
RPC localhost only; read-only whitelist; no wallet calls; invoice-only Lightning access; never logs Authorization.

## Attribution
Built on Bitcoin Core (unmodified), and not a fork. It runs the official snap build. Credit to bitcoin.org / bitcoincore.org and the Bitcoin Core contributors. Bitcoin Core is MIT-licensed. See `NOTICE` for exactly what this project adds on top.

## Registry as value-capture layer
The offer is registered at startup. Every x402 settlement, every Lightning settled invoice and every API-key call is recorded through `registry.py`. Paid responses carry `X-UnyKorn-Record: offer=<id>; record=<id>; status=...`. Failed chain writes queue in `registry.queue.jsonl` and are retried. The chain write is **pending a confirmed API**.