> ## 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 payments: pay-per-request Zerion API access

> Call Zerion API without an API key by paying per request in USDC on Base or Solana with the x402 protocol. No signup, rate limits, or monthly plan needed.

x402 is [Coinbase's open protocol](https://github.com/coinbase/x402) 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](./mpp), a sibling protocol that settles on Tempo. See [Authentication](/authentication) for an overview of all access methods.

## Quickstart with the Zerion CLI

The easiest way to use x402 is with the [Zerion CLI](./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`:

<Tabs>
  <Tab title="Base (EVM)">
    ```bash theme={null}
    export WALLET_PRIVATE_KEY="0x..."
    zerion-cli wallet portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --x402
    ```
  </Tab>

  <Tab title="Solana">
    ```bash theme={null}
    export SOLANA_PRIVATE_KEY="<base58-encoded-keypair>"
    export ZERION_X402_PREFER_SOLANA=true
    zerion-cli wallet portfolio 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --x402
    ```
  </Tab>
</Tabs>

<Tip>
  Set `ZERION_X402=true` to enable x402 globally for analytics commands instead of passing `--x402` on every call.
</Tip>

## Direct integration

If you're not using the CLI, use the [Coinbase x402 SDK](https://github.com/coinbase/x402) (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

```ts theme={null}
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 onchain settlement failed.

See the [Coinbase x402 troubleshooting docs](https://docs.cdp.coinbase.com/x402/support/troubleshooting#common-errors) for more.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.