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/multi-scheme.md

View on GitHub
# Multi-scheme recommendation (SKILL.md Step A3.5)

> **CLI down-sink:** balance-fetch, has-balance filtering, tie-break
> scoring, and recommendation-card math now live in the CLI. `onchainos payment
> quote` returns `candidates` / `alternatives` already ranked โ€” present
> `recommended:true`, confirm the selection, then `payment pay --payment-id`.
> This file is retained for the legacy manual A3.5 path only.

Loaded from `SKILL.md` **Step A3.5** when the combined candidate pool contains **2 or more** of `{exact, aggr_deferred, charge}`. Single-candidate flows skip this file and go straight to Step A4. This file owns the full recommend-and-confirm flow and hands the **selected candidate** back to Step A4 / Step A6.

> **๐Ÿ”‡ Silence rule for A3.5 internals.** Substeps A3.5.1โ€“A3.5.4 (candidate enumeration, wallet-status check, balance fetch, address/chain-mapping normalization, balance filtering, tie-breaker application) are **internal** โ€” produce **no user-facing narration** during them. The only A3.5 output the user sees is (a) the login prompt in A3.5.2 *if* the wallet isn't logged in, and (b) the recommendation card / alternatives list in A3.5.5. Do **not** announce "I'm checking your balance", "Let me verify the chain mapping", "After filtering, X candidates remain", "Per Rule 2 carve-outโ€ฆ", or any other progress chatter between Step A3 finishing and the recommendation card appearing. Just go silent and emit the card.
>
> **๐Ÿšซ Exactly one user gate per payment, mandatory.** Per payment, the user sees exactly one confirmation surface: A3.5's recommendation card (when 2+ candidates and the user accepts with `yes`), OR A4's per-payment confirmation card (when there's only 1 candidate, OR when the user picked an alternative from A3.5's expanded list). Do not skip the applicable gate on your own initiative โ€” no "past preference", "streamlining", or "they confirmed once before" shortcuts; those preferences do not exist. Equally, do not duplicate gates: after a `yes` on A3.5.5, do NOT also render A4 with the same info.

## A3.5.1: Build the candidate pool

- Each entry in `accepts[]` โ†’ one candidate. Scheme = `accepts[i].scheme` (`exact` or `aggr_deferred`).
- A `WWW-Authenticate: Payment` 402 with `intent="charge"` โ†’ one candidate. Scheme = `charge`.
- `WWW-Authenticate: Payment` with `intent="session"` is **never** part of this pool โ€” it's handled by the session-vs-one-shot branch in Step A2.

Each candidate carries `{scheme, chainId, tokenAddress, tokenSymbol, amount (atomic), amountHuman, isMainnet}`. Determine `isMainnet` from the chain registry (`onchainos wallet chains` lists chain metadata).

## A3.5.2: Get wallet balance

- If a recent wallet-balance snapshot already exists in conversation context (from an earlier `onchainos wallet balance` call this session), **reuse it** โ€” do not re-query.
- Otherwise, check login first via `onchainos wallet status`:
  - **Not logged in** โ†’ ask the user to log in (the recommendation depends on knowing their balance). Don't fall back silently.
  - **Logged in** โ†’ query balance:

    ```bash
    onchainos wallet balance
    ```

## A3.5.3: Filter by has-balance

Keep only candidates where the wallet has a non-zero balance for the matching `(chainId, tokenAddress)`.

**Edge case โ€” zero candidates pass the filter**: list **all original candidates** to the user (no recommendation badge, no tie-breakers applied). User picks one; carry it to Step A4.

## A3.5.4: Tie-breakers (apply in order; stop when one wins)

If more than one candidate remains after A3.5.3:

1. **Smallest required payment amount โ€” same-symbol only.** Group remaining candidates by `tokenSymbol`. If they all share a single symbol, the one with the smallest `amountHuman` wins. If the remaining set spans multiple symbols, skip this rule.
2. **Mainnet over testnet.** Drop testnet candidates if any mainnet candidate remains. Different mainnets are equal โ€” no preference between e.g. Ethereum, Base, X Layer.
3. **Scheme priority:** `aggr_deferred` > `exact` > `charge`.

The survivor is the **recommended candidate**. The rest are **alternatives**.

## A3.5.5: Display the recommendation

**Carve-out scoping** โ€” the recommendation card itself does **NOT** contain a `Scheme:` line, and the "N other methods" summary line does **NOT** preview their schemes / amounts / tokens. Scheme literals appear **only** inside the expanded alternatives list, and only when the user explicitly asks for it. Render the card with `N = number_of_alternatives`:

> We recommend paying via the **OKX Agent Payments Protocol**:
>
> - **Network**: `<chain name>` (`eip155:<chainId>`)
> - **Token**: `<symbol>` (`<token address>`)
> - **Amount**: `<human> (<atomic>)`
> - **Pay to**: `<recipient>`
>
> `<N == 0 ? "No other methods available." : "There are <N> other supported method(s) you could use instead.">` Use the recommended method? (yes / show others)

**โš ๏ธ Do NOT inline alternatives in the summary line.** Forbidden: โŒ "There are 2 other methods (exact 0.001 USDโ‚ฎ0, charge 0.0005 USDโ‚ฎ0)". Required: โœ… "There are 2 other supported methods you could use instead." Detail only appears after the user picks "show others".

- **yes** (or `N == 0`) โ†’ the recommended candidate becomes the **selected candidate**; continue at Step A4.
- **show others** โ†’ only now expand the alternatives list, each row as `<index>. scheme=<exact | aggr_deferred | charge>, network=<โ€ฆ>, token=<โ€ฆ>, amount=<โ€ฆ>`. User picks one by index โ†’ that becomes the selected candidate; continue at Step A4.

## A3.5.6: Carry the selection forward

- **`accepts`-based selection** (`exact` or `aggr_deferred` from `accepts[]`) โ†’ remember the **index of the selected accept within `decoded.accepts`**. In Step A6 you pass it as `--selected-index <index>` so the CLI signs exactly that entry and cannot deviate from the user's choice.
- **`charge` selection** (from WWW-Authenticate) โ†’ in Step A6, take the WWW-Authenticate / `references/charge.md` path; ignore the accepts-based candidates entirely.

Step A4 (back in `SKILL.md`) now describes the **selected candidate**. Step A5's wallet-status check is already satisfied if A3.5.2 ran the login flow โ€” skip the re-check; just continue to A6.
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 CodeCodexUnverifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall