#1: Get Data by ID or Address

First thing first, here’s few key rules that help you understand the basics

Do you know that by knowing how to use ‘id’ and ‘contract address’, you’re already able to use about half of the 30+ endpoints offered by CoinGecko API?

1. There are 2 main ways to query price & market data of specific Coins:

a) Coin ID

This is one of the most widely used endpoint to get the latest price of Bitcoin:

e.g. try to click on this link below:

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

You will see ids=bitcoin and vs_currencies=usd on the link above, it means we’re trying to get the price of bitcoin in USD.

How do we get the ids of specific coins? There are 3 options:

1. Use /coins/list API endpoint, it will return the full list of Coins available on CoinGecko. You may then search for coin in the list using “name” and “symbol”, then obtain the “id” of specific coins.

   1. Reminder: “name” and “symbol” might change in the future, they are not unique. ”id” is the main unique identifier for different coins for you to use with CoinGecko API.

2. You may also view the full list using this Google Sheet.

3. You can also look for the “id” by visiting the info section of a Coin page on CoinGecko. (look for ‘API id’)

b) Coin Contract Address

Other than using Coin ID, you may also query price & market data of a coin using contract address:

e.g.

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

In the query above, there are 3 values that we need to input:

• ethereum ← asset_platform_id

• 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 ← contract_address

• usd ← vs_currencies (more on this in the next section)

While trying to query an endpoint using contract address, you must also specify the asset platform, which is equivalent to ‘blockchain network’. You may use the following endpoint to find the ids of all asset platforms supported by CoinGecko:

https://api.coingecko.com/api/v3/asset_platforms

How do we get the contract address of specific coins? There are 2 options:

1. You may visit the info section of a Coin page, and look for ‘Contract’

Not all coins will have contract address on CoinGecko site.

If an address is not shown on CoinGecko page, you will not be able to query the coin by contract address via API

If a address is not shown on CoinGecko page, you will not be able to query the coin by contract address via API

1. You might get it from project wesbsite, whitepaper, documentation, or block explorer site like Etherscan. e.g. for Uniswap:

   • https://docs.uniswap.org/protocol/concepts/governance/overview#uni-address
   • https://etherscan.io/token/0x1f9840a85d5af5bf1d1762f925bdaddc4201f984

2. In most cases, you will have to specify in which currency that you want the API data return.

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

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

Type	Currency	vs_currencies (API value)
Fiat	US Dollar	usd
Fiat	Japanese Yen	jpy
Fiat	Euro	eur
Cryptocurrency	Bitcoin	btc
Cryptocurrency	Ether	eth
Cryptocurrency	Binance Coin	bnb

You can view the full list of supported currencies here:

https://api.coingecko.com/api/v3/simple/supported_vs_currencies

3. Here’s another way to obtain coin prices & market data in bulk, by using ‘per_page’

The /coins/market endpoint will allow you to query Coins data in bulk. e.g.

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

The query above will return the top 100 Coins on CoinGecko, ranked by Market Cap, which is similar to what you see at the homepage of CoinGecko: https://www.coingecko.com/?page=1

Let’s deep dive a little bit on the parameters included above:

• vs_currency: usd

• order: market_cap_desc ← the data will be ranked from the largest to smallest Market Cap.

• per_page: 100 ← here it specifies that the page should contain 100 coins (max is 250 coins per page)

• page: 1 ←here it specifies the page number. if you input ‘2’ here and per_page=100 , then you will get the 101st-200th coin on CoinGecko, ranked by Market Cap, which is similar as the result of https://www.coingecko.com/?page=2