企业官网建设流程全解析

本文详解 OKX Agent Payments Protocol（OKX 智能体支付协议，收录于本仓库vendored/okx）中所有用户可见金额的统一显示规范：为何必须同时呈现人类可读值与原子最小单位值（<human> (<atomic>)）、如何依据代币 decimals 完成换算、内置精度表覆盖哪些资产，以及遇到未知符号时如何在不阻塞支付流程的前提下安全降级。读完本文，你将掌握在 x402、MPP charge/session 与 a2a-pay 三类支付路径中正确渲染金额、费率、押金与退款的可执行方法，并能据此避免精度错位、误报金额等支付展示事故。

为什么金额必须双形态显示

在 Agent 与 Agent 之间的支付场景里，amount字段在协议层（HTTP 402 challenge、PAYMENT-REQUIRED头、WWW-Authenticate: Payment挑战）几乎总是以**原子最小单位（minimal units）**的字符串形式出现——例如"1000000"、"1500000000000000000"。直接把这些原始数字丢给用户，既无法判断实际价值，也无法核对与商定金额是否一致；而只显示人类可读值（如1.00 USDC），又会丢失链上签名/校验所需的精确原子值。

因此，该协议强制规定一条对所有用户可见金额一律适用的规则（见 vendored/okx/okx-agent-payments-protocol/_shared/amount-display.md）：

所有用户可见金额必须同时以人类可读形式和原子形式呈现：<human> (<atomic>)。

典型示例：

• 0.0004 USDC (400)
• 1.5 ETH (1500000000000000000)

这条规则不只作用于确认卡片，而是贯穿协议全流程：challenge 解码、确认展示、会话状态回显、close 退款计算、a2a 手续费渲染，全部遵循同一格式。在 SKILL.md 的 Cross-cutting「Amount display」一节中，该规则被再次明确并指向本共享文档，任何路径（accepts-based、charge、session、a2a-pay）都不能例外。

转换公式：human = atomic / 10^decimals

换算关系非常简单且唯一，decimals 必须取自 challenge 中的currency代币：

human = atomic / 10^decimals

• 已知原子值400、decimals 为 6（USDC/USDT/USDG）→400 / 10^6 = 0.0004
• 已知原子值1500000000000000000、decimals 为 18（ETH）→1.5

在解码链路中，这一转换有明确的落点：

• WWW-Authenticate: Payment路径：Step A3 解码出amount（base units 字符串，如"1000000"）与currency（ERC-20 合约地址）后，必须「Convertamountfrom base units to human-readable」——见 SKILL.md。其中currency就是决定 decimals 的关键字段：decimals 是代币属性而非金额属性，所以从 challenge 的currency代币解析。
• accepts-based 402 路径：v2 取option.amount、v1 取option.maxAmountRequired，同样用代币 decimals 从最小单位换算成人类可读值后展示（SKILL.md Step A4）。

内置 decimals 精度表

协议内置了一张硬编码精度表，覆盖三种 6 位小数稳定币与 ETH，是无需查询即可直接换算的白名单：

这张表在实际换算中的含义：

• 6 位小数资产（USDC/USDT/USDG）：1 unit = 10^6 = 1000000，即 1 个原子单位代表0.000001个代币。表中 USDC 的示例把1000000（= 1 USDC）显示为1.00 USDC，说明人类可读侧应保留两位小数格式。
• 18 位小数资产（ETH）：1 unit = 10^18，10000000000000000（= 0.01 ETH）显示为0.01 ETH。

协议规定换算时的展示精度以稳定币两位小数为基准，避免把1.000000 USDC这种浮夸位数呈现给用户；但原子侧必须原样保留字符串，不做任何四舍五入或截断，因为它是签名与对账的原始依据。

未知符号（不在表中）的回退流程

当 challenge 中的currency代币不在上述精度表内时，协议的规则是：绝不臆测 decimals（never assume）。回退流程分两步，见 amount-display.md：

1. 优先查询okx-dex获取该代币的 decimals（本仓库的 okx-dex 技能可返回链上代币元数据）。

