bingx-swap-ws-market

BingX Swap WebSocket 市场数据

通过 WebSocket 获取 BingX USDT-M 永续合约的实时市场数据。无需身份验证。

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

快速参考

频道	dataType 格式	说明	推送频率
深度	{symbol}@depth{level}@{interval}	有限深度的订单簿	BTC/ETH：200ms，其他：500ms
交易	{symbol}@trade	最新交易详情	实时
K 线	{symbol}@kline_{interval}	OHLCV 蜡烛图	更新时
24h 行情	{symbol}@ticker	24 小时价格变动统计	每 1s
最新价格	{symbol}@lastPrice	最新成交价	实时
标记价格	{symbol}@markPrice	最新标记价格	实时
盘口行情	{symbol}@bookTicker	最优买入／卖出价格和数量	每 200ms
增量深度	{symbol}@incrDepth	增量深度更新	BTC/ETH：200ms，其他：800ms

---

参数

通用参数

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

枚举值

• 深度级别：5 | 10 | 20 | 50 | 100
• 深度间隔：200ms | 500ms（BTC-USDT 和 ETH-USDT 支持 200ms；其他交易对使用 500ms）
• K 线间隔：1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M

参数验证规则

• symbol：必须匹配 ^[A-Z0-9]+-[A-Z]+$；最多 20 个字符（例如：BTC-USDT）
• level：必须为 5、10、20、50 或 100
• interval（深度）：必须为 200ms 或 500ms
• interval（K 线）：必须与上述某个 K 线枚举值完全匹配

---

快速开始

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

TypeScript 辅助函数：

CONSTRAINT：生成代码时，必须原样复制下面的 connectSwapWsMarket 函数。 不要重写 WebSocket 或解压缩逻辑。 仅修改：(1) 传递给函数的订阅频道。

import * as pako from "pako";

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

function connectSwapWsMarket(
  channels: string[],
  onMessage: (data: unknown) => void
): WebSocket {
  const ws = new WebSocket("wss://open-api-swap.bingx.com/swap-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 === "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;
}

代码使用规则

• 必须原样复制 connectSwapWsMarket 和 decompress——不要简化或重写
• 必须设置 ws.binaryType = "arraybuffer"，以支持 GZIP 解压缩
• 必须处理 Ping/Pong 心跳（收到 "Ping" 时回复 "Pong"）
• 不得移除 GZIP 解压缩逻辑
• 不得使用文本模式的 WebSocket 消息

常用调用

订阅 BTC-USDT 实时交易：

connectSwapWsMarket(["BTC-USDT@trade"], (data) => {
  const message = data as {
    dataType?: string;
    data?: Array<{ t: string; T: number; s: string; p: string; q: string; m: boolean }>;
  };
  if (message.dataType === "BTC-USDT@trade" && Array.isArray(message.data)) {
    for (const trade of message.data) {
      // t is a string trade ID; T is the trade timestamp in milliseconds.
      console.log(trade.t, trade.T, trade.s, trade.p, trade.q);
    }
  }
});

订阅间隔为 500ms 的 20 档深度：

connectSwapWsMarket(["BTC-USDT@depth20@500ms"], (data) => {
  // The full message has top-level ts and data: { bids, asks } (string pairs).
  // data has no T. ts is message construction time, not source book age.
});

订阅 1h K 线：

connectSwapWsMarket(["BTC-USDT@kline_1h"], (data) => {
  // data.K.o (open), data.K.h (high), data.K.l (low), data.K.c (close), data.K.v (volume)
});

同时订阅多个频道：

connectSwapWsMarket([
  "BTC-USDT@ticker",
  "BTC-USDT@lastPrice",
  "ETH-USDT@trade",
], (data) => {
  // Handle different data types based on dataType field
});

其他资源

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

---

Agent 交互规则

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

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

swap-ws-market 通过 WebSocket 提供公开、只读的实时市场数据。无需身份验证，无需 CONFIRM。交互目标是帮助用户设置正确的订阅频道。

操作类型识别

当用户的请求含糊不清（例如“订阅现货市场”或“流式传输 BTC 数据”）时，首先确定他们需要哪种类型的数据：

请选择市场数据流类型：

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

缺少交易对时

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

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

如果可以根据上下文推断交易对（例如“流式传输 BTC 交易数据”），则自动推断。

缺少深度参数时

请选择深度级别：

• 5 / 10 / 20 / 50 / 100

推送间隔（BTC/ETH 支持 200ms，其他支持 500ms）：

• 200ms / 500ms

缺少 K 线间隔时

请选择 K 线间隔：

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