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

# Querying Coin Data

> Coin IDs, contract addresses, bulk queries, historical data, and common CoinGecko API patterns

## Finding a Coin ID

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

> Find a coin's API ID on its [CoinGecko](https://www.coingecko.com) page, via [Coins List](/reference/coins-list), or this [Google Sheet](https://docs.google.com/spreadsheets/d/1wTTuxXt8n9q7C4NDXqQpI3wpKu1_5bGVmP9Xz0XGSyU/edit?usp=sharing).

<Frame>
  <img src="https://mintcdn.com/coingecko/i9l2MT4etZGYjSx8/assets/images/get-api-id.png?fit=max&auto=format&n=i9l2MT4etZGYjSx8&q=85&s=0fcda35a2d343d922c9a15dd2c6ecd19" width="2784" height="1602" data-path="assets/images/get-api-id.png" />
</Frame>

```bash wrap theme={null}
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.

```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/simple/token_price/ethereum?contract_addresses=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&vs_currencies=usd
```

* `id`: [asset platform](/reference/asset-platforms-list) ID (e.g. `ethereum`)
* `contract_addresses`: token contract address

Find contract addresses on the coin page at [CoinGecko](https://www.coingecko.com):

<Frame>
  <img src="https://mintcdn.com/coingecko/i9l2MT4etZGYjSx8/assets/images/get-coin-contract.png?fit=max&auto=format&n=i9l2MT4etZGYjSx8&q=85&s=f313ae741546438b55dd3e7adc071c25" width="2784" height="1602" data-path="assets/images/get-coin-contract.png" />
</Frame>

<Note>
  Not all coins have a contract address on CoinGecko. If unlisted, you can't query by address.
</Note>

Find addresses via [/coins/list](/reference/coins-list) with `include_platform=true`:

```json {5-9} theme={null}
{
  "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](/reference/simple-supported-currencies)

## Bulk Queries

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

```bash wrap theme={null}
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](/reference/coins-id-history)                                                    | Coin ID          | Snapshot at a specific date     |
| [/coins/\{id}/market\_chart](/reference/coins-id-market-chart)                                         | Coin ID          | Time series over N days         |
| [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range)                             | Coin ID          | Time series within a date range |
| [/coins/\{id}/contract/\{address}/market\_chart](/reference/contract-address-market-chart)             | Contract address | Time series over N days         |
| [/coins/\{id}/contract/\{address}/market\_chart/range](/reference/contract-address-market-chart-range) | Contract address | Time series within a date range |

<Note>
  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)
</Note>

***

## Common Patterns

| Pattern                   | How                                                                                                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **BTC exchange rate**     | **Current:** Use [/exchange\_rates](/reference/exchange-rates)<br />**Historical:** Use [/coins/id/history](/reference/coins-id-history)                                                 |
| **BTC dominance**         | Use [/global](/reference/crypto-global)<br />Read `market_cap_percentage.btc`                                                                                                            |
| **Category market caps**  | Use [/coins/categories](/reference/coins-categories)<br />Includes 24h change                                                                                                            |
| **Sparkline**             | Use [/coins/id](/reference/coins-id) or [/coins/markets](/reference/coins-markets)<br />Set `sparkline=true`                                                                             |
| **Stale price detection** | Use [/simple/price](/reference/simple-price)<br />Set `include_last_updated_at=true`                                                                                                     |
| **Inactive coins**        | Use [/coins/list](/reference/coins-list) with `status=inactive`<br />Then query [historical endpoints](#historical-data)<br />[Paid plan](https://www.coingecko.com/en/api/pricing) only |
| **DEX vs CEX**            | Use [/exchanges/id](/reference/exchanges-id)<br />Check `"centralized": false`                                                                                                           |