Querying Coin Data

Finding a Coin ID

Most endpoints require a coin ID (e.g. bitcoin, ethereum).

Find a coin’s API ID on its CoinGecko page, via Coins List, or this Google Sheet.

https://pro-api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd

Using Contract Addresses

Query by contract address instead of coin ID — useful when you don’t know the CoinGecko ID.

https://pro-api.coingecko.com/api/v3/simple/token_price/ethereum?contract_addresses=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&vs_currencies=usd

id: asset platform ID (e.g. ethereum)
contract_addresses: token contract address

Find contract addresses on the coin page at CoinGecko:

Not all coins have a contract address on CoinGecko. If unlisted, you can’t query by address.

Find addresses via /coins/list with include_platform=true:

{
  "id": "1inch",
  "symbol": "1inch",
  "name": "1inch",
  "platforms": {
    "ethereum": "0x111111111117dc0aa78b770fa6a738034120c302",
    "avalanche": "0xd501281565bf7789224523144fe5d98e8b28f267",
    "binance-smart-chain": "0x111111111117dc0aa78b770fa6a738034120c302"
  }
}

Target Currencies

Type	Examples
Fiat	`usd`, `eur`, `jpy`, `gbp`
Crypto	`btc`, `eth`, `bnb`

Full list: /simple/supported_vs_currencies

Bulk Queries

/coins/markets — price and market data for many coins at once (up to 250 per page).

https://pro-api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=100&page=1

Historical Data

Endpoint	Query by	Description
/coins/{id}/history	Coin ID	Snapshot at a specific date
/coins/{id}/market_chart	Coin ID	Time series over N days
/coins/{id}/market_chart/range	Coin ID	Time series within a date range
/coins/{id}/contract/{address}/market_chart	Contract address	Time series over N days
/coins/{id}/contract/{address}/market_chart/range	Contract address	Time series within a date range

Auto-granularity based on time range:

1 day from now → 5-minute intervals
1 day from any other time → hourly
2–90 days → hourly
90+ days → daily (00:00 UTC)

Common Patterns

Pattern	How
BTC exchange rate	Current: Use /exchange_rates Historical: Use /coins/id/history
BTC dominance	Use /global Read `market_cap_percentage.btc`
Category market caps	Use /coins/categories Includes 24h change
Sparkline	Use /coins/id or /coins/markets Set `sparkline=true`
Stale price detection	Use /simple/price Set `include_last_updated_at=true`
Inactive coins	Use /coins/list with `status=inactive` Then query historical endpoints Paid plan only
DEX vs CEX	Use /exchanges/id Check `"centralized": false`

Get Started

Guides

Resources

Finding a Coin ID

Using Contract Addresses

Target Currencies

Bulk Queries

Historical Data

Common Patterns

​Finding a Coin ID

​Using Contract Addresses

​Target Currencies

​Bulk Queries

​Historical Data

​Common Patterns

Finding a Coin ID

Using Contract Addresses

Target Currencies

Bulk Queries

Historical Data

Common Patterns