Skip to main content
Ace Data Cloud X402 目前使用两类 scheme:exact 和 upto。它们解决的是不同计费问题。

exact

exact 表示本次请求在进入目标 API 前就能确定价格。客户端签名的金额就是最终扣款金额。 适合:
  • 固定价格的图片生成;
  • 固定价格的视频任务创建;
  • 固定价格的搜索或工具 API;
  • 订单支付。
EVM exact 使用 USDC EIP-3009 TransferWithAuthorization:
Facilitator 在 /verify 阶段验证签名和金额,在 /settle 阶段把这笔授权提交到链上。

upto

upto 表示客户端授权一个最大上限,Ace Data Cloud 在请求完成后按实际用量结算,实际扣款不能超过上限。 适合:
  • 聊天补全:最终价格取决于 prompt tokens 和 completion tokens;
  • 流式响应:真实输出长度结束后才知道;
  • 未来的后置计量 API。
upto 使用 Permit2 PermitWitnessTransferFrom。客户端签名的不是固定转账,而是一个带 witness 的上限授权:
permitted.amount 是上限,不一定是最终扣款。Gateway 在 /record 阶段会把实际用量转换成 amount 传给 Facilitator。Facilitator 只允许结算 amount <= permitted.amount。 Base upto 的程序运行结果:
说明:
  • 402 中返回的授权上限是 95215 atomic USDC,客户端按这个上限签名。
  • 模型实际响应后只结算 3 atomic USDC,链上交易已在 BaseScan 可查。
  • 这个结果能说明 upto 的关键差异:签名金额是上限,链上 settlement 可以小于上限。
  • 如果实际用量超过上限,Facilitator 应拒绝 settlement,客户端需要重新按更高上限授权。
upto 目前只在 Base 上提供。SKALE 只提供 exact,如果你需要后置计量,请使用 Base。

为什么需要 Permit2 approve

upto 最终由 x402 proxy 通过 Permit2 从付款钱包拉取 USDC。第一次使用前,付款钱包需要给 Permit2 一次 ERC-20 allowance。 Python CLI:
程序方式:
授权完成后,每次请求仍然需要签一个新的 upto envelope,因为 nonce、deadline、witness 和金额上限都不同。

零金额结算

upto 支持实际金额为 0 的情况。例如目标 API 没有成功产生可计费用量,Gateway 可以传入 amount = "0"。Facilitator 会返回成功,但不会发链上交易。 这可以避免“请求没有成功但仍然扣链上费用”的问题。

选择建议

如果你不确定该选哪个,先使用 SDK 默认行为;SDK 会选择服务器返回的匹配网络 payment requirement。

Base upto 检查清单

接入或排查时,请确认以下参数来自同一次 402 响应,并在客户端签名时保持一致: 常见错误及处理方式: