bingx-coinm-market

BingX Coin-M（CSwap）市场数据

BingX Coin-M 反向永续合约的公开市场数据。无需 API 密钥或 HMAC 签名。只有合约信息需要当前的 timestamp；其他端点的 timestamp 均为可选参数。

Coin-M 合约以币本位计价（以基础资产结算，例如 BTC）。交易对格式为 BASE-USD（例如 BTC-USD、ETH-USD）。

快速参考

端点	方法	描述	必填	可选	身份验证
/openApi/cswap/v1/market/contracts	GET	合约规格	timestamp	symbol, recvWindow	否
/openApi/cswap/v1/market/depth	GET	订单簿买单与卖单	symbol	无	否
/openApi/cswap/v1/market/klines	GET	OHLCV K 线数据	symbol, interval	startTime, endTime, limit	否
/openApi/cswap/v1/market/premiumIndex	GET	标记价格与当前资金费率	无	symbol	否
/openApi/cswap/v1/market/openInterest	GET	总未平仓量	symbol	无	否
/openApi/cswap/v1/market/ticker	GET	24 小时价格变动统计	无	symbol	否

---

参数

通用参数

• timestamp：当前 Unix 时间戳，单位为毫秒。查询合约信息时必填，由辅助函数动态生成；其他端点中为可选参数。recvWindow 为可选参数。
• symbol：采用 BASE-USD 格式的交易对（例如 BTC-USD、ETH-USD）。注意：Coin-M 使用 USD，而非 USDT。
• limit：要返回的结果数量。默认值和最大值因端点而异。
• startTime：起始时间戳，单位为毫秒（例如 1735693200000）
• endTime：结束时间戳，单位为毫秒（例如 1735693200000）
• interval：K 线间隔（见下方枚举值）

枚举值

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

参数校验规则

• symbol：必须符合 ^[A-Z0-9]+-USD$；最多 20 个字符（例如 BTC-USD）。Coin-M 使用 USD，而非 USDT。
• limit：正整数；默认值和最大值因端点而异。
• startTime / endTime：以毫秒为单位的 Unix 时间戳；endTime 必须大于或等于 startTime。
• interval：必须与上述某个枚举值完全一致。

---

快速开始

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

TypeScript 辅助函数：

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

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 coinmMarket(
  path: string,
  params: Record<string, string | number> = {}
): Promise<unknown> {
  const all = path === "/openApi/cswap/v1/market/contracts"
    ? { ...params, timestamp: Date.now() } : { ...params };
  const query = new URLSearchParams(
    Object.entries(all).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;
    }
  }
}

代码使用规则

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

常用调用

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

const ticker = await coinmMarket("/openApi/cswap/v1/market/ticker", {
  symbol: "BTC-USD",
});
// ticker.lastPrice, ticker.priceChangePercent, ticker.volume

BTC-USD 的订单簿深度：

const depth = await coinmMarket("/openApi/cswap/v1/market/depth", {
  symbol: "BTC-USD",
});
// depth.bids: [price, qty][], depth.asks: [price, qty][]

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

const klines = await coinmMarket("/openApi/cswap/v1/market/klines", {
  symbol: "BTC-USD",
  interval: "1h",
  limit: 100,
});
// Each item: [openTime, open, high, low, close, volume, closeTime]

标记价格与当前资金费率：

const premium = await coinmMarket("/openApi/cswap/v1/market/premiumIndex", {
  symbol: "BTC-USD",
});
// premium.markPrice, premium.lastFundingRate, premium.nextFundingTime

未平仓量：

const oi = await coinmMarket("/openApi/cswap/v1/market/openInterest", {
  symbol: "BTC-USD",
});
// oi.openInterest, oi.symbol, oi.time

所有合约规格：

const contracts = await coinmMarket("/openApi/cswap/v1/market/contracts");
// Array of contract objects: symbol, pricePrecision, minTickSize, minTradeValue, status

其他资源

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

---

Agent 交互规则

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

cswap-market 提供公开的只读市场数据。无需 API 密钥或 HMAC 签名；只有合约信息需要动态 timestamp。无需 CONFIRM。 交互目标是收集查询参数。

注意：Coin-M 合约交易对格式为 BASE-USD（例如 BTC-USD），而不是 BASE-USDT。

操作识别

当用户的请求含糊不清时（例如“查看 Coin-M 市场”或“看看 BTC 反向合约”），先确认他们想查询哪种数据：

请选择市场数据类型：

• 价格／24 小时涨跌 — ticker
• 订单簿深度 — depth
• K 线／蜡烛图 — klines
• 标记价格／资金费率 — premiumIndex
• 未平仓量 — openInterest
• 合约规格列表 — contracts

缺少 symbol 时

适用端点：depth、klines、openInterest

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

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

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

仅 klines 端点缺少 interval 时

请选择 K 线间隔：

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

limit 处理

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

symbol 可选的端点

ticker 和 premiumIndex 的 symbol 为可选参数。如果用户未指定，则查询所有合约并告知用户；如果指定了交易对，则只查询该交易对。