okx-agent-payments-protocol

OKX Agent Payments Protocol（Dispatcher）

对于由 agent a2mcp invoke 启动的活跃 marketplace A2MCP 调用，请按照 ../okx-ai/references/a2mcp/invoke.md 完成确认、支付和结果展示。其绑定的 paymentId 不会在此处启动新的通用报价或确认流程。

请先阅读 — 触发时零文本 + 绝不跳过用户关卡。

从检测到 402（或任何触发词）到显示第一张面向用户的卡片——A3.5 步骤的推荐卡片，或 A4 步骤的确认卡片——期间，不得输出任何用户可见文本。不得说“收到 402”“触发了 OKX Agent Payments Protocol”“检测到 N 种方案”，不得枚举方案／网络／代币／金额，也不得说“正在加载技能”——任何语言都不行（同样禁止其他语言中的对应说法）。技能加载工具调用可以运行，但不得输出任何附带说明文字。

每笔支付恰好执行一张确认卡片：A3.5 的推荐卡片（有 2 个或更多候选项，且用户选择 yes），或者 A4 的确认卡片（只有一个候选项，或者用户从 A3.5 展开的列表中选择了其他选项）。不得以“过去的用户偏好”“简化流程”或“已确认过一次”为由跳过适用的卡片——不存在这些偏好。不得连续显示两张包含相同信息的卡片——在 A3.5.5 中收到 yes 后，直接进入 A5 步骤。检测到触发条件后，下一条面向用户的文本必须是这两张卡片之一。

三种支付路径，根据 HTTP 特征区分：基于 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，并始终用 Markdown 粗体（**OKX Agent Payments Protocol**）包裹，以突出显示。即使在其他内容为中文的句子中，也将其保留为固定的英文名词短语。协议字面量和内部标识符仅用于 CLI 调用、HTTP 标头、JSON 负载和代码 — 绝不可在面向用户的内容中提及。

规则 2 — 不要叙述内部协议检测过程。 分发逻辑（检测到哪个标头、正在加载哪个引用、选择了哪个方案／意图、TEE 路径还是本地密钥路径）属于内部信息 — 应保留为内部信息。用户只需要看到：(a) 将支付什么，(b) 需要确认什么，(c) 结果。

规则 2 的例外 — 范围狭窄，仅限备选项列表。 在步骤 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）。

示例

（英文）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、需要付款、x402、x402Version、X-PAYMENT、PAYMENT-REQUIRED、PAYMENT-SIGNATURE、WWW-Authenticate: Payment、permit2、upto、按量计费、打开 / 关闭 / 充值 / 结算通道、凭证、会话付款、channelId、channel_id、paymentId、a2a_、创建付款链接、付款链接、付款状态
• subscribe / subscription / recurring payment / recurring charge / "pay every month" / 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 方案）。
• 特例：来自 Agent Marketplace 的 AI 服务 / ASP 订阅（上下文：ASP / Agent#N / 任务 / 试用期 / 服务方；无 402 报价 / 资源 URL / paymentId）属于 okx-ai（onchainos agent my-subscriptions / subscribe-detail），而非 period 方案。对于没有任何信号的单独“我的订阅”，请先询问用户一次，不要自行假定属于 period。

channel_id 附近或会话上下文中的任何关闭 / 充值 / 结算 / 凭证 / 退款操作 = MPP 会话中操作 → references/session.md。

预检

预检：每个对话线程开始时，完成 ../okx-agentic-wallet/_shared/preflight.md 中的检查。如果该文件不存在，请读取 _shared/preflight.md。

命令路由与参考文档索引

每个 402 信号（或 paymentId）→ CLI 命令 → 参考文档。详细的门控条件以及解码／确认步骤见下文的路径 A／路径 B。

