Coin mapping

Growth This endpoint requires the growth plan or higher. Free, Basic and Startup plans can use preview access.

Resolve a coin by its external provider ID and receive the full Coinranking coin detail response. This is useful when you already have CoinGecko or CoinMarketCap IDs in your system and want to cross-reference them with Coinranking data without having to look up our UUIDs first.

The response is identical to our coin details endpoint.

https://api.coinranking.com/v2/mappings/:provider/coin/:providerId

Preview access

Free, Basic and Startup plans can test this endpoint with five successful requests per account per UTC day. Use the documented endpoint URL with your existing API key. Preview access is applied automatically. The allowance resets at 00:00 UTC.

All API keys, resource IDs, query parameters and pagination requests share this endpoint's allowance for your account. Failed requests do not consume the preview allowance. Successful previews also count toward your normal API usage, and your plan's result, historical-window and rate limits still apply. See endpoint previews for limits, response headers and quota errors.

Path parameters

Parameter Description
provider String

The external data provider to resolve the coin from.

Allowed values:
coingecko coinmarketcap

Example:
https://api.coinranking.com/v2/mappings/coingecko/coin/bitcoin
providerId String

The ID of the coin on the external provider's platform.

Example (CoinGecko):
bitcoin, ethereum, tether

Example (CoinMarketCap):
1 (Bitcoin), 1027 (Ethereum)

Query parameters

Parameter Description
referenceCurrencyUuid (optional) String

UUID of coin (either fiat or crypto), in which all the prices are calculated. Defaults to US Dollar, but you can use any coin. You can find UUIDs for reference currencies in any coin endpoint, including a convenient dedicated reference currency endpoint

Default value: yhjMzLPhuIDl

Example:
https://api.coinranking.com/v2/mappings/coingecko/coin/bitcoin?referenceCurrencyUuid=5k-_VTxqtCEI
timePeriod (optional) String

Time period where the change and sparkline are based on

The maximum timePeriod is 1y for Free and 5y for all paid plans. This endpoint supports up to five years of data. These limits apply to both preview and production requests.

Default value: 24h
Allowed values:
1h 3h 12h 24h 7d 30d 3m 1y 3y 5y

Example:
https://api.coinranking.com/v2/mappings/coingecko/coin/bitcoin?timePeriod=1y

Code examples

curl 
curl 'https://api.coinranking.com/v2/mappings/coingecko/coin/bitcoin' \
  -H 'x-access-token: your-api-key' \
  -G
curl 
curl 'https://api.coinranking.com/v2/mappings/coinmarketcap/coin/1' \
  -H 'x-access-token: your-api-key' \
  -G
JavaScript 
const options = {
  headers: {
    'x-access-token': 'your-api-key',
  },
};

fetch('https://api.coinranking.com/v2/mappings/coingecko/coin/bitcoin', options)
  .then((response) => response.json())
  .then((result) => console.log(result));

Response

json 
HTTP/1.1 200 OK
{
  "status": "success",
  "data": {
    "coin": {
      "uuid": "Qwsogvtv82FCd",
      "symbol": "BTC",
      "name": "Bitcoin",
      "description": "Bitcoin is the first decentralized digital currency.",
      "color": "#f7931A",
      "iconUrl": "https://cdn.coinranking.com/Sy33Krudb/btc.svg",
      "websiteUrl": "https://bitcoin.org",
      "links": [
        {
          "name": "Bitcoin",
          "url": "https://www.reddit.com/r/Bitcoin/",
          "type": "reddit"
        }
      ],
      "supply": {
        "confirmed": true,
        "supplyAt": 1640757180,
        "circulating": "17009275",
        "total": "17009275",
        "max": "21000000"
      },
      "24hVolume": "6818750000",
      "marketCap": "159393904304",
      "fullyDilutedMarketCap": "196790985529",
      "price": "9370.9993109108",
      "btcPrice": "1",
      "priceAt": 1640757180,
      "change": "-0.52",
      "rank": 1,
      "numberOfMarkets": 9800,
      "numberOfExchanges": 190,
      "sparkline": [
        "9515.0454185372",
        "9540.1812284677",
        "9554.2212643043",
        "9593.571539283",
        "9592.8596962985",
        "9562.5310295967",
        "9556.7860427046",
        "9388.823394515",
        "9335.3004209165",
        "9329.4331700521",
        "9370.9993109108"
      ],
      "allTimeHigh": {
        "price": "19500.471361532",
        "timestamp": 1513555200
      },
      "coinrankingUrl": "https://coinranking.com/coin/Qwsogvtv82FCd+bitcoin-btc",
      "tier": 1,
      "lowVolume": false,
      "listedAt": 1483228800,
      "notices": [
        {
          "type": "MESSAGE",
          "value": "Lorem ipsum dolor sit amet"
        }
      ],
      "contractAddresses": [],
      "tags": [
        "staking",
        "layer-1"
       ],
      "isWrappedTrustless": false,
      "wrappedTo": null,
      "coinGeckoId": "bitcoin",
      "coinMarketCapId": "1"
    }
  }
}

Response fields

Property Description
status String

Status of the request

Allowed values:
success
data Object
data.coin Object
data.coin.uuid String

UUID of the coin
data.coin.symbol String

Currency symbol
data.coin.name String

Name of the coin
data.coin.description String

Small description of the coin
data.coin.color String

Main HEX color of the coin
data.coin.iconUrl String

Location of the icon. Replace .svg with .png or .webp, optionally with ?size=WIDTHxHEIGHT (e.g. ?size=28x28) to control dimensions. See Icons for more details.
data.coin.websiteUrl String

URL of the primary website

List of links, like social media pages

Name of the link

Url to the specific link

The type of link

Allowed values:
website bitcointalk explorer discord facebook github instagram line-messenger linkedin medium qq quora reddit sina-weibo telegram tiktok twitter vkontakte wechat whitepaper youtube etc.
data.coin.supply Object
data.coin.supply.confirmed Boolean

Coins without a confirmed supply are ranked below coins with a confirmed supply. Read about our methodology.
data.coin.supply.supplyAt Number/null

Epoch timestamp of when the supply was synchronized. If the supply was never synchronized or the supply is manually updated the API will return null.
data.coin.supply.total String

Number of coins that are in existence
data.coin.supply.circulating String

Number of coins that are circulating in the public market
data.coin.supply.max String

Maximum amount the coin's supply can ever be.
data.coin.marketCap String

Market capitalization. Price times circulating supply
data.coin.fullyDilutedMarketCap String

Market capitalization. Price times circulating supply Full Market capitalization. Fully diluted market cap is a coin's price multiplied by its max supply. Or total supply if the max supply is not known. It shows what the market cap could be if all coins were in circulation, with the current price.

data.coin.price String

Price of the coin
data.coin.btcPrice String

Price of the coin expressed in Bitcoin
data.coin.priceAt Number/null

Epoch timestamp of when the price was calculated.
data.coin.24hVolume String

24h trade volume
data.coin.change String

Percentage of change over the given time period
data.coin.rank Number

The position in the ranks
data.coin.numberOfMarkets Number

The number of markets that contain the this coin
data.coin.numberOfExchanges Number

The number of exchanges that trade this coin
data.coin.sparkline String

Array of prices based on the time period parameter, useful for a sparkline
data.coin.allTimeHigh Object
data.coin.allTimeHigh.price String/null

The highest price that the coin has reached, expressed in the reference currency. Returns null if no all-time high data is available.
data.coin.allTimeHigh.timestamp Number/null

An Epoch timestamp in seconds when the coin reached its highest price. Returns null if no all-time high data is available.
data.coin.coinrankingUrl String

Where to find the coin on coinranking.com
data.coin.tier Number/null

Tier of the coin. We separate coins into three tiers. Learn more about our ranking methodology.
data.coin.lowVolume Boolean

If the coin is not much traded on listed exchanges it is marked as having a low volume. The threshold is currently set at the equivalent of 500.000 US Dollar in 24 hours
data.coin.listedAt Number/null

Epoch timestamp of when we started listing the coin.
data.coin.notices Object[]

List of notices, which signal some important information about the coin. The notices are in JSON format, and in most cases consist of a "type" property with an important keyword such as "WARNING", and a more human readable message in a "value" property.

data.coin.contractAddresses Object[]

List of contract addresses for this coin. The format is blockchain/contractAddress. A single coin can be minted on multiple blockchains. For example, Tether (USDT) is available on Ethereum (ethereum/0xda...) , Bitcoin Cash (bitcoin-cash/9fc...) and seven other blockchains.

data.coin.tags Object[]

List of tags, like "Staking" or "Meme"
data.coin.isWrappedTrustless Boolean

Indicates whether this coin is a wrapped version of another asset where the wrapping relationship is enforced by smart contracts without requiring trust in a third party.
data.coin.wrappedTo String/null

UUID of the coin that this coin is wrapped to. Returns null when this coin is not a wrapped version of another asset.
data.coin.coinGeckoId String/null

The CoinGecko ID of the coin. Returns null if no CoinGecko mapping is available.
data.coin.coinMarketCapId String/null

The CoinMarketCap ID of the coin. Returns null if no CoinMarketCap mapping is available.

Error responses

Error Description
COIN_NOT_FOUND Object

No Coinranking coin was found for the given provider ID. Verify the ID is correct for the specified provider.
Error Description
VALIDATION_ERROR Object

The request could not be validated. Check that provider is one of the supported values and that providerId is not empty.
REFERENCE_UNAVAILABLE Object

The reference currency used in the request is not available. Choose another UUID.
Previous

Fear and Greed Index

 Next

Bulk coins