bingx-spot-ws-market

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BingX Spot WebSocket Market Data

BingX 现货WebSocket行情数据

Real-time market data streams for BingX spot trading via WebSocket. No authentication required.

WebSocket Endpoint:

wss://open-api-ws.bingx.com/market

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

WebSocket接入地址：

wss://open-api-ws.bingx.com/market

Quick Reference

快速参考

Channel	dataType Format	Description	Push Frequency
Trade	`{symbol}@trade`	Latest trade detail	Real-time
K-Line	`{symbol}@kline_{interval}`	OHLCV candlestick	On update
Depth	`{symbol}@depth{level}`	Limited order book depth	Every 300ms
24h Ticker	`{symbol}@ticker`	24-hour price change statistics	Every 1s
Last Price	`{symbol}@lastPrice`	Latest trade price	Real-time
Book Ticker	`{symbol}@bookTicker`	Best bid/ask price & qty	Real-time
Incremental Depth	`{symbol}@incrDepth`	Incremental + full depth (1000 levels)	Every 500ms

通道	dataType格式	说明	推送频率
交易	`{symbol}@trade`	最新交易详情	实时
K线	`{symbol}@kline_{interval}`	OHLCV candlestick	更新时推送
深度	`{symbol}@depth{level}`	限定档位的订单簿深度	每300毫秒
24小时行情	`{symbol}@ticker`	24小时价格变动统计	每1秒
最新价格	`{symbol}@lastPrice`	最新成交价格	实时
买卖盘行情	`{symbol}@bookTicker`	最优买卖盘价格和数量	实时
增量深度	`{symbol}@incrDepth`	增量+全量深度（1000档位）	每500毫秒

Parameters

参数说明

Common Parameters

公共参数

symbol: Trading pair in
```
BASE-USDT
```
format (e.g.,
```
BTC-USDT
```
,
```
ETH-USDT
```
,
```
SOL-USDT
```
)

symbol: 交易对，格式为
```
BASE-USDT
```
（例如：
```
BTC-USDT
```
、
```
ETH-USDT
```
、
```
SOL-USDT
```
）

Enums

枚举值

depth level:
```
5
```
|
```
10
```
|
```
20
```
|
```
50
```
|
```
100
```
(default 20)

kline interval:

1min

3min

5min

15min

30min

1h

2h

4h

6h

8h

12h

1d

3d

1w

1M

Note: Spot kline intervals use
min
suffix (e.g.,
1min
) unlike swap which uses
m
(e.g.,
1m
).

depth level（深度档位）:
```
5
```
|
```
10
```
|
```
20
```
|
```
50
```
|
```
100
```
（默认20）
kline interval（K线周期）:
```
1min
```
|
```
3min
```
|
```
5min
```
|
```
15min
```
|
```
30min
```
|
```
1h
```
|
```
2h
```
|
```
4h
```
|
```
6h
```
|
```
8h
```
|
```
12h
```
|
```
1d
```
|
```
3d
```
|
```
1w
```
|
```
1M
```

注意：现货K线周期使用
min
后缀（例如
1min
），和合约使用
m
（例如
1m
）的规则不同。

Parameter Validation Rules

参数校验规则

symbol: Must match
```
^[A-Z0-9]+-[A-Z]+$
```
; max 20 characters (e.g.,
```
BTC-USDT
```
)
level: Must be one of
```
5
```
,
```
10
```
,
```
20
```
,
```
50
```
,
```
100
```
interval (kline): Must exactly match one of the kline enum values above

symbol: 必须匹配正则
```
^[A-Z0-9]+-[A-Z]+$
```
，最长20个字符（例如
```
BTC-USDT
```
）
level: 必须是
```
5
```
、
```
10
```
、
```
20
```
、
```
50
```
、
```
100
```
中的一个
interval（K线周期）: 必须严格匹配上方列出的K线枚举值之一

Quick Start

快速开始

WebSocket Connection: see

references/websocket.md

for connection basics, GZIP decompression, and Ping/Pong heartbeat.

TypeScript helper:

CONSTRAINT: You MUST copy the
connectSpotWsMarket
function below verbatim when generating code. Do NOT rewrite the WebSocket or decompression logic. Only modify: (1) subscription channels passed to the function.

typescript

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;
}

WebSocket连接： 连接基础逻辑、GZIP解压和Ping/Pong心跳机制请参考

references/websocket.md

。

TypeScript辅助工具：

约束： 生成代码时你必须逐字复制下方的
connectSpotWsMarket
函数，请勿重写WebSocket或解压逻辑，仅可修改：(1) 传入函数的订阅通道。

