WebSockets

Connection request to the WebSocket uses JWT_COOKIE based authentication. To generate a JWT token see - Generate A JWT Token. Each WebSocket exposes a set of topics that can be subscribed to.

Max Open WebSocket Connections

Each WebSocket category has a maximum number of open connections. Once it is reached, new WebSocket requests will be rejected. The WebSocket connections fall under the below categories.

Unauthenticated WebSockets, maximum of 100 open connections per IP address.
Authenticated WebSockets, maximum of 10 open connections per API key.

Send A Message Over The WebSocket

Messages sent by the client to the server over a WebSocket follows the JSON-RPC 2.0 Specification. The server then returns a response following the same JSON-RPC 2.0 format. The id field sent by the client will be included in the response, allowing the client to map the server's responses to the messages sent by the client. The client ensures the uniqueness of the id field.

Find below the message types accepted by the WebSocket:

Subscription Message
Keepalive Ping Message

Subscribe to receive a snapshot of your existing data and subsequently receive updates.

Two types of subscription:

Subscribe by <TOPIC>
Subscribe by <TOPIC> and <SYMBOL> plus optional fields (if any)

Message fields:

<TOPIC>: subscription topic
<SYMBOL>: market symbol
<COMMAND_ID>: unique unsigned long value

The subscription message would be constructed like below:

Subscribe by <TOPIC>

{
  "jsonrpc": "2.0",
  "type": "command",
  "method": "subscribe",
  "params": {
    "topic": "<TOPIC>"
  },
  "id": "<COMMAND_ID>"
}

Subscribe by <TOPIC> and <SYMBOL>

{
  "jsonrpc": "2.0",
  "type": "command",
  "method": "subscribe",
  "params": {
    "topic": "<TOPIC>",
    "symbol": "<SYMBOL>"
  },
  "id": "<COMMAND_ID>"
}

Sample subscription messages:

Orders

{
  "jsonrpc": "2.0",
  "type": "command",
  "method": "subscribe",
  "params": {
    "topic": "orders"
  },
  "id": "1611082473000"
}

L1 Order Book

{
  "jsonrpc": "2.0",
  "type": "command",
  "method": "subscribe",
  "params": {
      "topic": "l1Orderbook"
      "symbol": "BTCUSD"
  },
  "id": "1611082473000"
}

Find below the available <TOPIC>:

Unsubscribe To A Topic

Unsubscribe to stop receive updates.

One type of unsubscription for Day 1:

Unsubscribe from one <TOPIC> and <SYMBOL>

Find below the available <TOPIC> for Day 1:

Unified Anonymous Trades WebSocket (/trading-api/v1/market-data/trades)

Message fields:

<TOPIC>: subscription topic
<SYMBOL>: market symbol
<COMMAND_ID>: unique unsigned long value

The unsubscription message would be constructed like below:

Subscribe by <TOPIC> and <SYMBOL>

{
  "jsonrpc": "2.0",
  "type": "command",
  "method": "unsubscribe",
  "params": {
    "topic": "<TOPIC>",
    "symbol": "<SYMBOL>"
  },
  "id": "<COMMAND_ID>"
}

Sample subscription messages:

unified anonymous trade subscription

{
  "jsonrpc": "2.0",
  "type": "command",
  "method": "unsubscribe",
  "params": {
    "topic": "anonymousTrades",
    "symbol": "BTCUSDC"
  },
  "id": "1611082473000"
}

Keep WebSocket Open

Keep the WebSocket connection open by sending keepalive ping messages periodically. The WebSocket closes automatically after 5 minutes.

The keepalive ping message would be constructed like below:

{
  "jsonrpc": "2.0",
  "type": "command",
  "method": "keepalivePing",
  "params": {},
  "id": "<COMMAND_ID>"
}

Receive A Message From The WebSocket

JSON-RPC responses are of the following format:

Success responses

{
  "jsonrpc": "2.0",
  "id": "1650865877698",
  "result": {
    "responseCode": "200",
    "responseCodeName": "OK",
    "message": "Successfully subscribed"
  }
}

Error responses

{
  "jsonrpc": "2.0",
  "id": "1650865877698",
  "error": {
    "code": "-32602",
    "errorCode": "29013",
    "errorCodeName": "INVALID_TOPIC_ERROR",
    "message": "'a-random-topic' is not a valid topic"
  }
}

code: JSON-RPC 2.0 error code
responseCode/errorCode: unique id for response/error code
responseCodeName/errorCodeName: unique name for response/error code
message: textual description of the responseCode/errorCode

Snapshot responses are of the following format:

{
  "type": "snapshot",
  "dataType": "<DATA_TYPE>",
  "data": [ { <TOPIC_RESPONSE> } ]
}

Update responses are of the following format:

{
  "type": "update",
  "dataType": "<DATA_TYPE>",
  "data": { <TOPIC_RESPONSE> }
}

Error responses are of the following format:

{
  "type": "error",
  "dataType": "V1TAErrorResponse",
  "data": {
    "errorCode": <ERROR_CODE>,
    "errorCodeName": "<ERROR_CODE_NAME>"
  }
}

Heartbeat

this is a beta/experimental feature that is currently being tested
the heart beat message is periodically sent approximately every 30 seconds on the heartbeat topic for the Private Data WebSocket API and Multi-Order Book WebSocket API
the heat beat serves to validate end-to-end communication between the exchange and the client
if 3 heart beats are missed, then it is advisable to check the official status page for any announcements on the degradation of the exchanges features
if no announcements have been made, it is advisable to disconnect and reconnect the WebSocket API given the issue may be isolated to a specific gateway

Max Open WebSocket Connections​

Send A Message Over The WebSocket​

Subscribe To A Topic​

Unsubscribe To A Topic​

Keep WebSocket Open​

Receive A Message From The WebSocket​

Heartbeat​