开发者文档

支付模型

所有 premium 请求都会先返回 402 challenge。买方 Agent 完成支付、附带 proof 后，再对同一路径重试。

GET /api/premium/vendor-risk?address=0x1234&lang=zh
-> 402
-> parse payment_required
-> pay via AgentVault
-> retry same URL with x-payment-proof

核心接口

{
  "merchant": "/api/merchant?lang=zh",
  "catalog": "/api/catalog?lang=zh",
  "challenge": "/api/x402/challenge?resource=vendor-risk&lang=zh",
  "premium_vendor_risk": "/api/premium/vendor-risk?address=0x1234&lang=zh",
  "premium_verified_vendors": "/api/premium/verified-vendors?lang=zh",
  "premium_budget_report": "/api/premium/agent-budget-report?agent_id=demo-agent&lang=zh"
}

Challenge 结构

challenge 是付款金额、收款方、币种、nonce 和过期时间的权威来源。

{
  "status": 402,
  "error": "payment_required",
  "message": "需要支付",
  "seller": "AgentVault Data Market",
  "locale": "zh",
  "resource": {
    "id": "vendor-risk",
    "title": "供应商风险检查",
    "description": "返回某个地址的基础供应商可信评分。",
    "price_display": "0.001 USDC"
  },
  "payment_required": {
    "scheme": "exact",
    "network": "eip155:10143",
    "pay_to": "0xcE196a0c9969C5B2620B91b0c2136Bca2738C059",
    "amount": "1000",
    "currency": "0x534b2f3A21130d7a60830c2Df862319e593943A3",
    "facilitator": "https://x402-facilitator.molandak.org",
    "challenge_id": "656d9373-e534-431c-b2bf-995b52c77b43",
    "nonce": "78d7cb58a0b8bd60ea9b4e2d",
    "expires_at": "2026-04-12T12:39:58.129Z"
  },
  "instructions": {
    "text": "请完成支付挑战，并将 proof 放在 x-payment-proof 请求头中。",
    "header": "x-payment-proof",
    "demo_format": {
      "challenge_id": "656d9373-e534-431c-b2bf-995b52c77b43",
      "resource": "vendor-risk",
      "payer": "0xYourAgentWalletAddress",
      "tx_hash": "0xYourMonadTxHash",
      "amount": "1000",
      "currency": "0x534b2f3A21130d7a60830c2Df862319e593943A3",
      "nonce": "78d7cb58a0b8bd60ea9b4e2d"
    }
  }
}

Proof Header 示例

{
  "challenge_id": "challenge-id-from-402",
  "resource": "vendor-risk",
  "payer": "0xYourAgentWalletAddress",
  "tx_hash": "0xYourMonadTxHash",
  "amount": "1000",
  "currency": "0x534b2f3A21130d7a60830c2Df862319e593943A3",
  "nonce": "challenge-nonce"
}