> ## 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).

To resolve a name or symbol to a coin ID at runtime, use [/search](/reference/search-data) — it returns matching coins, categories, and markets:

```bash wrap theme={null}
https://pro-api.coingecko.com/api/v3/search?query=bitcoin
```

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

### Historical Data for Inactive Coins

Coins delisted from CoinGecko are excluded from [/coins/list](/reference/coins-list) by default, but their historical data stays queryable ([Analyst plan or above](https://www.coingecko.com/en/api/pricing)).

<Steps>
  <Step title="Get the coin ID — /coins/list">
    Call [/coins/list](/reference/coins-list) with `status=inactive`, then take the coin ID from the response.

    ```bash wrap theme={null}
    https://pro-api.coingecko.com/api/v3/coins/list?include_platform=false&status=inactive
    ```
  </Step>

  <Step title="Query the historical endpoints">
    Pass that coin ID to any of:

    * [/coins/\{id}/history](/reference/coins-id-history) — snapshot at a specific date
    * [/coins/\{id}/market\_chart](/reference/coins-id-market-chart) — time series over N days
    * [/coins/\{id}/market\_chart/range](/reference/coins-id-market-chart-range) — time series within a date range
    * [/coins/\{id}/contract/\{address}/market\_chart](/reference/contract-address-market-chart) — by contract address, over N days
    * [/coins/\{id}/contract/\{address}/market\_chart/range](/reference/contract-address-market-chart-range) — by contract address, within a date range
  </Step>
</Steps>

***

## 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` |
| **DEX vs CEX** | Use [/exchanges/id](/reference/exchanges-id)<br />Check `"centralized": false` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.