CoinGecko API v3

0.0.31 verified Sat Apr 25 auth: no javascript

A TypeScript-based Node.js client for the CoinGecko API v3, version 0.0.31. It provides full coverage of the CoinGecko API endpoints including simple price, coin data, market charts, exchange info, trending, and more. Zero runtime dependencies, ships with TypeScript definitions, and supports auto-retry on rate-limiting (HTTP 429). The library is actively maintained on GitHub with CI and code coverage. Key differentiator: a typed, fully promise-based client with minimal config compared to alternatives.

Common errors

error TypeError: coinGeckoApi_v3_1.default is not a constructor ↓

cause Using default import instead of named import. The package has a named export `CoinGeckoClient`, not a default export.

fix

Replace import CoinGeckoClient from 'coingecko-api-v3' with import { CoinGeckoClient } from 'coingecko-api-v3'.

error Cannot find module 'coingecko-api-v3' or its corresponding type declarations ↓

cause TypeScript may not find the types if `tsconfig.json` does not include ESM resolution. The package exports types but requires `moduleResolution: "node"` (or `nodenext/16`) and `esModuleInterop: true`.

fix

Ensure your tsconfig.json includes "moduleResolution": "node" and "esModuleInterop": true.

error Error: connect ETIMEDOUT ↓

cause Network timeout due to slow response from CoinGecko API or no internet connection.

fix

Increase the timeout option in the client constructor (default 30s). Also check your network and ensure you are not hitting API limits.

Warnings

gotcha Library is ESM-only; does not support CommonJS `require()`. Must use `import`. ↓

fix Use `import { CoinGeckoClient } from 'coingecko-api-v3'` instead of `require('coingecko-api-v3')`.

gotcha Free CoinGecko API has rate limits (~10-30 calls/min). The library's `autoRetry` only retries on 429, but does not handle other rate-limit responses or backoff beyond simple retry. ↓

fix Implement your own rate-limiting or use a paid CoinGecko plan to increase limits.

gotcha Some endpoints (e.g., `/coins/{id}/history`, `marketChart`) require a `date` parameter in format `dd-mm-yyyy`; passing an incorrect format or falsy value may result in 400 errors. ↓

fix Ensure `date` is a string in `dd-mm-yyyy` format when calling history methods.

deprecated The `/simple/price` endpoint has been deprecated by CoinGecko in favor of `/simple/price?include_...`, but the library still uses the old path, which may break in future API updates. ↓

fix Monitor CoinGecko API changelog; consider using `client.customRequest()` to manually call new endpoints.

gotcha The library does not include built-in caching; repeated calls to the same endpoint (e.g., coin list) will make new HTTP requests each time. ↓

fix Cache responses yourself or use a memoization pattern in your application.

Install

npm install coingecko-api-v3

yarn add coingecko-api-v3

pnpm add coingecko-api-v3

Imports

CoinGeckoClient

wrong

const CoinGeckoClient = require('coingecko-api-v3')

correct

import { CoinGeckoClient } from 'coingecko-api-v3'

ESM-only; named export. CommonJS require will not work.

CoinGeckoClientOptions

wrong

import { CoinGeckoClientOptions } from 'coingecko-api-v3'

correct

import type { CoinGeckoClientOptions } from 'coingecko-api-v3'

TypeScript users should use `import type` for this interface to avoid runtime bundling.

ResponseType

wrong

import { ResponseType } from 'coingecko-api-v3'

correct

import type { ResponseType } from 'coingecko-api-v3'

ResponseType is a type alias; use `import type` in TypeScript.

Quickstart

Initializes the client, pings the API, fetches Bitcoin price in USD, and retrieves trending coins.

import { CoinGeckoClient } from 'coingecko-api-v3';

const client = new CoinGeckoClient({
  timeout: 10000,
  autoRetry: true,
});

async function main() {
  try {
    const ping = await client.ping();
    console.log('Ping:', ping);
    const price = await client.simplePrice({
      ids: 'bitcoin',
      vs_currencies: 'usd',
    });
    console.log('BTC price:', price.bitcoin.usd);
    const trending = await client.trending();
    console.log('Trending:', trending);
  } catch (err) {
    console.error('Error:', err);
  }
}
main();