Rates

Rates provide aggregated price and volume data for cryptocurrencies across all exchanges. They represent the consolidated market data that Coinranking calculates for each coin.

The fastest way to get new rates is to subscribe to our WebSockets. You can request rates through our coins endpoints too, but they will only update once a minute. With our WebSockets you can establish a persistent connection through which new rates are pushed, so you get the latest price and 24 hour volume whenever they are calculated.

Authentication

The WebSocket protocol does not support regular HTTP headers, so it is not possible to use the x-access-token header when opening a new WebSocket. Authenticate to our WebSockets connections using a query parameter:

wss://api.coinranking.com/v2/real-time/rates?x-access-token=your-api-key
 Copy

Connection Setup

Establish a WebSocket connection to get rates in real-time.

wss://api.coinranking.com/v2/real-time/rates
 Copy

You can subscribe to rates in two ways:

1. URL Query Parameters: Specify subscriptions directly in the connection URL
2. Subscription Messages: Send JSON messages through the WebSocket after connecting to update your subscription

URL Query Parameters

You can specify your subscription preferences directly in the WebSocket connection URL using query parameters. This is the recommended approach when you know your subscription requirements at connection time.

Subscription Messages

After establishing a WebSocket connection, you can update your subscription by sending JSON messages through the socket. This allows you to change which currencies you're subscribed to without reconnecting.

Important: The list parameter is NOT supported in subscription messages. It can only be used in URL query strings when initially connecting.

Send a JSON message with the following structure:

json Copy code
{
  "throttle": "10s",
  "currencyUuids": ["Qwsogvtv82FCd", "razxDUgYGNAdQ"]
}

After sending a subscription message, the server will respond with a confirmation message (see Server Responses below).

Code examples

Javascript Copy code
// Connect with subscriptions specified in the URL
const connection = new WebSocket(
  'wss://api.coinranking.com/v2/real-time/rates?x-access-token=your-api-key&currency-uuids[]=Qwsogvtv82FCd&currency-uuids[]=razxDUgYGNAdQ&throttle=10s'
);

connection.onmessage = (event) => {
  const rate = JSON.parse(event.data);
  console.log(rate);
};

Javascript Copy code
// Send a JSON formatted message through the WebSocket client after establishing a connection
const connection = new WebSocket('wss://api.coinranking.com/v2/real-time/rates?x-access-token=your-api-key');

connection.onopen = () => {
  const subscriptions = {
    throttle: '10s',
    currencyUuids: [
      'Qwsogvtv82FCd',
      'razxDUgYGNAdQ',
    ],
  };

  connection.send(JSON.stringify(subscriptions));
};

connection.onmessage = (event) => {
  const rate = JSON.parse(event.data);
  console.log(rate);
};

http Copy code
GET wss://api.coinranking.com/v2/real-time/rates?x-access-token=your-api-key HTTP/1.1
Host: wss://api.coinranking.com
Connection: Upgrade
Pragma: no-cache
Cache-Control: no-cache
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: q4xkcO32u266gldTuKaSOw==

Responses

The WebSocket server sends different types of messages depending on the context:

Data Messages

When subscribed to rates, you receive aggregated price and volume data for cryptocurrencies. Rates represent consolidated market data calculated by Coinranking across all exchanges, providing a single unified price and 24-hour volume for each coin. Each rate message includes the currency UUID to identify which cryptocurrency the data represents, making it easy to track multiple coins simultaneously.

json Copy code
{
  "currencyUuid": "Qwsogvtv82FCd",
  "price": "125423.835504191964312353",
  "volume": "6270550403.287645846237386287"
}

Confirmation Messages

After sending a subscription update message through the WebSocket, the server responds with a confirmation message:

json Copy code
{
  "type": "confirmation",
  "topic": "rate",
  "throttle": "10s",
  "subscriptions": ["Qwsogvtv82FCd", "razxDUgYGNAdQ"]
}

This confirmation indicates that your subscription has been successfully updated.

Response Fields

When subscribed to one or more coins, you receive new rates whenever they are available. Each of these rates includes the UUID of the coin the rate pertains to, which is especially useful when you are subscribed to multiple coins. Rates include the latest price and 24-hour moving volume, both in US dollars.

Unlike our coin endpoints, we do not support other reference currencies than US dollars with WebSockets. You can, however, subscribe to multiple coins, which allows you to calculate them yourself.