Skip to main content

Messages

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:

  1. Subscription Message
  2. Keepalive Ping Message

Subscribe To A Topic​

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

Two types of subscription:

  1. Subscribe by <TOPIC>
  2. 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>:

  1. Multi-Order Book Data WebSocket
  2. Unified Anonymous Trades WebSocket
  3. Anonymous Market Data WebSocket
  4. Index Data WebSocket
  5. Private Data WebSocket

Unsubscribe To A Topic​

Unsubscribe to stop receive updates.

One type of unsubscription for Day 1:

  1. Unsubscribe from one <TOPIC> and <SYMBOL>

Find below the available <TOPIC> for Day 1:

  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"
}

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>"
  }
}