Get coin rank history

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

With the coin ranks endpoint you can check out how a coin was ranked throughout its existence. We have different rankings available for coins; by market cap (which is also the default ranking on coinranking.com), but also by 24 hour volume moving sum, by their sheer price in USD or in the fully diluted market cap.

https://api.coinranking.com/v2/coin/:uuid/rank-history

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
uuid `String`	UUID of the coin you want to request the rank data for. A UUID is our unique identifier for each coin. You can find them in all our coin endpoints, or look them up in the find UUID page.

Query parameters

Parameter Description

Parameter	Description
interval (optional) `String`	The interval determines the time period over which each rank item is determined. Default value: day Allowed values: hour day week month Example: `https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/rank-history?interval=hour`
limit (optional) `Number`	Limit. Limit the amount of time periods for which the ranks are retrieved. For example, when interval=hour and limit is 10, data will be returned for the last 10 hours. Free is limited to 100 results per response. Basic, Startup, Growth, and Professional can receive up to 5000 results per response, including previews. Default value: 50 Size range: 0-5000 Example: `https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/rank-history?limit=10`

interval (optional) String

The interval determines the time period over which each rank item is determined.

Default value: day
Allowed values:
hour day week month

Example:

 
https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/rank-history?interval=hour

limit (optional) Number

Limit. Limit the amount of time periods for which the ranks are retrieved. For example, when interval=hour and limit is 10, data will be returned for the last 10 hours. Free is limited to 100 results per response. Basic, Startup, Growth, and Professional can receive up to 5000 results per response, including previews.

Default value: 50
Size range: 0-5000

Example:

 
https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/rank-history?limit=10

Code examples

curl 'https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/rank-history?interval=hour&limit=50' \
  -H 'x-access-token: your-api-key' \
  -G

const options = {
  headers: {
    'x-access-token': 'your-api-key',
  },
};

fetch('https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/rank-history?interval=hour&limit=50', options)
  .then((response) => response.json())
  .then((result) => console.log(result));

<?php
  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/rank-history?interval=hour&limit=50",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "x-access-token: your-api-key"
      ),
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;

import requests

headers = {
  'x-access-token': 'your-api-key'
}

response = requests.request("GET", "https://api.coinranking.com/v2/coin/Qwsogvtv82FCd/rank-history?interval=hour&limit=50", headers=headers)

print(response.text)

Response

HTTP/1.1 200 OK
{
  "status": "success",
  "data": {
    "history": [
      {
        "startingAt": 1698310800,
        "tier": "1",
        "marketCapRank": "1",
        "fullyDilutedMarketCapRank": "1",
        "volumeRank": "2",
        "priceRank": "2"
      },
      {
        "startingAt": 1698307200,
        "tier": "1",
        "marketCapRank": "1",
        "fullyDilutedMarketCapRank": "1",
        "volumeRank": "2",
        "priceRank": "2"
      }
    ]
  }
}

Response fields

Property	Description
status `String`	Status of the request Allowed values: success
data `Object`
data.history `Object[]`	List of rank items
data.history.startingAt `Number`	An Epoch timestamp in seconds marking the start of the time period on which the rank values are based.
data.history.tier `String/null`	Tier of the coin. We have three distinct tiers.
data.history.marketCapRank `String/null`	The rank of the coin based on market cap. This is the rank we use on our website by default. time period
data.history.fullyDilutedMarketCapRank `String/null`	The rank of the coin based on fully diluted market cap. Fully diluted market cap is a coin's price multiplied by its max supply. Or total supply if the max supply is not known.
data.history.volumeRank `String/null`	Market cap based on its trading volume in the past 24 hours.
data.history.priceRank `String/null`	The rank of the coin based on how much US Dollars just one unit of the coin is worth. This metric greatly favors coins with a low supply.

Error response

HTTP/1.1 404 Not Found
{
  "status": "fail",
  "type": "COIN_NOT_FOUND",
  "message": "Coin not found"
}

Error responses

Error	Description
COIN_NOT_FOUND `Object`	The coin could not be found. Try another UUID

Error	Description
VALIDATION_ERROR `Object`	The request could not be validated. The response should provide more details.