信号	命令	参考文档
402 + PAYMENT-REQUIRED（v2）／正文中的 x402Version（v1）——一个或多个 accepts[] 方案（exact／exact+Permit2／upto／aggr_deferred）	主要方式 — 路径 A： payment quote <url> → 确认 → payment pay --payment-id --yes。单方案和多方案使用相同的报价流程（CLI 会解码、转换、检查余额、签名、重放并返回回执）。即使你已经用 curl 获取了原始 402，也要通过 payment quote <url> 重新进入流程——切勿手动组装请求头，也不要直接跳到仅签名流程。仅用于兼容： payment pay --payload [--selected-index]（仅签名 + 手动重放），适用于 quote 不可用的情况。	成功流程不会加载任何参考文档。仅在以下情况读取 references/accepts-schemes.md：支付后按方案读取回执、Permit2 allowance insufficient 时进行一次性授权、使用 pay-local、使用兼容路径 pay --payload，或处理旧版 x402 v1（CLI 输出中的字段会告诉你使用的方案——permit2Authorization = upto／exact+Permit2，sessionCert = aggr_deferred，authorization = exact）
402 报价中有一项 accepts[] 的 scheme == "period"（又称 permit2_subscription）——周期性／订阅计费	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 | ...]	（内嵌 — 路径 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	（内嵌 — 路径 A）
需要解码 PAYMENT-RESPONSE 请求头或扣款回执	payment decode-receipt (--header <b64> | --receipt <json>)	（内嵌 — 只读）

成功流程中不要加载参考文档。 在主要的路径 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 ... 子命令。

---

路径 A：HTTP 402

路径 A（基于 accepts）：报价 → 确认 → 支付 — 首选的两轮流程

对于基于 accepts 的 402 / A2MCP 端点，CLI 会完成所有机械性工作。 你只需进行两轮推理。（对于 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[] （该端点为 MCP 类型：URL 以 /mcp|/sse 结尾，或返回了 text/event-stream / JSON-RPC）， 付费墙位于工具调用层，而非裸 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、生成二维码或发送充值通知。
• 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. 运行 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，保留余额、地址、四种充值选项，且只保留一条 Gas 说明：X Layer = 资金到账后，链上 Gas 免费；其他链 = 通用 Gas 警告。保留“从 OKX 提币”的费用说明——交易所可能会收取提币手续费——绝不可声称交易所提币免费。
3. 遵循 displayMode：image-notify → 调用一次 user-notify --image-path；terminal-unicode → 包含 terminalQr。二维码生成失败 → 显示完整文本和地址。

提供 funded、cancel，以及仅在可用时提供 choose another payment method；绝不可宣传 pay anyway，也不可提出笼统的“是/否”问题。处理路径：funded → 重新报价；替代方式 → 显示 candidates[] + alternatives[] 中其他足额选项（如果报价已过期，先重新报价），然后通过 acceptsIndex 进行一次确认；cancel → 停止。用户主动且明确表示即使资金不足也要付款，即视为这一次授权；含糊的 yes 不算。不要运行 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 → 轮询 / 等待终态，然后继续。

随时可运行 onchainos payment decode-receipt (--header <b64> | --receipt <json>)，解码返回的 PAYMENT-RESPONSE 标头或收费收据。

---

步骤 A1：从原始响应开始（旧版 / WWW-Authenticate 详细信息）

基于 accepts 的 402 → 返回路径 A 的 payment quote。 以下步骤是旧版手动流程（解码 → 组装 → 自行重放），以及 WWW-Authenticate: Payment 费用 / 会话质询的通用解码详情。如果你持有的 402 基于 accepts（PAYMENT-REQUIRED 标头 v2 / x402Version 正文 v1 — exact / exact+Permit2 / upto / aggr_deferred，无论是单个方案还是多个方案），请勿继续此处：丢弃原始 402，并通过 payment quote <url> 重新进入路径 A。报价流程会运行相同的强制确认关卡，并为单方案和多方案返回相同的收据架构——单个方案也不能跳过 quote。只有在处理 WWW-Authenticate: Payment 费用 / 会话详情时，或者 payment quote 确实不可用、必须回退到显式的 pay --payload 仅签名兼容路径时，才继续以下步骤。

