Copy page

Listen Token 用户数据流

本篇为基于 wss://stream.binance.com:9443 的 listenKey 用户数据流的推荐替代方案，使用有效期较短的 listen token 与 WebSocket API 订阅方法，延迟更低。弃用公告请参见 变更日志。

连接

• REST 接口的 base URL：https://api.binance.com
• POST /sapi/v1/userListenToken 创建一个新的用户数据流并返回一个 listenToken。
  • 请求权重 (UID)：1
  • expirationTime = 当前时间 + validity。默认与最大有效期均为 24 小时。
  • isIsolated（BOOLEAN）：true 表示逐仓（此时 symbol 必填），默认为全仓。
  • 如需延长订阅，请在当前订阅过期之前再次调用 POST /sapi/v1/userListenToken，获取新的 listenToken，然后用新 token 再次调用 userDataStream.subscribe.listenToken，订阅将无缝延长至新的 expirationTime。
• WebSocket API 的 base URL：wss://ws-api.binance.com:443/ws-api/v3
  • testnet：wss://ws-api.testnet.binance.vision/ws-api/v3
• 通过 WebSocket API 方法 userDataStream.subscribe.listenToken 订阅，参数 listenToken（字符串，必填）。
  • 请求权重：2
  • 允许在非鉴权会话中使用此功能。
  • listenToken 无效时返回错误码 -1209。
• 若订阅未在 token 过期前延长，订阅将失效并推送 eventStreamTerminated 事件；此后不会再推送任何事件，直到创建新 token 并重新订阅。

---

HTTP 请求 — POST /sapi/v1/userListenToken

请求参数

名称	类型	是否必填	描述
symbol	STRING	条件必填	交易对符号；当 isIsolated 为 true 时必填，例如 BNBUSDT。
isIsolated	BOOLEAN	否	是否逐仓；true 为逐仓，默认为全仓。
validity	LONG	否	有效期，单位毫秒；默认 24 小时，最大 24 小时。

响应示例

Code
{
  "token": "6xXxePXwZRjVSHKhzUCCGnmN3fkvMTXru+pYJS8RwijXk9Vcyr3rkwfVOTcP2OkONqciYA",
  "expirationTime": 1758792204196
}

---

WebSocket API 方法 — userDataStream.subscribe.listenToken

使用从 POST /sapi/v1/userListenToken 获取的 listenToken 订阅用户数据流。

请求示例

Code
{
  "id": "f3a8f7a29f2e54df796db582f3d",
  "method": "userDataStream.subscribe.listenToken",
  "params": {
    "listenToken": "5DbylArkmImhyHkpG6s9tbiFy5uAMTFwzx9vwsFjDv9dC3GkKxSuoTCj0HvcJC0WYi8fA"
  }
}

响应示例

Code
{
  "id": "f3a8f7a29f2e54df796db582f3d",
  "status": 200,
  "result": {
    "subscriptionId": 0,
    "expirationTime": 1749094553955907
  }
}

---

事件：事件流终止

描述

当订阅因未在 listenToken 的 expirationTime 之前续期而到期时，会推送此事件。此后不会再推送任何事件，直到创建新的 listenToken 并重新订阅。

事件名称

eventStreamTerminated

负载

Code
{
  "subscriptionId": 0,
  "event": {
    "e": "eventStreamTerminated",
    "E": 1759089357377
  }
}