Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.zerion.io/llms.txt

Use this file to discover all available pages before exploring further.

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: 
export WALLET_PRIVATE_KEY="0x..."
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                  |
    | <-------------------------- |
    |                             |
  1. Client sends a request to an API endpoint
  2. Server returns 402 with a PAYMENT-REQUIRED header describing where and how much to pay
  3. Client signs a USDC transfer and retries with a PAYMENT-SIGNATURE header
  4. 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.