bingx-spot-market

BingX 现货市场数据

BingX 现货交易的公开市场数据。无需身份验证。

快速参考

端点	方法	描述	必填	可选	身份验证
/openApi/spot/v1/common/symbols	GET	现货交易交易对规格	无	symbol	否
/openApi/spot/v1/market/depth	GET	订单簿买单和卖单	symbol	limit	否
/openApi/spot/v2/market/depth	GET	聚合订单簿（含精度）	symbol, depth, type	无	否
/openApi/spot/v1/market/trades	GET	最新公开交易	symbol	limit	否
/openApi/spot/v2/market/kline	GET	OHLCV 蜡烛图数据	symbol, interval	startTime, endTime, limit	否
/openApi/spot/v1/ticker/24hr	GET	24 小时价格变动统计	无	symbol	否
/openApi/spot/v2/ticker/price	GET	最新价格行情	symbol	无	否
/openApi/spot/v1/ticker/bookTicker	GET	最优买价/卖价及数量	symbol	无	否
/openApi/market/his/v1/kline	GET	历史 K 线数据	symbol, interval	startTime, endTime, limit	否
/openApi/market/his/v1/trade	GET	历史交易查询	symbol	limit, fromId	否

---

参数

通用参数

• symbol：采用 BASE-USDT 格式的交易对（例如：BTC-USDT、ETH-USDT、SOL-USDT）。注意：订单簿聚合端点（/openApi/spot/v2/market/depth）使用下划线格式 BTC_USDT。
• limit：要返回的结果数量。默认值和最大值因端点而异。
• startTime：以毫秒为单位的起始时间戳（例如：1735693200000）
• endTime：以毫秒为单位的结束时间戳（例如：1735779600000）
• interval：K 线/蜡烛图间隔（见下方枚举值）

枚举值

• interval：1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M
• type（订单簿聚合精度）：step0 | step1 | step2 | step3 | step4 | step5

参数验证规则

• symbol：必须匹配 ^[A-Z0-9]+-[A-Z]+$（例如：BTC-USDT）；深度端点使用 BTC_USDT（下划线）
• limit：正整数；默认值和最大值因端点而异
• startTime / endTime：Unix 毫秒时间戳；endTime 必须大于或等于 startTime
• interval：必须与上述某个枚举值完全匹配
• type：使用时必须为 step0–step5 之一

---

快速开始

**基础 URL：**参见 references/base-urls.md

TypeScript 辅助函数：

CONSTRAINT：生成代码时，必须逐字复制下面的 fetchSpotMarket 函数。 不要重写请求或 JSON 解析逻辑。 仅可修改：(1) 用于自定义环境的 BASE_URLS 条目， (2) 传递给 fetchSpotMarket 的业务参数。

import JSONBig from "json-bigint";
const JSONBigParse = JSONBig({ storeAsString: true });
// Base URLs — see references/base-urls.md for all environments
// Domain priority: .com is mandatory primary; .pro is fallback for network/timeout errors ONLY.
const BASE_URLS = ["https://open-api.bingx.com", "https://open-api.bingx.pro"];

function isNetworkOrTimeout(e: unknown): boolean {
  if (e instanceof TypeError) return true;
  if (e instanceof DOMException && e.name === "AbortError") return true;
  if (e instanceof Error && e.name === "TimeoutError") return true;
  return false;
}

async function fetchSpotMarket(
  path: string,
  params: Record<string, string | number> = {}
): Promise<unknown> {
  const query = new URLSearchParams(
    Object.entries(params).map(([k, v]) => [k, String(v)])
  ).toString();
  for (const base of BASE_URLS) {
    try {
      const url = `${base}${path}${query ? `?${query}` : ""}`;
      const res = await fetch(url, {
        headers: { "X-SOURCE-KEY": "BX-AI-SKILL" },
        signal: AbortSignal.timeout(10000),
      });
      const json = JSONBigParse.parse(await res.text());
      if (json.code !== 0) throw new Error(`BingX error ${json.code}: ${json.msg}`);
      return json.data;
    } catch (e) {
      if (!isNetworkOrTimeout(e) || base === BASE_URLS[BASE_URLS.length - 1]) throw e;
    }
  }
}

