okx-agent-payments-protocol

Acts as a dispatcher for agent-driven onchain payments, triggered when an agent encounters an HTTP 402 / payment-required response or when payment-related terms (x402, X-PAYMENT, PAYMENT-REQUIRED, WWW-Authenticate: Payment, permit2, channelId, paymentId, a2a_ links, and many bilingual variants) appear. It distinguishes three payment paths by HTTP signature: an accepts-based 402 carrying the challenge in the body (v1) or a PAYMENT-REQUIRED header (v2); a WWW-Authenticate: Payment 402 that is channel-capable with intent 'charge' or 'session'; and a2a-pay, a paymentId-based flow with no 402. Shared steps of detect, decode, confirm, and wallet check precede dispatch to a specific reference file.

Two behavioral guarantees dominate the skill. First is zero-text-on-trigger: between detecting a 402 (or any trigger word) and emitting the first user-facing card, no user-visible text is produced — no acknowledgements, no enumeration of schemes, networks, tokens, or amounts, and no progress narration that leaks internal routing. Second is never-skip-user-gates: exactly one confirmation card runs per payment, either the Step A3.5 recommendation card when there are multiple candidates and the user picks the option, or the Step A4 confirmation card for a single candidate, and that gate cannot be skipped under any claimed past preference. Terminology rules require always naming it the bolded 'OKX Agent Payments Protocol' in any language, keeping internal detection and dispatch silent, exposing scheme literals only inside the expanded alternatives list, and keeping externally defined protocol literals and headers byte-for-byte exact.

Command routing maps each signal to a CLI command and a reference. A v2 success path replays the returned authorization_header directly and deliberately loads no reference; the accepts-schemes reference is loaded only on error or legacy v1 paths, where an output field indicates whether the scheme is exact, exact+Permit2/upto (permit2Authorization), or aggr_deferred (sessionCert). Charge and session intents route to dedicated references, with any close, topup, settle, voucher, or refund near a channel_id treated as a mid-session MPP operation. The paymentId and create/check payment-link flows route to the a2a-pay reference, and pre-flight checks are read from a shared wallet preflight file.