Skip to content

internet-court/internet-court-skill / vendored/okx/okx-agent-payments-protocol

okx-agent-payments-protocol

Verified

Use 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.

FileKindSize
LICENSEother341 B
SKILL.mdskill md32.8 KB
_shared/amount-display.mdmarkdown851 B
_shared/preflight.mdmarkdown2.0 KB
references/a2a_charge.mdmarkdown10.7 KB
references/a2mcp-mcp.mdmarkdown3.7 KB
references/accepts-schemes.mdmarkdown9.3 KB
references/charge.mdmarkdown4.3 KB
references/multi-scheme.mdmarkdown6.1 KB
references/session.mdmarkdown17.7 KB
references/subscription.mdmarkdown11.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).
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall