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/charge.md
View on GitHub# `charge` intent (one-shot)
> **CLI down-sink:** receipt-decode is now `onchainos payment
> decode-receipt (--header <b64> | --receipt <json>)`. Transaction-vs-hash mode
> routing stays with the agent.
> Loaded from `../SKILL.md` when the dispatcher decoded a `WWW-Authenticate: Payment` 402 challenge with `intent="charge"`. Decode + display + wallet-status check have already happened upstream — start here at "Decide mode".
One-shot payment. CLI TEE-signs an EIP-3009 authorization (or wraps a client-broadcast tx hash) and returns a ready `authorization_header`. Optional `methodDetails.splits[]` (max 10 entries) splits the amount across multiple recipients in a single signed authorization.
**TEE-only** — local private key signing is NOT supported on this path. If the wallet session is unavailable and the user can't log in, stop and surface the limitation.
## Decide mode
`methodDetails.feePayer` from the decoded challenge:
- **`true` → transaction mode** (default, server pays gas) → [Sign via TEE](#transaction-mode-sign-via-tee)
- **`false` → hash mode** (user broadcasts the on-chain tx first) → [Hash mode](#hash-mode-broadcast-then-wrap)
## Transaction mode (sign via TEE)
```bash
onchainos payment charge \
--challenge '<full WWW-Authenticate header value>' \
[--from '<0xPayer>']
```
The CLI auto-detects `methodDetails.splits[]` — no extra flag needed. Output:
```json
{ "ok": true, "data": { "authorization_header": "...", "wallet": "0x...", "mode": "transaction", "..." } }
```
Save `data.authorization_header` and proceed to [Replay](#replay).
## Hash mode (broadcast then wrap)
When `feePayer=false`, the user must broadcast `transferWithAuthorization` themselves before the CLI can wrap the credential. Ask:
> The seller isn't paying gas, so you need to send the payment transaction on-chain yourself first, then give me the tx hash. How would you like to send it?
> 1. **Help me send it** — switch to `okx-agentic-wallet` (recommended)
> 2. **I'll send it manually** — paste the tx hash when ready
Option 1: hand off to `okx-agentic-wallet`, return here with the resulting `0x...` hash. Option 2: wait for the user to paste a 66-char `0x...` hash.
Then:
```bash
onchainos payment charge \
--challenge '<full WWW-Authenticate header value>' \
--tx-hash '0x<64-char hex>' \
[--from '<0xPayer>']
```
Output is the same shape as transaction mode, but `mode: "hash"`. Save `authorization_header`.
## Replay
Send `Authorization: <authorization_header>` to the original URL — the value already includes the `Payment ` prefix, do **NOT** add another (`Payment Payment …` is rejected). Expect `HTTP 200` + a `Payment-Receipt` header; decode it locally (`echo '<value>' | base64 -d | jq .`). 关键字段:`status` / `transaction`(on-chain tx hash)/ `chainId`。Charge complete. If a fresh `HTTP 402` returns (stale challenge), re-run the original request to fetch a new `WWW-Authenticate`, then sign again from the top.
## CLI Reference
`onchainos payment charge` — sign or wrap a one-shot charge.
| Param | Required | Default | Description |
|---|---|---|---|
| `--challenge` | Yes | - | Full `WWW-Authenticate: Payment ...` header value from the 402 response |
| `--tx-hash` | Hash mode only | - | 66-char `0x...` tx hash of the user-broadcast `transferWithAuthorization` |
| `--from` | No | selected account | Payer address |
| `--base-url` | No | production | Override backend URL (must be `https://`; `http://` triggers a 301 POST→GET redirect that drops the body and surfaces as `30001 incorrect params`) |
## Reading seller errors
Use **`../SKILL.md` → "Reading seller errors"** (priority order + `❌ Seller rejected: <reason> (code <code>, HTTP <status>)` format).
## Edge cases
| Symptom | Cause | Fix |
|---|---|---|
| `30001 incorrect params` | Wrong base URL or `http://` redirect | Verify `MPP_SA_URL` is `https://...` |
| `--tx-hash` rejected: must be `0x` + 64 hex | Malformed hash | Copy full 66-char hash |
| `chain not found` | Unsupported chainId | `onchainos wallet chains` |
| Challenge expired (`expires` in the past) | Stale challenge | Re-send original request to fetch fresh 402 |
| `feePayer=false` but user has no wallet to broadcast | Hash mode prerequisite missing | Either log in to OKX wallet via `okx-agentic-wallet` or use `okx-agentic-wallet` to broadcast |
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 |