internet-court/internet-court-skill / vendored/okx/okx-agent-payments-protocol
okx-agent-payments-protocol
VerifiedUse when an agent hits HTTP 402 / payment-required, or the user mentions x402, x402Version, X-PAYMENT, PAYMENT-REQUIRED, PAYMENT-SIGNATURE, WWW-Authenticate: Payment, permit2, upto, metered billing, a payment channel / voucher / session, channelId / channel_id, opening / closing / topping up / settling / refunding a channel, a paymentId or a2a_ link, creating / checking a payment link, A2MCP / an A2MCP endpoint, or sending a request to / calling an Agent's endpoint with a concrete endpoint URL. Covers x402 (exact, exact+Permit2, upto, aggr_deferred), MPP (charge / session), and a2a-pay paymentId flows. Any close / topup / settle / voucher / refund near a channel_id or session is an MPP mid-session op. Two-phase quote/pay: `payment quote`, `payment pay --payment-id`, `decode-receipt`. The full bilingual trigger list (including Chinese) lives in the skill body.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 341 B |
| SKILL.md | skill md | 32.8 KB |
| _shared/amount-display.md | markdown | 851 B |
| _shared/preflight.md | markdown | 2.0 KB |
| references/a2a_charge.md | markdown | 10.7 KB |
| references/a2mcp-mcp.md | markdown | 3.7 KB |
| references/accepts-schemes.md | markdown | 9.3 KB |
| references/charge.md | markdown | 4.3 KB |
| references/multi-scheme.md | markdown | 6.1 KB |
| references/session.md | markdown | 17.7 KB |
| references/subscription.md | markdown | 11.5 KB |
references/a2mcp-mcp.md
View on GitHub# A2MCP over MCP transport (Streamable HTTP / SSE)
## When this applies
`payment quote` returned `data.mcpTools[]`, OR the endpoint URL ends in `/mcp`/`/sse`, OR the bare
probe returned `Content-Type: text/event-stream` or a JSON-RPC body. The paywall is at the
`tools/call` layer — a bare probe / `tools/list` returns no 402; only a real `tools/call` does.
The CLI does the whole `initialize → tools/list → tools/call` JSON-RPC handshake and SSE parsing
internally. Do NOT hand-write JSON-RPC or parse SSE yourself.
## Three-step flow
1. **Discover** — `onchainos payment quote <url>`
→ returns `data.mcpTools[]` (each `{name, description?, inputSchema?}`); no `paymentId`; free.
2. **Trigger 402** — pick a tool per the user's intent (`AskUserQuestion` if ambiguous), assemble
`--param key=value` from the tool's `inputSchema`, then
`onchainos payment quote <url> --tool <name> --param k=v …`
→ the CLI issues `tools/call`. A paid tool returns 402 → `data.{paymentId,accepts,candidates}`
(identical to a REST quote). A free / first-N-free tool returns `data.result` instead.
3. **Pay** — confirm the amount/scheme (Step A3), then
`onchainos payment pay --payment-id <id> [--selected-index <n>] --yes`
→ the CLI TEE-signs and replays the SAME `tools/call` with a `PAYMENT-SIGNATURE` header, then
parses the SSE response + `PAYMENT-RESPONSE` receipt.
(`--selected-index <n>` picks an `accepts[]` entry when the 402 offered multiple schemes.)
## `--param` coercion (must match the tool's `inputSchema`)
The CLI coerces each `--param` value per `inputSchema.properties[key].type`:
- `integer` / `number` → JSON number • `boolean` → JSON bool • `object` / `array` → parsed JSON
- other type / no schema / parse failure → kept as a string
Example: `zip` is declared `string` → `--param zip=01234` stays `"01234"`; `n` is declared
`integer` → `--param n=5` becomes JSON `5`. The coerced values are persisted in the paymentId state
and replayed verbatim by `payment pay`.
## SSE / tiered billing
The response is a Streamable-HTTP SSE stream (`event: message` / `data:` lines). In-stream
notifications (e.g. `progress`) that arrive before the response are skipped; the first `data:` line
carrying a JSON-RPC `result`/`error` is taken. Tiered billing is supported: `tools/list` is free,
a paid `tools/call` returns 402, and a "first N calls free" tool returns no 402 — that non-402
`tools/call` is a **free result** surfaced as `data.result`.
## Do NOT hallucinate a payment
A bare probe / `tools/list` returning no 402 does **NOT** mean the service is free — on an MCP
endpoint the paywall lives at the `tools/call` layer, so a tool's price only surfaces when you
actually invoke it. Never invent or assume a payment. If a real `tools/call` genuinely returns no
402 (a non-402 `data.result`), report the endpoint as **free / not x402-enabled** and stop — do not
fabricate a `paymentId`, an `accepts[]` challenge, or a signing step that the server never asked for.
## Error tokens (grep-able first word of `.error`)
- `endpoint_unreachable` — `initialize` / `tools/list` / `tools/call` transport failure; or a bare
405 on a non-`mcp|sse` URL with no `--tool` (retry with `--tool <name>` or `--method POST`).
- `invalid_input` — `--tool` names a tool not in the discovered catalog (the message lists the
available tool names).
- `unsupported` — the 402 challenge's `accepts[]` has no known payment scheme.
The destructive `payment pay` confirming gate (exit 2, `{confirming,…}`) and all REST error tokens
are reused unchanged.
## Not in scope
stdio / local MCP transport; paying for MCP `resources` / `prompts`; non-x402 MCP payment schemes;
cross-process MCP session caching (`quote` and `pay` each re-handshake).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |