自现货 listenKey 停用起成交和余额推送改在 WebSocket API 里订阅
币安现货账户的订单成交、余额变化这类推送,从 2026-02-20 07:00 UTC(北京时间当天 15:00)起不能再靠 listenKey 拿了。REST 里创建、续期、关闭 listenKey 的 POST、PUT、DELETE /api/v3/userDataStream,和 WebSocket API 里的 userDataStream.start、userDataStream.ping、userDataStream.stop,从那一刻起都不再提供。还在定时续 listenKey 的现货机器人,要把这一段换成 WebSocket API 里的订阅。
新的入口是 WebSocket API,地址 wss://ws-api.binance.com:443/ws-api/v3,443 端口连不上可以换 9443。连上以后有两个订阅方法:userDataStream.subscribe 要求这条连接先用 Ed25519 Key 登录;userDataStream.subscribe.signature 不用登录,HMAC、RSA、Ed25519 哪种 Key 签名都行。这次停掉的都是现货接口,U 本位合约和杠杆另有接法,放在第四节。
币安现货 listenKey 是哪一天停用的
从列为弃用到真正停掉,前后隔了十个多月,中间对 Key 类型的要求还放宽过一次。现货 API 更新日志里相关的条目:
| 更新日志日期 | 内容 |
|---|---|
| 2025-04-07 | 在 wss://stream.binance.com:9443 上用 listenKey 接收用户数据流列为弃用,改为在 WebSocket API 里订阅;当时这种订阅只能用 Ed25519 Key |
| 2025-04-29 | 预告在 listenKey 移除之前,WebSocket API 的用户数据流订阅会对任何类型的 API Key 开放 |
| 2025-08-12 | 新增 userDataStream.subscribe.signature,不用先登录,任何类型的 Key 都能用;一条连接可以同时订阅多个账户 |
| 2025-10-24 | 给 wss://stream.binance.com 用的 listenKey 相关文档全部删除,提醒改用 WebSocket API 订阅 |
| 2026-01-21 | 发出停用通知,停用时刻和接口清单见下图 |
判断自己的程序要不要改,在代码和配置里搜三样东西:listenKey、/api/v3/userDataStream、userDataStream.start。搜到的地方如果属于现货账户,就是要换掉的那一段。用的是第三方库或现成的机器人,就去看它的更新说明里有没有改用 WebSocket API 订阅用户数据流的记录,再决定要不要升级。
现货账户推送改用 userDataStream.subscribe 或 subscribe.signature 订阅
两个方法订的都是同一套用户数据流事件,差别在要不要先登录、能用哪种 Key、一次能管几个账户:
| 对照项 | userDataStream.subscribe | userDataStream.subscribe.signature |
|---|---|---|
| 前提 | 这条连接先用 session.logon 登录 | 不用登录,任何会话都能调用 |
| Key 类型 | 只支持 Ed25519 | 任何类型(HMAC、RSA、Ed25519) |
| 参数 | apiKey | apiKey、timestamp、signature,可选 recvWindow(最大 60000) |
| 订阅谁的推送 | 登录的那一个账户 | 你能给出签名的一个或多个账户 |
| 调用 session.logout 时 | 订阅随之关闭 | 订阅不受影响 |
| 请求权重 | 2 | 2 |
手里只有系统生成的 HMAC Key、暂时不想换 Key 的,用 signature 这个方法,改动最小。已经在用 Ed25519 Key、下单也打算走同一条 WebSocket 连接的,用 session.logon 登录后再调 userDataStream.subscribe:登录以后,这条连接上需要签名的请求都可以省掉 apiKey 和 signature,只是带签名的请求仍要传 timestamp。一条连接同时只能登录一把 Key,重复调用 session.logon 会换成新的那把。
两个方法成功后都返回一个 subscriptionId。要退订就调 userDataStream.unsubscribe:不带参数会关掉这条连接上的全部订阅,带上 subscriptionId 只关对应的那一个。
一条连接最多同时挂 1,000 个账户订阅
用 signature 方法可以在同一条连接上挂好几个账户,上限如下:
- 同一个账户在同一条连接上只能有一个活跃订阅。
- 单个会话最多同时 1,000 个活跃订阅,超过会报错。账户交易很频繁时,一次别开太多订阅,免得把连接压垮。
- 一个会话从建立到断开,累计最多开 65,535 次订阅;到了这个数会报错,要重新建连接才能再订。
- session.subscriptions 列出当前会话所有活跃订阅的 subscriptionId。
- session.status 返回的 userDataStream 字段:null 表示这个 WebSocket API 不提供用户数据流订阅,true 表示至少有一个活跃订阅,false 表示一个都没有。
举个例子:假设你给 3 个账户跑同一套现货策略,可以只开一条连接,对 3 个账户各调一次 userDataStream.subscribe.signature,拿到 3 个 subscriptionId,记成「subscriptionId → 账户」的对照表;之后每来一条推送,按 subscriptionId 查表,就知道该更新哪个账户的持仓和挂单。程序启动时调一次 session.status,看到 userDataStream 是 true 再开始等推送,比干等第一条推送更容易发现订阅没成功。
合约和杠杆账户的推送还用 listenKey 吗
不能拿现货的结论直接套。U 本位合约的接口文档在 2026 年 10 月还提供 listenKey 这一组:POST /fapi/v1/listenKey 生成,PUT 续期,DELETE 关闭。数据流在 60 分钟后关闭,除非期间续了期;账户已经有有效的 listenKey 时,POST 会返回同一个,并把有效期延长 60 分钟。续期大约每 60 分钟发一次。
杠杆账户推荐改用 listen token,用来替代 wss://stream.binance.com:9443 上的 listenKey 用户数据流。流程分两步:
- 在 REST(https://api.binance.com)调 POST /sapi/v1/userListenToken,拿到 token 和 expirationTime。validity 参数按毫秒填,默认和最大都是 24 小时;逐仓要传 isIsolated=true,这时 symbol 必填,不传 isIsolated 就是全仓。
- 在 WebSocket API 上调 userDataStream.subscribe.listenToken,参数只有 listenToken,不登录的会话也能用。token 无效会返回错误码 -1209。
续期的做法是在当前订阅过期之前再调一次 POST /sapi/v1/userListenToken 拿新 token,再用新 token 调一次 userDataStream.subscribe.listenToken,订阅会延长到新的 expirationTime。没赶上过期时间,会收到 eventStreamTerminated 事件,之后不再推送,直到用新 token 重新订阅。
| 账户 | 拿推送的方式 | 要按时做的事 |
|---|---|---|
| 现货 | WebSocket API 的 userDataStream.subscribe 或 .signature | 不再有 listenKey 续期;连接断了要重连、重订 |
| U 本位合约 | POST /fapi/v1/listenKey | 60 分钟内用 PUT 续一次 |
| 杠杆 | POST /sapi/v1/userListenToken + userDataStream.subscribe.listenToken | 24 小时有效期到之前换新 token 再订一次 |
连接满 24 小时会断开,收到 serverShutdown 就换新连接重订
WebSocket API 的单个连接只有效 24 小时,到点就会被断开。连接期间服务器每 20 秒发一个 ping 帧,一分钟内收不到 pong 就断开;收到 ping 要尽快回 pong,并把 ping 的 payload 原样带回。自己主动发的 pong 服务器也收,但不能防止断开。
服务器准备关闭时,会推一条 serverShutdown 事件,收到后应当尽快建立新连接。2026-06-09 的更新日志把断开前 10 分钟发送这个固定提前量从文档里删掉了,所以程序不要按 10 分钟倒数,收到就切换。
两个订阅方法订的都是当前这条连接上的推送,换一条新连接,登录和订阅就得重新做一遍。重连的步骤:
- 建立新连接。用 subscribe 方法的,先调 session.logon。
- 重新订阅,拿到新的 subscriptionId,更新对照表。
- 新连接的订阅确认成功以后,再关掉旧连接。
- 用 REST 或 WebSocket API 查一次挂单和余额,补上断线那段时间的变化。
第 4 步的做法和下单请求超时时一样:订单状态没在用户数据流里出现,就用接口查一次。超时时怎么查单、怎么避免重复下单,见下单请求超时了,这一单到底成没成?。
重连本身也有频率限制:按 IP 计,每 5 分钟最多 300 次连接。重连失败后别立刻再连,用逐次拉长的等待,写法和 接口返回 429 之后,先做什么、等多久再重试 里的退避一样。换用 Ed25519 Key 之前,权限和 IP 白名单怎么设,可以对照 币安 API 密钥怎么设才安全?只开交易权限也可能被对敲。