Node.js client for accessing CoinMarketCap data.
Uses a local cache to avoid re-fetching coin info too frequently. The cache can be configured or overriden with a custom implementation.
By default, most numbers are returned as bignumber.js instances. That behavior can be deactivated with a constructor option to make the library output only plain JavaScript numbers.
This choice was made because default JavaScript numbers are represented by floats internally, and thus are imprecise. BigNumber
s can be converted to plain JS numbers by calling .toNumber
on them, or prefixing them with the unary operator +
.
Requires Node.js v7 or superior. This module cannot be used in browsers due to CSP restrictions.
Installation
npm install node-coinmarketcap-extended-api
Usage
import CoinMarketCap from 'coinmarketcap-extended-api'
const CMC = new CoinMarketCap()
CMC.getMarketsFromTicker('ETH')
.then(markets => {
for (const market of markets) {
console.log(`ETH trades at ${market.priceUsd} USD on ${market.exchange}.`)
}
})
API
Constructor:
new CoinMarketCap([options]): APIInstance
Instance methods:
async
idFromTicker
(ticker)
:id
async
coins
()
:[Asset]
async
coin
(id)
:Asset
async
coinFromTicker
(ticker)
:Asset
async
coinsFromTicker
(ticker)
:Asset
async
getMarkets
(id)
:[Market]
async
getMarketsFromTicker
(ticker)
:[Market]
async
getLinks
(id)
:[Link]
async
getLinksFromTicker
(ticker)
:[Link]
async
global
()
:GlobalData
totalMarketCapUsd:
:BigNumber
(USD)total24hVolumeUsd:
:BigNumber
(USD)bitcoinDominance:
:BigNumber
(%): Percentage of Bitcoin marketcap relative to total marketcap.activeCurrencies:
:int
activeAssets
:int
activeMarkets
:int
lastUpdated
:int
(seconds): UNIX time.
Instance properties:
cache
: The cache instance. You typically won't need to interact with it directly, but it is provided as an escape hatch for finer grained control.async
get
(key: string)
:JSONSerializable
async
set
(key: string, value: JSONSerializable)
:boolean
async
has
(key: string)
:boolean
Types:
-
ticker
:string
: Symbol of asset on CoinMarketCap (e.g.:"BTC"
) -
id
:string
: ID of asset on CoinMarketCap (e.g.:"golem-network-tokens"
). Be advised that there is no reliable way to infer it programmatically from other informations. -
Asset
: Information related to a particular asset/cryptocurrency.id
:string
name
:string
symbol
:string
rank
:int
priceUsd
:BigNumber?
(USD)priceBtc
:BigNumber?
(BTC)volumeUsd24h
:BigNumber?
(USD)marketCapUsd
:BigNumber?
(USD)availableSupply
:BigNumber?
(tokens)totalSupply
:BigNumber?
(tokens)maxSupply
:BigNumber?
(tokens)percentChange1h
:BigNumber?
(%)percentChange24h
:BigNumber?
(%)percentChange7d
:BigNumber?
(%)lastUpdated
:int
(seconds): UNIX time.
-
Market
: Information related to a particular trading pair.exchange
:string
: Name of the exchange.base
:ticker
: Name of the base currency.quote
:ticker
: Name of the traded asset.url
:string
: URL to trading pair on exchange.volumeUsd24h
:BigNumber
(USD)priceUsd
:BigNumber
(USD)volumePercent
:BigNumber
: Percent of market 24h volume on global quote trading 24h volume.
-
Link
: Links related to the asset.label
:string
Resource labelurl
:string
: Resource URL
Cache
DefaultCache
The default cache can be configured with expiry for all entries. Default is 5 minutes.
import CoinMarketCap, { DefaultCache } from 'coinmarketcap-extended-api'
const CMC = new CoinMarketCap({
cache: new DefaultCache({
expiry: 30e3, // Expire cache entries after 30 seconds
}),
})
You can also configure the expiry of different type of cache entries individually:
const CMC = new CoinMarketCap({
cache: new DefaultCache({
expiry: {
assets: 2*60*1000, // Expire after 2 minutes
assetpage: 60*60*1000, // Expire after 1 hour
global: 40*1000// Expire after 40 seconds
default: 5*60*1000,
},
}),
})
API
Constructor:
new DefaultCache([options]): DefaultCacheInstance
options
: Object with any of the below properties:init
:[[key: string, value: any]]
Store's initial content, argument to Map consructor.expiry
:int|{group: string: int}
(default300000
ie. 5 minutes) Time in milliseconds before a cache entry is considered stale.
Can be indicated as a number for every entry, or an object with different durations for each group (see example). The object keys are groups and the values the corresponding expiry time. The object should have adefault
key.
Instance methods:
Cache interface:
async
get
(key: string)
:JSONSerializable
async
set
(key: string, value: JSONSerializable)
:boolean
async
has
(key: string)
:boolean
Additional methods and properties:
async
isStale
([key: string])
:boolean
Returns whether the given cache entry has expired.async
clear
([key: string])
:boolean
Delete data for an entry, or the entire store if no argument is supplied.store
Map
instance used as back-end store for the cache.
Cache keys
Cache keys follow a <group>:<key>
format.
assets:all
: Used withidFromTicker
,coins
,coin
,coinFromTicker
,coinsFromTicker
.assetpage:<id>
: Used withgetMarkets
,getMarketsFromTicker
,getLinks
,getLinksFromTicker
.global:all
: Used withglobal
.
Development
npm run build:watch
npm run test:watch