商户自助接入 x402

这份文档面向要自行接入 Axon x402 facilitator 的商户。目标是让商户自己完成钱包确权、API key 管理、resource 配置和 route 发布。

上线环境

• Base URL: https://x402.mavae.ai
• Network: eip155:8210
• 自助 onboarding: POST /v1/merchant/onboard/challenge 与 POST /v1/merchant/onboard/complete

1. 商户开通

1. 调用 POST /v1/merchant/onboard/challenge，提交 merchantPayTo。
2. 用同一个钱包对返回的 challenge 文本做签名。
3. 调用 POST /v1/merchant/onboard/complete，拿回一次性的 merchant_admin API key。

2. 创建 runtime key

使用 merchant_admin key 调用：

• GET /v1/merchant/api-keys
• POST /v1/merchant/api-keys
• POST /v1/merchant/api-keys/:keyId/revoke

商户服务端调用 /v2/x402/verify 和 /v2/x402/settle 时，应使用 payment_runtime key。

3. 创建 resource 与 route

使用 merchant_admin key 调用：

• POST /v1/merchant/resources
• POST /v1/merchant/resources/:resource/routes
• PATCH /v1/merchant/routes/:routeId
• POST /v1/merchant/routes/:routeId/disable

平台规则：

• 支付资产只能从平台白名单中选择。
• paymentRequirements.payTo 一律由 facilitator 自动设置为 vault。
• payoutAddress 固定等于商户的 merchantPayTo。
• unwrap_to_native 只允许用于 wrapped native 资产。

4. 商户后端接入

1. 先调用 discovery 读取自己某个 resource 的 accept route。
2. 在业务接口中返回 402 payment_required 和 accept route。
3. 收到用户 payment 后，调用 /v2/x402/verify。
4. verify 成功后，再调用 /v2/x402/settle。
5. settle 成功后，返回商户自己的业务结果。

5. Axon 兼容性补丁

• Axon 的 RPC receipt 返回与常规 EVM 节点有细微差异。
• 如果商户直接使用标准 ethers 或类似 SDK 的默认 receipt 解析流程，交易已经上链后仍可能收到解析异常。
• 建议商户在自己的链上等待逻辑中，对 eth_getTransactionReceipt 做原始 JSON-RPC 读取和归一化补丁，而不是完全依赖默认 formatter。
• 如果不打这个补丁，可能出现“链上实际成功，但应用侧误判失败”的情况，进而触发错误重试。

6. 异常与重试

• 409 通常表示同一笔 settlement 仍在处理中。
• 429 表示请求被限流，应做退避重试。
• 502 表示上游链路或 facilitator 依赖异常。
• 如果用户已经提交过某个 payment，应优先复用同一个 payment payload 重试，不能重新签新的 nonce。