Skip to main content

​
Overview

The Market API provides functions for fetching cryptocurrency market data, including top coins by market cap, price information, and historical performance charts. It integrates with CoinGecko’s /coins/markets and /coins/{id}/market_chart endpoints. File location: src/api/market/marketApi.js

​
Configuration

The Market API uses the shared axios client with:
  • Base URL: CoinGecko API v3 (https://api.coingecko.com/api/v3)
  • Timeout: 10 seconds
  • Authentication: Optional CoinGecko Pro API key
  • Caching: 5-minute TTL per unique request with Map-based cache

​
Functions

​
getTopMarketCoins

Fetches top cryptocurrencies by market cap with configurable filtering, sorting, and pagination. 
import { getTopMarketCoins } from './api/market/marketApi'

const topCoins = await getTopMarketCoins({
  vsCurrency: 'usd',
  perPage: 10,
  page: 1,
  sparkline: true,
  priceChangePercentage: '24h,7d'
})

console.log('Top coin:', topCoins[0].name)
console.log('Price:', topCoins[0].current_price)

​
Signature

getTopMarketCoins(options): Promise<Array<Object>>

​
Parameters

​
vsCurrency
string
default:"usd"
Target currency for market data (e.g., usd, eur, btc)
​
order
string
default:"market_cap_desc"
Sort order. Options:
  • market_cap_desc - Market cap descending (default)
  • market_cap_asc - Market cap ascending
  • volume_desc - Volume descending
  • volume_asc - Volume ascending
  • id_desc - ID descending
  • id_asc - ID ascending
​
perPage
number
default:"10"
Number of results per page (1-250)
​
page
number
default:"1"
Page number for pagination
​
sparkline
boolean
default:"true"
Include 7-day sparkline price data
​
priceChangePercentage
string
default:"24h,7d"
Price change percentage timeframes (e.g., 24h, 7d, 24h,7d,30d)

​
Returns

​
coins
array
Array of coin market data objects
​
id
string
Coin identifier (e.g., bitcoin, ethereum)
​
symbol
string
Coin symbol (e.g., btc, eth)
​
name
string
Coin name (e.g., Bitcoin, Ethereum)
​
image
string
URL to coin image/logo
​
current_price
number
Current price in target currency
​
market_cap
number
Market capitalization in target currency
​
market_cap_rank
number
Market cap rank (1 = highest)
​
total_volume
number
24-hour trading volume
​
price_change_percentage_24h
number
24-hour price change percentage
​
price_change_percentage_7d_in_currency
number
7-day price change percentage (if requested)
​
sparkline_in_7d
object
7-day price sparkline data
​
price
array
Array of price points for sparkline chart
​
circulating_supply
number
Circulating supply of the coin
​
total_supply
number
Total supply of the coin
​
max_supply
number
Maximum supply (null if unlimited)

​
Example Response

[
  {
    "id": "bitcoin",
    "symbol": "btc",
    "name": "Bitcoin",
    "image": "https://assets.coingecko.com/coins/images/1/large/bitcoin.png",
    "current_price": 45000,
    "market_cap": 850000000000,
    "market_cap_rank": 1,
    "total_volume": 25000000000,
    "price_change_percentage_24h": 2.5,
    "price_change_percentage_7d_in_currency": 5.2,
    "sparkline_in_7d": {
      "price": [43000, 43500, 44000, ...]
    }
  }
]

​
getCoinPerformanceChart

Fetches historical price data for a specific cryptocurrency to generate performance charts. 
import { getCoinPerformanceChart } from './api/market/marketApi'

const chartData = await getCoinPerformanceChart({
  coinId: 'bitcoin',
  vsCurrency: 'usd',
  days: 30
})

console.log('Price history:', chartData.prices)
console.log('First data point:', chartData.prices[0]) // [timestamp, price]

​
Signature

getCoinPerformanceChart(options): Promise<Object>

​
Parameters

​
coinId
string
default:"bitcoin"
Coin identifier (e.g., bitcoin, ethereum, solana)
​
vsCurrency
string
default:"usd"
Target currency for price data
​
days
number | string
default:"30"
Number of days of historical data. Options:
  • 1, 7, 14, 30, 90, 180, 365
  • max - All available data

​
Returns

​
chartData
object
Historical market data
​
prices
array
Array of [timestamp, price] pairs
​
market_caps
array
Array of [timestamp, market_cap] pairs
​
total_volumes
array
Array of [timestamp, volume] pairs

​
Example Response

{
  "prices": [
    [1709596800000, 45000.50],
    [1709683200000, 45500.25],
    [1709769600000, 46000.75]
  ],
  "market_caps": [
    [1709596800000, 850000000000],
    [1709683200000, 860000000000]
  ],
  "total_volumes": [
    [1709596800000, 25000000000],
    [1709683200000, 26000000000]
  ]
}

​
Caching Behavior

Both functions use Map-based caching with intelligent deduplication:
  • Cache TTL: 5 minutes (MARKET_CACHE_TTL_MS = 5 * 60 * 1000)
  • Cache key: JSON stringified request parameters
  • In-flight deduplication: Same requests share the same promise
  • Cache invalidation: Automatic on TTL expiry or request error
// Different parameters = different cache entries
const btcData = await getTopMarketCoins({ perPage: 10, page: 1 })
const ethData = await getTopMarketCoins({ perPage: 20, page: 1 })

// Same parameters within 5 min = cached result
const cachedBtcData = await getTopMarketCoins({ perPage: 10, page: 1 })

​
API Endpoints

​
Top Market Coins

CoinGecko Endpoint: GET /coins/markets Query Parameters:
  • vs_currency - Target currency
  • order - Sort order
  • per_page - Results per page
  • page - Page number
  • sparkline - Include sparkline
  • price_change_percentage - Change timeframes

​
Performance Chart

CoinGecko Endpoint: GET /coins/{id}/market_chart Path Parameters:
  • {id} - Coin identifier
Query Parameters:
  • vs_currency - Target currency
  • days - Number of days

​
Error Handling

try {
  const coins = await getTopMarketCoins({ perPage: 10 })
} catch (error) {
  // Normalized error structure
  console.error('HTTP Status:', error.status)
  console.error('Error Message:', error.message)
  console.error('Response Data:', error.data)
}
All errors are normalized by the axios interceptor in src/api/axios.js:35-46.

Build docs developers (and LLMs) love

Get started for freeTalk to us