feat: pay by BlockRun API key alongside the USDC wallet

[VickyXAI]

Adds a second way to fund Franklin: a prepaid BlockRun API key, next to the existing USDC wallet. Solana leads Base everywhere in the docs and CLI copy, and the README now says where to sign up and top up.

Design doc: docs/plans/2026-09-05-api-key-auth-design.md (probed facts, not assumptions).

The two gateways share no auth

	Wallet	API key
Host	sol.blockrun.ai/api / blockrun.ai/api	api.blockrun.ai (no /api)
Auth	x402 PAYMENT-SIGNATURE	Authorization: Bearer brk_...
Settlement	On-chain, per call	Prepaid credit

A bearer key on the x402 hosts is ignored and still 402s; api.blockrun.ai 401s with no x402 fallback. That isolation is what lets this ship without touching wallet users — with no key set, resolvePayMode() returns the same host and headers as before, asserted per chain by test rather than by inspection.

All 33 gateway paths Franklin calls were probed with a live key and route correctly. The four that return unsupported_endpoint are 404 on the x402 hosts too — dead references in src/, left for a separate cleanup.

The real problem was accounting, not routing

The key gateway settles silently and returns no charge amount. Franklin derives its whole ledger from the 402 handshake: paidUsd is only assigned inside the 402 branch, and exa.ts returned early on if (!settled). So every paid call in key mode would have recorded $0, silently disabling --max-spend, PreSpend hooks, and every budget in the product.

Paid calls are now priced from BlockRun's published rate card at /.well-known/x402, and each row is tagged exact vs estimated. franklin stats marks estimated totals with ~ and reports the estimated portion separately; franklin balance refuses to invent a credit balance it cannot read and links the dashboard instead.

Known bias: that rate card is the x402 one, which carries a 5% margin and $0.001/call that key mode does not charge. Franklin therefore reads a few percent high. That is the safe direction for a spend ceiling and it is disclosed in the README, not hidden. A x-blockrun-charged-usd response header on the gateway would remove the estimate entirely — see §7 of the design doc.

A bug found by live-testing the proxy

Node lowercases the proxied client's authorization; gatewayHeaders() returns the canonical Authorization. A plain object held both, fetch sent two Authorization headers, and the gateway read the client's — every proxied call 401'd. applyGatewayAuth() strips every case variant first. Regression test included.

Also

brk_ had no entry in the secret redactor, so a key could reach transcripts and franklin logs. Added.

Verification

• 711 CLI tests + the desktop suite pass (23 new tests).
• Live against the gateway with a real key: chat, Exa, Surf, and the payment proxy in key mode.
• Live in wallet mode: chat settles exactly as before ($0.004046 recorded from the x402 amount).
• Surf on the Solana wallet path fails with verification_failed — verified to reproduce identically on main, so it predates this branch. Flagged in §11, not fixed here.

Not done

An editable API-key field in the desktop panel. The desktop RPC is read-only for credentials by design and adding a secret write path is a bigger security decision than this change should make alone. The panel does now state when spend is coming from a key instead of presenting the USDC balance as the budget. Keys are set with franklin login.

Still needs a human

Dashboard reconciliation. The gateway exposes no key-scoped balance or usage endpoint, so Franklin's tally cannot be automatically checked against user.blockrun.ai. §6 has the manual procedure and the expected drift.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LZQ4mfQVs2JJhC2ALfyGjt

[VickyXAI]

Heads-up: a live API key was committed here and must be rotated

Commit e9611ef on this branch contained a real brk_live_ BlockRun API key in test/api-key.local.mjs. It was pushed to this public repository. e51674b replaces it with a synthetic value, but the key is still reachable in this branch's history and in this PR's timeline, so scrubbing the file does not undo the exposure.

Required action: revoke that key at user.blockrun.ai and issue a new one.

The test never needed a working credential — it only checks the key's shape and that masking hides it. It now uses brk_live_0000TESTKEYNOTREAL....

🤖 Generated with Claude Code

https://claude.ai/code/session_01LZQ4mfQVs2JJhC2ALfyGjt