feat(x402): platform fee on every paid agent request, not once per session

[bussyjd]

Supersedes #819, which is closed.

Why #819 could not work

isUnlockOffer is only consulted inside if rule.IsAuth(), and gate: auth routes take a verified wallet instead of payment. So the turns behind a minted session are free, and a fee attached there fires exactly once per session — recurring revenue was structurally impossible.

It also never fired in practice: an agent offer that declares no routes gets {Path: "/*", Gate: paid} from EffectiveRoutes(), so it does not enter the auth branch at all. And the shipped chat widget bundled ExactEvmScheme only, so an auth-capture challenge would have been unpayable by the client that was supposed to pay it.

What this does instead

The per-turn payments are ordinary paid requests, built by BuildV2RequirementWithAsset with a hardcoded Scheme: "exact" and no fee fields. An agent offer now advertises both schemes at the same price:

"accepts": [
  { "scheme": "auth-capture", "amount": "10000", "extra": { "feeRecipient": "0x…", "minFeeBps": 50, "maxFeeBps": 50, "autoCapture": true } },
  { "scheme": "exact",        "amount": "10000" }
]

x402Client.selectPaymentRequirements filters accepts[] down to the schemes the buyer registered and then takes the first survivor. So a buyer that speaks auth-capture pays the fee, and an exact-only buyer falls through to the second entry and is unaffected — nothing that works today stops working. autoCapture makes each charge single-shot, so the escrow splits feeBps to feeRecipient on every request.

Scope: agent offers only (rule.AgentRuntime). http offers keep advertising exact alone — their buyers are third-party clients we do not ship.

Settling a client-supplied struct

Auth-capture must settle against the requirement the client SIGNED: the signed PaymentInfo hash commits server-issued deadlines that are now-relative and drift between the 402 and the paid request, so our rebuilt copy would invalidate every signature. ResolveMatchedRequirement substitutes the signed struct, and that is only safe because validateSignedAuthCapture first pins every economically meaningful field against what we offered — the facilitator does not know our intended feeRecipient, payTo or amount, so a blind forward would let a buyer redirect the fee or underpay.

It compares the whole Extra map rather than an enumerated allowlist, so a field added to the requirement builder is pinned automatically instead of silently becoming client-controlled. Only the two deadlines may differ, and they are bounded on both ends. Thirteen tamper cases are covered, including fee redirection, fee zeroing, scheme downgrade, underpayment, and holding the authorization open past the configured window.

Blast-radius guards

• network scopes the fee to one chain. A facilitator only registers auth-capture for its configured chains. Advertising the fee where it cannot settle would make it the entry a capable buyer picks first and then fail their payment at verify. Confirm the chain is in the facilitator /supported before widening.
• offerPrefix is no longer required when enabled, and an empty prefix now means "no unlock offer" instead of matching every root-mounted rule. Without that, enabling the fee would convert any gate: auth offer at / into a paid unlock.

Off by default. The standalone unlock gate is unchanged and still available via offerPrefix.

Known limits

• A buyer that ignores the scheme filter and blindly signs accepts[0] will attempt auth-capture. Clients built on @x402/* filter correctly.
• Enforcement is by distribution, not cryptography: an operator can turn it off.
• @x402/evm 2.18.0 already exports AuthCaptureEvmScheme, so the vendor bundle rebuild keeps the validated version pin; only the export list and the ?v= cache-buster changed.

Verification

go build ./..., go vet, and the full go test ./... are green, and just generate produces no drift.

https://claude.ai/code/session_01PnhCQLz7CHuDBUhWd5xF8v