Skip to content

providers.md

Latest commit

 

History

History
301 lines (240 loc) · 7.69 KB

providers.md

File metadata and controls

301 lines (240 loc) · 7.69 KB

x402 Payment Providers

x402-deploy supports multiple payment networks and assets.

Supported Networks

EVM Networks

Network Chain ID Identifier USDC Address
Arbitrum One 42161 eip155:42161 0xaf88d065e77c8cC2239327C5EDb3A432268e5831
Base 8453 eip155:8453 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Ethereum 1 eip155:1 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Polygon 137 eip155:137 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
Optimism 10 eip155:10 0x7F5c764cBc14f9669B88837ca1490cCa17c31607

Recommended Network

Arbitrum One is recommended for:

  • Low gas fees (~$0.01-0.05)
  • Fast finality (~1 second)
  • Wide adoption
  • USDs availability (auto-yield)

Supported Assets

USDC (USD Coin)

The primary payment asset:

{
  "payment": {
    "network": "eip155:42161",
    "assets": ["USDC"]
  }
}

USDs (Sperax USD)

Auto-yield stablecoin (~5% APY):

{
  "payment": {
    "network": "eip155:42161",
    "assets": ["USDs"]
  }
}

Multiple Assets

Accept multiple assets:

{
  "payment": {
    "network": "eip155:42161",
    "assets": ["USDC", "USDs"]
  }
}

Payment Facilitator

The payment facilitator validates and settles payments.

Public Facilitator

Use the public facilitator (default):

{
  "payment": {
    "facilitator": "https://facilitator.x402.org"
  }
}

Self-Hosted Facilitator

Run your own facilitator:

npx @nirholas/x402-deploy facilitator

Configure:

{
  "payment": {
    "facilitator": "https://your-facilitator.com"
  }
}

Payment Flow

┌─────────────────────────────────────────────────────────────┐
│                    Payment Flow                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────┐         ┌──────────┐         ┌──────────┐     │
│  │  Client  │────1───►│  Server  │         │Facilitator│    │
│  │ (Agent)  │         │(Your API)│         │           │    │
│  └──────────┘         └──────────┘         └──────────┘     │
│       │                    │                    │           │
│       │                    │                    │           │
│       │◄───────2──────────┤  402 + Accept Headers          │
│       │                    │                    │           │
│       │                    │                    │           │
│       │                    │                    │           │
│       ├────────────────────┼────────3──────────►│           │
│       │                    │         Create Payment          │
│       │                    │                    │           │
│       │◄───────────────────┼────────4──────────┤           │
│       │                    │         Signed Payment          │
│       │                    │                    │           │
│       │                    │                    │           │
│       ├─────────5─────────►│                    │           │
│       │   Retry + X-PAYMENT header              │           │
│       │                    │                    │           │
│       │                    ├────────6──────────►│           │
│       │                    │         Verify Payment          │
│       │                    │                    │           │
│       │                    │◄───────7──────────┤           │
│       │                    │         Valid ✓                │
│       │                    │                    │           │
│       │◄───────8──────────┤                    │           │
│       │    200 OK + Data   │                    │           │
│       │                    │                    │           │
└─────────────────────────────────────────────────────────────┘

Steps:

  1. Client makes initial request
  2. Server returns 402 with payment requirements
  3. Client creates payment with facilitator
  4. Facilitator returns signed payment
  5. Client retries with X-PAYMENT header
  6. Server verifies payment with facilitator
  7. Facilitator confirms validity
  8. Server returns data

402 Response Format

When payment is required, your API returns:

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:42161",
      "maxAmountRequired": "10000",
      "resource": "/api/price/BTC",
      "description": "Get BTC price",
      "mimeType": "application/json",
      "payTo": "0x...",
      "asset": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    }
  ],
  "error": null
}

Fields:

Field Description
x402Version Protocol version (currently 2)
scheme Payment scheme (exact)
network Network identifier
maxAmountRequired Amount in smallest units
payTo Recipient address
asset Token contract address

X-PAYMENT Header

Client includes payment in retry:

X-PAYMENT: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...

The header contains:

  • Payment signature
  • Amount
  • Recipient
  • Nonce
  • Expiry

Settlement

Instant Settlement

Payments settle instantly on-chain:

  1. Facilitator verifies signature
  2. Funds transfer atomically
  3. Server receives payment

Gas Sponsorship

For micropayments, the facilitator can sponsor gas:

{
  "payment": {
    "gasless": true
  }
}

Multi-Network Support

Accept payments on multiple networks:

{
  "payment": {
    "networks": [
      {
        "network": "eip155:42161",
        "wallet": "0xArbitrumWallet..."
      },
      {
        "network": "eip155:8453",
        "wallet": "0xBaseWallet..."
      }
    ]
  }
}

Webhooks

Receive payment notifications:

{
  "payment": {
    "webhooks": {
      "onPayment": "https://your-api.com/webhooks/payment"
    }
  }
}

Webhook payload:

{
  "event": "payment.received",
  "payment": {
    "id": "pay_abc123",
    "amount": "10000",
    "asset": "USDC",
    "from": "0x...",
    "to": "0x...",
    "txHash": "0x...",
    "timestamp": "2024-01-15T12:00:00Z"
  }
}

Testing

Testnet Configuration

{
  "payment": {
    "network": "eip155:421614",
    "wallet": "0xTestWallet...",
    "testnet": true
  }
}

Testnet Faucets

Network Faucet
Arbitrum Sepolia https://faucet.arbitrum.io
Base Sepolia https://www.coinbase.com/faucets/base-sepolia-faucet

Next Steps