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/session.md
View on GitHub# `session` intent (channel: open / voucher / topUp / close)
> **CLI down-sink:** voucher reuse-vs-sign, cumulative math, the
> top-up inequality, resign-on-drift, and refund-on-close are now decided by the
> CLI. Run `onchainos payment session <open|voucher|topup|close>` and relay
> `data.{strategy, needsTopUp, cumulative_amount, refund, recovery, reason_text}`
> — don't recompute them. NL→command routing for each op stays here.
> Loaded from `../SKILL.md` when the dispatcher decoded a `WWW-Authenticate: Payment` 402 challenge with `intent="session"`. Decode + display + wallet-status check have already happened upstream — start here at "Phase S1: Open Channel".
>
> **Also enter this reference for any mid-session operation** (close / topUp / settle / voucher / refund) when the user mentions an existing `channel_id`, even without a fresh 402. Jump directly to the matching phase below.
State machine: **open → N vouchers → close**, optional **topUp** between vouchers. The seller drives transitions via fresh 402 challenges (or the user issues a close).
**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.
> **🔑 Action-first, URL-stays-the-same** — When a user asks for ANY
> mid-session operation ("open / 开通道", "buy a translation", "top up /
> 充值", "close / 关闭"), the action lives in the credential
> `payload.action`, NOT in the URL path. The URL is **always the
> original business URL** — the same one the user asked to access.
>
> | User intent (any language) | `payload.action` | CLI command |
> |---|---|---|
> | open / 开通道 / start session | `open` | `payment session open` |
> | buy / call / 调用 / use service | `voucher` | `payment session voucher` |
> | top up / 充值 / add deposit | `topUp` | `payment session topup` |
> | close / 关闭 / end session / settle | `close` | `payment session close` |
>
> All four flows share ONE URL and ONE pattern:
> 1. Re-issue the **original business URL** with no `Authorization` →
> seller responds `402 + WWW-Authenticate: Payment ... intent="session"`.
> 2. Pick the right CLI command above and pass the WWW-Authenticate as
> `--challenge`. The CLI sets `payload.action` for you.
> 3. Resend to the **same original business URL** with
> `Authorization: <authorization_header>`.
>
> **`<authorization_header>` already includes the `Payment ` scheme
> prefix** — paste the CLI's `data.authorization_header` value verbatim
> into the `Authorization` header. **Do NOT** prepend another `Payment `
> yourself; that would produce `Payment Payment <b64>` and the seller
> will reject it.
>
> **Never probe** for `/open`, `/voucher`, `/topup`, `/close`,
> `/<resource>/topup`, etc. — they don't exist. If you can't think of
> a URL, the answer is always "the original business URL the user
> asked about".
## Talk to users in plain language
Match the user's language. Use action-verb phrasing — "issue a voucher / 签发凭证", "top up your balance / 补充余额", "close the channel / 关闭通道", "your prepaid balance / 通道余额" — don't dump bare jargon (`voucher`, `topUp`, `close`, `escrow`, `cumulativeAmount`) on the user. Field names are fine in **state echo** since the user copy-pastes those across sessions.
## Session state to track
Save the moment `payment session open` returns and maintain across phases:
| Field | Source |
|---|---|
| `channel_id` | `payment session open` output |
| `escrow` | open challenge `methodDetails.escrowContract` |
| `chain_id` | open challenge `methodDetails.chainId` |
| `currency` | open challenge `currency` |
| `payer_addr` | open output `wallet` |
| `current_cum` | highest signed cum so far (open `--initial-cum` or last issued voucher's cum) |
| `current_sig` | last voucher signature (`signature` field of open / voucher / close output) |
| `estimated_spent` | sum of `unit_amount` across served business requests since the last fresh sign |
| `unit_amount` | latest voucher challenge `amount` (seller is authoritative) |
| `deposit` | open output `deposit` + topup `--additional-deposit` |
Track in conversation context. Across conversations, ask the user to re-supply `channel_id` / `escrow` / `current_cum` / `current_sig` to continue.
**Mandatory state echo** — after `payment session open`, after each voucher (sign or reuse), after topup, and immediately before close, end your message with one line:
> 📋 Channel `<channel_id>` · chain `<chain_id>` · escrow `<escrow>` · deposit `<human(deposit)>` (`<deposit>`) · cum `<human(current_cum)>` (`<current_cum>`) · spent~`<human(estimated_spent)>` (`<estimated_spent>`) · sig `<current_sig prefix...>`
**All user-facing amounts in BOTH human and atomic form** — `<human> (<atomic>)`; see `../_shared/amount-display.md` for the decimals table + fallback.
---
## Phase S1: Open Channel
First step of any session. Decide the **deposit** with the user:
> A session payment needs you to lock a prepaid balance up front (held in escrow). How much would you like to prepay?
> Suggested: `<human(suggestedDeposit)> (<suggestedDeposit>)` (or `unit_amount × 100` if no suggestion — enough for ~100 requests).
> Each request draws from this balance. You can add more later, or close the channel anytime to refund whatever's unused.
Wait for the user's amount.
### Optional initial-voucher prepay
Opening a channel signs a baseline voucher with `cumulativeAmount=0` by default. To override:
- `--initial-cum N` — explicit baseline (atomic units).
- `--prepay-first` — use the unit price from `challenge.amount` (silently falls back to 0 if missing/`"0"`).
Pick from user intent: no preference → no flag; "pay first request immediately" → `--prepay-first`; "pre-authorize N" → `--initial-cum N`. Constraint: `initial_cum ≤ deposit` (SDK rejects with `70012`).
### Mode branch
Branch by `methodDetails.feePayer`.
**Transaction mode (`feePayer=true`)**:
```bash
onchainos payment session open \
--challenge '<full WWW-Authenticate header value>' \
--deposit '<atomic units>' \
[--initial-cum '<atomic>' | --prepay-first] \
[--from '<0xPayer>']
```
CLI TEE-signs EIP-3009 `receiveWithAuthorization` (deposit into escrow) + EIP-712 baseline Voucher (channelId, cum=initial_cum). Output: `data.{authorization_header, channel_id, escrow, chain_id, deposit, wallet}` — save all to session state. Initial `current_cum` = the initial-cum value (default `"0"`).
**Hash mode (`feePayer=false`)** — user must send the on-chain "open channel" tx themselves first (delegate to `okx-agentic-wallet` or manual). Then:
```bash
onchainos payment session open \
--challenge '<full WWW-Authenticate header value>' \
--deposit '<atomic units>' \
--tx-hash '0x<64-char hex>' \
--salt '0x<64-char hex>' \
[--initial-cum '<atomic>' | --prepay-first] \
[--from '<0xPayer>']
```
`--salt` MUST be the same bytes32 the user passed to the on-chain `escrow.open(...)` call. The CLI recomputes `channelId = keccak256(abi.encode(payer, payee, token, salt, authorizedSigner, escrow, chainId))` and the seller compares it to what the on-chain event emitted — supply a fresh random salt and the open is rejected with a channelId mismatch. If the user broadcast through `okx-agentic-wallet`, the salt is the bytes32 they (or you) passed into the gateway's contract-call arguments.
CLI still TEE-signs the initial voucher; only the deposit tx is replaced by the supplied hash.
### Send open to seller
```
<original method> <original url>
Authorization: <authorization_header>
```
Outcomes:
- **HTTP 200** — channel open, response carries the first business result. Echo state. Subsequent requests to the same resource: send without `Authorization` first; seller responds with a voucher 402 → Phase S2.
- **HTTP 402 (fresh `WWW-Authenticate: Payment`)** — channel opened but seller wants the first voucher signed. Go straight to Phase S2.
---
## Phase S2: Business Request (Voucher Loop)
Run for **each** business request during the session.
**Enter triggers** when `channel_id` is active: user says "next request" / "again" / "another one" / "再调一次" / "再发一个" / "继续" / "voucher" / "凭证" / "签一个授权"; or user requests the resource again and gets a fresh 402.
### How vouchers actually work
A voucher is a **cumulative authorization**, not a single-request payment. Once signed, the seller keeps deducting until `spent` reaches the signed `cumulativeAmount`. So one voucher with `cum=50` funds 50× `unit_amount=1` requests **without re-signing** — provided the seller supports reuse (mppx / OKX TS Session / OKX Rust SDK ≥ this version). Legacy OKX Rust SDK treats byte-replay as idempotent retry and skips the deduct; force re-sign every request if you suspect this.
Per-request job: pick **reuse** vs **sign** based on remaining balance.
### S2.1: Send the request
If you don't have a fresh challenge yet, send the business request. Seller responds with HTTP 402 + fresh `WWW-Authenticate: Payment` — this is a **voucher challenge** for the new request. Decode `request` to extract `amount` (the seller-quoted unit price).
### S2.2: Decide reuse vs sign
```
unit_amount = <amount from this voucher challenge> // seller is authoritative
remaining = current_cum - estimated_spent // headroom under existing voucher
if current_sig is set AND remaining >= unit_amount:
strategy = REUSE # spend remaining headroom under existing voucher
cum_for_this_call = current_cum # unchanged
else:
strategy = SIGN # need a higher cum
cum_for_this_call = current_cum + unit_amount
# Hard guards (apply regardless of strategy)
if cum_for_this_call > deposit:
→ Phase S2b (TopUp) first, then re-evaluate
if methodDetails.minVoucherDelta is set AND strategy == SIGN:
ensure (cum_for_this_call - current_cum) >= minVoucherDelta
```
`unit_amount` always comes from the **current** voucher challenge, never a cached value — the seller can adjust pricing between requests and the latest 402 wins.
### S2.3a: Reuse path (no TEE)
```bash
onchainos payment session voucher \
--challenge '<fresh WWW-Authenticate from this 402>' \
--channel-id '<saved channel_id>' \
--cumulative-amount '<current_cum>' \
--reuse-signature '<saved current_sig>' \
[--from '<saved payer_addr>']
```
Don't pass `--escrow` / `--chain-id` here — the existing signature already binds them. CLI skips TEE and wraps the existing signature bytes verbatim. `mode = "reuse"`.
### S2.3b: Sign path (TEE)
```bash
onchainos payment session voucher \
--challenge '<fresh WWW-Authenticate from this 402>' \
--channel-id '<saved channel_id>' \
--cumulative-amount '<cum_for_this_call>' \
--escrow '<saved escrow>' \
--chain-id '<saved chain_id>' \
[--from '<saved payer_addr>']
```
CLI signs an EIP-712 Voucher(channelId, cum_for_this_call) via TEE. `mode = "sign"`. Both paths return `data.{authorization_header, channel_id, cumulative_amount, signature, mode}`.
### S2.4: Replay the business request
```
<original method> <original url>
Authorization: <authorization_header>
```
**Non-empty Step A3-Params plan?** Also attach its params on their carriers (query / body / header / path), using the plan's `input.method` if it differs from the original. The `Authorization` voucher header rides alongside. (Channel ops — open / topup / close — carry their action in the credential payload, not business params, so they're unaffected.)
Expected: `HTTP 200`. **Update state**: `current_cum = cum_for_this_call`, `current_sig = <signature>`, `estimated_spent += unit_amount`. (Reuse path: `current_cum` / `current_sig` unchanged; only `estimated_spent` advances.)
### S2.5: Insufficient-balance fallback
When the seller rejects a voucher with `reason: "insufficient balance"`, `detail: "voucher exhausted"`, or OKX Rust SDK private code `70015`, `estimated_spent` drifted. Recover:
1. Surface the seller's reason: `❌ Seller rejected: insufficient balance — your current authorization is fully used. Signing a new one to continue.`
2. Set `estimated_spent = current_cum` (treat existing voucher as exhausted).
3. Re-enter S2.2 — `remaining = 0`, **SIGN** is picked.
4. Sign a new voucher with `cum = current_cum + unit_amount` and retry.
**Do NOT loop reuse-on-insufficient-balance** — always escalate to SIGN.
Other rejections: `amount_exceeds_deposit` → topup (S2b); `delta_too_small` → raise cum; `invalid_signature` → check seller logs. Always surface the seller's reason text first, code in parens second.
### S2.6: Loop
Repeat S2.1–S2.4 for each request. Same voucher funds many calls while `remaining ≥ unit_amount`; re-sign only when balance runs out.
> Voucher rejections come from **seller-SDK local validation**, not a backend round-trip (the `700xx` codes are in Troubleshooting below).
---
## Phase S2b (Optional): TopUp Mid-Session
Triggered when `current_cum + unit_amount > deposit` (seller refuses with `70012` or pre-emptively sends a topUp challenge).
Ask the user:
> Your prepaid balance is running low. How much would you like to add (atomic units)?
> Current balance: `<human(deposit)> (<deposit>)` · Used so far: `<human(current_cum)> (<current_cum>)`
Branch by `methodDetails.feePayer` from the topUp challenge.
**Transaction mode**:
```bash
onchainos payment session topup \
--challenge '<WWW-Authenticate for topUp>' \
--channel-id '<saved channel_id>' \
--additional-deposit '<atomic units>' \
--escrow '<saved escrow>' \
--chain-id '<saved chain_id>' \
--currency '<saved currency>' \
[--from '<saved payer_addr>']
```
CLI TEE-signs `receiveWithAuthorization`. EIP-3009 nonce is `keccak256(abi.encode(channelId, additionalDeposit, from, topUpSalt))` — must match the on-chain contract.
**Hash mode** (user broadcasts top-up tx first, then):
```bash
onchainos payment session topup \
--challenge '<WWW-Authenticate for topUp>' \
--channel-id '<saved channel_id>' \
--additional-deposit '<atomic units>' \
--escrow '<saved escrow>' \
--chain-id '<saved chain_id>' \
--tx-hash '0x<64-char hex>' \
[--from '<saved payer_addr>']
```
`--currency` is optional in hash mode (CLI doesn't sign EIP-3009; the on-chain tx already covers it).
**After TopUp**: `deposit = deposit + additional_deposit`. Resume Phase S2.
---
## Phase S3: Close Channel
When the user is done — says "close the channel / 关闭通道 / end the session", or after the final request. **Always close** when done; otherwise the prepaid balance stays escrowed until the seller's timeout (typically 12–24h).
### S3.1: Decide final cumulativeAmount
`final_cum = current_cum` — the highest voucher cum sent in this session. **Don't add `unit_amount`** — close reuses the last voucher's cum (no new service is delivered).
### S3.2: Sign close voucher
```bash
onchainos payment session close \
--challenge '<WWW-Authenticate for close, or fresh 402 if seller issues one>' \
--channel-id '<saved channel_id>' \
--cumulative-amount '<final_cum>' \
--escrow '<saved escrow>' \
--chain-id '<saved chain_id>' \
[--from '<saved payer_addr>']
```
CLI signs an EIP-712 Voucher(channelId, final_cum) via TEE — same signing path as a regular voucher, used at close time. Output: `data.{authorization_header, channel_id, cumulative_amount}`.
### S3.3: Send close to seller
```
<original method> <original url> # typically a dedicated close endpoint, e.g. /session/manage
Authorization: <authorization_header>
```
Seller settles on-chain (transfers `final_cum` to merchant, refunds the rest to payer) and returns a `Payment-Receipt` header. Decode it locally (`echo '<value>' | base64 -d | jq .`) — 关键字段:`status` / `transaction`(on-chain tx hash,S3.4 报给用户用)/ `chainId`。
**Clear session state** — channel is closed.
### S3.4: Confirm to user
> ✅ Channel closed. Charged `<human(final_cum)> (<final_cum>)` of your `<human(deposit)> (<deposit>)` prepaid balance. Refund of `<human(deposit - final_cum)> (<deposit - final_cum>)` returned to your wallet.
> On-chain tx: `<reference from response>`
---
## Reading seller errors
Use **`../SKILL.md` → "Reading seller errors"** (priority order + `❌ Seller rejected: <reason> (code <code>, HTTP <status>)` format).
## Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| `not logged in` / `session expired` | Wallet session missing or expired | `onchainos wallet login` |
| Voucher rejected: `70012 amount_exceeds_deposit` | cum > channel deposit | Phase S2b TopUp first |
| Voucher rejected: `70000 invalid_params` (cum not strictly increasing) | new_cum ≤ current_cum | Increase strictly; ensure you're tracking current_cum |
| Voucher rejected: `70013 voucher_delta_too_small` | Delta below `minVoucherDelta` | Raise cum by at least the minimum |
| Voucher rejected: `InsufficientBalance` (HTTP 402; OKX Rust SDK `70015`) | seller's spent + new_amount > highest voucher | S2.5 fallback |
| Open fails: `chain not found` | Unsupported chainId or chain entry missing | `onchainos wallet chains` to list supported chains |
| `--tx-hash` rejected: must be `0x` + 64 hex chars | Malformed hash | Copy full 66-char hash (with `0x` prefix) |
| Session 402 keeps repeating after voucher sent | channel_id / escrow / chain_id mismatch | Re-check saved session state; all three must match the open |
| `30001 incorrect params` | Wrong base URL / `http://` redirect | Verify backend URL is `https://...` |
| `70004 invalid signature` | EIP-3009 typename mismatch / wrong domain | Check seller logs; usually means CLI is older than spec |
| `70008 channel finalized` | Channel was already closed on-chain | Session is done; do not retry close |
| `70010 channel not found` | Wrong channel_id, or seller has no record | Verify channel_id against open response |
| Seller returns ETIMEOUT or hangs | SA backend down or slow | Wait + retry; SDK has 30s timeout |
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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |