# x402: Pay-per-Request for Agents

Buy Arkham API responses one request at a time with USDC — no account, no API key, no subscription. Built for AI agents that need blockchain intelligence on demand, priced exactly like the classic API.

  **Base URL:** `https://api.arkm.com/x402` — agent instructions at [/skill.md](https://api.arkm.com/x402/skill.md), machine-readable catalog with prices at [/openapi.json](https://api.arkm.com/x402/openapi.json), full API docs for agents at [arkm.com/llms.txt](https://arkm.com/llms.txt)

## How It Works

Every endpoint speaks the [x402 protocol](https://x402.org) (v2): an unauthenticated request returns HTTP `402 Payment Required` with a signed price quote, the client pays in USDC on Base or Solana, and the same request succeeds.

1. **Request** — `POST` the endpoint with a JSON body (all parameters, including path parameters, go in the body).
2. **Quote** — the response is `402` with a `PAYMENT-REQUIRED` header: a base64 JSON challenge carrying the price, the receiving address, and the exact resource URL.
3. **Pay** — the client signs the payment for whichever network it picked from the challenge: an EIP-3009 USDC transfer authorization on Base, or a USDC payment transaction on Solana. No gas needed on your side; the facilitator broadcasts and pays gas.
4. **Response** — the request is retried with the payment header, Arkham serves the data, and settlement happens on-chain only after a successful response.

::: info
**Failed requests are never charged.** Payment settles only when the upstream call returns a success — an invalid parameter or a server error costs you nothing.
:::

Any x402-compatible client handles steps 2–4 automatically (the `@x402/*` SDKs among others); your agent code just makes HTTP calls with a funded wallet.

## Try It

Inspect a price quote without paying — request any endpoint and decode the challenge:

```bash
curl -s -X POST https://api.arkm.com/x402/balances/address \
  -H "Content-Type: application/json" \
  -d '{"address": "0x28C6c06298d514Db089934071355E5743bf21d60"}' \
  -D - -o /dev/null | tr -d '\r' | grep -i payment-required | cut -d' ' -f2 | base64 -d
```

The decoded challenge lists every accepted network (`eip155:8453` — Base mainnet, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` — Solana mainnet), each with its USDC asset address, the amount, and the `payTo` treasury address.

## Pricing

Prices mirror the classic API's [credit weights](/usage/credit-pricing) at **$0.20 per credit** — the same request costs the same whether you pay with a subscription or with USDC.

  Per-Call
  Fixed price each time you call the endpoint
  **Price = credits × $0.20**

  Per-Row
  Priced by the `limit` you request (default 50 if omitted), whether or not that many rows come back
  **Price = credits × limit × $0.20**

For per-row endpoints, pass the smallest `limit` that covers what you need: you pay for the limit you request, not the rows returned.

Per-endpoint prices are published in the catalog: every operation in [`/openapi.json`](https://api.arkm.com/x402/openapi.json) carries an `x-payment-info` block, and [`/skill.md`](https://api.arkm.com/x402/skill.md) lists them in a table.

## Free Discovery Endpoints

Three endpoints cost nothing so agents can orient before spending: `chains`, `networks/status`, and `arkm/circulating`. Instead of payment they ask for a **Sign-In-With-X** wallet signature (the `402` carries a `sign-in-with-x` challenge; sign it to prove wallet ownership — no funds move).

## Rate Limits

Enforced per paying wallet, per endpoint: **20 requests/second** by default, **1 request/second** on heavy endpoints (transfers, swaps, flow, counterparties, intelligence search, token leaderboards). The full list is in [`/skill.md`](https://api.arkm.com/x402/skill.md).

## Differences from the Classic API

| | Classic API | x402 |
|---|---|---|
| Auth | API key header | none — payment is the auth |
| Method | mostly `GET` | always `POST`, parameters in the JSON body |
| Billing | monthly credits | USDC per request, settled on-chain |
| Coverage | full API | public read catalog (~90 endpoints) |

Response schemas are identical — data comes from the same API.

## When to Use Which

Use **x402** for autonomous agents, one-off lookups, and integrations where provisioning an API key is impractical. Use the [classic API](/getting-started/access) for sustained volume — a subscription with monthly credits is cheaper at scale and covers endpoints outside the public read catalog.