Public Websocket API

Published on Updated on

(Public WebSocket) Market Data WebSocket Interface

URL: /api/v1/public/ws

Description

  • 01. When subscribing or unsubscribing, the server will validate the channel. For invalid channels, the server will respond with an error message, for example: {"type":"error","content":{"code":"INVALID_CONTRACT_ID""msg":"invalid contractId:100000001"}}
  • 02. The message structure for subscribing and unsubscribing is: {"type": "subscribe", "channel": "ticker.10000001"}.
  • 03. Ping-Pong Mechanism:
    • Server Ping (Heartbeat):
      • After a successful WebSocket connection, the server sends a Ping message at a fixed interval. The message body looks like: {"type":"ping","time":"1693208170000"}. The time field is the server's timestamp when the Ping was sent.
      • The client must respond with a Pong message upon receipt, with a body like: {"type":"pong","time":"1693208170000"}.
      • If the server doesn't receive a Pong response after 5 consecutive Pings, the server will terminate the connection.
    • Client Ping (Latency Measurement):
      • After a successful WebSocket connection, the client can also initiate a Ping message with a body like: {"type":"ping","time":"1693208170000"}. The time field is the client's timestamp when the Ping was sent.
      • The server will immediately respond with a Pong message, with a body like: {"type":"pong","time":"1693208170000"}. The time field in the Pong will match the time field in the client's Ping.

Subscription Metadata

Request

{
  "type": "subscribe",
  "channel": "metadata"
}
 

Response

{
  "type": "subscribed",
  "channel": "metadata"
}
 

Payload

{
  // error
  "type":  "quote-event",
  "channel": "metadata",
  "content": {
    // snapshot quote-event 
    "dataType": "Snapshot", 
    // 
    "channel": "metadata",
    "data": [
      {
        // Coin information
        "coin": [
        ],
        // Contract information
        "contract": [
        ]
      }
    ]
  }
}
 

Subscribe to 24-Hour Market Ticker

Channel Explanation

Channel Description
ticker.{contractId} Subscribe to the ticker of contract contractId
ticker.all Subscribe to the ticker of all contracts
ticker.all.1s Subscribe to the ticker of all contracts (periodic push)

Request

{
  "type": "subscribe",
  "channel": "ticker.10000001"
}
 

Response

{
  "type": "subscribed",
  "channel": "ticker.10000001"
}
 

Payload

{
  "type": "payload",
  "channel": "ticker.10000001",
  "content": {
    "dataType": "Snapshot",
    "channel": "ticker.10000001",
    "data": [
      {
        "contractId": "string",
        "priceChange": "string",
        "priceChangePercent": "string",
        "trades": "string",
        "size": "string",
        "value": "string",
        "high": "string",
        "low": "string",
        "open": "string",
        "close": "string",
        "highTime": "string",
        "lowTime": "string",
        "startTime": "string",
        "endTime": "string",
        "lastPrice": "string"
      }
    ]
  }
}
 

Subscribe to K-Line Data

Channel Explanation

Channel Description
kline.{priceType}.{contractId}.{interval} Subscribe to the interval K-Line of contract contractId based on priceType

priceType Parameter

Value Description
LAST_PRICE Last Price K-Line
MARK_PRICE Mark Price K-Line

interval Parameter

Value Description
MINUTE_1 1-Minute K-Line
MINUTE_5 5-Minute K-Line
MINUTE_15 15-Minute K-Line
MINUTE_30 30-Minute K-Line
HOUR_1 1-Hour K-Line
HOUR_2 2-Hour K-Line
HOUR_4 4-Hour K-Line
HOUR_6 6-Hour K-Line
HOUR_8 8-Hour K-Line
HOUR_12 12-Hour K-Line
DAY_1 Daily K-Line
WEEK_1 Weekly K-Line
MONTH_1 Monthly K-Line

Request

{
  "type": "subscribe",
  "channel": "kline.LAST_PRICE.10000001.MINUTE_1"
}
 

Response

{
  "type": "subscribed",
  "channel": "kline.LAST_PRICE.10000001.MINUTE_1"
}
 

Payload

{
  "type": "payload",
  "channel": "kline.LAST_PRICE.10000001.MINUTE_1",
  "content": {
    "dataType": "Changed",
    "channel": "kline.LAST_PRICE.10000001.MINUTE_1",
    "data": [
      {
        "klineId": "1",
        "contractId": "10000001",
        "klineType": "MINUTE_1",
        "klineTime": "1688365544504",
        "trades": "5",
        "size": "10.1",
        "value": "100000",
        "high": "31200",
        "low": "31000",
        "open": "3150",
        "close": "31010",
        "makerBuySize": "5",
        "makerBuyValue": "150000"
      }
    ]
  }
}
 

Subscribe to Order Book

Usage Instructions

After a successful subscription, a full dataset is pushed once initially (depthType=SNAPSHOT), and subsequent pushes will be incremental updates (depthType=CHANGED).

Channel Explanation

Channel Description
depth.{contractId}.{depth} Subscribe to the order book of contract contractId with a depth of depth

depth Parameter

Value Description
15 15 levels
200 200 levels

Request

{
  "type": "subscribe",
  "channel": "depth.10000001.15"
}
 

Response

{
  "type": "subscribed",
  "channel": "depth.10000001.15"
}
 

Payload

{
  "type": "payload",
  "channel": "depth.10000001.15",
  "content": {
    "dataType": "Snapshot",
    "channel": "depth.10000001.15",
    "data": [
      {
        "startVersion": "string",
        "endVersion": "string",
        "level": 0,
        "contractId": "10000001",
        "depthType": "Snapshot", // Data type: SNAPSHOT for full data, CHANGED for incremental data
        "bids": [
          [
            "26092",
            // Price
            "0.9014"
            // Size. A size of 0 indicates a deletion. Positive numbers mean increase. Negative numbers mean decrease.
          ],
          [
            "26091",
            "0.9667"
          ]
        ],
        "asks": [
          [
            "26093",
            "0.964"
          ],
          [
            "26094",
            "1.0213"
          ]
        ]
      }
    ]
  }
}
 

Subscribe to Latest Trades

Channel Explanation

Channel Description
trades.{contractId} Subscribe to the latest trades of contract contractId

Request

{
  "type": "subscribe",
  "channel": "trades.10000001"
}
 

Response

{
  "type": "subscribed",
  "channel": "trades.10000001"
}
 

Payload

{
  "type": "payload",
  "channel": "trades.10000001",
  "content": {
    "dataType": "Changed",
    "channel": "trades.10000001",
    "data": [
      {
        "ticketId": "1",
        "time": "1688365544504",
        "price": "30065.12",
        "size": "0.01",
        "value": "300.6512",
        "takerOrderId": "10",
        "makerOrderId": "11",
        "takerAccountId": "3001",
        "makerAccountId": "3002",
        "contractId": "10000001",
        "isBestMatch": true,
        "isBuyerMaker": false
      }
    ]
  }
}

Was this article helpful?

0 out of 0 found this helpful