WebSocket Overview

Futures WebSocket provides real-time pushes for market quotes, order book, K-lines including the 1-second interval, trades, mark price, and private channel updates for orders, balances, and positions.

Connection Endpoints

Type	Endpoint
Public channel	ws://<host>:9021/ws
Private channel	ws://<host>:9021/ws (send auth after connection)

Client Request Format

All client requests use the unified {op, args} structure.

Subscribe

{
  "op": "subscribe",
  "args": [
    "ticker@BTC_USDT",
    "depth@BTC_USDT,20",
    "kline@BTC_USDT,1s",
    "BTC_USDT@markPrice@1s"
  ]
}

Unsubscribe

{
  "op": "unsubscribe",
  "args": ["ticker@BTC_USDT"]
}

Authentication (Private Channels)

Login uses the same HmacSHA256 signing mechanism as the REST API. For details, see Common Module · WebSocket Interface.

Heartbeat

{ "op": "ping" }

Server Response Format

Success Response

{
  "op": "subscribe",
  "success": true,
  "args": ["ticker@BTC_USDT"]
}

Error Response

{
  "op": "subscribe",
  "success": false,
  "msg": "invalid channel format"
}

Authentication Response

{ "op": "auth", "success": true }

{ "op": "auth", "success": false, "msg": "token is expired" }

Pong Response

{ "op": "pong" }

Push Message Format

All push messages use the following format:

{
  "ch": "<channel>",
  "d": { ... }
}

Field	Description
ch	Channel name
d	Data payload

Channel Summary

Channel Type	Format	Example	Access	Futures Specific
Ticker	ticker@{symbol}	ticker@BTC_USDT	Public	-
Order book snapshot	depth@{symbol},{level}	depth@BTC_USDT,20	Public	-
Order book delta	depth_update@{symbol}	depth_update@BTC_USDT	Public	-
K-line	kline@{symbol},{interval}	kline@BTC_USDT,1s	Public	Yes, supports 1s interval
Trade	trade@{symbol}	trade@BTC_USDT	Public	-
Mark price (3s)	{symbol}@markPrice	BTC_USDT@markPrice	Public	Yes
Mark price (1s)	{symbol}@markPrice@1s	BTC_USDT@markPrice@1s	Public	Yes
Order	order	order	Private	-
Balance	balance	balance	Private	-
Position	position	position	Private	Yes

Error Messages

Error Message	Description
invalid message format	Invalid message format
invalid channel format	Invalid channel format
unknown operation	Unknown operation
authentication required	Authentication required
invalid token	Invalid token
max subscriptions reached	Subscription limit reached

Quick Start Example

const ws = new WebSocket('ws://host:9021/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: 'subscribe',
    args: [
      'ticker@BTC_USDT',
      'depth@BTC_USDT,20',
      'BTC_USDT@markPrice@1s',
      'kline@BTC_USDT,1s'
    ]
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.ch) {
    console.log('Channel:', msg.ch, 'Data:', msg.d);
  } else if (msg.op) {
    console.log('Response:', msg);
  }
};

setInterval(() => ws.send(JSON.stringify({ op: 'ping' })), 30000);