Skip to main content

General WSS information

General WebSocket Information​

Base URL: wss://fstream.x.group/ws/market (Public channels; no listenKey required)

Request Headers​

When initiating the HTTP upgrade for the WebSocket connection, it is recommended to enable the per‑message compression extension:

Recommended Header
Sec-Websocket-Extensions: permessage-deflate

Subscription Steps​

  1. Establish a WebSocket connection.
  2. To subscribe to a public channel event, send:
Subscribe
{
  "method": "SUBSCRIBE",
  "params": ["{topic}@{symbol_you_follow}"],
  "id": "id_field_could_call_whatever_you_want"
}

Request Message Format​

Subscribe / Unsubscribe example

Message format
{
  "method": "SUBSCRIBE/UNSUBSCRIBE",
  "params": ["{topic1}@{arg1},{arg2}", "{topic2}@{arg}"],
  "id": "id_field_could_call_whatever_you_want" // callback ID
}

Response Message Format​

Response
{
  "id": "{id}", // callback ID
  "code": 1, // result 0=success; 1=failure; 2=listenKey invalid
  "msg": ""
}

Push Message Format​

Format
{
  "topic": "topic",
  "event": "{topic}@{symbol}", // title
  "data": {}
}
Example
{
  "topic": "trade",
  "event": "trade@btc_usdt",
  "data": {
    "s": "btc_usdt",
    "i": 6316559590087222000,
    "t": 1655992403617,
    "p": "43000",
    "q": "0.21",
    "b": true
  }
}

Heartbeat​

Each client connection must periodically send a text ping message. The server will reply with a text pong.

If the server does not receive a ping within 30 seconds, it will proactively close the connection.

Error Codes​

Error codeDescription
400Bad request payload. Please check it.

Order Book Management​

How to maintain a local order book correctly

  1. Connect to wss://fstream.xt.com/ws/market, and subscribe to depth_update@btc_usdt.
  2. Buffer the events received from the stream.
  3. Fetch a depth snapshot: https://fapi.xt.com/future/market/v1/public/depth?symbol=btc_usdt&level=500.
  4. Discard any event where u <= lastUpdateId in the snapshot.
  5. The first processed event should satisfy fu <= lastUpdateId + 1 and u >= lastUpdateId + 1.
  6. While listening to the stream, each new event must have fu == previous.u + 1.
  7. The data in each event is the absolute quantity at each price level.
  8. If the quantity is 0, remove that price level.
  9. Receiving deletion of a price level that does not exist locally may happen and is normal.

Notes​

Because the depth snapshot limits the number of levels, levels that have no changes after the initial snapshot will not be updated in the incremental depth stream. Therefore, even if you apply all updates correctly, those levels will not appear in the local order book, which may cause minor differences from the actual order book. For most use cases, a 500‑level snapshot is sufficient to understand the market and trade effectively.