coinmarketcap-api-typescript

Full-featured CoinMarketCap API v1 wrapper for TypeScript and Node.js

This wrapper covers all endpoints of the CoinMarketCap Professional API. Get your API key at pro.coinmarketcap.com/pricing.

Install

npm install coinmarketcap-api-typescript
# OR
yarn add coinmarketcap-api-typescript

Quick Start

import CoinMarketCap from 'coinmarketcap-api-typescript';

const client = new CoinMarketCap('your-api-key');

// Get top 10 cryptocurrencies
const tickers = await client.getTickers({ limit: 10 });

// Get Bitcoin price
const btc = await client.getQuotes({ symbol: 'BTC' });

// Get global market stats
const global = await client.getGlobal();

// Convert 1 BTC to USD, EUR and GBP
const conversion = await client.getPriceConversion({
  amount: 1,
  symbol: 'BTC',
  convert: ['USD', 'EUR', 'GBP'],
});

API Reference

Constructor

new CoinMarketCap(apiKey: string, options?: CoinMarketCapOptions)

Parameter	Type	Default	Description
`apiKey`	`string`	—	Your CoinMarketCap API key
`options.version`	`string`	`'v1'`	API version
`options.fetcher`	`function`	`node-fetch`	Custom fetch implementation
`options.config`	`object`	`{}`	Additional fetch request options

Cryptocurrency

`getIdMap(args?)`

Get a paginated list of all active cryptocurrencies with their CoinMarketCap IDs.

Parameter	Type	Default	Description
`listingStatus`	`string`	`'active'`	`'active'`, `'inactive'`, or `'untracked'`
`start`	`number`	`1`	Offset the start of the paginated list
`limit`	`number`	—	How many results to return
`symbol`	`string \| string[]`	—	Filter by symbol(s)
`sort`	`string`	`'id'`	Sort field: `'id'` or `'cmc_rank'`
`aux`	`string`	—	Comma-separated auxiliary fields

client.getIdMap().then(console.log);
client.getIdMap({ listingStatus: 'inactive', limit: 10 }).then(console.log);
client.getIdMap({ symbol: ['BTC', 'ETH'] }).then(console.log);

`getMetadata(args?)`

Get static metadata for cryptocurrencies (logo, description, website URLs, social links, etc.).

Parameter	Type	Description
`id`	`string \| string[] \| number \| number[]`	CoinMarketCap ID(s)
`symbol`	`string \| string[]`	Cryptocurrency symbol(s)
`slug`	`string \| string[]`	Cryptocurrency slug(s)
`aux`	`string`	Comma-separated auxiliary fields

client.getMetadata({ id: 1 }).then(console.log);
client.getMetadata({ id: [1, 2] }).then(console.log);
client.getMetadata({ symbol: ['BTC', 'ETH'] }).then(console.log);
client.getMetadata({ slug: 'bitcoin' }).then(console.log);

`getTickers(args?)`

Get latest cryptocurrency listings with market data (price, volume, market cap, etc.).

Parameter	Type	Default	Description
`start`	`number`	`1`	Offset the start of the paginated list
`limit`	`number`	`100`	Results to return [1–5000]; pass `0` for all 5000
`convert`	`string \| string[]`	`'USD'`	Price conversion currency
`sort`	`string`	`'market_cap'`	Sort field
`sortDir`	`string`	—	`'asc'` or `'desc'`
`cryptocurrencyType`	`string`	`'all'`	`'all'`, `'coins'`, or `'tokens'`
`aux`	`string`	—	Comma-separated auxiliary fields

client.getTickers({ limit: 10 }).then(console.log);
client.getTickers({ convert: 'EUR' }).then(console.log);
client.getTickers({ cryptocurrencyType: 'coins', sort: 'volume_24h' }).then(console.log);

`getHistoricalListings(args)` (paid plan)

Get a historical snapshot of all cryptocurrencies for a given date.

Parameter	Type	Description
`date`	`string \| number`	Required. Date (ISO 8601 or Unix timestamp)
`start`	`number`	Offset
`limit`	`number`	Results to return
`convert`	`string \| string[]`	Price conversion currency
`sort`	`string`	Sort field
`sortDir`	`string`	`'asc'` or `'desc'`
`cryptocurrencyType`	`string`	`'all'`, `'coins'`, or `'tokens'`

client.getHistoricalListings({ date: '2021-01-01' }).then(console.log);
client.getHistoricalListings({ date: '2021-01-01', limit: 100, convert: 'EUR' }).then(console.log);

`getQuotes(args?)`

Get the latest market quotes for one or more cryptocurrencies. Either id or symbol is required.

Parameter	Type	Description
`id`	`string \| string[] \| number \| number[]`	CoinMarketCap ID(s)
`symbol`	`string \| string[]`	Cryptocurrency symbol(s)
`convert`	`string \| string[]`	Price conversion currency
`aux`	`string`	Comma-separated auxiliary fields
`skipInvalid`	`boolean`	Skip invalid IDs/symbols

client.getQuotes({ symbol: 'BTC' }).then(console.log);
client.getQuotes({ id: [1, 2], convert: ['USD', 'EUR'] }).then(console.log);

`getHistoricalQuotes(args?)` (paid plan)

Get historical price quotes for cryptocurrencies over an interval of time. Either id or symbol is required.

Parameter	Type	Default	Description
`id`	`string \| string[] \| number \| number[]`	—	CoinMarketCap ID(s)
`symbol`	`string \| string[]`	—	Symbol(s)
`timeStart`	`string \| number`	—	Start timestamp
`timeEnd`	`string \| number`	—	End timestamp
`count`	`number`	`10`	Data points to return [1–10000]
`interval`	`string`	`'5m'`	Time interval: `'5m'`, `'1h'`, `'1d'`, etc.
`convert`	`string \| string[]`	`'USD'`	Price conversion currency

client.getHistoricalQuotes({ symbol: 'BTC', timeStart: '2021-01-01', count: 30, interval: '1d' }).then(console.log);

`getMarketPairs(args?)`

Get all active market pairs for a cryptocurrency. One of id, symbol, or slug is required.

Parameter	Type	Description
`id`	`string \| number`	CoinMarketCap ID
`symbol`	`string`	Cryptocurrency symbol
`slug`	`string`	Cryptocurrency slug
`start`	`number`	Offset
`limit`	`number`	Results to return
`category`	`string`	`'all'`, `'spot'`, `'derivatives'`, `'otc'`, `'perpetual'`
`feeType`	`string`	Fee type filter
`convert`	`string \| string[]`	Price conversion currency

client.getMarketPairs({ symbol: 'BTC', limit: 10 }).then(console.log);
client.getMarketPairs({ id: 1, category: 'spot', convert: 'EUR' }).then(console.log);

`getOhlcv(args?)` (paid plan)

Get the latest OHLCV (open/high/low/close/volume) data. Either id or symbol is required.

Parameter	Type	Description
`id`	`string \| string[] \| number \| number[]`	CoinMarketCap ID(s)
`symbol`	`string \| string[]`	Symbol(s)
`convert`	`string \| string[]`	Price conversion currency
`skipInvalid`	`boolean`	Skip invalid entries

client.getOhlcv({ symbol: 'BTC' }).then(console.log);
client.getOhlcv({ id: [1, 1027], convert: 'EUR' }).then(console.log);

`getHistoricalOhlcv(args?)` (paid plan)

Get historical OHLCV data for a cryptocurrency. Either id or symbol is required.

Parameter	Type	Default	Description
`id`	`string \| number`	—	CoinMarketCap ID
`symbol`	`string`	—	Cryptocurrency symbol
`timePeriod`	`string`	`'daily'`	`'hourly'`, `'daily'`, `'weekly'`, `'monthly'`, `'yearly'`
`timeStart`	`string \| number`	—	Start timestamp
`timeEnd`	`string \| number`	—	End timestamp
`count`	`number`	`10`	Data points to return
`interval`	`string`	—	Time interval
`convert`	`string \| string[]`	`'USD'`	Price conversion currency

client.getHistoricalOhlcv({ symbol: 'BTC', timeStart: '2021-01-01', count: 30 }).then(console.log);

`getPricePerformanceStats(args?)` (paid plan)

Get price performance statistics for cryptocurrencies.

Parameter	Type	Default	Description
`id`	`string \| string[] \| number \| number[]`	—	CoinMarketCap ID(s)
`symbol`	`string \| string[]`	—	Symbol(s)
`slug`	`string \| string[]`	—	Slug(s)
`timePeriod`	`string`	`'all_time'`	`'1h'`, `'24h'`, `'7d'`, `'30d'`, `'365d'`, `'all_time'`
`convert`	`string \| string[]`	`'USD'`	Price conversion currency

client.getPricePerformanceStats({ symbol: 'BTC', timePeriod: '7d,30d,365d' }).then(console.log);

`getCategories(args?)`

Get all cryptocurrency categories (DeFi, NFT, Layer 1, etc.).

Parameter	Type	Default	Description
`start`	`number`	`1`	Offset
`limit`	`number`	`100`	Results to return
`id`	`string \| number`	—	Filter by category ID
`slug`	`string`	—	Filter by category slug
`symbol`	`string \| string[]`	—	Filter by symbol

client.getCategories({ limit: 20 }).then(console.log);

`getCategory(args)`

Get information about a single category, including its cryptocurrencies.

Parameter	Type	Description
`id`	`string`	Required. Category ID
`start`	`number`	Offset
`limit`	`number`	Results to return
`convert`	`string \| string[]`	Price conversion currency

client.getCategory({ id: '6053d9545778035c15d9e4be' }).then(console.log);

`getAirdrops(args?)`

Get a list of airdrops.

Parameter	Type	Default	Description
`start`	`number`	`1`	Offset
`limit`	`number`	`100`	Results to return
`status`	`string`	`'ongoing'`	`'upcoming'`, `'ongoing'`, or `'ended'`
`id`	`string \| number`	—	Filter by cryptocurrency ID
`slug`	`string`	—	Filter by slug
`symbol`	`string`	—	Filter by symbol

client.getAirdrops({ status: 'upcoming', limit: 10 }).then(console.log);

`getAirdrop(args)`

Get information about a specific airdrop.

Parameter	Type	Description
`id`	`string`	Required. Airdrop ID

client.getAirdrop({ id: '10050' }).then(console.log);

`getTrending(args?)` (paid plan)

Get the latest trending cryptocurrencies.

Parameter	Type	Default	Description
`start`	`number`	`1`	Offset
`limit`	`number`	`100`	Results to return
`timePeriod`	`string`	`'24h'`	`'24h'`, `'30d'`, or `'7d'`
`convert`	`string \| string[]`	`'USD'`	Price conversion currency

client.getTrending({ limit: 10 }).then(console.log);
client.getTrending({ timePeriod: '7d' }).then(console.log);

`getMostVisited(args?)` (paid plan)

Get the most visited cryptocurrencies on CoinMarketCap.

Same parameters as getTrending.

client.getMostVisited({ limit: 10 }).then(console.log);

`getGainersLosers(args?)` (paid plan)

Get top cryptocurrency gainers or losers.

Parameter	Type	Default	Description
`start`	`number`	`1`	Offset
`limit`	`number`	`100`	Results to return
`timePeriod`	`string`	`'24h'`	`'1h'`, `'24h'`, `'7d'`, `'30d'`
`sort`	`string`	—	Sort field
`sortDir`	`string`	`'desc'`	`'asc'` or `'desc'`
`convert`	`string \| string[]`	`'USD'`	Price conversion currency

client.getGainersLosers({ timePeriod: '7d', limit: 10 }).then(console.log);
client.getGainersLosers({ sortDir: 'asc' }).then(console.log); // losers

Fiat

`getFiatMap(args?)`

Get a mapping of all supported fiat currencies to CoinMarketCap IDs.

Parameter	Type	Default	Description
`start`	`number`	`1`	Offset
`limit`	`number`	`100`	Results to return
`sort`	`string`	`'id'`	`'id'` or `'name'`
`includeMetals`	`boolean`	`false`	Include precious metals

client.getFiatMap().then(console.log);
client.getFiatMap({ includeMetals: true }).then(console.log);

Exchange

`getExchangeMap(args?)`

Get a mapping of all supported exchanges to CoinMarketCap IDs.

Parameter	Type	Default	Description
`listingStatus`	`string`	`'active'`	`'active'`, `'inactive'`, or `'untracked'`
`slug`	`string \| string[]`	—	Filter by slug(s)
`start`	`number`	`1`	Offset
`limit`	`number`	`100`	Results to return
`sort`	`string`	`'id'`	Sort field
`aux`	`string`	—	Auxiliary fields
`cryptoId`	`string \| number`	—	Filter by listed cryptocurrency ID

client.getExchangeMap({ limit: 10 }).then(console.log);
client.getExchangeMap({ slug: 'binance' }).then(console.log);

`getExchangeMetadata(args?)`

Get static metadata for exchanges (logo, description, website URLs, etc.). Either id or slug is required.

Parameter	Type	Description
`id`	`string \| string[] \| number \| number[]`	Exchange ID(s)
`slug`	`string \| string[]`	Exchange slug(s)
`aux`	`string`	Auxiliary fields

client.getExchangeMetadata({ slug: 'binance' }).then(console.log);
client.getExchangeMetadata({ id: [270, 294] }).then(console.log);

`getExchangeListings(args?)`

