x402 Micropayment Integration

What is x402?

x402 is a machine-to-machine payment protocol built around HTTP 402 Payment Required. In AgentWallex, x402 is implemented with v2 headers and EIP-3009 authorization payloads.

x402 v2 Headers

• PAYMENT-REQUIRED — 402 challenge (Resource Server -> Client)
• PAYMENT-SIGNATURE — signed payment payload (Client -> Resource Server)
• PAYMENT-RESPONSE — settlement response (Resource Server -> Client)

High-Level Flow

Client Agent               Paid API               AgentWallex
    │                        │                         │
    │── GET /resource ──────▶│                         │
    │◀── 402 + PAYMENT-REQUIRED                        │
    │                        │                         │
    │── POST /api/v1/x402/pay ───────────────────────▶ │
    │                        │     (sign + policy)     │
    │◀── payment_info        │                         │
    │                        │                         │
    │── GET /resource + PAYMENT-SIGNATURE ───────────▶ │
    │◀── 200 + PAYMENT-RESPONSE                        │

Using AgentWallex x402 APIs

1. Check if target URL supports x402

POST /api/v1/x402/check

{
  "url": "https://paid-api.example.com/v1/data"
}

2. Optional: create a session budget

POST /api/v1/x402/sessions

{
  "agent_id": "agent_uuid",
  "budget_limit": "100.00",
  "chain": "eip155:84532",
  "ttl_seconds": 3600,
  "allowed_urls": [
    "https://paid-api.example.com/v1/data"
  ]
}

3. Trigger payment negotiation

POST /api/v1/x402/pay

{
  "agent_id": "agent_uuid",
  "target_url": "https://paid-api.example.com/v1/data",
  "session_id": "optional_session_uuid",
  "chain": "eip155:84532"
}

Typical response includes payment_info with fields such as:

• ledger_id
• amount
• fee_amount
• fee_rate
• token
• chain
• status

For Service Providers

If you expose paid APIs, your server should return an x402 v2 challenge when payment is missing.

1. Return 402 with PAYMENT-REQUIRED

Encode a JSON challenge (base64) into the PAYMENT-REQUIRED header. The payload should include:

• x402Version: 2
• resource
• accepts[] with scheme/network/amount/asset/payTo/maxTimeoutSeconds

2. Verify PAYMENT-SIGNATURE

Use AgentWallex facilitator endpoint:

POST /api/v1/x402/facilitator/verify

3. Settle payment

POST /api/v1/x402/facilitator/settle

4. Query supported chains

GET /api/v1/x402/facilitator/supported

Public Fee Tiers

GET /api/v1/x402/fees/tiers

Use this endpoint to show current tiered fee schedule in your UI instead of hardcoding rates.

Operational Defaults (from current backend config)

• Settlement interval: 300s
• Settlement threshold: 10.0
• Max settlement delay: 3600s
• x402 supported chains: eip155:84532, eip155:8453, eip155:1, eip155:137

Error Contract

{
  "code": "insufficient_funds",
  "type": "invalid_request_error",
  "message": "human readable error"
}