Skip to main content
x402 is an open protocol for pay-per-request HTTP access. Instead of an API key, your client pays a small amount of USDC on Base for each request — ideal for AI agents that need onchain data without managing subscriptions or key rotation.

​
Quickstart with the Zerion CLI

The easiest way to use x402 is with the Zerion CLI, which handles the payment handshake, wallet signing, and retries automatically. Set the private key of the wallet that holds USDC on Base, then make a request: 
export WALLET_PRIVATE_KEY="0x..."
zerion-cli wallet portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

​
Without the CLI

If you’re integrating x402 directly, you’ll need:
  • A wallet with USDC on Base mainnet
  • The private key of that wallet to sign payments:
export WALLET_PRIVATE_KEY="0x..."
Use the Coinbase x402 SDK (Go, TypeScript, Python) to handle payment construction and retries.

​
How it works

  Client                       Zerion API
    │                               │
    │   1. GET /v1/wallets/...      │
    │ ────────────────────────────▶ │
    │                               │
    │   2. 402 Payment-Required     │
    │ ◀──────────────────────────── │
    │      {payTo, maxAmount, ...}  │
    │                               │
    │   3. GET /v1/wallets/...      │
    │      Payment-Signature: ...   │
    │ ────────────────────────────▶ │
    │                               │
    │   4. 200 OK                   │
    │ ◀──────────────────────────── │
    │                               │
  1. Client sends a request to a /v1/ endpoint
  2. Server returns 402 with payment terms (how much, where to pay)
  3. Client signs a USDC transfer and retries with a Payment-Signature header
  4. Server settles the payment and returns the response
Payment is in USDC on Base mainnet, settled via the Coinbase Developer Platform.

​
Base URL

https://api.zerion.io/v1/
No Authorization header needed. Responses are identical to the standard API — same JSON:API structure, same query parameters, same filters.
All standard wallet and market endpoints are available via x402, with two exceptions: wallet simulation and wallet-set endpoints are not supported. The transactions endpoint automatically enables the claim operation type — no X-Supports-Claim-Operation-Type header needed.

​
Rate limits

Fixed rate limits do not apply to x402 payments. The flow is lightweight: requests without a payment header are immediately prompted to pay, while requests with a valid header go through a fast local check and a Coinbase settlement. The system scales with traffic, so there’s no per-second or monthly quota to manage.

​
Error handling

For errors and troubleshooting, see the Coinbase x402 troubleshooting docs.