Skip to main content
GET
/
coins
/
markets
Coins List with Market Data
curl --request GET \
  --url https://api.coingecko.com/api/v3/coins/markets \
  --header 'x-cg-demo-api-key: <api-key>'
[
  {
    "id": "bitcoin",
    "symbol": "btc",
    "name": "Bitcoin",
    "image": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
    "current_price": 70187,
    "market_cap": 1381651251183,
    "market_cap_rank": 1,
    "fully_diluted_valuation": 1474623675796,
    "total_volume": 20154184933,
    "high_24h": 70215,
    "low_24h": 68060,
    "price_change_24h": 2126.88,
    "price_change_percentage_24h": 3.12502,
    "market_cap_change_24h": 44287678051,
    "market_cap_change_percentage_24h": 3.31157,
    "circulating_supply": 19675987,
    "total_supply": 21000000,
    "max_supply": 21000000,
    "ath": 73738,
    "ath_change_percentage": -4.77063,
    "ath_date": "2024-03-14T07:10:36.635Z",
    "atl": 67.81,
    "atl_change_percentage": 103455.83335,
    "atl_date": "2013-07-06T00:00:00.000Z",
    "roi": null,
    "last_updated": "2024-04-07T16:49:31.736Z"
  }
]

​
Tips

  • You can retrieve specific coins using their unique ids, names, or symbols instead of returning the whole list.
  • To filter results based on the coin’s category, use the category param (refer to /coins/categories/list for available categories).
  • Use the per_page and page params to manage the number of results you receive and navigate through the data.

​
Note

  • When multiple lookup params are provided, the following priority order is applied: category (highest) > ids > names > symbols (lowest).
  • When searching by name, you need to URL-encode any spaces (e.g. “Binance Coin” becomes “Binance%20Coin”).
  • The include_tokens=all param is exclusively for use with the symbols lookup and is limited to maximum of 50 symbols per request.
  • Wildcard searches are not supported for lookup params (ids, names, symbols).
  • Cache/Update Frequency:
    • Every 60 seconds for Public API.
    • Every 45 seconds for Pro API (Analyst, Lite, Pro, Enterprise).

Authorizations

​
x-cg-demo-api-key
string
header
required

Query Parameters

​
vs_currency
string
default:usd
required

target currency of coins and market data *refers to /simple/supported_vs_currencies.

Example:

"usd"

​
ids
string
default:bitcoin

coins' IDs, comma-separated if querying more than 1 coin. *refers to /coins/list.

​
names
string
default:Bitcoin

coins' names, comma-separated if querying more than 1 coin.

​
symbols
string
default:btc

coins' symbols, comma-separated if querying more than 1 coin.

​
include_tokens
enum<string>

for symbols lookups, specify all to include all matching tokens Default top returns top-ranked tokens (by market cap or volume)

Available options:
top,
all
​
category
string
default:layer-1

filter based on coins' category *refers to /coins/categories/list.

Example:

"layer-1"

​
order
enum<string>

sort result by field, default: market_cap_desc

Available options:
market_cap_asc,
market_cap_desc,
volume_asc,
volume_desc,
id_asc,
id_desc
​
per_page
integer

total results per page, default: 100 Valid values: 1...250

​
page
integer

page through results, default: 1

​
sparkline
boolean

include sparkline 7 days data, default: false

​
price_change_percentage
string
default:1h

include price change percentage timeframe, comma-separated if query more than 1 timeframe Valid values: 1h, 24h, 7d, 14d, 30d, 200d, 1y

​
locale
enum<string>

language background, default: en

Available options:
ar,
bg,
cs,
da,
de,
el,
en,
es,
fi,
fr,
he,
hi,
hr,
hu,
id,
it,
ja,
ko,
lt,
nl,
no,
pl,
pt,
ro,
ru,
sk,
sl,
sv,
th,
tr,
uk,
vi,
zh,
zh-tw
​
precision
enum<string>

decimal place for currency price value

Available options:
full,
0,
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15,
16,
17,
18

Response

200 - application/json

List all coins with market data

​
id
string

coin ID

​
symbol
string

coin symbol

​
name
string

coin name

​
image
string

coin image url

​
current_price
number

coin current price in currency

​
market_cap
number

coin market cap in currency

​
market_cap_rank
number

coin rank by market cap

​
fully_diluted_valuation
number

coin fully diluted valuation (fdv) in currency

​
total_volume
number

coin total trading volume in currency

​
high_24h
number

coin 24hr price high in currency

​
low_24h
number

coin 24hr price low in currency

​
price_change_24h
number

coin 24hr price change in currency

​
price_change_percentage_24h
number

coin 24hr price change in percentage

​
market_cap_change_24h
number

coin 24hr market cap change in currency

​
market_cap_change_percentage_24h
number

coin 24hr market cap change in percentage

​
circulating_supply
number

coin circulating supply

​
total_supply
number

coin total supply

​
max_supply
number

coin max supply

​
ath
number

coin all time high (ATH) in currency

​
ath_change_percentage
number

coin all time high (ATH) change in percentage

​
ath_date
string<date-time>

coin all time high (ATH) date

​
atl
number

coin all time low (atl) in currency

​
atl_change_percentage
number

coin all time low (atl) change in percentage

​
atl_date
string<date-time>

coin all time low (atl) date

​
roi
string
​
last_updated
string<date-time>

coin last updated timestamp