bingx-swap-market

BingX 合约市场数据

BingX 永续合约的公开市场数据。无需 API 密钥或 HMAC 签名。只有交易规则和历史成交需要当前的 timestamp；不要在每个请求中都添加它。私有交易和账户端点仍需身份验证。

快速参考

端点	方法	描述	必填	可选
/openApi/swap/v2/quote/contracts	GET	所有合约规格	无	symbol
/openApi/swap/v1/tradingRules	GET	交易规则和规格	timestamp，symbol	recvWindow
/openApi/swap/v2/quote/depth	GET	订单簿买单和卖单	symbol	limit，timestamp，recvWindow
/openApi/swap/v2/quote/trades	GET	近期公开成交	symbol	limit，timestamp，recvWindow
/openApi/swap/v1/market/historicalTrades	GET	查询历史成交	timestamp	symbol，limit，fromId，recvWindow
/openApi/swap/v2/quote/premiumIndex	GET	标记价格和溢价指数	无	symbol，timestamp，recvWindow
/openApi/swap/v2/quote/fundingRate	GET	当前和下一次资金费率	无	symbol，startTime，endTime，limit，timestamp，recvWindow
/openApi/swap/v3/quote/klines	GET	OHLCV K 线数据	symbol，interval	startTime，endTime，limit，timestamp，recvWindow
/openApi/swap/v1/market/markPriceKlines	GET	标记价格 K 线数据	symbol，interval	startTime，endTime，limit，timestamp，recvWindow
/openApi/swap/v2/quote/openInterest	GET	总未平仓量	symbol	timestamp，recvWindow
/openApi/swap/v2/quote/ticker	GET	24 小时价格变动统计	无	symbol，timestamp，recvWindow
/openApi/swap/v1/ticker/price	GET	最新价格行情	无	symbol，timestamp，recvWindow
/openApi/swap/v2/quote/bookTicker	GET	最优买卖价格和数量	symbol	timestamp，recvWindow
/openApi/swap/v2/server/time	GET	查询服务器时间	无	无

---

参数

通用参数

• timestamp：当前 Unix 时间，单位为毫秒。仅交易规则和历史成交必填；仅在上表列出的情况下可选。辅助函数会为这两个必填端点动态生成该值。
• symbol：交易对，格式为 BASE-QUOTE（例如 BTC-USDT、ETH-USDT、SOL-USDT）
• limit：返回结果数量。默认值和最大值因端点而异。
• startTime：起始时间戳，单位为毫秒（例如 1735693200000）
• endTime：结束时间戳，单位为毫秒（例如 1735693200000）
• interval：K 线间隔（参见下方枚举）
• recvWindow：请求有效时间窗口，单位为毫秒（可选，默认值为 5000，最大值为 60000）

枚举

• interval：1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M

参数验证规则

• symbol：必须符合 ^[A-Z0-9]+-[A-Z]+$；最多 20 个字符（例如 BTC-USDT）
• limit：正整数；默认值和最大值因端点而异（通常为 500–1000）
• startTime / endTime：Unix 时间戳，单位为毫秒；endTime 必须 ≥ startTime
• interval：必须与上述枚举值之一完全一致
• recvWindow：整数，1–5000 ms（参见重放保护）
• timestamp：Unix 时间，单位为毫秒；必须在服务器时间的 recvWindow 范围内

---

快速开始

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

TypeScript 辅助函数：

约束：生成代码时，必须原样复制下面的 fetchSwapMarket 函数。 不要重写请求或 JSON 解析逻辑。仅可修改：(1) 自定义环境的 BASE URL 条目；(2) 传递给 fetchSwapMarket 的业务参数。此辅助函数仅适用于 公开 GET 市场端点，不适用于私有交易或账户 API。

