Skip to main content
Facilitator 是 X402 链路中的服务端结算组件。客户端负责签名，Gateway 或你的服务端负责调用 Facilitator 的 /verify 和 /settle。 Ace Data Cloud 的生产 Facilitator 地址为：
源码仓库：https://github.com/AceDataCloud/FacilitatorX402

​
v2 wire 约定

Ace Data Cloud 的 X402 链路已全量使用官方 x402 v2，不再接受 v1 的 X-Payment 请求头。接入时需要注意三点：
  • 请求头是 PAYMENT-SIGNATURE，值是 base64 编码的 JSON envelope。
  • envelope 顶层必须是 x402Version: 2，并用 accepted 对象声明本次选择的 scheme 和 network。
  • network 使用 CAIP-2 标识（如 eip155:8453），不能写 base 这类简称。
envelope 结构：
402 响应除 JSON body 外，还会带一个 PAYMENT-REQUIRED 响应头，值是同一份挑战内容的 base64 编码，便于客户端在不解析 body 的情况下读取支付要求。

​
核心接口

​
GET /supported

查看支持的网络和 scheme：
返回示例：
结果说明：
  • network 使用 CAIP-2 标识，不是 base、skale 这类简称。
  • /supported 表示 Facilitator 具备对应验证与结算能力。
  • Base、SKALE 和 Solana 都支持 exact；upto 目前只在 Base 上提供。
  • signers 是 Facilitator 用于提交结算交易的地址。
  • 某个具体 API 是否允许这些选项，仍以该 API 的 402 accepts 为准。

​
POST /verify

验证客户端传来的 PAYMENT-SIGNATURE 是否满足某个 payment requirement。 请求体：
v2 的 paymentRequirements 字段是 scheme、network、asset、amount、payTo、maxTimeoutSeconds 和 extra，金额字段是 amount。API 402 响应的 accepts[] 里还会额外返回 maxAmountRequired 供客户端读取上限，但它不属于 Facilitator 请求体的字段。 成功响应：
生产订单支付的 PAYMENT-RESPONSE 响应头解码后包含 settlement 结果。Base 订单支付的程序运行结果：
结果说明：
  • success=True 表示 Facilitator settlement 成功。
  • transaction 是链上交易哈希，订单的 pay_id 也写入同一个值。
  • explorer 上可以看到 1200000 atomic USDC 的 Base USDC 转账。
  • errorReason=None 表示这次 settlement 没有返回业务错误。
验证失败也通常返回 HTTP 200，但 isValid 为 false。业务侧应该读取 invalidReason，而不是只看 HTTP 状态码。

​
POST /settle

把已经验证过的授权结算到链上。 请求体和 /verify 基本一致。upto 的区别是：paymentRequirements.amount 在 settle 时改写为实际结算金额；签名上限由 Facilitator 在 verify 阶段记录，settle 时校验实际金额不得超过该上限。 成功响应：
如果 upto 实际金额为 0，transaction 可能为空字符串，表示无需发链上交易。

​
Ace Data Cloud Gateway 如何使用 Facilitator

Ace Data Cloud API Gateway 的链路如下：
  1. 客户端第一次请求 API，不带 Authorization 和 PAYMENT-SIGNATURE。
  2. Gateway 计算请求的预估价格，返回 402 和 accepts。
  3. 客户端签名后带 PAYMENT-SIGNATURE 重试。
  4. Gateway 解码 PAYMENT-SIGNATURE，选择匹配的 payment requirement。
  5. Gateway 调用 Facilitator /verify。
  6. /verify 成功后，Gateway 放行请求到目标 API。
  7. 目标 API 返回后，Gateway 在 /record 阶段调用 Facilitator /settle。
  8. Gateway 把链上交易哈希写入使用记录 metadata。
exact 在步骤 7 结算签名金额；upto 在步骤 7 根据真实用量写入 amount，再结算实际金额。

​
自己的 API 如何接入

如果你要让自己的 API 支持 X402，可以按这个结构实现：
  1. 为每个付费接口准备 paymentRequirements，包含网络、金额、收款地址、资产地址和签名 domain。
  2. 如果请求没有 PAYMENT-SIGNATURE，返回 HTTP 402 和 accepts。
  3. 如果请求有 PAYMENT-SIGNATURE，Base64 解码得到 paymentPayload。
  4. 调用 Facilitator /verify。
  5. 验证成功后执行业务逻辑。
  6. 业务成功后调用 Facilitator /settle。
  7. 保存 payer、transaction、amount、network 以便对账。
服务端必须用自己生成的 paymentRequirements 调 /verify 和 /settle，不要信任客户端回传的金额、收款地址或资产地址。

​
重放保护

Facilitator 会记录 nonce。相同 nonce 的授权不能重复验证和结算。 这意味着：
  • 客户端每次请求都应该签一个新的 envelope；
  • 如果 /settle 已提交交易但暂时没有确认，可以用相同 nonce 重试 /settle 做幂等对账；
  • 不要把同一个 PAYMENT-SIGNATURE 缓存后用于多次 API 调用。

​
常见错误