CoinGecko API Client for Node.js

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES Module (ESM) environment without proper configuration, or trying to use `import` with a CommonJS-only package.
  fix Ensure your project is configured for CommonJS (`"type": "commonjs"` in `package.json` or by using `.cjs` file extensions) or use a modern CoinGecko client that supports ESM imports.

• TypeError: CoinGeckoClient.someNewMethod is not a function

  cause The package is abandoned and does not support new endpoints or methods introduced in the CoinGecko API since its last update over six years ago.
  fix Check the official CoinGecko API documentation for the method you are trying to call. If it's a new endpoint, this wrapper will not support it. Migrate to a more recent, actively maintained CoinGecko API client or use direct HTTP requests.

• Error fetching data from CoinGecko: 429 Too Many Requests

  cause Exceeded the rate limits for the CoinGecko API (e.g., 50 requests/minute for the public API).
  fix Introduce a delay between API calls, implement a robust rate-limiting strategy, or subscribe to a CoinGecko Pro API plan for higher rate limits. Note that this wrapper does not handle rate limiting internally.

• property 'market_cap_rank' of undefined / null

  cause Accessing `market_cap_rank` or similar fields that have been deprecated or modified in the CoinGecko API since this wrapper's last update.
  fix The official CoinGecko API has introduced `market_cap_rank_with_rehypothecated` and deprecated `trust_score`. This wrapper is unaware of these changes. Either update to a current API client or add defensive coding to handle potentially `null` or missing data for these specific fields.

Warnings

• breaking This package (v1.0.10) has not been updated in over six years and does not reflect recent breaking changes in the official CoinGecko API. Endpoints, parameters, or data structures may have diverged significantly, leading to unexpected behavior or incorrect data.
  Fix: Consider migrating to a more actively maintained CoinGecko API client, such as `coingecko-api-v3` or `@crypto-coffee/coingecko-api`, which are regularly updated and support modern JavaScript/TypeScript features.
• breaking The official CoinGecko API made significant breaking changes regarding how `market_cap_rank` is handled for rehypothecated tokens and deprecated the `trust_score` field in early 2026. This wrapper will likely return `null` or outdated values for these fields as it has not been updated to reflect these changes.
  Fix: Verify the expected data structure and field availability against the current official CoinGecko API documentation. Use an updated client or implement custom handling for potentially `null` or missing data.
• gotcha This package is CommonJS-only. Attempting to use `import CoinGecko from 'coingecko-api';` directly in an ES Module context will result in a runtime error unless a compatible CJS interop mechanism is used.
  Fix: Always use `const CoinGecko = require('coingecko-api');` when importing this package. If you require ESM, use a transpilation step or a different, modern API client.
• gotcha The public CoinGecko API has rate limits (e.g., 50 calls/minute for the free tier). This wrapper does not include built-in rate limiting or retry mechanisms. Exceeding limits will result in HTTP 429 Too Many Requests errors.
  Fix: Implement custom rate limiting and retry logic in your application. For higher call volumes, consider obtaining a CoinGecko Pro API key and ensure your client supports API key authentication, which this wrapper may not fully facilitate.

Install

• npm install coingecko-api npm
• yarn add coingecko-api yarn
• pnpm add coingecko-api pnpm

Imports

• CoinGecko
  wrong:

  import CoinGecko from 'coingecko-api';

  correct:

  const CoinGecko = require('coingecko-api');

  This package is CommonJS-only, last updated over six years ago. ESM imports will result in a runtime error unless using a CJS interop loader.
• CoinGecko.ORDER
  wrong:

  import { ORDER } from 'coingecko-api';

  correct:

  const CoinGecko = require('coingecko-api');
  const order = CoinGecko.ORDER.MARKET_CAP_DESC;

  Constants like ORDER are exposed as properties of the main CoinGecko export, not as named exports. Requires CommonJS `require` syntax.
• CoinGecko.STATUS_UPDATE_CATEGORY
  wrong:

  import { STATUS_UPDATE_CATEGORY } from 'coingecko-api';

  correct:

  const CoinGecko = require('coingecko-api');
  const category = CoinGecko.STATUS_UPDATE_CATEGORY.GENERAL;

  Similar to ORDER, constants are properties of the main CoinGecko export. Direct named import will fail.

Quickstart

Demonstrates initializing the CoinGecko API client, making a simple ping request, fetching Bitcoin's price, and listing top coins by market cap using an internal constant.

const CoinGecko = require('coingecko-api');

const CoinGeckoClient = new CoinGecko();

const fetchPingAndBitcoinPrice = async () => {
  try {
    // Ping the API to check connectivity
    let pingData = await CoinGeckoClient.ping();
    console.log('API Ping Status:', pingData.data.gecko_says);

    // Get current price of Bitcoin in USD
    let bitcoinPrice = await CoinGeckoClient.simple.price({
      ids: 'bitcoin',
      vs_currencies: 'usd'
    });
    console.log('Bitcoin Price (USD):', bitcoinPrice.data.bitcoin.usd);

    // Example using a constant for ordering results
    let markets = await CoinGeckoClient.coins.markets({
      vs_currency: 'usd',
      order: CoinGecko.ORDER.MARKET_CAP_DESC,
      per_page: 5
    });
    console.log('Top 5 Coins by Market Cap:', markets.data.map(coin => coin.name));

  } catch (error) {
    console.error('Error fetching data from CoinGecko:', error.message);
  }
};

fetchPingAndBitcoinPrice();