CoinGecko API Integration

CoinGecko API Integration

CoinGecko is one of two major market data aggregators (the second is CoinMarketCap). If you need token prices, historical data, coin metadata, or market cap — CoinGecko API covers most tasks. Free tier (Demo) is sufficient for most applications; Pro gives higher limits and additional endpoints.

Limits and Authentication

Demo key obtained on the website, passed as x-cg-demo-api-key header or ?x_cg_demo_api_key= parameter. Without key — very strict rate limit (~10 req/min), can't work in production like that.

const COINGECKO_BASE = 'https://api.coingecko.com/api/v3';

class CoinGeckoClient {
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  private async get<T>(endpoint: string, params: Record<string, string> = {}): Promise<T> {
    const url = new URL(`${COINGECKO_BASE}${endpoint}`);
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));

    const response = await fetch(url.toString(), {
      headers: {
        'x-cg-demo-api-key': this.apiKey,
        'Accept': 'application/json',
      },
    });

    if (response.status === 429) {
      throw new RateLimitError('CoinGecko rate limit exceeded');
    }

    if (!response.ok) {
      throw new Error(`CoinGecko API error: ${response.status}`);
    }

    return response.json();
  }
}

Key Endpoints

Token price — most frequent request:

// Price of one or multiple tokens
async function getTokenPrices(
  coinIds: string[],
  vsCurrencies: string[] = ['usd', 'eur']
): Promise<Record<string, Record<string, number>>> {
  return this.get('/simple/price', {
    ids: coinIds.join(','),         // 'bitcoin,ethereum,tether'
    vs_currencies: vsCurrencies.join(','),
    include_24hr_change: 'true',
    include_last_updated_at: 'true',
  });
}

// By contract address (without knowing CoinGecko ID)
async function getTokenPriceByContract(
  contractAddress: string,
  platform: string = 'ethereum'  // 'binance-smart-chain', 'polygon-pos', etc.
): Promise<TokenPrice> {
  return this.get(`/simple/token_price/${platform}`, {
    contract_addresses: contractAddress,
    vs_currencies: 'usd',
    include_24hr_change: 'true',
  });
}

Historical data for charts:

// OHLC data (candles)
async function getOhlcData(coinId: string, days: number): Promise<[number, number, number, number, number][]> {
  // Returns array [timestamp, open, high, low, close]
  return this.get(`/coins/${coinId}/ohlc`, {
    vs_currency: 'usd',
    days: days.toString(),  // 1, 7, 14, 30, 90, 180, 365, 'max'
  });
}

// Market chart (price + volume + marketcap over time)
async function getMarketChart(coinId: string, days: number) {
  return this.get(`/coins/${coinId}/market_chart`, {
    vs_currency: 'usd',
    days: days.toString(),
    interval: days <= 1 ? 'minutely' : days <= 90 ? 'hourly' : 'daily',
  });
}

Caching — Mandatory

Pulling CoinGecko on every user request is a quick way to exhaust limits. Prices update every 60 seconds; caching for 30–60 seconds doesn't hurt accuracy:

import { Redis } from 'ioredis';

class CachedCoinGeckoClient extends CoinGeckoClient {
  constructor(private redis: Redis, apiKey: string) {
    super(apiKey);
  }

  async getCachedPrice(coinId: string): Promise<number> {
    const cacheKey = `coingecko:price:${coinId}`;
    const cached = await this.redis.get(cacheKey);

    if (cached) return parseFloat(cached);

    const data = await this.getTokenPrices([coinId]);
    const price = data[coinId]?.usd;

    if (price) {
      await this.redis.setex(cacheKey, 60, price.toString());  // TTL 60 seconds
    }

    return price;
  }
}

For high-traffic services: background job updates prices every 30 seconds, all user requests read from cache.

Finding CoinGecko ID by Contract

Problem: you have a token address but not its CoinGecko ID. Solution:

// Get list of all coins with their contracts
// This endpoint is called rarely, cached for hours
async function buildContractToIdMap(platform: string): Promise<Map<string, string>> {
  const coins = await this.get<Array<{ id: string; platforms: Record<string, string> }>>(
    '/coins/list',
    { include_platform: 'true' }
  );

  const map = new Map<string, string>();
  for (const coin of coins) {
    const contractAddress = coin.platforms[platform];
    if (contractAddress) {
      map.set(contractAddress.toLowerCase(), coin.id);
    }
  }

  return map;
}

Cache coin list (~15,000 items) for several hours — it changes rarely.

Error Handling and Retry

async function fetchWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err instanceof RateLimitError) {
        // Exponential backoff on rate limit
        const delay = baseDelay * Math.pow(2, attempt);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw err;  // Don't retry other errors
    }
  }
  throw new Error('Max retries exceeded');
}

For critical services: add fallback to CoinMarketCap or Binance Public API if CoinGecko is unavailable.