代码使用规则

• 必须逐字复制 fetchSpotMarket，不得简化或重写
• 必须使用 json-bigint（JSONBigParse.parse）解析响应，不得使用 JSON.parse
• 必须在每个请求中包含 X-SOURCE-KEY: BX-AI-SKILL 标头
• 不得移除域名回退循环或 isNetworkOrTimeout 检查

常见调用

BTC-USDT 的 24 小时行情：

const ticker = await fetchSpotMarket("/openApi/spot/v1/ticker/24hr", {
  symbol: "BTC-USDT",
});
// ticker[0].lastPrice, ticker[0].priceChangePercent, ticker[0].volume

最新价格：

const price = await fetchSpotMarket("/openApi/spot/v2/ticker/price", {
  symbol: "BTC-USDT",
});
// price[0].trades[0].price

订单簿深度（前 20 档）：

const depth = await fetchSpotMarket("/openApi/spot/v1/market/depth", {
  symbol: "BTC-USDT",
  limit: 20,
});
// depth.bids: [price, qty][], depth.asks: [price, qty][]

1 小时 K 线（最近 100 根）：

const klines = await fetchSpotMarket("/openApi/spot/v2/market/kline", {
  symbol: "BTC-USDT",
  interval: "1h",
  limit: 100,
});
// Each item: [openTime, open, high, low, close, volume, closeTime, quoteVolume]

最优买价/卖价：

const bookTicker = await fetchSpotMarket("/openApi/spot/v1/ticker/bookTicker", {
  symbol: "BTC-USDT",
});
// bookTicker[0].bidPrice, bookTicker[0].askPrice

最新交易：

const trades = await fetchSpotMarket("/openApi/spot/v1/market/trades", {
  symbol: "BTC-USDT",
  limit: 50,
});
// trades[0].price, trades[0].qty, trades[0].time

其他资源

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

---

Agent 交互规则

参数安全。 从用户意图中提取结构化值——绝不要将用户的原始文本复制到 API 参数中。调用 API 前，根据文档规定的模式（正则表达式／枚举／范围）验证每个值。拒绝任何包含 &、=、?、# 或换行符的值。

spot-market 提供公开的只读市场数据。无需身份验证，无需 CONFIRM。交互目标是收集查询参数。

操作识别

当用户的请求比较模糊（例如“查看现货市场”或“看看 BTC 价格”）时，首先确认他们想查询哪种类型的数据：

请选择市场数据类型：

• 价格／24 小时涨跌 — ticker/24hr
• 最新成交价 — ticker/price
• 最优买价／卖价（盘口顶部）— bookTicker
• 订单簿深度 — depth
• K 线／蜡烛图 — kline
• 最近成交记录 — trades
• 历史 K 线 — historical kline
• 历史成交记录 — historical trades
• 交易对规格列表 — symbols

缺少交易对时

适用的端点：depth、trades、kline、ticker/price、bookTicker、historical kline、historical trades

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

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

如果可以从上下文推断出交易对（例如“今天 BTC 的市场情况”或“以太坊价格”），则自动推断，无需再次询问。

缺少时间间隔时（仅限 kline 端点）

请选择 K 线时间间隔：

• 1m（1 分钟）
• 5m（5 分钟）
• 15m（15 分钟）
• 1h（1 小时）
• 4h（4 小时）
• 1d（每日）
• 1w（每周）

limit 处理

• kline：默认值为 100，无需询问——告知用户“默认返回最近的 100 根 K 线”
• depth：默认值为 20，无需询问
• trades：默认值为 100，无需询问

交易对为可选参数的端点

ticker/24hr 的交易对为可选参数（省略时返回所有交易对）。bookTicker 和 price ticker 必须指定交易对。如果用户未为 ticker/24hr 指定交易对，则查询所有交易对并告知用户；如果指定了交易对，则只查询该交易对。