BoltBrain is an L402-first bitcoin spend governance kernel with policy controls and auditable receipts.

• Proxies outbound HTTP requests and auto-pays L402 challenges when policy allows.
• Enforces budget caps (per-invoice and daily).
• Records receipts to a JSONL ledger for audit and correlation.
• Supports optional idempotency to prevent duplicate payments.
• Works with the mock merchant/payer for local development.

• Not a full payments node implementation.
• Not a general-purpose API gateway.
• Not a replacement for upstream authentication/authorization.

Health check:

./scripts/doctor.sh

Run the demo (starts mock merchant + boltbraind, runs paid/budget/idempotency flows):

./scripts/demo-up.sh --isolated --keep

Use ./scripts/demo-up.sh --isolated --keep for a clean, reproducible demo (avoids port conflicts and cache interference).

• Budget enforcement: per-invoice and daily limits are checked before paying.
• Receipts: each request produces a receipt written to JSONL.
• Idempotency (optional): prevents duplicate payment for the same logical attempt when enabled.
• TLS-only upstream: outbound requests to merchants must be HTTPS.

• docs/spec/headers.md (HTTP headers & correlation)
• docs/spec/security_boundary_v1.md (current security boundary and proof boundary)
• docs/PILOT_READINESS.md (required vs optional release gates, environment caveats, proof coverage)
• docs/RC4_GO_NO_GO.md (current RC4 release decision baseline)
• docs/RC5_RELEASE_NOTES.md (RC5 implemented-state summary for pilot/public release prep)
• docs/RC5_PILOT_TAG_PLAN.md (RC5 pilot tag and handoff planning)
• docs/RC6_GO_NO_GO.md (current pilot/public go-no-go criteria for the implemented release profile)
• docs/RELEASE_PROCESS.md (release readiness, pilot handoff, release cut, and manifest recording sequence)
• docs/PILOT_HANDOFF_CHECKLIST.md (what to hand to a pilot reviewer/operator for an RC6 candidate)
• docs/PUBLIC_RELEASE_CHECKLIST.md (final repo/tag-public checklist for the packaged RC6 release)
• docs/spec/spend_intent_v1.md (contract-grade v1 normalized spend intent schema + current BoltBrain flow mapping)
• DEMO.md (3-minute acceptance & evidence checklist)