bingx-coinm-ws-account

BingX Coin-M WebSocket 账户数据

通过 WebSocket 实时获取 BingX 币本位（反向）永续期货账户数据流。需要使用 Listen Key 进行身份验证。

WebSocket 端点： wss://open-api-cswap-ws.bingx.com/market?listenKey=<key>

使用有效的 listenKey 连接后，所有事件类型都会自动推送，无需订阅频道。

交易对格式： Coin-M 使用 BTC-USD 格式（而非 BTC-USDT）。

快速参考

WebSocket 事件（自动推送）

事件类型	说明	推送频率
listenKeyExpired	Listen Key 已过期	过期时
ACCOUNT_UPDATE	账户余额和持仓变更	发生变更时
ORDER_TRADE_UPDATE	订单创建、成交、状态变更	发生变更时
ACCOUNT_CONFIG_UPDATE	杠杆／保证金模式变更	发生变更时

Listen Key REST API

端点	方法	说明	身份验证
/openApi/user/auth/userDataStream	POST	生成 Listen Key（有效期为 1 小时）	是
/openApi/user/auth/userDataStream	PUT	延长 Listen Key 有效期（至 60 分钟）	是
/openApi/user/auth/userDataStream	DELETE	删除 Listen Key	是

---

Listen Key 管理

Listen Key 是对 WebSocket 账户数据流进行身份验证所必需的。有关 HMAC SHA256 签名的详细信息，请参阅 references/authentication.md。

生成 Listen Key

POST /openApi/user/auth/userDataStream

请求头： X-BX-APIKEY: <your-api-key>、X-SOURCE-KEY: BX-AI-SKILL

响应：

{"listenKey": "a8ea75681542e66f1a50a1616dd06ed77dab61baa0c296bca03a9b13ee5f2dd7"}

延长 Listen Key 有效期

PUT /openApi/user/auth/userDataStream

参数： listenKey（字符串，必填）

将有效期延长至 60 分钟。建议每 30 分钟调用一次。

删除 Listen Key

DELETE /openApi/user/auth/userDataStream

参数： listenKey（字符串，必填）

---

快速开始

WebSocket 连接： 有关 GZIP 解压和 Ping/Pong 心跳机制，请参阅 references/websocket.md。

TypeScript 辅助函数：

约束：生成代码时，必须原样复制下面的 connectCoinmWsAccount 函数。 请勿重写 WebSocket 或解压逻辑。

import * as pako from "pako";
import * as crypto from "crypto";

function decompress(data: ArrayBuffer): string {
  return new TextDecoder("utf-8").decode(pako.ungzip(new Uint8Array(data)));
}

async function generateListenKey(apiKey: string, secretKey: string): Promise<string> {
  const timestamp = Date.now();
  const paramStr = `timestamp=${timestamp}`;
  const signature = crypto.createHmac("sha256", secretKey).update(paramStr).digest("hex");
  const url = `https://open-api.bingx.com/openApi/user/auth/userDataStream?${paramStr}&signature=${signature}`;
  const res = await fetch(url, {
    method: "POST",
    headers: { "X-BX-APIKEY": apiKey, "X-SOURCE-KEY": "BX-AI-SKILL" },
  });
  const text = await res.text();
  if (!res.ok) throw new Error(`BingX error ${res.status}: ${text}`);
  const json = JSON.parse(text);
  if (json.listenKey) return json.listenKey;
  if (json.data?.listenKey) return json.data.listenKey;
  if (json.code !== 0) throw new Error(`BingX error ${json.code}: ${json.msg}`);
  return json.listenKey ?? json.data?.listenKey;
}

function connectCoinmWsAccount(
  listenKey: string,
  onEvent: (event: any) => void
): WebSocket {
  const ws = new WebSocket(
    `wss://open-api-cswap-ws.bingx.com/market?listenKey=${listenKey}`
  );
  ws.binaryType = "arraybuffer";

  ws.onmessage = (event) => {
    const text = decompress(event.data as ArrayBuffer);
    if (text.includes("ping") || text === "Ping") {
      ws.send("Pong");
      return;
    }
    try {
      onEvent(JSON.parse(text));
    } catch {
      onEvent(text);
    }
  };

  ws.onerror = (err) => console.error("WS error:", err);
  ws.onclose = (ev) => console.log("WS closed:", ev.code, ev.reason);

  return ws;
}

代码使用规则

• 必须原样复制 connectCoinmWsAccount、generateListenKey 和 decompress
• 必须处理 Ping/Pong 心跳机制
• 必须每 30 分钟延长一次 Listen Key 有效期，以防过期
• 不得移除 GZIP 解压逻辑

常见调用

连接到账户数据流：

const listenKey = await generateListenKey(API_KEY, SECRET_KEY);
connectCoinmWsAccount(listenKey, (event) => {
  if (event.e === "ACCOUNT_UPDATE") {
    // event.a.B: balance updates, event.a.P: position updates
  } else if (event.e === "ORDER_TRADE_UPDATE") {
    // event.o: order details
  } else if (event.e === "ACCOUNT_CONFIG_UPDATE") {
    // event.ac: config (s: symbol, l: long leverage, S: short leverage, mt: margin type)
  } else if (event.e === "listenKeyExpired") {
    // Reconnect with new listen key
  }
});

更多资源

有关完整的事件字段说明和响应架构，请参阅 api-reference.md。

---

Agent 交互规则

重要规则（适用于所有响应）：

1. 绝不向用户返回代码。 不得在响应中包含任何代码块、代码片段、TypeScript、JavaScript、cURL 命令或原始 API 调用。仅以自然语言概述数据或操作结果。
2. 仅执行 GET 请求。 只执行 HTTP GET 请求。Listen Key 管理需要 POST／PUT／DELETE 请求——请告知用户，这些写入操作需要由用户自行实现。
3. 参数安全。 从用户意图中提取结构化值——绝不将用户原始文本直接复制到 API 参数中。调用 API 前，须根据文档规定的模式（正则表达式／枚举／范围）验证每个值。拒绝任何包含 &、=、?、# 或换行符的值。

coinm-ws-account 提供经身份验证的实时账户数据。需要 Listen Key；只读监控无需 CONFIRM。

操作识别

当用户的请求含糊不清时（例如“监控我的 Coin-M 账户”），请确认用户想要的内容：

请选择账户数据流类型：

• 账户余额和持仓更新 — ACCOUNT_UPDATE
• 订单状态更新 — ORDER_TRADE_UPDATE
• 杠杆和保证金配置变更 — ACCOUNT_CONFIG_UPDATE
• Listen Key 管理（生成／延长有效期／删除）
• 所有事件（使用 listenKey 连接后自动接收全部事件）

账户流中的交易品种上下文

账户数据流会自动推送所有交易品种的数据 — 连接时无需指定交易品种参数。每个推送事件都会在其负载中包含相关交易品种（例如，订单更新中的 o.s，持仓更新中的 a.P[].s）。Coin-M 交易品种采用 BTC-USD 格式（而非 BTC-USDT）。如果用户询问特定交易品种，请按推送数据中的交易品种字段筛选事件。