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.

To resolve a name or symbol to a coin ID at runtime, use /search — it returns matching coins, categories, and markets:

https://pro-api.coingecko.com/api/v3/search?query=bitcoin

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)

Historical Data for Inactive Coins

Coins delisted from CoinGecko are excluded from /coins/list by default, but their historical data stays queryable (Analyst plan or above).

Get the coin ID — /coins/list

Call /coins/list with status=inactive, then take the coin ID from the response.

https://pro-api.coingecko.com/api/v3/coins/list?include_platform=false&status=inactive

Query the historical endpoints

Pass that coin ID to any of:

/coins/{id}/history — snapshot at a specific date
/coins/{id}/market_chart — time series over N days
/coins/{id}/market_chart/range — time series within a date range
/coins/{id}/contract/{address}/market_chart — by contract address, over N days
/coins/{id}/contract/{address}/market_chart/range — by contract address, within a date range

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`
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

Historical Data for Inactive Coins

Common Patterns

​Finding a Coin ID

​Using Contract Addresses

​Target Currencies

​Bulk Queries

​Historical Data

​Historical Data for Inactive Coins

​Common Patterns

Finding a Coin ID

Using Contract Addresses

Target Currencies

Bulk Queries

Historical Data

Historical Data for Inactive Coins

Common Patterns