Crypto Price Data Guide

---
name: crypto-price-data-guide
description: How cryptocurrency prices work — the complete data pipeline from CEX order books and DEX pools through oracle networks to aggregators. Covers free API alternatives to CoinGecko, VWAP/TWAP calculations, and building price feeds without paid APIs. Use when explaining price sources, building market data features, or comparing data providers.
license: MIT
metadata:
  category: analysis
  difficulty: intermediate
  author: clawhub
  tags: [analysis, crypto-price-data-guide]
---

# Crypto Price Data Guide

Where do crypto prices actually come from? This guide breaks down the entire data pipeline — from raw exchange data to the numbers you see in apps.

## The Price Data Pipeline

```
┌──────────────────────────────────────────────────────────┐
│  LAYER 1: Primary Sources (where prices originate)       │
│                                                          │
│  CEX Order Books          DEX AMM Pools                  │
│  ┌──────────────┐        ┌──────────────┐                │
│  │ Binance      │        │ Uniswap V3   │                │
│  │ Coinbase     │        │ Curve        │                │
│  │ Kraken       │        │ Camelot      │                │
│  │ OKX, Bybit   │        │ Balancer     │                │
│  └──────┬───────┘        └──────┬───────┘                │
│         │                       │                        │
├─────────┼───────────────────────┼────────────────────────┤
│  LAYER 2: Oracle Networks (aggregate + post on-chain)    │
│         │                       │                        │
│         ▼                       ▼                        │
│  ┌──────────────────────────────────────┐                │
│  │ Chainlink     Pyth     Redstone      │                │
│  │ (median of multiple data sources)    │                │
│  └──────────────────┬───────────────────┘                │
│                     │                                    │
├─────────────────────┼────────────────────────────────────┤
│  LAYER 3: Aggregators (combine everything)               │
│                     ▼                                    │
│  ┌──────────────────────────────────────┐                │
│  │ CoinGecko  DeFi Llama  CoinMarketCap │                │
│  │ DexScreener  CoinCap   CoinPaprika   │                │
│  └──────────────────┬───────────────────┘                │
│                     │                                    │
├─────────────────────┼────────────────────────────────────┤
│  LAYER 4: Consumer Apps                                  │
│                     ▼                                    │
│  Portfolio trackers, trading bots, DeFi protocols,       │
│  AI agents (like SperaxOS), wallets                      │
└──────────────────────────────────────────────────────────┘
```

## Layer 1: Primary Price Sources

### Centralized Exchange (CEX) APIs

CEXes are the **dominant** price source for high-cap tokens. Their order books determine the "true" price through supply/demand matching.

| Exchange | Public API | Rate Limit | WebSocket |
|----------|-----------|-----------|-----------|
| **Binance** | `api.binance.com/api/v3/` | 1200 req/min | ✅ Real-time |
| **Coinbase** | `api.exchange.coinbase.com/` | 10 req/sec | ✅ Real-time |
| **Kraken** | `api.kraken.com/0/public/` | 1 req/sec | ✅ Real-time |
| **OKX** | `okx.com/api/v5/market/` | 20 req/2sec | ✅ Real-time |
| **Bybit** | `api.bybit.com/v5/market/` | 120 req/sec | ✅ Real-time |

**All of these are free, no API key required for public market data.**

#### Example: Binance Spot Price

```
GET https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT

Response: { "symbol": "BTCUSDT", "price": "64523.45000000" }
```

#### Example: Binance 24h Ticker

```
GET https://api.binance.com/api/v3/ticker/24hr?symbol=ETHUSDT

Response: {
  "symbol": "ETHUSDT",
  "priceChange": "45.20",
  "priceChangePercent": "1.42",
  "lastPrice": "3245.67",
  "volume": "584231.45",
  "highPrice": "3289.00",
  "lowPrice": "3178.23"
}
```

### DEX On-Chain Data

For tokens that aren't listed on CEXes (the **long tail**), DEX pools are the only price source.

| Source | Chains | How Price Is Determined |
|--------|--------|----------------------|
| **Uniswap V2** | ETH, Arbitrum, etc. | Constant product: price = reserveB / reserveA |
| **Uniswap V3** | ETH, Arbitrum, etc. | Square root price from pool slot0: sqrtPriceX96 |
| **Curve** | ETH, Arbitrum, etc. | StableSwap invariant (optimized for pegged assets) |
| **Camelot** | Arbitrum | V2 + V3 pools (Arbitrum-native) |

**Reading DEX prices**:
1. **Direct RPC** — Call pool contracts to read reserves/sqrtPrice
2. **The Graph** — Query indexed swap events via GraphQL
3. **DexScreener API** — Aggregated DEX data across 80+ chains

#### DexScreener Example

```
GET https://api.dexscreener.com/latest/dex/tokens/0xD74f5255D557944cf7Dd0E45FF521520002D5748

Returns: SPA pair data across all DEXes
```

### How CEX and DEX Prices Stay in Sync

**Arbitrage bots**. If ETH is $3,200 on Binance but $3,210 on Uniswap:
1. Bot buys on Binance (cheaper)
2. Bot sells on Uniswap (expensive)
3. Price difference narrows until it's less than gas + bridge costs

This is why prices across venues are usually within 0.1–0.5% of each other.

## Layer 2: Oracle Networks

Oracles aggregate CEX + DEX data and make it available **on-chain** for smart contracts.

### Chainlink

The dominant oracle network. ~1000+ price feeds across EVM chains.

