feat(x402): settle chat at the actual cost on Base with upto (Permit2)

[VickyXAI]

Why

blockrun.ai settles every x402 chat call with exact: the wallet signs a fixed pre-call quote, so discounts the gateway only learns after the call can never reach x402 callers. A DeepSeek prompt-cache hit is one example ($0.028/M cached input vs $0.14/M). The gateway can offer upto as accepts[1], with exact staying at accepts[0] (BILLING_UPTO_DEEPSEEK / BILLING_UPTO_ALL). With upto it settles the actual amount, which is never more than the signed ceiling.

What

blockrun_llm/x402_upto.py (new) and chat wiring in LLMClient / AsyncLLMClient, covering non-stream and stream calls in both sync and async.

Signing follows the official @x402/evm 2.28.0 UptoEvmScheme / trySignEip2612PermitExtension:

• Permit2 PermitWitnessTransferFrom: spender 0x4020…0002, witness {to: payTo, facilitator: extra.facilitatorAddress, validAfter: 0}, deadline now + maxTimeoutSeconds, random 256-bit nonce.
• The optional EIP-2612 permit approves Permit2 for exactly the ceiling. The proxy reverts with Permit2612AmountMismatch otherwise, and CDP rejects MaxUint256. It is attached as extensions.eip2612GasSponsoring.info, merged with @x402/core semantics.
• The tests pin a vector generated by the official client (scripts/gen-upto-vector.mjs). The payload, both signatures and both EIP-712 digests match it byte for byte.

Selection: never worse than exact. upto is used only when all of these hold:

• the 402 offers an EVM upto option with extra.facilitatorAddress, for USDC on a network in EVM_NETWORKS;
• the USDC balance is at least the ceiling;
• the Permit2 allowance is at least the ceiling, or the 402 declares eip2612GasSponsoring (a wallet with no ETH works);
• the ceiling passes the spend limits.

In every other case, and on any RPC or signing error, the SDK signs exact as before and logs at debug level only. Other rules:

• If the gateway rejects an upto payment before serving anything (a 402, or a 4xx payment-verification body), the SDK retries once with the same 402's exact entry. It remembers the rejection for this client and network. If exact is rejected too, the original error surfaces. A 2xx response or a stream already in progress is never retried.
• Only one gas-sponsored upto payment per wallet and network can be in flight. The SDK records the USDC nonce each permit signs over. While the on-chain nonce hasn't moved and the permit's deadline hasn't passed, any call that would need another permit pays exact. An allowance that already covers the ceiling means upto with no permit.
• Chain reads go to the public Base RPCs, now shared with get_balance() through EVM_NETWORKS, with a 3 s timeout each. The async client reads without blocking the event loop.
• Opt out with payment_scheme="exact" or BLOCKRUN_PAYMENT_SCHEME=exact. Solana, AnthropicClient and the non-chat endpoints are unchanged.

Accounting: a ceiling is not a charge.

• An upto call books the settled amount from PAYMENT-RESPONSE when the gateway reports one. Otherwise it books the ceiling and labels it.
• Labels: ChatResponse.payment_scheme and cost_is_ceiling (also on stream chunks), get_spending()["ceiling_usd"], cost_basis on cost-log rows, and (upto ceiling) in transactions.log.
• Spend limits count the ceiling in full.
• When the 402 also offers upto, exact books and caps on its own amount, because the body's price is then the upto ceiling.

Verification

• pytest tests/unit on 3.13: 1063 passed. The CI 3.9 command: 952 passed, 11 skipped. black --check . and ruff check . are clean. mypy has no new errors (249 now vs 253 on main).
• 76 new tests in tests/unit/test_x402_upto.py: the reference vector, selection fallbacks, the sponsored permit being attached or skipped, the nonce guard, rejection with one exact retry, accounting, streaming, and chain reads.
• Mutation-checked: disabling the nonce guard, the permit-value rule, the rejection retry, the settled-amount cap, the balance check or the price-vs-amount fix each makes a test fail.
• The chain reads were checked live and read-only against Base public RPCs (sync and async).
• The live blockrun.ai 402 for deepseek/deepseek-chat does not offer upto yet, so against production this change currently signs exact, exactly as today.

Open points

• The gateway's PAYMENT-RESPONSE has no settled amount yet, so non-stream upto calls book the labeled ceiling until the server adds it. Streams always will, because their header is sent before settlement.
• Version is not bumped and nothing is published.

🤖 Generated with Claude Code