x402 協議參考

Linkex 實作 x402 第 2 版的 exact 方案用於帳戶充值。本頁是完整的整合參考；引導式教學見 x402 自動充值。

時序

端點

方法與路徑	認證	用途
`GET /api/user/topup/x402/config`	API Key 或工作階段	查詢啟用的網路、代幣、金額範圍與收款地址
`GET /api/user/topup/x402/orders`	API Key 或工作階段	列出待付訂單（附新鮮 challenge）
`POST /api/user/topup/x402/orders`	API Key 或工作階段	建立訂單（有速率限制）
`POST /api/user/topup/x402/orders/{id}/resume`	API Key 或工作階段	為待付訂單重新簽發 challenge
`POST /api/x402/pay/{orderId}`	無——簽名即授權	提交簽名付款（有速率限制，body 上限 1 MiB）

互動式 schema：API 參考 → x402。

建立訂單

POST /api/user/topup/x402/orders
{ "amount_usd": 5, "network": "eip155:8453", "symbol": "USDC" }

amount_usd——需在 config 的 [min_topup_usd, max_topup_usd] 內（預設 $1–$1,000）。
network / symbol——可選；省略時使用平台預設網路及其預設代幣（BNB Chain 預設 $U，其餘 USDC）。
Agent 綁定： 用 Agent Key 時訂單強制綁定該 Agent 錢包；body 中的 agent_wallet_id 被忽略。
每帳戶最多 3 筆待付訂單（X402_PENDING_CAP）。
訂單建立後 600 秒過期。

Challenge 結構

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "5000000",
    "maxAmountRequired": "5000000",
    "resource": "https://linkex.ai/api/x402/pay/12345",
    "payTo": "0xRECIPIENT",
    "maxTimeoutSeconds": 300,
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

extra 依結算方式而異：

方式	網路	`extra`
EIP-3009	Base USDC、BNB $U	`{ "name", "version" }`——代幣的 EIP-712 domain（BNB 另含 `"assetTransferMethod": "eip3009"`）
Permit2	BNB USDT / USDC	`{ "assetTransferMethod": "permit2-exact", "spenderAddress" }`
SVM	Solana USDC	`{ "feePayer", "memo" }`——代付手續費帳戶與需附帶的 invoice memo

簽名前務必將 payTo（Solana 還包括推導出的代幣帳戶）與 GET /api/user/topup/x402/config 核對。Linkex 官方用戶端會拒絕不一致的收款地址；你的實作也應如此。

提交付款

POST /api/x402/pay/{orderId} 附上簽名 payload。閘道校驗 scheme、network、asset、payTo 與精確的 amount 與訂單一致後結算。

回應始終為 HTTP 200 的信封格式：

{ "success": true, "data": { "order_id": 12345, "status": "settled", "balance_added": 5, "new_balance": 12.34 } }

status 取值：settled（已入帳）或 credit_pending（鏈上確認進行中；後台對帳程序——每 2 分鐘一次、帶鏈上驗證——會完成入帳）。

消費上限（Agent 訂單）

Agent 綁定的訂單在 pending→settling 轉換時原子扣減上限：

per_call_cap_usd——單筆
daily_cap_usd——按日曆日重置
total_cap_usd——累計

超過任一上限回傳 SPEND_CAP_EXCEEDED；失敗或重置的訂單會沖正扣減。

錯誤碼

以 success: false 加大寫 message 回傳：

錯誤碼	含義
`X402_DISABLED`	此部署未啟用該通道
`X402_INVALID_AMOUNT`	超出金額範圍
`X402_UNSUPPORTED_ASSET`	未知的網路/代幣組合
`X402_PENDING_CAP`	已有 3 筆待付訂單
`ORDER_NOT_FOUND` / `INVALID_ORDER_ID`	訂單引用無效
`ORDER_EXPIRED`	超過 600 秒有效期——請建立新訂單
`PAYLOAD_MISMATCH`	簽名 payload 與訂單不符
`SETTLING_IN_PROGRESS`	結算中重複提交
`ORDER_NOT_PENDING` / `ORDER_ALREADY_SETTLED`	訂單狀態不符
`SPEND_CAP_EXCEEDED`	將突破 Agent 消費上限
`X402_SETTLE_PENDING`	Facilitator 確認中——之後自動入帳
`X402_SOLANA_FEEPAYER_UNAVAILABLE`	代付帳戶暫不可用

相容的簽名器

Binance Agentic Wallet——baw x402-payment preview / sign
@linkexai/agent-sdk——buildX402PaymentPayload（EVM）、buildSvmPaymentPayload（Solana）
Coinbase x402 工具鏈及任何符合規範的 x402 v2 用戶端

本頁內容