私有用户数据流¶

证据：UserDataApiController、WS_API_SPOT.md 私有章节、Postman ListenKey / OpenAPI-WS。

listenKey REST¶

Method	Path	鉴权
`POST`	`/openapi/v1/userDataStream`	仅 API Key（`validKeyOnly`）
`PUT`	`/openapi/v1/userDataStream?listenKey=...`	仅 API Key
`DELETE`	`/openapi/v1/userDataStream?listenKey=...`	仅 API Key

续期：按 WS_API_SPOT.md 指引，每 30 分钟 PUT 一次。

连接¶

wss://<host>/openapi/ws/<listenKey>/spot

无效 / 过期 Key → 握手 HTTP 401。连接后网关自动订阅私有频道 — 无需再发 SUBSCRIBE。

事件（示意，来自 WS_API_SPOT.md）¶

订单更新 — `orderReport`¶

{
  "e": "orderReport",
  "i": 4293153,
  "c": "my-order-id",
  "s": "BTC_USDT",
  "S": "BUY",
  "o": "LIMIT",
  "oO": "LIMIT",
  "f": "GTC",
  "p": "0.10264410",
  "aP": "0.00000000",
  "q": "1.00000000",
  "a": "0.10264410",
  "z": "0.00000000",
  "Z": "0.00000000",
  "X": "NEW",
  "O": 1672515782136,
  "P": "0.00000000",
  "tT": 0,
  "tC": "",
  "r": ""
}

状态：NEW · PARTIALLY_FILLED · FILLED · CANCELED · EXPIRED

[NEEDS-CONFIRMATION: 生产载荷中交易对分隔符为 BTC_USDT 还是 BTCUSDT]

成交更新 — `tradeReport`¶

{
  "e": "tradeReport",
  "t": 987654,
  "s": "BTC_USDT",
  "i": 4293153,
  "l": "0.50000000",
  "L": "0.10264410",
  "Y": "0.05132205",
  "N": "USDT"
}

余额更新 — `balanceReport`¶

{
  "e": "balanceReport",
  "B": [{ "a": "BTC", "f": "0.50000000", "l": "0.00000000", "t": "0.50000000" }]
}

WS 错误帧¶

{ "code": 401, "msg": "invalid or expired listenKey", "id": null }

WS 指南中的代码：400、401、429（与 REST ApiErrorCode 不同命名空间）。