On-Demand Crypto Data via x402

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 flow.

x402 Overview

x402 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:

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.

Sign a USDC payment authorization

Your wallet signs an EIP-3009 transferWithAuthorization for the exact amount. The @x402/fetch client library handles this automatically; custom clients can sign with any EIP-712-compatible wallet.

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.

Authentication

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

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. Requires sharetoken header
`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 for how to obtain one.

Pricing & Payment Method


Network	Base mainnet (chain ID 8453)
Token	USDC — `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
Facilitator	Coinbase CDP
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`

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.

# 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

{
  "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 — 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 — surfaces CoinStats in its AI-agent marketplace alongside other x402-enabled data services.

Getting started

AI Agents Integration

Wallet Data

User Portfolio

Token Security

x402 Overview

How It Works

Authentication

Supported Endpoints

Pricing & Payment Method

Request Example

Node.js — `@x402/fetch`

cURL — manual

Response Example

Discovery

Further Reading

​x402 Overview

​How It Works

​Authentication

​Supported Endpoints

​Pricing & Payment Method

​Request Example

​Node.js — @x402/fetch

​cURL — manual

​Response Example

​Discovery

​Further Reading

x402 Overview

How It Works

Authentication

Supported Endpoints

Pricing & Payment Method

Request Example

Node.js — `@x402/fetch`

cURL — manual

Response Example

Discovery

Further Reading