2. 若仍无法解析，则以<atomic> <symbol>形式渲染，并附加提示语：

   unknown decimals — please double-check the seller-provided amount（未知精度——请复核卖家提供的金额）

关键约束是不要阻塞支付流程（Do not block the flow）：精度未知只影响展示形态，不影响 Agent 是否继续完成支付。这保证了即使遇到长尾代币，用户体验依然是「提示存疑、流程照走」，而不是卡死在查询环节。

值得注意的是，协议在 references/accepts-schemes.md 中同样遵循「不臆测」精神：Permit2 一次性授权金额询问中，数字型授权至少需达到<required>原子单位，且必须由用户明示，绝不默认给 MAX。

双形态规范在各支付路径中的落地

该规范不是孤立的展示规则，而是被三条支付路径反复引用的硬性要求（引用点见 SKILL.md、SKILL.md）。

accepts-based 402（exact / aggr_deferred / upto）

确认卡片中的金额行来自 v2option.amount或 v1option.maxAmountRequired，换算后展示<human-readable amount>（SKILL.md Step A4）。多方案推荐流程中，每个候选都携带amount (atomic)与amountHuman两个字段，推荐卡片同样呈现Amount: <human> (<atomic>)（见 references/multi-scheme.md 与 L52）。

WWW-Authenticate charge（一次性支付）

确认卡片要求Amount per request: <human-readable> (atomic: <amount>)——人类可读在前、原子值以atomic:标注在后（SKILL.md）。此外 charge 支持methodDetails.splits[]（最多 10 笔拆分收款），拆分会改变单方实收，但金额展示仍以 challenge 声明的总量为基准换算。

session（通道/会话支付）

session 路径是双形态规范最密集的使用场景（references/session.md）：

• 每次状态回显强制采用📋 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...>格式——押金、累计授权额、预估消费额全部双形态。
• 开通道时的建议押金：Suggested: <human(suggestedDeposit)> (<suggestedDeposit>)，无建议时按unit_amount × 100推算（约 100 次请求的预算）。
• 充值询问：Current balance: <human(deposit)> (<deposit>) · Used so far: <human(current_cum)> (<current_cum>)。
• 关闭通道后的结算确认，涉及三处换算：已扣费Charged <human(final_cum)> (<final_cum>)、总押金<human(deposit)> (<deposit>)、退款Refund of <human(deposit - final_cum)> (<deposit - final_cum>)（session.md S3.4）。

这里尤其要注意：退款、累计消费、押金差这些「派生金额」同样必须双形态，不能因为只是差额就偷懒只给一边。

a2a-pay（paymentId 支付链接）

a2a 路径的金额显示有两点特殊（见 references/a2a_charge.md）：

1. 手续费渲染：status返回的fee_amount是顶层字符串（最小单位），另有fee_bps表示基点。换算<fee_decimal>需要查代币 decimals；而<fee_symbol>无法从 status 响应中取回，必须复用卖家在create时传入的--symbol（上游调用方为唯一事实来源）；两者皆缺时，直接原样展示fee_amount最小单位。
2. a2a 例外：a2a 把信任委托给上游，因此遇到未列入精度表的符号时，不查询okx-dex、不阻塞，直接套用未知 decimals 回退（<atomic> <symbol>+ "double-check"）。

这一例外与通用规则形成对照：唯一查询okx-dex的来源是 HTTP 402 类路径，a2a 由于签署的是服务器下发的 challenge、无需本地精度换算，故直接降级。

常见陷阱与最佳实践

总结

金额显示是支付协议与用户交互的「最后一公里」：<human> (<atomic>)双形态格式保证了可读性与精确性兼得，human = atomic / 10^decimals配合内置精度表覆盖了 USDC/USDT/USDG/ETH 四种高频资产，而未知符号的「查 okx-dex → 降级渲染 → 不阻塞」三级策略兜底了长尾代币场景。这套规范在accepts-based、charge、session、a2a-pay 四条路径中由 SKILL.md 统一引用，是任何基于 OKX Agent Payments Protocol 构建的支付 Agent 都必须遵守的展示基线。