Skip to content
On this page

Action: Subscribe

Before being able to receive any data, you need to subscribe to a stream. This is done by sending a subscribe action to the server as described below. Make sure that you are already authenticated.

Stream

Within the subscribe action, you need to specify which stream you want to be subscribed to. This is done through Stream filters, which are JSON objects that help the server identify which streams to connect you with. Within a Stream object, some attribute are optional. If an optional attribute is omitted, the server will include all streams matching the other specified attributes. For instance, if exchangeId is not provided, you'll be subscribed to streams from all exchanges that match the remaining criteria. Here's an example of a Stream filter object containing all possible attributes:

json
{
  "eventType": "trade",       // Required. The type of event, e.g. "trade"
  "base": "BTC",              // Optional*. The base asset of the market
  "quote": "USDT",            // Optional*. The quote asset of the market
  "exchangeId": 2,            // Optional. The ID of the exchange
  "market": "BTCUSDT"        // Optional*, the exchange-specific market name
}

While base, quote and market are optional, either both base and quote must be provided, or market must be provided. Usually, you would provide base and quote and omit market as follows:

json
{
  "eventType": "trade",
  "base": "BTC",
  "quote": "USDT"
}

The above would subscribe you to trade streams from all exchanges that have a market with the base asset BTC and the quote asset USDT. Optionally, you could have provided an exchangeId to only subscribe to trade streams from a specific exchange. For a list of all available exchanges with their ID's, check out the Exchanges section.

Operation

In order to actually subscribe to streams you should send a subscribe action with an array of Stream objects (see above) as the "streams" property of the body, like so:

json
{
  "id": "1234567890", // optional, for your own reference
  "action": "subscribe",
  "body": {
    "streams": [
      {
        "eventType": "trade",
        "base": "BTC",
        "quote": "USDT"
      },
      {
        "eventType": "trade",
        "base": "BTC",
        "quote": "USDC"
      }
    ]
  }
}

If the server was able to subscribe you successfully, it will respond with a successful subscribe action-response:

json
{
  "id": "1234567890", // optional, for your own reference
  "action": "subscribe",
  "success": true
}