okx-agent-payments-protocol

What it does

The skill is a dispatcher for payments that triggers on HTTP 402 or related payment indicators (e.g., x402, X-PAYMENT, PAYMENT-REQUIRED, a2a-pay, etc.). It coordinates decoding of 402 payloads, building a parameter plan for replay, and guiding the user through a single confirmation card flow per payment. It supports three paths: session (channel-based), charge (one-shot), and a2a-pay (paymentId-based), and it references specific CLI commands and reference maps for each path. It enforces zero-user-text until the final confirmation card is shown and ensures a single confirmation card is emitted per payment, with exact user-facing terminology and internal routing details kept away from the user.

How it works

• When a response indicates a payment protocol (e.g., WWW-Authenticate: Payment or PAYMENT-REQUIRED with x402Version), it differentiates between v1/v2 formats and between session vs. one-shot flows.
• It may prompt the user to choose between session and one-shot if both are offered, otherwise proceeds to decode the appropriate payload.
• Step A3-Accepts decodes a base64-encoded v2 payload or uses the v1 JSON to extract the available accepts options for display, while preserving the raw payload for the actual CLI replay.
• Step A3-WWW-Authenticate decodes the header payload to gather intent (charge vs. session) and shows methodDetails like chainId, escrowContract, and other fields; it validates supported methods and expiry of challenges.
• Step A3-Params builds a plan of parameters to attach to the replay, sourced either from the decoded outputSchema/input or from explicit seller signals, with one plan entry per declared param.
• Step A3.5 (multi-scheme) engages only when two or more of exact, aggr_deferred, charge, period are present, and directs loading of references/multi-scheme guidance; otherwise, it proceeds to Step A4 with the chosen candidate.

When to use it

Use when an agent encounters HTTP 402 / payment-required or sees trigger words related to x402, X-PAYMENT, PAYMENT-REQUIRED, a2a-pay, or channel-based payment operations (opening/closing/top-up/settle/refund). The skill covers x402 variants (exact, exact+Permit2, upto, aggr_deferred), MPP (charge / session), and a2a-pay paymentId flows.

What it can touch

• Uses CLI commands like payment pay --payload [--selected-index], payment subscription subscribe/access/change/cancel/cancel-pending/my-subscriptions/allowance-status, payment charge --challenge, payment session open/voucher/topup/close, and payment a2a-pay create/pay/status as references for routing. It relies on decoding headers and payloads and building a param plan; it does not itself perform the actual payment but guides the dispatcher to the correct flow.

Caveats

• The protocol relies on specific external literals (e.g., x402Version, WWW-Authenticate: Payment, PAYMENT-REQUIRED) and must present user-facing text only about the payment, confirmation options, and results; internal routing stays hidden.
• If a method in WWW-Authenticate is not supported (e.g., tempo, svm, stripe), the flow must stop.
• The instruction requires a single confirmation card per payment and prohibits narrating internal protocol detection to the user.
• The license is MIT, as declared in the skill metadata.