**How it works**:
1. Multiple independent oracle nodes fetch prices from CEXes and DEXes
2. Each node submits its observation to the aggregator contract
3. The contract takes the **median** of all observations
4. Updates when: deviation > threshold (typically 0.5–1%) OR heartbeat time passes

**Reading a Chainlink feed on-chain**:

```
// ETH/USD on Ethereum: 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419
// SPA/USD on Arbitrum: Available via Chainlink

function getPrice() {
    (, int256 price,,,) = priceFeed.latestRoundData();
    return uint256(price); // 8 decimals
}
```

**Key feeds**:

| Feed | Address (Ethereum) | Decimals |
|------|-------------------|----------|
| ETH/USD | `0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419` | 8 |
| BTC/USD | `0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c` | 8 |
| USDC/USD | `0x8fFfFfd4AfB6115b954Bd326cbe7B4BA576818f6` | 8 |

> **Sperax Context**: USDs uses Chainlink price feeds via its MasterPriceOracle to value collateral (USDC, USDT) and maintain its peg.

### Pyth Network

**Pull oracle** — prices update sub-second but consumers must "pull" the latest update on-chain.

```
GET https://hermes.pyth.network/api/latest_price_feeds?ids[]=0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace

Returns: { price: "6452345000000", expo: -8, conf: "2500000" }
```

### Chainlink vs Pyth

| Feature | Chainlink | Pyth |
|---------|-----------|------|
| Model | Push (auto-updates) | Pull (consumer requests) |
| Latency | 1–60 min heartbeat | ~400ms |
| Cost | Gas paid by oracle network | Gas paid by consumer |
| Coverage | 1000+ feeds | 500+ feeds |
| Security | Battle-tested (5+ years) | Newer but growing fast |

## Layer 3: Free Aggregator APIs

These combine CEX + DEX + oracle data into convenient APIs.

### DeFi Llama (Best Free Option)

**Zero rate limiting. Zero API key. Most generous free API in crypto.**

| Endpoint | What It Returns |
|----------|----------------|
| `coins.llama.fi/prices/current/{coins}` | Current prices for any token |
| `api.llama.fi/protocols` | All tracked protocols with TVL |
| `yields.llama.fi/pools` | All yield pools across DeFi |
| `stablecoins.llama.fi/stablecoins` | All stablecoin market data |

**Price query example**:
```
GET https://coins.llama.fi/prices/current/arbitrum:0xD74f5255D557944cf7Dd0E45FF521520002D5748

Returns: USDs price from on-chain sources
```

### CoinCap

Simple, clean API for top 2000 coins.

```
GET https://api.coincap.io/v2/assets?limit=10

Returns: Top 10 coins by market cap with price, volume, change
```

### CoinPaprika

Decent free tier with ATH data and social links.

```
GET https://api.coinpaprika.com/v1/tickers/btc-bitcoin

Returns: Price, ATH, ATH date, volume, market cap, beta, supply
```

### CryptoCompare

Good for OHLCV (candlestick) data.

```
GET https://min-api.cryptocompare.com/data/v2/histoday?fsym=BTC&tsym=USD&limit=30

Returns: 30 days of daily OHLCV data
```

## Building Without CoinGecko

A practical multi-source approach:

| Data Need | Primary Source | Fallback |
|-----------|---------------|----------|
| Top coin prices | Binance API | CoinCap |
| Long-tail tokens | DexScreener | DeFi Llama |
| Historical OHLCV | CryptoCompare | Binance klines |
| TVL / protocol data | DeFi Llama | — (only source) |
| Yield / APY data | DeFi Llama yields | — |
| On-chain accurate price | Chainlink feeds | Pyth |
| Token metadata | CoinPaprika | Token Lists |
| Market sentiment | Fear & Greed API | — |

**Waterfall strategy** (what production apps use):
```
1. Try Binance (fastest, most liquid)
2. Fall back to CoinCap (broader coverage)
3. Fall back to DexScreener (on-chain tokens)
4. Fall back to DeFi Llama (universal)
```

> **SperaxOS** uses a similar multi-provider waterfall: Binance → CoinCap → DexScreener → CoinGecko for maximum reliability.

## Price Calculation Methods

### VWAP (Volume-Weighted Average Price)

How aggregators compute a single price from multiple exchanges:

```
VWAP = Σ(Price_i × Volume_i) / Σ(Volume_i)
```

Example:
| Exchange | Price | 24h Volume |
|----------|-------|-----------|
| Binance | $3,200 | $2B |
| Coinbase | $3,205 | $500M |
| Kraken | $3,198 | $100M |

```
VWAP = (3200×2B + 3205×500M + 3198×100M) / (2B + 500M + 100M)
     = $3,200.96
```

### TWAP (Time-Weighted Average Price)

Used by Uniswap V3 oracle and some protocols:

```
TWAP = Average price over a time window (e.g., last 30 minutes)
```

More resistant to manipulation than spot price.

## Agent Tips

1. **Never rely on a single source** — always implement fallbacks
2. **CEX data is freshest** for major tokens — use Binance/Coinbase first
3. **DEX data is essential** for tokens not listed on CEXes
4. **DeFi Llama is the best free API** — zero rate limiting, comprehensive
5. **Chainlink feeds are the gold standard** for on-chain price verification
6. **Always show the data source** — users should know where prices come from

## Links

- DeFi Llama API: https://defillama.com/docs/api
- Binance API: https://binance-docs.github.io/apidocs/
- Chainlink Feeds: https://data.chain.link
- DexScreener: https://docs.dexscreener.com
- CoinCap: https://docs.coincap.io
- Pyth Network: https://pyth.network
- Sperax (uses Chainlink for USDs pricing): https://app.sperax.io