Get latest exchange listings with volume and other market data.

Parameter	Type	Default	Description
`start`	`number`	`1`	Offset
`limit`	`number`	`100`	Results to return
`sort`	`string`	`'volume_24h'`	Sort field
`sortDir`	`string`	—	`'asc'` or `'desc'`
`marketType`	`string`	`'all'`	`'all'`, `'spot'`, `'derivatives'`, `'dex'`, `'otc'`
`convert`	`string \| string[]`	`'USD'`	Price conversion currency
`aux`	`string`	—	Auxiliary fields

client.getExchangeListings({ limit: 10, sort: 'volume_24h' }).then(console.log);
client.getExchangeListings({ marketType: 'spot' }).then(console.log);

`getExchangeQuotes(args?)`

Get the latest market quotes for one or more exchanges. Either id or slug is required.

Parameter	Type	Description
`id`	`string \| string[] \| number \| number[]`	Exchange ID(s)
`slug`	`string \| string[]`	Exchange slug(s)
`convert`	`string \| string[]`	Price conversion currency
`aux`	`string`	Auxiliary fields

client.getExchangeQuotes({ slug: 'binance' }).then(console.log);
client.getExchangeQuotes({ id: [270, 294], convert: 'EUR' }).then(console.log);

`getExchangeMarketPairs(args?)`

Get active market pairs for an exchange. Either id or slug is required.

Parameter	Type	Default	Description
`id`	`string \| number`	—	Exchange ID
`slug`	`string`	—	Exchange slug
`start`	`number`	`1`	Offset
`limit`	`number`	`100`	Results to return
`category`	`string`	`'all'`	`'all'`, `'spot'`, `'derivatives'`, `'otc'`, `'perpetual'`
`feeType`	`string`	—	Fee type filter
`matchedId`	`string \| number`	—	Restrict to pairs with this currency ID
`matchedSymbol`	`string`	—	Restrict to pairs with this currency symbol
`convert`	`string \| string[]`	`'USD'`	Price conversion currency

client.getExchangeMarketPairs({ slug: 'binance', limit: 10 }).then(console.log);
client.getExchangeMarketPairs({ slug: 'binance', matchedSymbol: 'BTC', category: 'spot' }).then(console.log);

Global Metrics

`getGlobal(convert?)`

Get the latest global cryptocurrency market metrics.

Parameter	Type	Default	Description
`convert`	`string \| string[] \| { convert: string \| string[] }`	`'USD'`	Price conversion currency

client.getGlobal().then(console.log);
client.getGlobal('EUR').then(console.log);
client.getGlobal(['USD', 'EUR', 'GBP']).then(console.log);
client.getGlobal({ convert: 'EUR' }).then(console.log);

`getHistoricalGlobal(args?)` (paid plan)

Get historical global market metrics over a time interval.

Parameter	Type	Default	Description
`timeStart`	`string \| number`	—	Start timestamp
`timeEnd`	`string \| number`	—	End timestamp
`count`	`number`	`10`	Data points to return [1–10000]
`interval`	`string`	`'1d'`	Time interval: `'1h'`, `'6h'`, `'1d'`, `'7d'`, etc.
`convert`	`string \| string[]`	`'USD'`	Price conversion currency
`aux`	`string`	—	Auxiliary fields

client.getHistoricalGlobal({ timeStart: '2021-01-01', count: 30, interval: '1d' }).then(console.log);

Tools

`getPriceConversion(args)`

Convert an amount of one cryptocurrency or fiat currency to another. Either id or symbol is required.

Parameter	Type	Description
`amount`	`number`	Required. Amount to convert
`id`	`string \| number`	Source currency CoinMarketCap ID
`symbol`	`string`	Source currency symbol
`time`	`string \| number`	Historical timestamp for conversion
`convert`	`string \| string[]`	Target currency/currencies

client.getPriceConversion({ amount: 1, symbol: 'BTC', convert: 'USD' }).then(console.log);
client.getPriceConversion({ amount: 1000, symbol: 'USD', convert: ['BTC', 'ETH'] }).then(console.log);
client.getPriceConversion({ amount: 1, id: 1, convert: ['USD', 'EUR', 'GBP'] }).then(console.log);

Blockchain

`getBlockchainStats(args?)` (paid plan)

Get the latest blockchain statistics for one or more blockchains. One of id, symbol, or slug is required.

Parameter	Type	Description
`id`	`string \| string[] \| number \| number[]`	CoinMarketCap ID(s)
`symbol`	`string \| string[]`	Symbol(s)
`slug`	`string \| string[]`	Slug(s)

