General WSS information

WebSocket base URL: wss://fstream.xt.com/ws/user (User private channel)

---

Request headers

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

Recommended header

Sec-Websocket-Extensions: permessage-deflate

---

Subscription steps

1. Call the API to obtain a ListenKey: GET https://fapi.xt.com/future/v1/user/listen-key. (Tip: you may also link to “Contract API → User → Get ListenKey” in your docs sidebar.)
2. After the WebSocket connection is established, to subscribe to user‑related events, send the JSON below:

SUBSCRIBE

{
  "method": "SUBSCRIBE",
  "params": ["{topic_you_follow}@{ListenKey_from_step_1}"],
  "id": "id_field_could_call_whatever_you_want"
}

Notes

• If you receive invalid_listen_key, the ListenKey has expired or is invalid. 👉 Request a new ListenKey via API.
• User data is pushed after subscription succeeds and when there is a change.
• To unsubscribe, set method to UNSUBSCRIBE.

---

Request message format

Subscribe / Unsubscribe

Message format

{
  "method": "SUBSCRIBE/UNSUBSCRIBE",
  "params": [
    "order@{ListenKey}",
    "trade@{ListenKey}",
    "balance@{ListenKey}",
    "position@{ListenKey}",
    "notify@{ListenKey}"
  ],
  "id": "{id}" // user-defined
}

Subscribe example — After the WebSocket is established, send the JSON below to the server.

SUBSCRIBE example

{
  "method": "SUBSCRIBE",
  "params": ["order@A246C3DF8EE532DC75007BC5D86698541678596355681"],
  "id": "test1"
}

---

Response message format

Format

{
  "id": "{id}", // callback ID
  "code": 1, // result: 0 = success; 1 = failure; 2 = ListenKey invalid
  "msg": "" // message of subscription result / details
}

Example

{"id": "123", "code": 0, "msg": "success"}

---

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 code	Description
{topic}@invalid_listenkey	ListenKey expired or invalid. Please request again.
Invalid Parameter	Invalid parameters. Please check the JSON string.