> ## Documentation Index
> Fetch the complete documentation index at: https://coinstats.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# On-Demand Crypto Data via x402

> Pay-per-request access to CoinStats market data, wallet balances, news, and portfolio reads — no API key required. Built on Coinbase's x402 open payment protocol.

<Note>
  These endpoints are pay-per-use and intended for AI agents and experimental use
  cases. Features and pricing may change. For production workloads, we recommend
  the standard [API key authentication](/authentication) flow.
</Note>

## x402 Overview

[x402](https://www.x402.org) is an open payment protocol developed by
Coinbase that uses HTTP `402 Payment Required` responses to charge for
individual API calls with instant stablecoin payments. Instead of signing
up for an account and managing an API key, agents pay in USDC per request
directly from a wallet.

CoinStats exposes a pay-per-use surface covering every read-only endpoint
in the CoinStats Public API — live coin prices, market data, news,
insights, wallet balances and DeFi positions, plus shared portfolio reads.

## How It Works

Every request to a protected endpoint follows the same three-step flow:

<Steps>
  <Step title="Request the endpoint">
    Send a normal `GET` request. Because no payment is attached, the
    gateway responds with HTTP `402 Payment Required` — the response
    includes the required amount, currency, wallet address, and network.
  </Step>

  <Step title="Sign a USDC payment authorization">
    Your wallet signs an EIP-3009 `transferWithAuthorization` for the
    exact amount. The [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch)
    client library handles this automatically; custom clients can sign
    with any EIP-712-compatible wallet.
  </Step>

  <Step title="Retry with the payment header">
    Send the same request again, this time with the `X-PAYMENT` header
    containing the signed authorization. The facilitator settles on
    chain and the gateway returns the data with an `X-PAYMENT-RESPONSE`
    receipt. A `Set-Cookie: auth_token=...` header is also issued —
    subsequent calls within one hour skip the facilitator entirely.
  </Step>
</Steps>

## Authentication

No API key is needed. Point your client at the dedicated x402 subdomain
and skip the `x-api-key` header:

```text theme={null}
https://x402.coinstats.app
```

Every path that exists at `https://api.coinstats.app/v1` under the
supported list below is gated by x402 at `https://x402.coinstats.app`.

## Supported Endpoints

Every listed endpoint is a read-only `GET`. Prices are quoted in USDC
and settle on Base mainnet (chain ID 8453).

| Endpoint                               | Price   | Description                                                                                                                                          |
| -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /coins`                           | \$0.001 | CoinStats list of all cryptocurrencies with live market data — price, volume, market cap, rank, % changes                                            |
| `GET /wallet/defi`                     | \$0.04  | CoinStats DeFi positions for a wallet — staked, lent, borrowed, LP balances across protocols (Aave, Lido, Uniswap, Curve, etc.)                      |
| `GET /coins/{coinId}`                  | \$0.001 | CoinStats detailed data for a single cryptocurrency — price, market cap, supply, rank, links                                                         |
| `GET /wallet/balance`                  | \$0.004 | CoinStats live balance for a wallet address on a single blockchain — coins and token amounts with USD values                                         |
| `GET /coins/price/avg`                 | \$0.001 | CoinStats historical average price for a cryptocurrency at a given timestamp                                                                         |
| `GET /coins/price/exchange`            | \$0.001 | CoinStats historical price on a specific exchange (Binance, Coinbase, Kraken, etc.) at a timestamp                                                   |
| `GET /coins/{coinId}/charts`           | \$0.001 | CoinStats price chart for a single cryptocurrency — time series over 24h/1w/1m/1y/all                                                                |
| `GET /markets`                         | \$0.001 | CoinStats global cryptocurrency market data — total market cap, 24h volume, BTC dominance, % changes                                                 |
| `GET /tickers/exchanges`               | \$0.001 | CoinStats list of supported cryptocurrency exchanges with metadata                                                                                   |
| `GET /tickers/markets`                 | \$0.001 | CoinStats ticker market data — live prices across exchanges for a trading pair                                                                       |
| `GET /fiats`                           | \$0.001 | CoinStats list of supported fiat currencies (USD, EUR, GBP, JPY, etc.) with conversion metadata                                                      |
| `GET /currencies`                      | \$0.001 | CoinStats live currency exchange rates for supported fiat pairs                                                                                      |
| `GET /news/sources`                    | \$0.001 | CoinStats list of crypto news sources aggregated across the industry                                                                                 |
| `GET /news/type/{type}`                | \$0.001 | CoinStats crypto news filtered by topic (handpicked, trending, latest, bullish, bearish)                                                             |
| `GET /news/{id}`                       | \$0.001 | CoinStats crypto news article by id — title, body, source, sentiment                                                                                 |
| `GET /news`                            | \$0.001 | CoinStats latest crypto news feed — articles on Bitcoin, Ethereum, DeFi, NFTs, regulation                                                            |
| `GET /insights/btc-dominance`          | \$0.001 | CoinStats Bitcoin market dominance percentage over time — share of total crypto market cap                                                           |
| `GET /insights/fear-and-greed/chart`   | \$0.001 | CoinStats Fear & Greed Index historical chart — market sentiment over time                                                                           |
| `GET /insights/fear-and-greed`         | \$0.001 | CoinStats current Fear & Greed Index — sentiment score from Extreme Fear (0) to Extreme Greed (100)                                                  |
| `GET /insights/rainbow-chart/{coinId}` | \$0.001 | CoinStats rainbow chart for BTC/ETH — logarithmic valuation bands from cycle lows to bubble highs                                                    |
| `GET /wallet/blockchains`              | \$0.001 | CoinStats list of supported wallet blockchains and their connectionId identifiers                                                                    |
| `GET /wallet/balance/many`             | \$0.004 | CoinStats multi-chain wallet balances — aggregate holdings across multiple wallets + blockchains in one call                                         |
| `GET /wallet/status`                   | \$0.001 | CoinStats wallet sync status — whether CoinStats has finished indexing transactions for the given wallet                                             |
| `GET /wallet/transactions`             | \$0.003 | CoinStats wallet transaction history — token transfers, swaps, buys, sells for a wallet address                                                      |
| `GET /wallet/charts`                   | \$0.004 | CoinStats portfolio value charts across multiple wallets — aggregated historical balance over time                                                   |
| `GET /wallet/chart`                    | \$0.004 | CoinStats portfolio value chart for a single wallet — historical USD value with PnL                                                                  |
| `GET /exchange/support`                | \$0.001 | CoinStats list of supported cryptocurrency exchanges for portfolio connection (Binance, Coinbase, Kraken, Bybit, OKX, etc.)                          |
| `GET /portfolio/snapshot/items`        | \$0.05  | CoinStats portfolio snapshot — historical coin balances over time for a shared portfolio. Provide sharetoken header from a Degen-plan CoinStats user |
| `GET /portfolio/value`                 | \$0.001 | CoinStats shared portfolio total value and PnL — total value, DeFi value, unrealized + realized profit/loss. Requires sharetoken header              |
| `GET /portfolio/coins`                 | \$0.001 | CoinStats shared portfolio holdings — all coins with current value, PnL, performance metrics. Requires sharetoken header                             |
| `GET /portfolio/chart`                 | \$0.001 | CoinStats shared portfolio value chart — historical USD value over 24h/1w/1m/1y. Requires sharetoken header                                          |
| `GET /portfolio/transactions`          | \$0.001 | CoinStats shared portfolio transaction history — all buys, sells, transfers with timestamps and prices. Requires sharetoken header                   |
| `GET /portfolio/defi`                  | \$0.04  | CoinStats shared portfolio DeFi positions — staking, lending, LP pools, yield farming across protocols. Requires sharetoken header                   |

Endpoints marked with `sharetoken` require a `sharetoken` header —
the CoinStats user shares a portfolio link from the mobile app and
hands the token to the agent. See [shareToken](/sharetoken) for how
to obtain one.

## Pricing & Payment Method

|                  |                                                              |
| ---------------- | ------------------------------------------------------------ |
| **Network**      | Base mainnet (chain ID 8453)                                 |
| **Token**        | USDC — `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`          |
| **Facilitator**  | [Coinbase CDP](https://docs.cdp.coinbase.com/x402)           |
| **Minimum call** | \$0.001 USDC                                                 |
| **Gas**          | Sponsored by the facilitator — payers need USDC only, no ETH |

Pricing is tiered by the underlying data cost. Simple lookups (coin
price, markets, news) are $0.001. Wallet-scoped queries are $0.004.
Heavy DeFi/portfolio aggregations are $0.04–$0.05.

## Request Example

### Node.js — `@x402/fetch`

```ts theme={null}
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { x402Client } from "@x402/core/client";

const account = privateKeyToAccount("0x..."); // wallet funded with USDC on Base
const client = new x402Client();
registerExactEvmScheme(client, {
  signer: account,
  networks: ["eip155:8453"],
});
const paid = wrapFetchWithPayment(fetch, client);

const res = await paid("https://x402.coinstats.app/coins/bitcoin");
const data = await res.json();
console.log(data);
```

The first request triggers the 402 → sign → settle loop; subsequent
calls within an hour reuse the `auth_token` cookie and skip the
facilitator round-trip.

### cURL — manual

The `402` challenge is returned in the `payment-required` response
header (base64-encoded JSON). To settle manually you'd need to sign an
EIP-3009 authorization and replay the request with `X-PAYMENT`. For
any real workload, use the `@x402/fetch` client library above.

```bash theme={null}
# Probe the challenge — no payment yet
curl -s -D - https://x402.coinstats.app/coins/bitcoin -o /dev/null | \
  grep -i payment-required | \
  sed 's/^payment-required: //' | base64 -d | jq
```

## Response Example

```json theme={null}
{
  "id": "bitcoin",
  "icon": "https://static.coinstats.app/coins/1650455588819.png",
  "name": "Bitcoin",
  "symbol": "BTC",
  "rank": 1,
  "price": 43250.75,
  "priceBtc": 1,
  "volume": 15420000000,
  "marketCap": 849231200000,
  "availableSupply": 19628543,
  "totalSupply": 21000000,
  "priceChange1h": 0.12,
  "priceChange1d": 2.45,
  "priceChange1w": -1.87,
  "priceChange1m": 5.24
}
```

The `X-PAYMENT-RESPONSE` header on a 200 contains the settlement
receipt (transaction hash + facilitator ack) for record-keeping.

## Discovery

CoinStats endpoints are discoverable by agents via two indexes:

* **[CDP Bazaar](https://docs.cdp.coinbase.com/x402/bazaar)** — every
  paid call is indexed under
  `https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources`
  with full-text searchable descriptions and input/output schemas.
* **[agentic.market](https://agentic.market)** — surfaces CoinStats in
  its AI-agent marketplace alongside other x402-enabled data services.

## Further Reading

* [x402 protocol site](https://www.x402.org) — spec, reference clients, ecosystem
* [CDP x402 Quickstart](https://docs.cdp.coinbase.com/x402/quickstart)
* [Cloudflare's x402 integration post](https://blog.cloudflare.com/x402/)
* [CoinStats Public API reference](/api-reference) — detailed schemas for every endpoint