okx-agent-payments-protocol

OKX Agent Payments Protocol（ディスパッチャー）

agent a2mcp invoke で開始した有効なマーケットプレイスの A2MCP 呼び出しについては、確認、支払い、結果の表示まで ../okx-ai/references/a2mcp/invoke.md に従ってください。呼び出しに紐付いた paymentId によって、ここで新たな一般的な見積もりや確認のフローが始まることはありません。

最初にお読みください — トリガー時はテキストを一切出力しないこと＋ユーザーの確認ゲートを絶対に省略しないこと。

402（またはトリガーワード）を検出してから、最初のユーザー向けカード（ステップ A3.5 の推奨カード、またはステップ A4 の確認カード）を表示するまで、ユーザーに見えるテキストを一切出力しないでください。「402 を受信しました」「OKX Agent Payments Protocol がトリガーされました」「N 個のスキームを検出しました」、スキーム／ネットワーク／トークン／金額の列挙、「スキルを読み込み中」など、いかなる言語でも出力してはいけません（同じ禁止事項は、他の言語における同等の表現にも適用されます）。スキル読み込みのツール呼び出しは実行してかまいませんが、その前後に文章を出力してはいけません。

1 回の支払いにつき、確認カードを実行するのは必ず 1 枚だけです。A3.5 の推奨カード（候補が 2 つ以上あり、ユーザーが yes を選択した場合）か、A4 の確認カード（候補が 1 つの場合、またはユーザーが A3.5 の展開リストから別の候補を選択した場合）のいずれかです。「以前のユーザー設定」「手順の簡略化」「すでに一度確認済み」などを口実に、該当するカードを省略してはいけません。そのような設定は存在しません。同じ情報を載せた両方のカードを続けて表示してはいけません。A3.5.5 で yes を受け取ったら、ステップ A5 に直接進んでください。検出後、次にユーザーに見えるテキストは、必ず 2 枚のうちいずれかのカードにしてください。

支払い経路は、HTTP のシグネチャによって 3 種類に区別されます。accepts ベースの 402（v1 では本文内のチャレンジ、v2 では PAYMENT-REQUIRED ヘッダー）、WWW-Authenticate: Payment 402（チャネル対応、intent="charge" または "session"）、および a2a-pay（paymentId ベース、402 なし）です。共通の手順（検出 → デコード → 確認 → ウォレットの確認）を実行した後、該当するリファレンスに振り分けてください。

ユーザー向け用語 — 重要

ルール 1 — 常に「OKX Agent Payments Protocol」と呼び、必ず太字で表記してください。 ユーザーに表示されるメッセージでは、ユーザーの言語にかかわらず、正確な英語の用語 OKX Agent Payments Protocol を使い、常にマークダウンの太字（**OKX Agent Payments Protocol**）で囲んで強調してください。中国語の文中でも、固定の英語名詞句として扱ってください。プロトコルのリテラルと内部識別子は、CLI の呼び出し、HTTP ヘッダー、JSON ペイロード、コード内でのみ使用し、ユーザーには決して伝えないでください。

ルール 2 — プロトコルの内部検出について説明しないでください。 ディスパッチのロジック（検出されたヘッダー、読み込まれる参照、選択されたスキーム／インテント、TEE とローカルキーのどちらの経路か）は内部情報です。内部にとどめてください。ユーザーに伝える必要があるのは、（a）何に対する支払いか、（b）何を確認する必要があるか、（c）結果だけです。

ルール 2 の例外 — 限定的な例外。選択肢リストの中でのみ。 Step A3.5 では、リテラルの exact／aggr_deferred／charge をユーザーに提示できるのは、ユーザーが「ほかを表示」を選んだ後に表示される、展開された選択肢リストの中だけです。この時点で、ユーザーは明示的にスキームを選択しています。これらをデフォルトの推奨カード、「ほか N 件の方法」の要約行、状況説明、エラー表示、支払い後の要約、その他のどこにも表示してはいけません。推奨カードにはネットワーク／トークン／金額／受取人のみを表示し、スキーム名は決して表示しないでください。

ルール 3 — 外部で定義されたプロトコルのリテラルは、バイト単位で正確に保ってください。 JSON フィールド x402Version、HTTP ヘッダー X-PAYMENT／PAYMENT-SIGNATURE／PAYMENT-REQUIRED／WWW-Authenticate: Payment、参照 URL https://x402.org は、プロトコル／サーバーで必要とされる箇所では、必ずそのまま記載してください。これらは外部で定義されており、変更すると相互運用性が損なわれます。CLI のサブコマンド名（onchainos payment pay／pay-local／charge／session ...／a2a-pay ...）はこの CLI 独自のインターフェースであり、変更される場合があります。CLI の呼び出しやコードでは現在の名前を使用できますが、ユーザーには決して伝えないでください（ルール 2）。

例

(EN) Preparing a payment via the **OKX Agent Payments Protocol**. Here are the charge details — please confirm before I proceed… 別の言語で説明する場合は、この導入文を翻訳し、OKX Agent Payments Protocol は英語の名詞句のまま太字で記載してください。

進行状況の説明もユーザー向けです — ルール 1〜3 は引き続き適用されます。

時間のかかる処理（デコード → 確認 → ウォレット確認 → 署名 → リプレイ）では、状況を伝えたくなります。すべての進行状況メッセージ（「現在〜しています」やその中国語訳）はユーザー向けです。ステップ名や参照名／スキーム名は内部情報です。ユーザーに伝えてはいけません。次の例に従ってください。

言ってはいけないこと	言うべきこと
「HTTP 402 を検出したため、OKX Agent Payments Protocol を開始します」／「PAYMENT-REQUIRED を検出し、exact を読み込みます」	(無言 — 検出／ルーティングは内部処理です)
「CLI が exact を選択し、PAYMENT-SIGNATURE ヘッダーを組み立てています」／「TEE 経路を使用しています」	「署名が完了しました。リクエストをリプレイしています」
「2 つのスキームを検出しました：exact（USD₮0）、aggr_deferred（USDG）」／「候補を絞るために残高を確認しています」	(無言 — 列挙と残高確認は内部処理です。ユーザーに表示するのは推奨カードのみです)
「セッション／チャージモードに入ります」	「チャネルを開きました」— 内部モードではなく、ユーザーから見える結果を説明します
「以前の設定に基づき、再確認なしで支払います」	(禁止 — そのような設定はありません。確認は毎回必須です)

これらのルールは、ほかの言語で説明する場合にも同様に適用されます。英語の文言だけでなく、「言ってはいけないこと」／「言うべきこと」の例が示す意図に従ってください。

これらのルールは常に優先され、必ず適用されます — 状況説明が内部情報を漏らすか判断に迷う場合は、上の表の例と照らし合わせ、何も伝えないでください。

トリガー（全リスト）

• EN: 402、payment required、x402、x402Version、X-PAYMENT、PAYMENT-REQUIRED、PAYMENT-SIGNATURE、WWW-Authenticate: Payment、permit2、upto、従量課金、チャネルのオープン／クローズ／トップアップ／決済、バウチャー、セッション決済、channelId、channel_id、paymentId、a2a_、支払いリンクの作成、支払いリンク、支払い状況
• subscribe / subscription / recurring payment / recurring charge / 「毎月支払う」 / cancel subscription / upgrade plan / downgrade plan → period スキーム（references/subscription.md を参照）
  • 例外： メッセージに jobId / subId / ASP / provider / trial / renew / deliver / periodCount / subscription task が含まれる場合は、Agent Commerce サブスクリプションタスク（月額サービス契約）です。代わりに okx-ai にルーティングしてください。
• 同じトリガー語彙は、他の言語での同等表現にも適用されます（例：中国語のサブスクリプション／定期課金に関する用語も、同じように period スキームにルーティングします）。
• 対象外：エージェントマーケットプレイスの AI サービス／ASP サブスクリプション（文脈：ASP / Agent#N / 任务 / 试用期 / 服务方、かつ 402 オファー／リソース URL／paymentId がない場合）は okx-ai（onchainos agent my-subscriptions / subscribe-detail）に該当し、period スキームには該当しません。「my subscriptions / 我的订阅」のみで、どちらのシグナルもない場合は、period と決めつけずにユーザーに一度確認してください。

channel_id またはセッションの文脈で close / topup / settle / voucher / refund が使われている場合は、MPP のセッション中操作です → references/session.md

事前確認

事前確認：各スレッドの開始時に、../okx-agentic-wallet/_shared/preflight.md の確認を完了してください。見つからない場合は、_shared/preflight.md を読んでください。

コマンドルーティングとリファレンスマップ

各 402 シグナル（または paymentId）→ CLI コマンド → リファレンス。詳細なゲーティングとデコード／確認の手順は、以下の Path A／Path B に記載されています。

シグナル	コマンド	リファレンス
402 + PAYMENT-REQUIRED（v2）／本文の x402Version（v1）— exact／exact+Permit2／upto／aggr_deferred のいずれか、または複数の accepts[] スキーム	Primary — Path A: payment quote <url> → 確認 → payment pay --payment-id --yes。単一スキームと複数スキームで、同じ quote フローを使います（CLI がデコード、変換、残高確認、署名、再送を行い、レシートを返します）。生の 402 をすでに curl していても、payment quote <url> から再度実行してください。ヘッダーを手動で組み立てたり、署名のみの処理へ直接進んだりしないでください。互換用のみ： quote を利用できない場合は、payment pay --payload [--selected-index]（署名のみ＋手動再送）を使用します。	成功パスではリファレンスを読み込みません。次の場合に限り references/accepts-schemes.md を参照します：支払い後にスキーム固有のレシートを読み取る場合、Permit2 allowance insufficient の一回限りの承認、pay-local、pay --payload 互換パス、またはレガシー x402 v1（スキームは CLI 出力のフィールドで判別できます。permit2Authorization = upto／exact+Permit2、sessionCert = aggr_deferred、authorization = exact）
scheme == "period"（別名 permit2_subscription）の accepts[] エントリーを含む 402 オファー — 定期／サブスクリプション課金	payment subscription subscribe/access/change/cancel/cancel-pending/my-subscriptions/allowance-status	references/subscription.md
402 + WWW-Authenticate: Payment、intent="charge"	payment charge --challenge	references/charge.md
402 + WWW-Authenticate: Payment、intent="session"（またはセッション中の channel_id）	payment session open/voucher/topup/close	references/session.md
paymentId／a2a_… リンク／支払いリンクの作成または確認	payment a2a-pay create/pay/status	references/a2a_charge.md
A2MCP／402 エンドポイント URL、「このエンドポイントに支払う」、エントリー A／B の支払いノード	payment quote <url> [--param k=v ...] [--method GET | POST | ...]	（インライン — Path A）
A2MCP MCP トランスポートエンドポイント（URL が /mcp または /sse で終わる、text/event-stream／JSON-RPC を返す、またはツール名がある場合）	payment quote <url>（検出 → mcpTools[]）→ payment quote <url> --tool <name> --param k=v（402 を発生させる）→ payment pay --payment-id <id> --yes	references/a2mcp-mcp.md
ユーザーが見積もり済みの支払い（選択した通貨／金額／スキーム）を確認した場合	payment pay --payment-id <id> [--selected-index <n>] --yes	（インライン — Path A）
PAYMENT-RESPONSE ヘッダーまたは課金レシートをデコードする必要がある場合	payment decode-receipt (--header <b64> | --receipt <json>)	（インライン — 読み取り専用）

成功パスではリファレンスを読み込まないでください。 Path A の主要フローでは、onchainos payment pay --payment-id --yes が署名、再送、決済済みレシートの返却まで直接行います。そのため、references/accepts-schemes.md は完全にスキップしてください（これは accepts[] スキームが単一の場合も複数の場合と同様です）。互換用の pay --payload パスでは、CLI が authorization_header を返し、自分で再送します。成功時は同じルールに従い、リファレンスは不要です。references/accepts-schemes.md を読み込むのは、失敗時／レガシーパスに限ります。Permit2 allowance insufficient の場合は references/accepts-schemes.md（一回限りの承認）、レガシー x402 v1 の生の証明の場合は「Legacy: x402 v1」セクションを参照してください。charge／session／a2a_charge は複数フェーズのフローであるため、常に読み込みます。

セッション中のチャネル操作（有効な channel_id が指定された close／topup／settle／voucher／refund。新しい 402 の有無は問いません）→ ここにとどまり、該当フェーズの references/session.md に直接進んでください。別個の close-channel／topup-channel／settle-channel ツールを探してはいけません。これらはすべて onchainos payment session ... のサブコマンドです。

---

Path A: HTTP 402

パス A（accepts ベース）：見積もり → 確認 → 支払い — 推奨される2ラウンドフロー

accepts ベースの402 / A2MCP エンドポイントでは、機械的な処理はすべて CLI が行います。 必要な推論ラウンドは正確に2回です。（WWW-Authenticate: Payment のチャージ／セッションチャレンジの場合は、これをスキップして、以下のプロトコル検出手順を使用してください。）

ステップ A1 — パラメーターの抽出（ラウンド1）

ユーザープロンプト（エントリー A）またはタスクの支払いノード（エントリー B）から、 エンドポイントの url と、判明しているビジネスパラメーターを抽出します。自分で curl、デコード、 変換を行わないでください。

ステップ A2 — 見積もり

実行します：onchainos payment quote <url> [--param key=value ...] [--method GET|POST|...] CLI がエンドポイントをプローブして402を解析し、ウォレット残高を確認し、候補を順位付けして、 paymentId を書き込みます。

プローブメソッド — CLI はデフォルトで GET を使用してプローブします。サービスの 宣言またはユーザーの意図から、エンドポイントへの最初の呼び出しが GET ではないとわかる 場合（例：Bazaar の outputSchema.method ／ビジネスのマインドマップで "POST" と宣言されている、 またはユーザーが「このエンドポイントにPOSTして」と指示している場合）は、--method POST（または 正しい動詞）を指定してください。判明しているビジネスパラメーターは、クエリー文字列ではなく JSON ボディに格納されます。 デフォルトの GET で POST 専用の A2MCP エンドポイントをプローブすると、405 または402以外の レスポンスが返り、支払いチャレンジではなく endpoint_unreachable になることがあります。（支払い後の再実行では outputSchema.method が引き続き使用されます。このフラグで修正されるのは最初のプローブのみです。）

MCP トランスポートの A2MCP（tools/call ゲート型）。 payment quote が data.mcpTools[] を返した場合（URL が /mcp|/sse で終わる、または text/event-stream / JSON-RPC が返された MCP タイプのエンドポイントです）、ペイウォールは URL そのものではなく、ツール呼び出しの層にあります。references/a2mcp-mcp.md を読み、 その手順に従ってください：ユーザーの意図に応じて mcpTools[] からツールを選び（曖昧な場合は AskUserQuestion を使用）、ツールの inputSchema から --param key=value を組み立て、 payment quote <url> --tool <name> --param … を再実行して402を発生させ、paymentId を取得します。その後、 通常のステップ A3 確認 → ステップ A4 payment pay --payment-id <id> --yes> に進みます。JSON-RPC を手書きしたり SSE を解析したりしないでください。CLI が initialize → tools/list → tools/call のハンドシェイクと SSE の解析を内部で行います。

data を読みます：

• summary — ユーザー向けの一文です。ここでは needsConfirm は常に true です。
• candidates[]（recommended:true を含むもの）と alternatives[] — 順位付けされたスキームです。それぞれに acceptsIndex が含まれます。これは accepts[] 内の位置です（順位付けされた順序は accepts[] と異なるため、候補のリスト上の位置をインデックスとして扱わないでください）。
• すべての候補には balanceStatus（sufficient / insufficient / unavailable）、availableAmount、requiredAmount、および shortfall も含まれます。ユーザーが支払い方法を選択する前は、各方法についてステータスのみを表示し、不足している場合は不足額も併記してください — depositAddress を表示したり、QR コードを生成したり、資金追加の通知を送ったりしないでください。
• missingParams[] + merchantBody — CLI が補完できなかったパラメーターです。残りの情報は merchantBody から確認してください。
• walletError — login_required の場合は、ユーザーにログインを案内してから見積もりを再実行してください。
• すべての候補で recommended:null の場合 ⇒ どの方法でも残高がありません。リストを提示してユーザーに尋ねてください。

ステップ A3 — 確認（2 回目）— 必須、省略禁止

支払い条件をすべて確認してください。ステップ A4 に表示される内容と同じものを提示し、署名する前に支払先を必ず購入者に確認してもらいます。十分な候補がある場合は AskUserQuestion を使用してください。候補が不十分な場合は、以下で説明する資金不足カードが唯一の確認画面になります。

• ネットワーク：選択した候補の chainName（chainId）
• トークン／金額：amountHuman tokenSymbol（upto スキームの場合、これは認可上限です。固定額ではなく「最大 amountHuman」と表示してください）
• スキーム：選択した候補の scheme
• 支払先：チャレンジの recipient（payTo アドレス）
• missingParams があれば、それも提示します

選択した候補が insufficient の場合は、資金調達を優先するカードを 1 枚表示してください。

1. onchainos agent funding-notice --chain <chainName> --currency <tokenSymbol> --available <availableAmount> --required <requiredAmount> --shortfall <shortfall> --deposit-address <depositAddress> --deposit-chain <chainName> --reason payment-402 --format json を実行します。
2. contentCanonical をローカライズし、残高、アドレス、4 つの資金調達方法、およびガスに関する説明は 1 つだけ残してください。X Layer の場合は 資金到着後、オンチェーンのガス代は無料です。それ以外のチェーンでは、一般的なガスに関する警告を表示します。「OKX から出金」の手数料に関する注記（取引所で出金手数料が発生する場合があります）は残し、取引所からの出金が無料だとは決して伝えないでください。
3. displayMode に従います。image-notify の場合は user-notify --image-path を 1 回呼び出します。terminal-unicode の場合は terminalQr を含めます。QR に失敗した場合は、全文とアドレスを表示します。

funded、cancel、および利用可能な場合に限り choose another payment method を提示してください。「そのまま支払う」は決して提示せず、一般的な「はい／いいえ」も尋ねないでください。次のように処理します。funded → 再見積もりします。代替手段 → candidates[] + alternatives[] の中から十分な他の候補を表示します（期限切れの場合は、先に再見積もりします）。その後、acceptsIndex を使用して 1 回確認します。cancel → 停止します。資金不足を承知のうえで支払うという、明示的かつ一義的な自発的リクエストは、その 1 回限りの認可として扱います。曖昧な「はい」は認可として扱いません。funding-check を実行したり、残高による厳格なゲートを追加したりしないでください。

選択した候補の acceptsIndex を --selected-index として渡してください（candidates[]／alternatives[] 内での位置ではありません）。これにより、CLI はユーザーが承認した候補に限って正確に署名します。支払いの前に必ず停止して確認してください。自動で支払ってはいけません。

ステップ A4 — 支払い

実行します：onchainos payment pay --payment-id <id> --selected-index <n> --yes [--param key=value ...] --yes は必須です（資金移動を伴う確認ゲートです）。pay は見積もられたペイロードに署名して再送し、レシートを返します。402 を再取得することはありません。data.status を確認してください。

• success → txHash を報告します。（エントリー B）タスクシステムがノードを支払い済みにします。
• failed → data.error を提示し、再試行を提案します。
• pending → ポーリングするか、終端状態になるまで待ってから続行します。

返された PAYMENT-RESPONSE ヘッダーまたは課金レシートをいつでもデコードするには、onchainos payment decode-receipt (--header <b64> | --receipt <json>) を実行します。

---

ステップ A1：元のレスポンスから開始する（レガシー／WWW-Authenticate の詳細）

accepts ベースの 402 → Path A の payment quote に戻ってください。 以下の手順は、レガシーな手動経路（デコード → 組み立て → 自分で再送）と、WWW-Authenticate: Payment のチャージ／セッションチャレンジに共通するデコードの詳細です。手元の 402 が accepts ベース（PAYMENT-REQUIRED ヘッダー v2／x402Version ボディ v1 — exact／exact+Permit2／upto／aggr_deferred。単一スキームでも複数スキームでも）である場合は、ここで続行しないでください。生の 402 を破棄し、payment quote <url> を使って Path A から再開してください。見積もりフローでは、同じ必須の確認ゲートを通過し、単一スキームでも複数スキームでも同じレシートスキーマが返されます。単一スキームだからといって、quote を省略できるわけではありません。以下に進むのは、WWW-Authenticate: Payment のチャージ／セッションの詳細を扱う場合、または payment quote が本当に利用できず、明示的な pay --payload の署名のみの互換経路にフォールバックする必要がある場合に限ります。

元の HTTP レスポンスはすでに取得しています。402 でない場合は、ボディをそのまま返します。それ以外の場合は → ステップ A2 に進みます。

ユーザーのプロンプトに含まれるリクエストパラメーターをすべて取得します（例：「サンフランシスコの天気」→ city=San Francisco、token=0x…、「中国語に翻訳」→ lang=zh）。ステップ A3-Params の計画用に、それぞれを name → value として記録します。ここで与えられた値を再度尋ねることはありません。確認カードに表示するだけです。最初のリクエストで必要なかった場合も保持してください。有料で再送する際に、販売者が必要とする可能性があります。

ステップ A2：プロトコルを検出する

Priority 1: response.headers['WWW-Authenticate']
  starts with "Payment "        → continue at Step A3-WWW-Authenticate
Priority 2: response.headers['PAYMENT-REQUIRED']
  base64-encoded JSON           → continue at Step A3-Accepts (v2)
Priority 3: response body JSON has "x402Version"
                                → continue at Step A3-Accepts (v1)
Otherwise                       → not a supported payment protocol, stop

両方のインジケーターが存在する場合 — WWW-Authenticate のインテントに基づいて分岐します。

• intent="session" が accepts ベースのオプションとともに提示された場合 → 停止してユーザーに尋ねます。

  サーバーは OKX Agent Payments Protocol を介して、2 種類の支払い方法を提示しています。

  1. セッション（複数リクエスト） — チャネルを開き、リクエストごとにバウチャーを発行します
  2. 一回限りの購入

  どちらを使用しますか？

  オプション 1 → ステップ A3-WWW-Authenticate（セッション経路）に進みます。オプション 2 → セッションインテントを除外し、accepts オプションを使ってステップ A3-Accepts に進みます。

• intent="charge" が accepts ベースのオプションとともに提示された場合 → すべてのオプションが一回限りです。セッションと一回限りの購入のどちらかを尋ねるプロンプトは表示しないでください。両方のプロトコルファミリーをデコードし（ステップ A3-Accepts とステップ A3-WWW-Authenticate）、候補を統合して、ステップ A3.5 で推奨を処理します。

ステップ A3-Accepts：デコード

402 ペイロードを自分でデコードし、表示と推奨のみに使用します — CLI との往復はありません。

raw_402 = response.headers['PAYMENT-REQUIRED']   // v2 (base64-encoded JSON)
       or response.body                          // v1 (already plain JSON)

decoded = JSON.parse(atob(raw_402))              // v2; for v1 it's already JSON: JSON.parse(response.body)

表示用に抽出します。

accepts = decoded.accepts
option  = decoded.accepts[0]       // for display only

raw_402 はそのまま保持してください — ステップ A6 で onchainos payment pay --payload に直接渡します（CLI が再度デコードして署名します）。ローカルでのデコードは表示専用です。再エンコードや組み立ては絶対に行わないでください。

ステップ A3-WWW-Authenticate：デコード

WWW-Authenticate ヘッダーを解析します。

Payment id="...", realm="...", method="evm", intent="...", request="<base64url>", expires="..."

request を base64url デコードして JSON ボディを取得します。以下を保存します。

intent              charge | session
amount              base units string (e.g. "1000000")
currency            ERC-20 contract address
recipient           merchant payee address
methodDetails:
  chainId           EVM chain ID (e.g. 196 for X Layer)
  escrowContract    REQUIRED for session, ABSENT for charge
  feePayer          true (transaction mode) | false (hash mode)
  splits            optional, charge only, max 10 entries
  minVoucherDelta   optional, session only
  channelId         optional, session topUp/voucher only — pre-existing channel
suggestedDeposit    optional, session only — suggested initial deposit
unitType            optional — "request" | "second" | "byte" etc.

メソッドの確認 — ここでサポートされるのは method="evm" のみです。method が "tempo"、"svm"、"stripe" などの場合 → 停止し、このディスパッチャーでは処理できないことをユーザーに伝えます。

チャレンジの有効期限 — expires=...（ISO-8601）が過去の場合、チャレンジは無効です。署名する前に元のリクエストを再送して、新しい 402 を取得してください。有効期限切れのチャレンジは 30001 incorrect params で失敗します。

amount を最小単位から人間が読みやすい形式に変換します（_shared/amount-display.md を参照）。

ステップ A3-Params：リクエストパラメーター計画の作成

ステップ A3 のデコード後、確認カードを表示する前に実行します。 支払い条件に加えて、販売者が有料で再送するリクエストに必要なパラメーターとその渡し方を指定する場合があります。支払いとともにユーザーがパラメーターを確認でき、再送時に正しく付加されるよう、パラメーター計画を作成します。

パラメーター計画は { name, value, carrier, required, source } のリストで、carrier ∈ {query, body, header, path} です。販売者が指定したパラメーターも、ユーザーが指定したパラメーターもない場合は、計画は空となり、再送時に変更はありません。

ソース 1 — Bazaar の outputSchema.input（推奨）

デコードした 402（または任意の accepts[i]）に outputSchema.input が含まれている場合は、解析します。

フィールド	用途
input.type	"http" → ここで処理します。"mcp" → 対象外のため、パラメーターの組み立てをスキップします。
input.method	再実行に使用するメソッドです（元のメソッドと異なる場合があります）。GET／HEAD／DELETE → パラメーターはクエリに指定します。POST／PUT／PATCH → 本文に指定します（input.bodyType：json／form-data／text）。
input.queryParams／input.body／input.pathParams／input.headers	各転送先（クエリ／本文／パス／ヘッダー）のパラメーターです。

JSON Schema の properties と required から、各パラメーターの型と必須かどうかがわかります。宣言されたパラメーターごとに計画エントリーを 1 つ作成します。

ソース 2 — Bazaar 以外（保守的な対応）

outputSchema.input がない場合、販売者が明示的に示したときのみパラメーターを追加します。決して作り出さないでください。

• レスポンスの本文に要件（required／params／parameters／fields／inputSchema）が記載されている、または
• エラーメッセージに不足しているパラメーターが明記されている（例：missing required query param "city"）、または
• ドキュメントに記載されたレスポンスのヘッダーがパラメーターを求めている。

曖昧な場合は何も追加せず、そのまま再実行します。

値の入力

各エントリーについて、value を次の順に解決します。（1）ユーザーのプロンプト（ステップ A1）→ source=prompt とし、再度尋ねません。（2）会話のコンテキスト → source=context。（3）まだ不足しており、必須の場合 → すべてをまとめて 1 つの質問でユーザーに尋ねます（正当なゲートであり、説明ではありません。ZERO-TEXT-ON-TRIGGER はこれを禁止しません）。任意で未解決のパラメーターは省略します。

ステップ A3.5：複数スキームの推奨（該当する場合）

該当するのは、候補プール全体に {exact, aggr_deferred, charge, period} のうち2 つ以上が含まれる場合のみです。それ以外は、利用可能な候補 1 つを使ってステップ A4 に進みます。

402 の accepts[] に {exact, aggr_deferred, charge, period} のうち 2 つ以上が含まれる場合は、references/multi-scheme.md を読み込みます。period は継続課金の選択肢として扱い、ユーザーの意図が単発の呼び出しではなく継続的なサブスクリプションである場合にのみ推奨します。

該当する場合は、references/multi-scheme.md を読み込み、最初から最後までその指示に従います。選択された候補が返され、再開位置が示されます。ユーザーが別の選択肢を選んだ場合はステップ A4、yes で承認した場合はステップ A6 に直接進みます（A5 のウォレット確認はすでに完了しています）。

ステップ A4：支払いの詳細を表示して停止する

A3.5.5 でユーザーが yes と回答して推奨案を承認した場合は、このステップを完全にスキップします（カードにはネットワーク／トークン／金額／受取人がすでに表示されています）。ステップ A5（A3.5.2 ですでにログインが処理されている場合は何も行いません）→ A6 に進みます。

次のいずれかに該当する場合は、このステップを通常どおり実行します。

• ステップ A3.5 が実行されなかった場合（候補が 1 つの経路）、または
• ユーザーが A3.5 の展開リストから別の候補を選んだ場合（選択された候補には、まだ詳細な確認が必要です）。

実行時の必須事項： 詳細を表示し、ユーザーの明示的な確認を待つために停止します。ユーザーが確認するまで、onchainos wallet status やその他のツールを呼び出してはいけません。

見積もりフローの候補では、balanceStatus も表示します。不足している場合は、 availableAmount、requiredAmount、shortfall を表示し、ステップ A3 の 資金調達を最優先する単一カードとアクションテーブルに従います。

accepts ベースの 402（PAYMENT-REQUIRED ヘッダー v2／x402Version 本文 v1）の場合：

このリソースの利用には、OKX Agent Payments Protocol による支払いが必要です。

• ネットワーク：<チェーン名>（<option.network>）
• トークン：<トークンシンボル>（<option.asset>）
• 金額：<人間が読みやすい金額>（v2 の場合は option.amount、v1 の場合は option.maxAmountRequired から取得し、トークンの小数桁数を使って最小単位から変換します）。upto スキームでは、この金額は固定料金ではなく承認上限です。「最大 <amount>」と表示します。
• 支払先：<option.payTo>
• リクエストパラメーター（ステップ A3-Params のプランが空の場合、この行は完全に省略します）：パラメーターごとに <name> = <value> → <carrier: query | body | header | path> の形式で 1 行ずつ表示

支払いを続行しますか？（yes／no）

WWW-Authenticate: Payment 402 の場合：

このリソースの利用には、OKX Agent Payments Protocol による支払いが必要です。

• 支払いタイプ：<1 回限りの支払い | セッション（複数のリクエスト）>（「1 回限りの支払い」／「セッション（複数のリクエスト）」と表示します。「単一購入」としてはいけません。別の言語に翻訳する場合も、同じ区別を維持します）
• ネットワーク：<チェーン名>（eip155:<chainId>）
• トークン：<シンボル>（<通貨アドレス>）
• リクエストごとの金額：<人間が読みやすい金額>（アトミック単位：<amount>）
• 支払先：<受取人>
• ガス代の負担者：<サーバー（トランザクションモード） | 自分でブロードキャスト（ハッシュモード）>
• 分割受取人（1 回限りの場合のみ。存在する場合）：<N 人の他の受取人にも分配されます>
• 推奨プリペイド残高（セッションの場合のみ。存在する場合）：<人間が読みやすい金額>
• リクエストパラメーター（ステップ A3-Params のプランが空の場合、この行は完全に省略します）：パラメーターごとに <name> = <value> → <carrier: query | body | header | path> の形式で 1 行ずつ表示

支払いを続行しますか？（yes／no）

• ユーザーが確認した場合 → ステップ A5。
• ユーザーが拒否した場合 → 停止します。支払いもウォレット確認も行いません。

ステップ A5：ウォレットの状態を確認する（ユーザーが明示的に確認した後のみ）

onchainos wallet status

• ログイン済み → ステップ A6。
• 未ログイン（accepts ベースの経路） → (1) ウォレットログイン（TEE 署名）または (2) ローカル秘密鍵（onchainos payment pay-local。exact + EIP-3009、exact + Permit2、upto をサポート。aggr_deferred はサポートされず、TEE セッションキーが必要です）のどちらを選ぶか、ユーザーに確認します。ユーザーが選択するまで、ファイルを読み込んだり環境変数を確認したりしてはいけません。
• 未ログイン（WWW-Authenticate: Payment の経路） → onchainos wallet login でログインするようユーザーに確認します。この経路は TEE 専用です。ローカルキーへのフォールバックはありません（フォールバックがあるのは accepts ベースの経路のみです）。

ステップ A6：スキーム／インテントのリファレンスに進む

パス

アクション

accepts ベース（PAYMENT-REQUIRED ヘッダー v2／x402Version ボディ v1）

プライマリ — パス A： すでに payment quote <url> → 確認 → payment pay --payment-id --yes のフロー（パス A の冒頭）に進んでいるはずです。このフローは署名し、再送して、レシートを返します。手動で組み立てる必要はなく、成功時にリファレンスを読み込む必要もありません。これは単一の accepts[] スキームでも、複数スキームでも同じです。 互換用／フォールバックのみ（quote が利用できない場合、または明示的なレガシーリクエストの場合）：onchainos payment pay --payload '<raw_402 from Step A3>' を実行します。Step A3.5 が実行され、ユーザーが accepts ベースの候補を選んだ場合は、CLI がそのエントリに正確に署名するよう --selected-index <index in decoded.accepts> を追加します。候補が 1 つの場合は省略します（CLI が自動選択します）。CLI はデコードし、選択されたアカウントで署名して、{authorization_header, header_name, scheme, wallet} を返します。手動で組み立てる必要はありません。その後、以下の再送に進みます。 ユーザーがローカルキーのフォールバックを選んだ場合は、代わりに onchainos payment pay-local --payload '<raw_402>' を実行します（成功時のルールは同じです。exact + EIP-3009、exact + Permit2、upto をサポートします。aggr_deferred は TEE 専用です）。 Permit2 allowance insufficient エラー（upto ／ exact + permit2 で、そのトークンに対する初回の支払いの場合）→ 一度限りの承認手順について references/accepts-schemes.md を読み込み、その後、支払いを再試行します。 レガシー v1 — CLI が生の証明（authorization_header を含まない signature + authorization）を返した場合 → references/accepts-schemes.md を読み込み、「Legacy: x402 v1」セクションに従って X-PAYMENT ヘッダーを組み立てます。

| period（サブスクリプション／permit2_subscription） | 「Decide operation」（subscribe、access、change、cancel の選択）にある references/subscription.md を読み込みます。初回のオファー → payment subscription subscribe、すでに有効なリソース → payment subscription access（再サブスクリプションはしません）、アップグレード／ダウングレード → change、終了 → cancel ／ cancel-pending。 | | WWW-Authenticate: Payment、intent="charge" | 「Decide mode」にある references/charge.md を読み込みます。 | | WWW-Authenticate: Payment、intent="session" | 「Phase S1: Open Channel」にある references/session.md を読み込みます（または、ユーザーが有効な channel_id でセッションの途中にいる場合は S2 ／ S2b ／ S3 に進みます）。 |

再送（成功パス — リファレンス不要）： 返されたヘッダー（<header_name>: <authorization_header>、またはレガシー v1 用に組み立てた X-PAYMENT）を使って元のリクエストを再送し、HTTP 200 を確認します。PAYMENT-RESPONSE ヘッダーがあれば、ローカルでデコードして（echo '<value>' | base64 -d | jq .）、status ／ transaction ／ amount ／ payer を確認します。決済の詳細をユーザーに伝え、会話の流れに沿って次の手順を提案します。内部のフィールド名やスキル ID は決して公開しないでください。

---

パス B：a2a-pay（paymentId ベース、402 なし）

ユーザーが paymentId ／ a2a_... リンクに言及する、「支払いリンクを作成して」と頼む、または a2a 支払いのステータス確認を求めるなど、このパスを明示的に呼び出した場合に使用します。

ステップ B1：役割を特定する

ユーザーの発言…	読み込むリファレンス	役割
「支払いリンクを作成」／「支払いを生成」／--amount／--recipient	references/a2a_charge.md → 「Seller — Create」	売り手
支払い対象の paymentId ／ a2a_... を提示	references/a2a_charge.md → 「Buyer — Pay」	買い手
paymentId を提示し、ステータスを尋ねる	references/a2a_charge.md → 「Status — Query」	どちらでも可

ユーザーが paymentId を提示せずに「支払いたい」とだけ言った場合は、停止して、売り手が発行した paymentId を提示するようユーザーに依頼します。それ以外の操作は試みないでください。

ステップ B2：ウォレットのステータス

create と pay のどちらにも、有効なウォレットセッションが必要です。onchainos wallet status を実行します。

• ログイン済み → 続行します（リファレンスを読み込み、その指示に従います）。
• 未ログイン → onchainos wallet login でログインするようユーザーに依頼します。有効なセッションがない状態で署名してはいけません。

ステップ B3：references/a2a_charge.md に引き継ぐ

リファレンスには、作成／支払い／ステータスの一連のフロー（自動ポーリングと信頼委任に関する注記を含む）がすべて記載されています。購入者側の信頼は上流に委任されており、購入者はサーバー上のチャレンジで宣言された内容に署名します。

---

共通事項

販売者のエラーを読み取る（WWW-Authenticate: Payment / a2a-pay）

販売者が拒否した場合、生の JSON や数値コードだけを表示してはいけません。優先順位に従って、人が読める説明を抽出し、最初に見つかった空でない値を使用します。

1. body.reason（mppx、OKX TS Session）
2. body.detail（RFC 9457 ProblemDetails）
3. body.message
4. body.msg（OKX SA API）
5. body.error
6. body.title（RFC 9457 の短いタイトル — フォールバックのみ）
7. 該当なし — 本文全体を整形し、HTTP ステータスを追加

形式：

販売者によって拒否されました：<reason text>（コード <code if present>、HTTP <status>）

金額表示

ユーザー向けの金額はすべて、人間可読形式と最小単位形式の両方で表示します：<human> (<atomic>)。例：0.0004 USDC (400)。小数点以下の桁数の表と不明なシンボルのフォールバックについては、_shared/amount-display.md を参照してください。

次のステップを提案する

支払いとレスポンスが成功した後、会話の流れに沿って次のステップを提案します。

完了した処理	提案
payment quote が needsConfirm:true を返した	1 回だけ確認します。十分な情報がある場合は AskUserQuestion を使用し、不十分な場合は QR コードを付加した適応型確認（image-notify PNG／terminal-unicode）を使用します。その後、payment pay --payment-id <id> --selected-index <n> --yes を実行します
payment quote が data.mcpTools[]（MCP トランスポート、paymentId なし）を返した	ユーザーの意図に応じてツールを選び、次に payment quote <url> --tool <name> --param k=v … を実行して 402 を発生させます（references/a2mcp-mcp.md を参照）
payment pay が status:"success" を返した	txHash を報告します。PAYMENT-RESPONSE ヘッダーがある場合は、payment decode-receipt --header <b64> を実行します
payment pay が status:"pending" を返した	payment a2a-pay status --payment-id <id> --wait（a2a）を実行するか、ファシリテーターのコールバックを待ちます
HTTP 402 の再送が成功した	okx-agentic-wallet で残高への影響を確認するか、同じリソースに別のリクエストを送信します
a2a の支払いが成功した	okx-agentic-wallet で支払い後の残高を確認します
再送で 402（期限切れ）が発生した	新しい署名で再試行します
チャネルセッションが進行中	次のリクエストが届いたらバウチャーを発行し、完了したらチャネルを閉じます