Get bitcoin dominance history

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

Get a list of bitcoin dominance history along with the bitcoin market capitalization data.

On Coinranking, we use this endpoint on our bitcoin dominance chart.

https://api.coinranking.com/v2/stats/bitcoin-dominance-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.

Query parameters

Parameter Description

Parameter	Description
referenceCurrencyUuid (optional) `String`	UUID of coin (either fiat or crypto), in which all the market caps 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/stats/bitcoin-dominance-history?referenceCurrencyUuid=5k-_VTxqtCEI`
timePeriod (optional) `String`	Timeperiod where the percentage and marketCap are based on The maximum `timePeriod` is `1y` for Free, `5y` for Basic, and `all` for Startup and higher plans. These historical windows apply to both preview and production requests. Default value: 24h Allowed values: 1h 3h 12h 24h 7d 30d 3m 1y 3y 5y all Example: `https://api.coinranking.com/v2/stats/bitcoin-dominance-history?timePeriod=1y`

referenceCurrencyUuid (optional) String

UUID of coin (either fiat or crypto), in which all the market caps 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/stats/bitcoin-dominance-history?referenceCurrencyUuid=5k-_VTxqtCEI

timePeriod (optional) String

Timeperiod where the percentage and marketCap are based on

The maximum timePeriod is 1y for Free, 5y for Basic, and all for Startup and higher plans. These historical windows apply to both preview and production requests.

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

Example:

 
https://api.coinranking.com/v2/stats/bitcoin-dominance-history?timePeriod=1y

Code examples

curl 'https://api.coinranking.com/v2/stats/bitcoin-dominance-history?referenceCurrencyUuid=5k-_VTxqtCEI&timePeriod=7d'  \
  -H 'x-access-token: your-api-key' \
  -G

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

fetch('https://api.coinranking.com/v2/stats/bitcoin-dominance-history?referenceCurrencyUuid=5k-_VTxqtCEI&timePeriod=7d', 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/stats/bitcoin-dominance-history?referenceCurrencyUuid=5k-_VTxqtCEI&timePeriod=7d",
    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/stats/bitcoin-dominance-history?referenceCurrencyUuid=5k-_VTxqtCEI&timePeriod=7d", headers=headers)

print(response.text)

Response

HTTP/1.1 200 OK
{
  "status": "success",
  "data": [
    {
      "timestamp": 1742814600,
      "percentage": 58.91,
      "marketCap": 1740828021051
    },
    {
      "timestamp": 1742814900,
      "percentage": 58.9,
      "marketCap": 1740456972714
    },
    {
      "timestamp": 1742815200,
      "percentage": 58.89,
      "marketCap": 1739283421198
    }
  ]
}

Response fields

Property	Description
status `String`	Status of the request Allowed values: success
data `Object`
data.timestamp `Number`	An Epoch timestamp in seconds
data.percentage `Number/null`	Percentage of bitcoin dominance by market cap
data.marketCap `Number/null`	Bitcoin market cap, calculated in the reference currency

Error response

HTTP/1.1 422 Unprocessable Entity
{
  "status": "fail",
  "type": "REFERENCE_UNAVAILABLE",
  "message": "Reference currency not available"
}

Error responses

Error	Description
VALIDATION_ERROR `Object`	The request could not be validated. The response should provide more details.
REFERENCE_UNAVAILABLE `Object`	The reference currency used in the request is not available. Choose another UUID.