你已获得原始 HTTP 响应。如果它不是 402，则直接返回正文。否则 → 步骤 A2。

捕获用户提示词中提供的任何请求参数（例如，“旧金山的天气” → city=San Francisco、token=0x…；“翻译成中文” → lang=zh）。将每项记为 name → value，用于步骤 A3-Params 的计划——此处提供的值绝不会再次询问，只会显示在确认卡片中。即使第一次请求不需要这些参数，也要保留它们；卖方可能会在付费重放时要求提供。

步骤 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 提供两种支付方式：

  1. 会话（多请求） — 建立通道，并为每个请求签发凭证
  2. 一次性购买

  你想使用哪种方式？

  选项 1 → 继续步骤 A3-WWW-Authenticate（会话路径）。选项 2 → 忽略 session 意图，并通过 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 可确定每个参数的类型及其是否必填。每个声明的参数对应一个计划条目。

来源 2 — 非 Bazaar（保守处理）

没有 outputSchema.input → 仅当卖方明确信号时才添加参数；绝不自行编造：

• 响应正文列出了要求（required / params / parameters / fields / inputSchema），或
• 错误消息指出缺失的参数（例如，missing required query param "city"），或
• 有文档说明的响应标头要求提供参数。

有歧义 → 不添加任何内容，原样重放。

填充值

对每个条目，确定 value：（1）用户的提示词（步骤 A1）→ source=prompt，无需再次询问；（2）对话上下文 → source=context；（3）仍然缺失且为必填 → 向用户询问，并将所有问题合并成一个问题（这是合理的门控，不是旁白 — ZERO-TEXT-ON-TRIGGER 不禁止这样做）。可选且未解析 → 丢弃。

步骤 A3.5：多方案推荐（适用时）

仅当组合候选池包含 {exact, aggr_deferred, charge, period} 中的两个或更多时适用。否则，直接跳至步骤 A4，使用唯一可用的候选项。

当 402 accepts[] 包含 {exact, aggr_deferred, charge, period} 中的两个或更多时，加载 references/multi-scheme.md。将 period 视为定期计费选项：仅当用户意图是持续订阅时才推荐，不用于单次调用。

适用时 → 加载 references/multi-scheme.md 并从头到尾遵循其中的说明。它会返回选定的候选项，并告知你从何处继续：步骤 A4（用户选择了替代方案）或直接跳至步骤 A6（用户回复 yes 表示接受 — A5 的钱包检查已满足）。

步骤 A4：显示付款详情并停止

如果用户在 A3.5.5 中用 yes 接受了推荐选项，则完全跳过此步骤（卡片已显示网络 / 代币 / 金额 / 收款方）。直接进入步骤 A5（如果 A3.5.2 已处理登录，则此步骤不执行任何操作）→ A6。

如果满足以下任一条件，则正常执行此步骤：

• 未运行步骤 A3.5（单候选项路径），或
• 用户从 A3.5 展开的列表中选择了其他选项（所选候选项仍需完整详情确认）。

**执行此步骤时必须遵守：**显示详情并停止，等待用户明确确认。在用户确认前，不要调用 onchainos wallet status 或任何其他工具。

对于报价流程中的候选项，还要显示其 balanceStatus；余额不足时，显示 availableAmount、requiredAmount 和 shortfall，然后按照步骤 A3 中单张先充值卡片和操作表的方式处理。

对于基于 accepts 的 402（PAYMENT-REQUIRED 标头 v2 / x402Version 请求体 v1）：

此资源需要通过 OKX Agent Payments Protocol 付款：

• 网络：<chain name>（<option.network>）
• 代币：<token symbol>（<option.asset>）
• 金额：<human-readable amount>（v2 使用 option.amount，v1 使用 option.maxAmountRequired；根据代币精度将其从最小单位换算）。对于 upto 方案，此金额是授权上限，而非固定费用 — 显示为“最多 <amount>”。
• 付款至：<option.payTo>
• 请求参数（如果步骤 A3-Params 计划为空，则完全省略此行）：每个参数单独一行，格式为 <name> = <value> → <carrier: query | body | header | path>

是否继续付款？（yes / no）

对于 WWW-Authenticate: Payment 402：

此资源需要通过 OKX Agent Payments Protocol 付款：

• 付款类型：<one-shot payment | session (multiple requests)>（显示为“一次性付款”/“会话（多个请求）” — 绝不能使用“单次购买”；翻译成其他语言时也要保留这一区别）
• 网络：<chain name>（eip155:<chainId>）
• 代币：<symbol>（<currency address>）
• 每次请求金额：<human-readable>（原子单位：<amount>）
• 付款至：<recipient>
• Gas 费用由谁支付：<server (transaction mode) | you broadcast it yourself (hash mode)>
• 分账收款方（仅限一次性付款，且在存在时显示）：<N other parties also receive a share>
• 建议预付余额（仅限会话，且在存在时显示）：<human-readable>
• 请求参数（如果步骤 A3-Params 计划为空，则完全省略此行）：每个参数单独一行，格式为 <name> = <value> → <carrier: query | body | header | path>

是否继续付款？（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：转到 scheme/intent 参考文档

路径

操作

基于 accepts（PAYMENT-REQUIRED header v2 / x402Version body v1）

主要流程 — 路径 A：你应该已经进入 payment quote <url> → 确认 → payment pay --payment-id --yes 流程（路径 A 顶部）；此流程会签名、重放请求并返回回执——无需手动组装，成功时也无需加载参考文档。单个 accepts[] scheme 和多 scheme 的流程完全相同。 仅用于兼容/回退（quote 不可用，或收到明确的旧版请求）：运行 onchainos payment pay --payload '<raw_402 from Step A3>'。如果执行了步骤 A3.5，且用户选择了一个基于 accepts 的候选项，请添加 --selected-index <index in decoded.accepts>，以便 CLI 准确签署该条目；如果只有一个候选项，则省略此参数（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 返回原始证明（signature+authorization，没有 authorization_header）→ 加载 references/accepts-schemes.md，并按照其中的“Legacy: x402 v1”部分组装 X-PAYMENT header。

| period（订阅 / permit2_subscription） | 在“Decide operation”部分加载 references/subscription.md（选择 subscribe、access、change 还是 cancel）。首次订阅 → 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（<header_name>: <authorization_header>，或为旧版 v1 组装的 X-PAYMENT）重新发送原始请求，预期得到 HTTP 200，并在本地解码任何 PAYMENT-RESPONSE header（echo '<value>' | base64 -d | jq .），以读取 status / transaction / amount / payer。向用户说明结算详情；以对话方式建议后续操作——绝不要暴露内部字段名或 skill 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 状态码

格式：

卖方拒绝：<原因文本>（代码 <如有代码>，HTTP <状态码>）

金额显示

所有面向用户的金额都应同时以人类可读形式和原子单位显示：<人类可读金额> (<原子单位>)，例如 0.0004 USDC (400)。小数位数表及未知符号的后备处理 → _shared/amount-display.md。

建议后续步骤

成功支付并收到响应后，以自然对话的方式建议：

刚完成的操作	建议
payment quote 返回 needsConfirm:true	确认一次：条件允许时使用 AskUserQuestion，条件不足时使用自适应的二维码增强确认（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），或等待 facilitator 回调
HTTP 402 重放成功	通过 okx-agentic-wallet 检查余额变化；或再次请求同一资源
a2a 支付成功	通过 okx-agentic-wallet 验证支付后的余额
重放时返回 402（已过期）	使用新的签名重试
通道会话进行中	收到下一个请求时签发另一张凭证；完成后关闭通道