在 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}}