Use this workflow when you need historical market data for charts, analytics, or backtesting.
Choose the right endpoint
Use GET /v3/cryptocurrency/quotes/historical when you want a historical quote series
Use GET /v2/cryptocurrency/ohlcv/historical when you need candlestick data with open, high, low, close, and volume
Use GET /v5/cryptocurrency/ohlcv/historical when you need candles for one cryptocurrency as compact rows, or calendar-week (1w) and calendar-month (1M) candles
Historical quotes example
This example fetches the last 7 daily quote points for Bitcoin in USD.
curl -G 'https://pro-api.coinmarketcap.com/v3/cryptocurrency/quotes/historical' \
--data-urlencode 'id=1' \
--data-urlencode 'count=7' \
--data-urlencode 'interval=daily' \
--data-urlencode 'convert=USD' \
-H 'Accept: application/json' \
-H 'X-CMC_PRO_API_KEY: YOUR_API_KEY'
The same request with the official SDKs, @coinmarketcap/sdk and coinmarketcap-sdk :
import { CoinMarketCap } from "@coinmarketcap/sdk" ;
const cmc = new CoinMarketCap ({ apiKey: process.env. CMC_PRO_API_KEY });
const { data , error } = await cmc.api.cryptocurrency. quotesHistorical ({
query: { id: "1" , count: 7 , interval: "daily" , convert: "USD" },
});
if (error) throw error;
console. log (data);
import os
from coinmarketcap import CoinMarketCap
cmc = CoinMarketCap( api_key = os.environ[ "CMC_PRO_API_KEY" ])
history = cmc.cryptocurrency.quotes_historical( id = "1" , count = 7 , interval = "daily" , convert = "USD" )
print (history)
In Go, with a client created as on the Go SDK page:
history, err := cmc.Cryptocurrency. QuotesHistorical (ctx, & coinmarketcap . CryptocurrencyQuotesHistoricalParams {
ID: coinmarketcap. String ( "1" ),
Count: coinmarketcap. Float64 ( 7 ),
Interval: coinmarketcap. Ptr (coinmarketcap. GetV3CryptocurrencyQuotesHistoricalParamsInterval ( "daily" )),
Convert: coinmarketcap. String ( "USD" ),
})
Use this when you want a time series of quote snapshots. Truncated response:
{
"status" : {
"timestamp" : "2025-01-15T12:00:00.000Z" ,
"error_code" : 0 ,
"error_message" : null ,
"elapsed" : 15 ,
"credit_count" : 1
},
"data" : [
{
"id" : 1 ,
"name" : "Bitcoin" ,
"symbol" : "BTC" ,
"quotes" : [
{
"timestamp" : "2025-01-08T23:59:59.999Z" ,
"quote" : {
"USD" : {
"price" : 96800.00 ,
"volume_24h" : 28000000000 ,
"market_cap" : 1916640000000 ,
"timestamp" : "2025-01-08T23:59:59.999Z"
}
}
},
{
"timestamp" : "2025-01-09T23:59:59.999Z" ,
"quote" : {
"USD" : {
"price" : 97250.50 ,
"volume_24h" : 30500000000 ,
"market_cap" : 1925561000000 ,
"timestamp" : "2025-01-09T23:59:59.999Z"
}
}
}
]
}
]
}
OHLCV example
This example fetches 7 daily OHLCV candles for Bitcoin in USD.
curl -G 'https://pro-api.coinmarketcap.com/v2/cryptocurrency/ohlcv/historical' \
--data-urlencode 'id=1' \
--data-urlencode 'time_period=daily' \
--data-urlencode 'count=7' \
--data-urlencode 'convert=USD' \
-H 'Accept: application/json' \
-H 'X-CMC_PRO_API_KEY: YOUR_API_KEY'
With the official SDKs, reusing the cmc client from the first example:
const { data , error } = await cmc.api.cryptocurrency. ohlcvHistorical ({
query: { id: "1" , time_period: "daily" , count: 7 , convert: "USD" },
});
candles = cmc.cryptocurrency.ohlcv_historical( id = "1" , time_period = "daily" , count = 7 , convert = "USD" )
In Go:
candles, err := cmc.Cryptocurrency. OhlcvHistorical (ctx, & coinmarketcap . CryptocurrencyOhlcvHistoricalParams {
ID: coinmarketcap. String ( "1" ),
TimePeriod: coinmarketcap. Ptr (coinmarketcap. GetV2CryptocurrencyOhlcvHistoricalParamsTimePeriod ( "daily" )),
Count: coinmarketcap. Float64 ( 7 ),
Convert: coinmarketcap. String ( "USD" ),
})
Use this when you need chart-ready candle data with open, high, low, close, and volume. Truncated response:
{
"status" : {
"timestamp" : "2025-01-15T12:00:00.000Z" ,
"error_code" : 0 ,
"error_message" : null ,
"elapsed" : 18 ,
"credit_count" : 1
},
"data" : {
"id" : 1 ,
"name" : "Bitcoin" ,
"symbol" : "BTC" ,
"quotes" : [
{
"time_open" : "2025-01-08T00:00:00.000Z" ,
"time_close" : "2025-01-08T23:59:59.999Z" ,
"time_high" : "2025-01-08T14:32:00.000Z" ,
"time_low" : "2025-01-08T03:15:00.000Z" ,
"quote" : {
"USD" : {
"open" : 95800.00 ,
"high" : 97200.00 ,
"low" : 95100.00 ,
"close" : 96800.00 ,
"volume" : 28000000000 ,
"timestamp" : "2025-01-08T23:59:59.999Z"
}
}
}
]
}
}
What to choose
Choose quotes/historical for historical snapshots and simpler price-series workflows
Choose ohlcv/historical for candlestick charts and technical-analysis pipelines
Common mistakes
Using OHLCV when all you need is a simpler historical quote series
Forgetting to specify count when you are not sending an explicit time window
Using symbol in production when id would be more stable
Good next steps