client.getBlockchainStats({ symbol: 'BTC' }).then(console.log);
client.getBlockchainStats({ id: [1, 1027] }).then(console.log); // BTC and ETH

Key

`getKeyInfo()`

Returns API key details and monthly usage statistics. Useful for monitoring your credit quota.

client.getKeyInfo().then(console.log);

TypeScript Types

All parameter interfaces are exported and available for import:

import CoinMarketCap, {
  CoinMarketCapOptions,
  GetIdMapArgs,
  GetMetadataArgs,
  GetTickersArgs,
  GetHistoricalListingsArgs,
  GetQuotesArgs,
  GetHistoricalQuotesArgs,
  GetMarketPairsArgs,
  GetOhlcvArgs,
  GetHistoricalOhlcvArgs,
  GetPricePerformanceStatsArgs,
  GetCategoriesArgs,
  GetCategoryArgs,
  GetAirdropsArgs,
  GetAirdropArgs,
  GetTrendingArgs,
  GetGainersLosersArgs,
  GetFiatMapArgs,
  GetExchangeMapArgs,
  GetExchangeMetadataArgs,
  GetExchangeListingsArgs,
  GetExchangeQuotesArgs,
  GetExchangeMarketPairsArgs,
  GetHistoricalGlobalArgs,
  GetPriceConversionArgs,
  GetBlockchainStatsArgs,
} from 'coinmarketcap-api-typescript';

Testing

Unit tests (no API key required):

npm test
# or just unit tests:
npx jest __tests__/unit.test.js

Integration tests (requires a valid API key):

COINMARKETCAP_API_KEY=your-key npx jest test.js
# or with a .env file:
echo "COINMARKETCAP_API_KEY=your-key" > .env
npx jest test.js

Contributing

Contributions are welcome!

Fork it.
Create your feature branch: git checkout -b my-new-feature
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin my-new-feature
Submit a pull request :D

Or open up an issue.

License

Licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
__tests__		__tests__
docs		docs
src		src
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc		.prettierrc
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
jest.setup.js		jest.setup.js
package-lock.json		package-lock.json
package.json		package.json
renovate.json		renovate.json
test.js		test.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

coinmarketcap-api-typescript

Table of Contents

Install

Quick Start

API Reference

Constructor

Cryptocurrency

getIdMap(args?)

getMetadata(args?)

getTickers(args?)

getHistoricalListings(args) (paid plan)

getQuotes(args?)

getHistoricalQuotes(args?) (paid plan)

getMarketPairs(args?)

getOhlcv(args?) (paid plan)

getHistoricalOhlcv(args?) (paid plan)

getPricePerformanceStats(args?) (paid plan)

getCategories(args?)

getCategory(args)

getAirdrops(args?)

getAirdrop(args)

getTrending(args?) (paid plan)

getMostVisited(args?) (paid plan)

getGainersLosers(args?) (paid plan)

Fiat

getFiatMap(args?)

Exchange

getExchangeMap(args?)

getExchangeMetadata(args?)

getExchangeListings(args?)

getExchangeQuotes(args?)

getExchangeMarketPairs(args?)

Global Metrics

getGlobal(convert?)

getHistoricalGlobal(args?) (paid plan)

Tools

getPriceConversion(args)

Blockchain

getBlockchainStats(args?) (paid plan)

Key

getKeyInfo()

TypeScript Types

Testing

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`getIdMap(args?)`

`getMetadata(args?)`

`getTickers(args?)`

`getHistoricalListings(args)` (paid plan)

`getQuotes(args?)`

`getHistoricalQuotes(args?)` (paid plan)

`getMarketPairs(args?)`

`getOhlcv(args?)` (paid plan)

`getHistoricalOhlcv(args?)` (paid plan)

`getPricePerformanceStats(args?)` (paid plan)

`getCategories(args?)`

`getCategory(args)`

`getAirdrops(args?)`

`getAirdrop(args)`

`getTrending(args?)` (paid plan)

`getMostVisited(args?)` (paid plan)

`getGainersLosers(args?)` (paid plan)

`getFiatMap(args?)`

`getExchangeMap(args?)`

`getExchangeMetadata(args?)`

`getExchangeListings(args?)`

`getExchangeQuotes(args?)`

`getExchangeMarketPairs(args?)`

`getGlobal(convert?)`

`getHistoricalGlobal(args?)` (paid plan)

`getPriceConversion(args)`

`getBlockchainStats(args?)` (paid plan)

`getKeyInfo()`

Packages