Exchange Rates

Exchange rates show the price and volume of specific cryptocurrencies on individual exchanges, unlike rates, which aggregate data from multiple exchanges.

The fastest way to get new exchange rates is to subscribe to our WebSockets. You can request rates through our exchange coin listings endpoints too, but they will only update once a minute. With our WebSockets you can establish a persistent connection through which new exchange 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/exchange-rates?x-access-token=your-api-key
 Copy

Connection Setup

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

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

You can subscribe to exchange 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.

Important: You must choose only ONE of the following subscription parameters: references, exchange-uuids, currency-uuids, or list. You cannot mix different parameter types.

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 exchange rates 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. Note that you must choose only ONE subscription type per message:

json Copy code
{
  "exchangeUuids": ["-zdvbieRdZ", "TjMe3QlK0"],
  "throttle": "10s"
}

Or using currency UUIDs:

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

Or using references:

json Copy code
{
  "references": ["-zdvbieRdZ_Qwsogvtv82FCd"],
  "throttle": "10s"
}

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/exchange-rates?x-access-token=your-api-key&exchange-uuids[]=-zdvbieRdZ&exchange-uuids[]=TjMe3QlK0&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/exchange-rates?x-access-token=your-api-key');

connection.onopen = () => {
  const subscriptions = {
    throttle: '10s',
    exchangeUuids: [
      '-zdvbieRdZ',
      'TjMe3QlK0',
    ],
  };

  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/exchange-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 exchange rates, you receive price and volume updates for specific exchange-currency pairs. Each message includes both the exchange UUID and currency UUID, allowing you to identify which exchange the rate comes from and which cryptocurrency it represents. This is particularly useful when tracking the same currency across different exchanges or monitoring multiple trading pairs.

json Copy code
{
  "exchangeUuid": "-zdvbieRdZ",
  "currencyUuid": "Qwsogvtv82FCd",
  "exchangeType": "cex",
  "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": "exchange-rate",
  "throttle": "10s",
  "subscriptions": ["exchange:-zdvbieRdZ", "exchange:TjMe3QlK0"]
}

Response fields

When subscribed to exchange rates, you receive new rates whenever they are available. Each exchange rate includes the UUID of both the exchange and currency, which is especially useful when you are subscribed to multiple exchanges or currencies. Exchange rates include the latest price and 24-hour moving volume, both in US dollars.

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