Tickers

Tickers provide detailed trading pair data from specific markets, showing the exchange rate between two currencies (e.g., BTC/USD). They include granular market information like base/quote volumes, close price, and more.

The fastest way to get new tickers is to subscribe to our WebSockets. You can request tickers through our get market details endpoints too, but they will only update once a minute. With our WebSockets you can establish a persistent connection through which new tickers are pushed, so you get the latest ticker data 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/tickers?x-access-token=your-api-key
 Copy

Connection Setup

Establish a WebSocket connection to get ticker data in real-time.

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

You can subscribe to tickers 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: market-uuids, 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 tickers 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
{
  "marketUuids": ["dj23kKgETIie", "ia4qVnkhIxcQ"],
  "throttle": "10s"
}

Or using exchange UUIDs:

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

Or using currency UUIDs:

json Copy code
{
  "currencyUuids": ["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/tickers?x-access-token=your-api-key&market-uuids[]=dj23kKgETIie&market-uuids[]=ia4qVnkhIxcQ&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/tickers?x-access-token=your-api-key');

connection.onopen = () => {
  const subscriptions = {
    throttle: '10s',
    marketUuids: [
      'dj23kKgETIie',
      'ia4qVnkhIxcQ',
    ],
  };

  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/tickers?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 tickers, you receive detailed trading pair data including price, volume, and market statistics. Each ticker message contains comprehensive information about a specific market pair: the market UUID, exchange UUID, base currency UUID, and quote currency UUID. This granular data allows you to track individual trading pairs across different exchanges, monitor base and quote volumes separately, and analyze market-specific price movements.

json Copy code
{
  "marketUuid": "dj23kKgETIie",
  "exchangeUuid": "zdvbieRdZ",
  "baseUuid": "Qwsogvtv82FCd",
  "quoteUuid": "cpjRxjFYD",
  "exchangeType": "cex",
  "close": "124590.91",
  "price": "124590.91",
  "baseVolume": "24290.53392",
  "quoteVolume": "3036047751.1820064",
  "volume": "3036047751.1820064",
  "filters": []
}

Confirmation Messages

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

json Copy code
{
  "type": "confirmation",
  "topic": "ticker",
  "throttle": "10s",
  "subscriptions": ["market:dj23kKgETIie","market:ia4qVnkhIxcQ"]
}

This confirmation indicates that your subscription has been successfully updated.

Response fields

When subscribed to tickers, you receive new ticker data whenever it is available. Each ticker includes the UUID of the market, exchange, base currency, and quote currency, which is especially useful when you are subscribed to multiple markets or exchanges. Tickers include the latest price, close price, and volume data, both in base and quote currencies, as well as in US dollars.

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