HTTP API

所有 JSON 路由使用 application/json。商户 API 通过 bearer API key 认证，x402 支付提交使用 PAYMENT-SIGNATURE。

核心路由

方法	路由	用途
GET	/healthz	网关健康状态。
POST	/merchant/challenge	创建短期 payTo 所有权挑战。
POST	/merchant/register	验证签名后注册商户。
GET	/merchant/me	读取已认证商户资料。
POST	/merchant/rotate-key	轮换 API 或 notify key。
POST	/merchant/revoke-key	撤销旧 key。
POST	/ref	创建支付引用。
GET	/ref/:refId	读取公开引用元数据。
GET	/ref?pay_to=...	分页列出已认证 refs。
POST	/ref/:refId/revoke	撤销引用。
POST	/payto/:payTo/revoke	退役 payTo。
GET	/pay/:refId	提供钱包签名 relay 页面。
GET	/receive/:payTo	协商或提交 x402 支付。
POST	/verify-receipt	验证收据上下文和链上状态。
POST	/verify-refund-receipt	验证退款收据与反向转账。
GET	/tx/:txHash	查询有边界的交易状态。
GET	/txs	查询有边界的转账历史。
POST	/recover-settlement	恢复结算后结果，且不再次结算。

认证矩阵

路由组	认证方式
Health、challenge、registration、公开 ref	公开，但受 route rate limit 约束
Ref mutation/list、payTo、merchant profile 和 key	生产环境使用 Authorization: Bearer <apiKey>
Receive 协商与结算	付款方提供 x402 PAYMENT-SIGNATURE
Tx、history、receipt、recovery	受部署策略和 abuse gate 控制
Order 与 refund mutation	商户 bearer key 且启用 order mode

商户注册

POST /merchant/challenge 接收 payTo、network、action: "merchant.register" 和可选 webhook URL。响应 challenge 会绑定 gateway origin、action、payTo、network、webhook hash、nonce 和 expiry。

POST /merchant/register 接收 challenge id、payTo、network、label、webhook URL 和 signature。一次性响应返回 merchantId、apiKey、notifyHmacKey、notifyHmacKeyId 和 payTo。

PaymentRef 路由

POST /ref

JSON
1{2  "payTo": "0x1111111111111111111111111111111111111111",3  "network": "base",4  "asset": "USDC",5  "amount": "24000000",6  "invoiceId": "order_7K9M2",7  "label": "订单 7K9M2",8  "expiresInSecs": 900,9  "notifyUrl": "https://merchant.example/x402/notify"10}

响应返回 refId、可传输 refUrl 和不可变 payment snapshot。开放金额 ref 省略 amount；invoiceId 必须配合固定 amount。

GET /ref 使用 pay_to、可选有界 limit 和不透明 cursor，返回 items 与可选 nextCursor。不能自行构造或修改 cursor。

Receive 协商

不带 PAYMENT-SIGNATURE 时，/receive/:payTo 返回 402 和 base64url 编码的 payment-required header。带有效支付签名时，它会验证完整上下文、调用 facilitator /verify 和 /settle，并返回包含交易哈希的结算结果。

常见 query 是 ref=<refId>，开放金额还使用 amount=<atomic>；退款路径会绑定 refundOf=sha256:<receiptHash>。

PaymentRequired 绑定 resource URL、exact scheme、network、原子金额、token contract、payTo、timeout 与 extension。生产响应应包含 signed offer，并精确绑定 origin、resource、paymentId、payTo、amount、network、chain id、asset、expiry 和 nonce。

结算请求的 PAYMENT-SIGNATURE 是 base64url x402 payload，包含 EIP-3009 signature、authorization 和 payment-identifier。它是可重放敏感数据，不能记录日志。

成功响应返回 x402Version、success、network、transaction hash、payer、receiptStatus、response code/message，以及可选的 offer-receipt 签名和完整 receipt。

验证与历史

POST /verify-receipt

请求包含 signedReceipt、完整 receipt、可选 expectedPayTo、expectedAmount 和 minConfirmations。结果会分开返回签名/上下文 validity 与确认数 policy，并提供字段匹配证据。

GET /tx/:txHash

返回 found、status、确认数、block number、转账两端、token contract、value 和可用的有界 logs。

GET /txs

支持 pay_to、from、asset、from_block、limit 和不透明 cursor。至少需要 pay_to、from 或 cursor。部署会限制 block span、响应大小、RPC timeout 和调用频率。

POST /recover-settlement

提交 refId、原始 paymentPayload，以及可选 tx hash、signed offer 或 starting block。恢复只检查不可变 ref 上下文和链证据，不能再次调用 facilitator settle。

可选 order 与 refund 路由

方法	路由	用途
POST	/order	创建租户隔离 unpaid order 和 ref
GET	/order/:orderId	读取订单
GET	/order	按可选 status 列出订单
POST	/order/:orderId/cancel	取消 unpaid order
POST	/order/:orderId/refund	创建随机绑定 refund intent
GET	/order/:orderId/refund/:refundId	读取退款状态
GET	/order/:orderId/refunds	列出订单退款
POST	/order/:orderId/refund/:refundId/reject	签发 rejected refund receipt
POST	/refund-receipt/rejected	签发无状态 rejected refund receipt

所有 order lookup 都按已认证 merchant id 隔离，裸 orderId 不是全局权限。

错误 envelope

JSON
1{2  "x402Version": 2,3  "error": {4    "code": "ref_expired",5    "message": "payment reference expired",6    "details": {}7  }8}

稳定 code 包括 invalid_request、unauthorized、forbidden、not_found、ref_expired、ref_revoked、payto_revoked、payment_required、payment_verification_failed、settlement_failed、receipt_invalid、rpc_unavailable 和 rate_limited。

错误使用稳定的结构化 code，便于 SDK 区分输入错误、策略拒绝、暂时不可用和结算后状态不明确等情况。