Developer Docs

Payment Model

Every premium request first returns a 402 challenge. Your buyer agent pays, attaches proof, then retries the exact same endpoint.

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

Core Endpoints

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

Challenge Contract

Use the challenge as the canonical input for payment amount, payee, currency, nonce, and expiry.

{
  "status": 402,
  "error": "payment_required",
  "message": "Payment Required",
  "seller": "AgentVault Data Market",
  "locale": "en",
  "resource": {
    "id": "vendor-risk",
    "title": "Vendor Risk Check",
    "description": "Return a simple vendor trust score for an address.",
    "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": "fa10030a-df72-4fd8-8c87-0cd39b6d240d",
    "nonce": "15073ba587a9ae80d017d74f",
    "expires_at": "2026-04-12T13:19:47.320Z"
  },
  "instructions": {
    "text": "Sign a payment challenge and include the proof in the x-payment-proof header.",
    "header": "x-payment-proof",
    "demo_format": {
      "challenge_id": "fa10030a-df72-4fd8-8c87-0cd39b6d240d",
      "resource": "vendor-risk",
      "payer": "0xYourAgentWalletAddress",
      "tx_hash": "0xYourMonadTxHash",
      "amount": "1000",
      "currency": "0x534b2f3A21130d7a60830c2Df862319e593943A3",
      "nonce": "15073ba587a9ae80d017d74f"
    }
  }
}

Sample Proof Header

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