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

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:

json Copy code
{
  "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 1s.
• 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

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

Javascript Copy code
// 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);
};

Javascript Copy code
// 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));
});

http Copy code
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 that subscribes through the URL does not receive one; data starts arriving right away.
• error: a refused URL parameter or subscription message, see Errors.

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

Errors

Refused before the connection opens. A missing or unknown API key, a plan without real-time access, 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.

json Copy code
{
  "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.