在 PolyPay 接入 x402

在平台创建受保护资源规则，然后在服务端路由中使用 PolyPay SDK。SDK 会处理 402 challenge、付款验证和结算调用。

AI Agent 收款需要有效订阅，Pay-as-you-go 也可使用。套餐过期或未启用订阅时，资源配置不会被删除，但后台管理和 verify/settle 运行时会冻结；恢复有效订阅后无需重新创建资源即可恢复。

PolyPay SDK 默认使用 x402 v2：402 响应通过 PAYMENT-REQUIRED 返回付款要求，Agent 通过 PAYMENT-SIGNATURE 提交授权，业务响应再通过 PAYMENT-RESPONSE 返回结算凭证。仅在受控迁移期间才应显式设置 protocolVersion: 1。

resource 和 method 配置会作为规范化的公开请求标识，即使应用位于反向代理之后也不会改用内部 URL。v2 仅接受 PAYMENT-SIGNATURE；旧 X-PAYMENT 仅在 protocolVersion: 1 时启用。

接入流程

1. 在 Dashboard 的 AI Agent 收款页面创建 Resource configuration。
2. 填写公开 resource URL、HTTP method、价格、网络、USDC 合约和 settlement wallet。
3. 在服务端路由中安装并初始化 PolyPay SDK，API Key 只能放在服务端环境变量里。
4. 用 SDK 包装受保护接口。未付款时返回 402，付款成功后继续返回业务数据。
5. 在平台查看 Payment records，跟踪验证、结算和链上交易状态。

服务端 SDK 示例

x402 必须在服务端使用 API Key 模式。不要把 API Key 或 settlement 逻辑放到浏览器包中。

import { polypayX402 } from '@polypay/sdk/x402';

const x402 = polypayX402({
  apiKey: process.env.POLYPAY_API_KEY!,
  resource: {
    resource: 'https://merchant.example.com/api/premium-data',
    method: 'GET',
    price: '$0.01',
    amount: '10000',
    network: 'eip155:8453',
    asset: 'USDC',
    payTo: '0xYourMerchantSettlementWallet',
    description: 'Premium market data'
  }
});

export async function GET(request: Request) {
  const result = await x402.verifyAndSettle(request);
  if (!result.paid) {
    return result.required();
  }

  return Response.json(
    { data: 'premium payload' },
    { headers: result.responseHeaders }
  );
}

支持网络

当前仅支持标准 EVM exact 流程，也就是 Circle USDC 的 transferWithAuthorization。

SDK 会在初始化时严格校验 scheme、网络、对应的 Circle USDC 合约和 EIP-3009 元数据；不受支持的覆盖配置会在生成付款 challenge 前直接报错。

平台验证规则

• scheme 必须是 exact。
• network、asset、assetContract、payTo、amount 必须和资源配置匹配。
• resource URL 和 HTTP method 会强制匹配当前请求。
• 对应 Resource 必须保持启用；缺失、停用或无法唯一匹配的资源会被拒绝结算。
• validAfter / validBefore 必须处于有效窗口内，nonce 只能结算一次。
• EIP-712 签名必须恢复到 authorization.from。

原始 facilitator settle 响应返回 paymentId/replayed，SDK 的 verifyAndSettle() 结果会将其映射为稳定的 fulfillmentKey/shouldFulfill。只有赢得首次 confirmed 状态跃迁的请求才会得到 shouldFulfill=true，并发及后续重放均为 false；但这个标志不能替代业务幂等。写入数据或触发外部动作的接口仍必须以 fulfillmentKey 为唯一键原子保存业务结果，重试时返回已保存结果，不能因为 paid=true 再执行一次。只读接口在 paid=true 时可继续返回相同内容。

标准 Facilitator 接口

使用官方或第三方 x402 server SDK 直接调用 PolyPay 时，请将 facilitator base URL 配置为 https://api.polypay.ai/api/v2/x402。该入口直接返回标准 supported、verify 和 settle JSON；现有 PolyPay SDK 继续使用兼容的 /api/v1/pay/x402 接口。

如果 settle 请求超时，结果属于未确定状态。请使用完全相同的付款凭证重试；PolyPay 会重发已持久化的同一签名交易或对账已有结算，不会创建第二笔扣款。不要仅因超时重新生成授权。标准请求未携带 method/resource 时，还必须能从已启用资源中唯一匹配。

暂不支持的链

BSC、Tron、Solana、TON、BTC 不属于当前标准 EVM exact 流程。后续如果支持，需要单独的 x402 scheme 或 PolyPay 扩展。

HTTP/1.1 429 Too Many Requests
Retry-After: 10
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 10

{"code":40001,"message":"RateLimitExceeded","data":{"retry_after":10}}