typescript

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;
}

Code Usage Rules

代码使用规则

MUST copy
```
connectSpotWsMarket
```
and
```
decompress
```
verbatim -- do not simplify or rewrite
MUST set
```
ws.binaryType = "arraybuffer"
```
for GZIP decompression
MUST handle Ping/Pong heartbeat (spot uses lowercase
```
ping
```
detection)
MUST NOT remove GZIP decompression logic
MUST NOT use text-mode WebSocket messages

必须逐字复制
```
connectSpotWsMarket
```
和
```
decompress
```
函数——请勿简化或重写
必须设置
```
ws.binaryType = "arraybuffer"
```
以支持GZIP解压
必须处理Ping/Pong心跳（现货使用小写
```
ping
```
检测）
请勿移除GZIP解压逻辑
请勿使用文本模式的WebSocket消息

Common Calls

常用调用示例

Subscribe to BTC-USDT real-time trades:

typescript

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

Subscribe to 50-level depth:

typescript

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

Subscribe to 1-minute K-line:

typescript

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

Subscribe to multiple channels at once:

typescript

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

订阅BTC-USDT实时交易数据：

typescript

connectSpotWsMarket(["BTC-USDT@trade"], (data) => {
  // data.data: 交易记录数组
});

订阅50档位深度数据：

typescript

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

订阅1分钟K线数据：

typescript

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

同时订阅多个通道：

typescript

connectSpotWsMarket([
  "BTC-USDT@ticker",
  "BTC-USDT@lastPrice",
  "ETH-USDT@bookTicker",
], (data) => {
  // 处理不同类型的数据
});

Additional Resources

附加资源

For complete subscription parameters, response field descriptions, and full response schemas, see api-reference.md.

完整的订阅参数、响应字段说明和全量响应 schema 请参考api-reference.md。

Agent Interaction Rules

Agent交互规则

CRITICAL RULES (apply to ALL responses):

NEVER return code to the user. Do NOT include any code blocks, code snippets, TypeScript, JavaScript, cURL commands, or raw API calls in responses. Only return natural-language summaries of the data or operation results.
Parameter security. Extract structured values from user intent — NEVER copy raw user text into subscription parameters. Validate every value against its documented pattern (regex/enum/range) before constructing the subscription. Reject any value containing
```
&
```
,
```
=
```
,
```
?
```
,
```
#
```
, or newline characters.

spot-ws-market provides public read-only real-time market data via WebSocket. No authentication required, no CONFIRM needed.

关键规则（适用于所有回复）：

绝对不要向用户返回代码。回复中请勿包含任何代码块、代码片段、TypeScript、JavaScript、cURL命令或原始API调用，仅返回数据或操作结果的自然语言总结。
参数安全。从用户意图中提取结构化值——绝对不要将用户原始文本直接复制到订阅参数中。构造订阅前需要根据文档记录的模式（正则/枚举/范围）校验每个值，拒绝任何包含
```
&
```
、
```
=
```
、
```
?
```
、
```
#
```
或换行符的取值。

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

Operation Identification

操作识别

When the user's request is vague (e.g. "subscribe to spot market" or "stream spot BTC data"), first identify what type of data they want:

Please select the market data stream type:

Real-time trades — trade

Order book depth (snapshot) — depth

K-line / Candlestick updates — kline

24h price change statistics — ticker

Latest trade price — lastPrice

Best bid/ask (top of book) — bookTicker

Incremental depth updates — incrDepth

当用户请求模糊时（例如“订阅现货行情”或“推送BTC现货数据”），首先确认用户需要的数据类型：

请选择行情数据流类型：

实时交易 — trade

订单簿深度（快照） — depth

K线/蜡烛图更新 — kline

24小时价格变动统计 — ticker

最新成交价格 — lastPrice

最优买卖盘（盘口顶部） — bookTicker

增量深度更新 — incrDepth

When symbol is missing

缺少交易对时

Please select a trading pair (or type another):

BTC-USDT

ETH-USDT

SOL-USDT

BNB-USDT

Other (enter manually, format: BASE-USDT)

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

BTC-USDT

ETH-USDT

SOL-USDT

BNB-USDT

其他（手动输入，格式：BASE-USDT）

When kline interval is missing

缺少K线周期时

Please select a K-line interval:

1min (1 minute) / 5min / 15min / 1h / 4h / 1d / 1w

请选择K线周期：

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

Depth level handling

深度档位处理

Default level is 20. Only ask if user wants a specific level.

默认档位为20，仅当用户需要特定档位时才询问。