Skip to navigation
Tutorials

1. Get data by ID or Address

Methods to query price & market data of coins

a. Coin ID

Using the /simple/price endpoint as an example:

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

  • The provided endpoint URL includes parameters such as ids=bitcoin and vs_currencies=usd, indicating the intention to retrieve the current price of Bitcoin in US Dollars.

How to obtain Coin ID aka API ID? There are 3 options:

  • Use /coins/list endpoint, example of responses:

    JSON
    [
      ......
      {
      "id": "bitcoin", 👈
      "symbol": "btc",
      "name": "Bitcoin"
      },
      ......
    ]

  • View the full list of coins with API ID, symbol and name using this Google Sheet.

  • Look for the “API ID” by visiting the info section of a coin page on CoinGecko:

b. Contract Address

Other than using Coin ID, you may also query price & market data of a coin using contract address, using the /simple/token_price/{id} endpoint as an example:

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

There are 3 parameter values required for this endpoint:

  • id: ethereum (Asset Platform ID)
  • contract_addresses: 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 (Contract Address)
  • vs_currencies: usd (Target Currencies)

How to obtain Coins/Tokens Contract Address

  • Use /coins/list endpoint (include_platform=true), example of responses:
    JSON
    [
      ......
    	{
        "id": "1inch",
        "symbol": "1inch",
        "name": "1inch",
        "platforms": {
          "ethereum": "0x111111111117dc0aa78b770fa6a738034120c302",
          "avalanche": "0xd501281565bf7789224523144fe5d98e8b28f267",
          "binance-smart-chain": "0x111111111117dc0aa78b770fa6a738034120c302",
          "near-protocol": "111111111117dc0aa78b770fa6a738034120c302.factory.bridge.near",
          "energi": "0xdda6205dc3f47e5280eb726613b27374eee9d130",
          "harmony-shard-0": "0x58f1b044d8308812881a1433d9bbeff99975e70c",
          "polygon-pos": "0x9c2c5fd7b07e95ee044ddeba0e97a665f142394f"
          }
       },
      ......
    ]
  • Look for the “Contract” by visiting the info section of a coin page on CoinGecko.

Notes

  • Not all coins will have a contract address listed on the CoinGecko site.
  • If an address is not shown on the CoinGecko page, you will not be able to query the coin by its contract address via the API.
  • The contract addresses are curated by the CoinGecko team, if you find any missing contract address, feel free to share with us to review.

Specify target currency to return

In the 2 examples above, both queries for Coin ID and Contract Address contain vs_currencies=usd. Most of the CoinGecko API endpoints will require you to specify the currency.

CoinGecko API data supports all major fiat currencies and some famous cryptocurrencies like the following:

TypeCurrencyvs_currencies (Param value)
FiatUS Dollarusd
FiatJapanese Yenjpy
FiatEuroeur
CryptocurrencyBitcoinbtc
CryptocurrencyEthereth
CryptocurrencyBinance Coinbnb

For full list of supported currencies, please go to /simple/supported_vs_currencies endpoint.

Other ways to obtain coin prices & market data

Using the /coins/markets endpoint as an example to query prices and market data of coins in bulk:

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

There are 4 parameter values for this endpoint:

  • vs_currency: usd
  • order: market_cap_desc — The endpoint response will be sorted in descending order, from the coins with the largest market cap to those with the smallest.
  • per_page: 100 — The results of coins per page are set at 100 in this case (maximum is 250).
  • page: 1 — The page number of the results is determined by the parameter per_page. In the case of per_page=100 and page=2, the responses will include coins ranked 101 to 200 on CoinGecko, sorted by market cap, as per the specified endpoint.