> ## 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

> Access the Zerion API per-request using USDC on Base or Solana — no API key required.

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 on-chain settlement failed.

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