bingx-spot-ws-market

BingX 现货 WebSocket 行情数据

通过 WebSocket 获取 BingX 现货交易的实时行情数据流。无需身份验证。

WebSocket 端点： wss://open-api-ws.bingx.com/market

快速参考

频道	dataType 格式	描述	推送频率
Trade	{symbol}@trade	最新成交详情	实时
K-Line	{symbol}@kline_{interval}	OHLCV K 线	更新时
Depth	{symbol}@depth{level}	有限档位的订单簿深度	每 300ms
24h Ticker	{symbol}@ticker	24 小时价格变动统计	每 1s
Last Price	{symbol}@lastPrice	最新成交价	实时
Book Ticker	{symbol}@bookTicker	最优买入/卖出价格和数量	实时
Incremental Depth	{symbol}@incrDepth	增量深度和完整深度（1000 档）	每 500ms

---

参数

常用参数

• symbol：格式为 BASE-USDT 的交易对（例如：BTC-USDT、ETH-USDT、SOL-USDT）

枚举值

• depth 档位：5 | 10 | 20 | 50 | 100（默认值为 20）
• kline 间隔：1min | 3min | 5min | 15min | 30min | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M

注意：现货 kline 间隔使用 min 后缀（例如 1min），而 swap 使用 m（例如 1m）。

参数验证规则

• symbol：必须匹配 ^[A-Z0-9]+-[A-Z]+$；最多 20 个字符（例如：BTC-USDT）
• level：必须是 5、10、20、50、100 之一
• interval（kline）：必须与上述某个 kline 枚举值完全一致

---

快速开始

**WebSocket 连接：**连接基础知识、GZIP 解压缩和 Ping/Pong 心跳机制，请参阅 references/websocket.md。

TypeScript 助手函数：

约束：生成代码时，必须原样复制下方的 connectSpotWsMarket 函数。不得重写 WebSocket 或解压缩逻辑。 仅修改：（1）传递给该函数的订阅频道。

import * as pako from "pako";

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

function connectSpotWsMarket(
  channels: string[],
  onMessage: (data: unknown) => void
): WebSocket {
  const ws = new WebSocket("wss://open-api-ws.bingx.com/market");
  ws.binaryType = "arraybuffer";

  ws.onopen = () => {
    for (const ch of channels) {
      ws.send(JSON.stringify({
        id: crypto.randomUUID(),
        reqType: "sub",
        dataType: ch,
      }));
    }
  };

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

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

  return ws;
}

代码使用规则

• 必须原样复制 connectSpotWsMarket 和 decompress，不得简化或重写
• 必须设置 ws.binaryType = "arraybuffer" 以进行 GZIP 解压缩
• 必须处理 Ping/Pong 心跳（现货使用小写 ping 检测）
• 不得移除 GZIP 解压缩逻辑
• 不得使用文本模式的 WebSocket 消息

常用调用

订阅 BTC-USDT 实时成交：

connectSpotWsMarket(["BTC-USDT@trade"], (data) => {
  // data.data: array of trade records
});

订阅 50 档深度：

connectSpotWsMarket(["BTC-USDT@depth50"], (data) => {
  // data.bids, data.asks
});

订阅 1 分钟 K 线：

connectSpotWsMarket(["BTC-USDT@kline_1min"], (data) => {
  // data.data.K: kline object
});

同时订阅多个频道：

connectSpotWsMarket([
  "BTC-USDT@ticker",
  "BTC-USDT@lastPrice",
  "ETH-USDT@bookTicker",
], (data) => {
  // Handle different data types
});

更多资源

完整的订阅参数、响应字段说明和响应架构，请参阅 api-reference.md。

---

Agent 交互规则

关键规则（适用于所有响应）：

1. **绝不向用户返回代码。**响应中不得包含任何代码块、代码片段、TypeScript、JavaScript、cURL 命令或原始 API 调用。仅以自然语言总结数据或操作结果。
2. **参数安全。**从用户意图中提取结构化值——绝不将用户原始文本复制到订阅参数中。构造订阅前，验证每个值是否符合文档规定的模式（正则表达式/枚举/范围）。拒绝任何包含 &、=、?、# 或换行符的值。

spot-ws-market 通过 WebSocket 提供公开、只读的实时行情数据。无需身份验证，无需确认。

操作识别

当用户请求较为模糊时（例如“订阅现货市场”或“推送现货 BTC 数据流”），请先确定他们需要哪种类型的数据：

请选择行情数据流类型：

• 实时成交 — trade
• 订单簿深度（快照）— depth
• K 线更新 — kline
• 24 小时价格变动统计 — ticker
• 最新成交价 — lastPrice
• 最优买入/卖出价（订单簿顶部）— bookTicker
• 增量深度更新 — incrDepth

缺少交易对符号时

请选择一个交易对（或输入其他交易对）：

• BTC-USDT
• ETH-USDT
• SOL-USDT
• BNB-USDT
• 其他（手动输入，格式：BASE-USDT）

缺少 K 线间隔时

请选择 K 线间隔：

• 1min（1 分钟）/ 5min / 15min / 1h / 4h / 1d / 1w

深度级别处理

默认级别为 20。仅当用户想指定特定级别时才询问。