x402 Payments

x402 is Coinbase’s open protocol for pay-per-request HTTP access. Instead of an API key, you pay a small amount of USDC on Base or Solana for each request - ideal for AI agents that need onchain data without managing subscriptions or key rotation. This is an alternative authorization method for the same Zerion API. Endpoints, JSON:API responses, query parameters, and filters all behave exactly as in the rest of the docs - only the way you prove access changes. Zerion also supports MPP, a sibling protocol that settles on Tempo. See Authentication for an overview of all access methods.

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, then make a request with --x402:

Base (EVM)
Solana

export WALLET_PRIVATE_KEY="0x..."
zerion-cli wallet portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --x402

export SOLANA_PRIVATE_KEY="<base58-encoded-keypair>"
export ZERION_X402_PREFER_SOLANA=true
zerion-cli wallet portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --x402

Set ZERION_X402=true to enable x402 globally for analytics commands instead of passing --x402 on every call.

Direct integration

If you’re not using the CLI, use the Coinbase x402 SDK (Go, TypeScript, Python) to handle payment construction and retries. You’ll need a wallet with USDC on Base or Solana and its private key.

Example

import { wrapFetchWithPayment, x402Client } from '@x402/fetch'
import { registerExactEvmScheme } from '@x402/evm/exact/client'
import { privateKeyToAccount } from 'viem/accounts'

const client = new x402Client()
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.WALLET_PRIVATE_KEY),
})

const fetchWithPayment = wrapFetchWithPayment(fetch, client)

const res = await fetchWithPayment(
  'https://api.zerion.io/v1/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/portfolio'
)
const data = await res.json()

How it works

  Client                     Zerion API
    |                             |
    |  1. GET /v1/wallets/...     |
    | --------------------------> |
    |                             |
    |  2. 402 Payment Required    |
    | <-------------------------- |
    |     PAYMENT-REQUIRED:       |
    |     <challenge>             |
    |                             |
    |  3. GET /v1/wallets/...     |
    |     PAYMENT-SIGNATURE:      |
    |     <signed payment>        |
    | --------------------------> |
    |                             |
    |  4. 200 OK                  |
    | <-------------------------- |
    |                             |

Client sends a request to an API endpoint
Server returns 402 with a PAYMENT-REQUIRED header describing where and how much to pay
Client signs a USDC transfer and retries with a PAYMENT-SIGNATURE header
Zerion settles the payment via the Coinbase Developer Platform and returns the response

Rate limits

None - pay per request, no per-second or monthly quota.

Error handling

402 Payment required - no or invalid payment signature. Inspect the PAYMENT-REQUIRED response header for a fresh challenge and retry.
402 x402 payment rejected - the facilitator rejected the signature. The detail field contains the reason.
402 x402 payment settlement failed - the signature was valid but on-chain settlement failed.

See the Coinbase x402 troubleshooting docs for more.

Get Started

Core Concepts

Migrating to Zerion API

Quickstart with the Zerion CLI

Direct integration

Example

How it works

Rate limits

Error handling

​Quickstart with the Zerion CLI

​Direct integration

​Example

​How it works

​Rate limits

​Error handling

Quickstart with the Zerion CLI

Direct integration

Example

How it works

Rate limits

Error handling