import JSONBig from "json-bigint";
const JSONBigParse = JSONBig({ storeAsString: true });
// Domain priority: .com is mandatory primary; .pro is fallback for network/timeout errors ONLY.
const BASE = {
  "prod-live": ["https://open-api.bingx.com", "https://open-api.bingx.pro"],
  "prod-vst":  ["https://open-api-vst.bingx.com", "https://open-api-vst.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;
}
function validateParams(params: Record<string, unknown>): void {
  const FORBIDDEN = /[&=?#\r\n]/;
  for (const [k, v] of Object.entries(params)) {
    const s = String(v);
    if (FORBIDDEN.test(s)) throw new Error(`Param "${k}" has forbidden char in: "${s}"`);
  }
}
async function fetchSwapMarket(env: string,
  path: string, params: Record<string, string | number> = {}
) {
  const urls = BASE[env] ?? BASE["prod-live"];
  const requiresTimestamp = path === "/openApi/swap/v1/tradingRules"
    || path === "/openApi/swap/v1/market/historicalTrades";
  const all = requiresTimestamp ? { ...params, timestamp: Date.now() } : { ...params };
  validateParams(all);
  const qs = new URLSearchParams(
    Object.entries(all).map(([k, v]) => [k, String(v)])
  ).toString();
  for (const base of urls) {
    try {
      const url = `${base}${path}${qs ? `?${qs}` : ""}`;
      const res = await fetch(url, {
        method: "GET",
        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 === urls[urls.length - 1]) throw e;
    }
  }
}

代码使用规则

• MUST 原样复制 fetchSwapMarket ——不得简化或改写
• MUST 使用 json-bigint（JSONBigParse.parse）解析响应——不得使用 JSON.parse
• MUST 在每个请求中包含 X-SOURCE-KEY: BX-AI-SKILL 请求头
• MUST NOT 移除域名回退循环或 isNetworkOrTimeout 检查

常见调用

BTC-USDT 的 24 小时行情价格：

const ticker = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/ticker", { symbol: "BTC-USDT" }
);
// ticker.lastPrice, ticker.priceChangePercent, ticker.volume

订单簿深度（前 20 档）：

const depth = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/depth", { symbol: "BTC-USDT", limit: 20 }
);
// depth.bids: [price, qty][], depth.asks: [price, qty][]

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

const klines = await fetchSwapMarket("prod-live",
  "/openApi/swap/v3/quote/klines", { symbol: "BTC-USDT", interval: "1h", limit: 100 }
);
// Each item: [openTime, open, high, low, close, volume, closeTime]

当前资金费率：

const funding = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/fundingRate", { symbol: "BTC-USDT" }
);
// funding.fundingRate, funding.nextFundingTime

最优买入／卖出价格：

const bookTicker = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/bookTicker", { symbol: "BTC-USDT" }
);
// bookTicker.bidPrice, bookTicker.askPrice

交易规则和历史成交（时间戳由助手生成）：

const rules = await fetchSwapMarket("prod-live",
  "/openApi/swap/v1/tradingRules", { symbol: "BTC-USDT" }
);
const historicalTrades = await fetchSwapMarket("prod-live",
  "/openApi/swap/v1/market/historicalTrades", { symbol: "BTC-USDT", limit: 10 }
);

更多资源

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

---

Agent 交互规则

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

swap-market 提供公开的只读市场数据。不要请求 API 密钥，也不要对这些请求签名。交易规则和历史成交仍需要动态 timestamp。无需 CONFIRM。 交互目标是收集查询参数。

操作识别

当用户的请求含糊不清时（例如“查看市场”或“看看 BTC”），首先确定他们想查询的数据类型：

请选择市场数据类型：

• 价格／24 小时涨跌 — ticker
• 最优买入／卖出价格（盘口顶部）— bookTicker
• 订单簿深度 — depth
• K 线／蜡烛图 — klines
• 资金费率 — fundingRate
• 标记价格／溢价指数 — premiumIndex
• 未平仓合约量 — openInterest
• 合约规格列表 — contracts

缺少交易对时

适用的端点：depth、trades、fundingRate、klines、openInterest

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

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

如果可以根据上下文推断交易对（例如“今天的 BTC 市场”或“Ethereum 资金费率”），则自动推断，无需再次询问。

klines 端点缺少时间间隔时

请选择 K 线时间间隔：

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

limit 处理

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

symbol 为可选参数的端点

ticker 和 premiumIndex 的 symbol 为可选参数（省略时返回所有合约）。bookTicker 则需要 symbol。如果用户未为 ticker／premiumIndex 指定交易对，则查询所有合约并告知用户；如果指定了交易对，则只查询该交易对。