WebSockets

A WebSocket is a persistent, two-way connection. You open it once, receive new data as soon as it is calculated, and change your subscriptions at any time by sending a message, without reconnecting.

This page explains how to connect and how to manage a connection. What you can subscribe to, and the messages you receive, are described per topic: Rates, Exchange Rates, and Tickers. Prefer plain HTTP? The same topics are available as Server-Sent Events.

Authentication

The browser's WebSocket API cannot set request headers, so authenticate with a query parameter:

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

Server-side WebSocket libraries can set headers on the opening request. There, send the key in the x-access-token header instead, exactly as for the REST endpoints, which keeps it out of URLs and logs. A key in a web page is visible to every visitor, so for a public website, connect from your server and relay the data to the browser.

Connection Setup

Real-time streaming requires the Professional plan or higher. Your plan’s connection limits and minimum update interval apply.

The optional throttle supports 1s, 5s, 10s, 30s, or 60s. When omitted in the URL or a subscription message, it uses your plan’s minimum interval. A supported value faster than your plan allows is rejected with THROTTLE_NOT_ALLOWED.

Open a connection to the path of the topic you want to receive:

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

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

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

A connection receives one topic. You can subscribe in two ways, and combine them:

1. URL query parameters: put your subscriptions in the connection URL. This is the simplest option when you know what you need when you connect. The parameters are listed on each topic page.
2. Subscription messages: send a JSON message through the open connection to set or change your subscriptions.

A connection without any subscription is accepted; it receives nothing until you send a subscription message.

Subscription Messages

Send a JSON object with the subscription fields of the topic you connected to, and optionally a throttle:

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

• A message replaces your subscription. It does not add to what you subscribed to before, whether in the URL or in an earlier message. The same goes for the throttle: a message without throttle sets it back to your plan’s minimum interval.
• Every accepted message is answered with a confirmation listing your subscriptions and throttle.
• A refused message leaves your previous subscription unchanged. You receive an error message, the connection stays open, and the data you were already subscribed to keeps arriving.
• list=all is only available as a URL query parameter. To switch to or from a full list, open a new connection.

Code examples

// 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 message = JSON.parse(event.data);
  console.log(message);
};

// Connect first, then send a JSON formatted subscription message
const connection = new WebSocket('wss://api.coinranking.com/v2/real-time/rates?x-access-token=your-api-key');

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

connection.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.type === 'confirmation') console.log('Subscribed to', message.subscriptions);
  else if (message.type === 'error') console.error(message.code, message.errors);
  else console.log(message);
};

// Server-side, with the ws package: send the API key in a header
import WebSocket from 'ws';

const connection = new WebSocket(
  'wss://api.coinranking.com/v2/real-time/rates?currency-uuids[]=Qwsogvtv82FCd&throttle=10s',
  { headers: { 'x-access-token': process.env.COINRANKING_API_KEY } }
);

connection.on('message', (data) => {
  console.log(JSON.parse(data));
});

GET /v2/real-time/rates?x-access-token=your-api-key HTTP/1.1
Host: api.coinranking.com
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: q4xkcO32u266gldTuKaSOw==

Messages

Every message from the server is a JSON text frame with a type field:

• rate, exchange-rate, or ticker: a data message. Its fields are described on the topic page.
• confirmation: the answer to an accepted subscription message. A connection also receives one when it opens, confirming its URL subscriptions and effective throttle.
• error: a refused URL parameter or subscription message, see Errors.

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

Errors

Refused before the connection opens. A missing or unknown API key, an account without an active API subscription, or an exhausted rate limit is refused during the HTTP upgrade, before any WebSocket exists. The response is a normal 401, 403, or 429 with the same JSON body as on the Server-Sent Events endpoint. Browsers do not expose that response: the WebSocket only fires an error event followed by a close event with code 1006. To see the reason, request the Server-Sent Events URL of the same topic with the same key, which is refused with the same status and body.

Refused after the connection opens. An invalid URL parameter or subscription message is answered with an error message. After an invalid URL parameter, the server closes the connection; after an invalid subscription message, the connection stays open.

{
  "type": "error",
  "code": "UNKNOWN_CURRENCY_UUID",
  "errors": ["Could not find coins with the following UUIDs: notarealuuid"]
}

The codes are the same on both transports. Match on code rather than on the text in errors; the messages may be reworded.

Reconnecting

There is no maximum connection duration. The server sends a WebSocket ping frame every 25 seconds, which browsers and WebSocket libraries answer automatically. A connection that leaves two consecutive pings unanswered is closed, so a client that stops responding is cut off rather than buffered without bound.

When the real-time service is deployed or restarted, every connection is closed with code 1001. Reconnect after a short delay. Subscriptions in the URL are restored by reconnecting with the same URL; subscriptions you set with a message have to be sent again. Opening a connection counts toward your rate limit, so do not retry a refused connection without fixing its cause, and back off when you hit the limit.