bingx-spot-trade

BingX 现货交易

BingX 现货市场的身份验证交易端点。所有端点均需要 HMAC SHA256 签名身份验证。

**基础 URL：**参见 references/base-urls.md | **身份验证：**参见 references/authentication.md

---

快速参考

端点	方法	描述	身份验证
/openApi/spot/v1/trade/order	POST	下单	是
/openApi/spot/v1/trade/batchOrders	POST	批量下单（最多 5 个）	是
/openApi/spot/v1/trade/cancel	POST	撤销订单	是
/openApi/spot/v1/trade/cancelOrders	POST	批量撤销订单	是
/openApi/spot/v1/trade/cancelOpenOrders	POST	撤销某交易对的所有未成交订单	是
/openApi/spot/v1/trade/cancelAllAfter	POST	自动撤单倒计时（紧急停止开关）	是
/openApi/spot/v1/trade/order/cancelReplace	POST	撤销并替换订单	是
/openApi/spot/v1/trade/query	GET	查询订单详情	是
/openApi/spot/v1/trade/openOrders	GET	查询当前未成交订单	是
/openApi/spot/v1/trade/historyOrders	GET	查询订单历史记录	是
/openApi/spot/v1/trade/myTrades	GET	查询交易详情（成交记录）	是
/openApi/spot/v1/user/commissionRate	GET	查询交易手续费率	是
/openApi/spot/v1/oco/order	POST	创建 OCO 订单	是
/openApi/spot/v1/oco/cancel	POST	撤销 OCO 订单	是
/openApi/spot/v1/oco/orderList	GET	查询 OCO 订单列表	是
/openApi/spot/v1/oco/openOrderList	GET	查询所有未成交 OCO 订单	是
/openApi/spot/v1/oco/historyOrderList	GET	查询 OCO 历史订单列表	是

---

参数

订单参数

• symbol：采用 BASE-QUOTE 格式的交易对（例如，BTC-USDT、ETH-USDT）
• side：订单方向——BUY 或 SELL
• type：订单类型（参见枚举值）
• quantity：以基础资产计价的订单数量（例如，BTC-USDT 的数量为 0.1 BTC）
• quoteOrderQty：以计价资产计价的订单金额（例如，100 USDT）；如果两者都提供，则优先使用 quantity
• price：限价（LIMIT、TAKE_STOP_LIMIT、TRIGGER_LIMIT 必填）
• stopPrice：触发价（TAKE_STOP_LIMIT、TAKE_STOP_MARKET、TRIGGER_LIMIT、TRIGGER_MARKET 必填）
• timeInForce：GTC | IOC | FOK | PostOnly——默认为 GTC；LIMIT 类型必填
• newClientOrderId：自定义订单 ID，1–40 个字符
• recvWindow：请求有效期窗口，单位为毫秒（最大值为 60000）
• orderId：系统订单 ID（用于撤销或查询）
• clientOrderID：自定义订单 ID（用于撤销或查询）

枚举值

type（订单类型）：

• MARKET — 市价单（按当前可用的最优价格立即成交）
• LIMIT — 限价单（需要 price 和 timeInForce）
• TAKE_STOP_LIMIT — 止盈/止损限价单（需要 stopPrice 和 price）
• TAKE_STOP_MARKET — 止盈/止损市价单（需要 stopPrice）
• TRIGGER_LIMIT — 触发限价单（需要 stopPrice 和 price）
• TRIGGER_MARKET — 触发市价单（需要 stopPrice）

side：BUY | SELL

timeInForce：GTC | IOC | FOK | PostOnly

cancelReplaceMode：

• STOP_ON_FAILURE — 如果撤单步骤失败，则中止
• ALLOW_FAILURE — 即使撤单失败，也下达新订单

cancelRestrictions（按订单状态限制撤单）：

• NEW | PENDING | PARTIALLY_FILLED

参数验证规则

发送请求前，请在客户端验证参数，避免不必要的 API 错误：

• symbol：必须匹配 ^[A-Z0-9]+-[A-Z]+$；最多 20 个字符（例如，BTC-USDT）
• quantity：必须为正数（> 0）；精度取决于该交易对的手数过滤器
• quoteOrderQty：提供时必须为正数（> 0）；表示计价资产的金额
• price：提供时必须为正数（> 0）
• stopPrice：提供时必须为正数（> 0）
• newClientOrderId：1–40 个字符；避免使用可能被视为注入内容的特殊字符
• recvWindow：整数，1–5000 ms；尽量保持较小（参见重放保护）
• timestamp：以毫秒为单位的 Unix 时间；必须在服务器时间的 recvWindow 范围内

---

快速开始

约束：生成代码时，必须原样复制下面的 fetchSigned 函数。 不得重写签名、请求或 JSON 解析逻辑。只能修改：(1) 自定义环境的 BASE URL 条目；(2) 传递给 fetchSigned 的业务参数。有关支持 URL 编码和 JSON 请求体的完整客户端，请参见 references/authentication.md。

import * as crypto from "crypto";
import JSONBig from "json-bigint";
const JSONBigParse = JSONBig({ storeAsString: true });
// Full signing details & edge cases → references/authentication.md
// 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 fetchSigned(env: string, apiKey: string, secretKey: string,
  method: "GET" | "POST" | "DELETE", path: string, params: Record<string, unknown> = {}
) {
  const urls = BASE[env] ?? BASE["prod-live"];
  const all = { ...params, timestamp: Date.now() };
  validateParams(all);
  const qs = Object.keys(all).sort().map(k => `${k}=${all[k]}`).join("&");
  const sig = crypto.createHmac("sha256", secretKey).update(qs).digest("hex");
  const signed = `${qs}&signature=${sig}`;
  for (const base of urls) {
    try {
      const url = method === "POST" ? `${base}${path}` : `${base}${path}?${signed}`;
      const res = await fetch(url, {
        method,
        headers: { "X-BX-APIKEY": apiKey, "X-SOURCE-KEY": "BX-AI-SKILL",
          ...(method === "POST" ? { "Content-Type": "application/x-www-form-urlencoded" } : {}) },
        body: method === "POST" ? signed : undefined,
        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;
    }
  }
}

代码使用规则

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

---

常见调用

下达市价买单（花费 100 USDT）：

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/spot/v1/trade/order", {
    symbol: "BTC-USDT",
    side: "BUY",
    type: "MARKET",
    quoteOrderQty: 100,
  }
);
// order.orderId, order.status, order.executedQty, order.cummulativeQuoteQty

下达限价卖单：

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/spot/v1/trade/order", {
    symbol: "BTC-USDT",
    side: "SELL",
    type: "LIMIT",
    quantity: 0.001,
    price: 100000,
    timeInForce: "GTC",
  }
);

取消订单：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/spot/v1/trade/cancel", {
    symbol: "BTC-USDT",
    orderId: 123456789,
  }
);

查询未完成订单：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/trade/openOrders", {
    symbol: "BTC-USDT",
  }
);
// data.orders[].orderId, data.orders[].price, data.orders[].status

查询订单历史：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/trade/historyOrders", {
    symbol: "BTC-USDT",
    pageIndex: 1,
    pageSize: 20,
  }
);

查询订单的成交记录：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/trade/myTrades", {
    symbol: "BTC-USDT",
    orderId: 123456789,
  }
);
// data.fills[].price, data.fills[].qty, data.fills[].commission

查询手续费率：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/user/commissionRate", {
    symbol: "BTC-USDT",
  }
);
// data.takerCommissionRate, data.makerCommissionRate

更多资源

有关完整的参数说明、响应架构和全部 17 个端点，请参见 api-reference.md。

---

Agent 交互规则

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

所有写入操作（下单、取消订单、创建／取消 OCO）在 prod-live 环境中都需要确认。只读查询则不需要。

• prod-live：在下单或取消任何订单前，请用户输入 CONFIRM。
• prod-vst：无需确认。告知用户：“您正在 Production Simulated (VST) 环境中操作。”

步骤 1 — 确定操作

如果用户意图不明确，请提供以下选项：

您想进行什么操作？

• 下达新订单
• 取消订单／取消所有订单
• 查看未完成订单
• 查看订单历史
• 查看成交记录（交易详情）
• 查看交易手续费率
• OCO 订单（创建／取消／查询）

步骤 2 — 收集交易对（如果用户未提供）

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

• BTC-USDT
• ETH-USDT
• SOL-USDT
• BNB-USDT
• 其他（格式：BASE-USDT）

步骤 3 — 收集方向（下单时）

订单方向：

• BUY
• SELL

步骤 4 — 收集订单类型

订单类型：

• MARKET — 按最优价格立即成交
• LIMIT — 按指定价格成交（需要 price 和 timeInForce）
• TAKE_STOP_LIMIT — 止盈／止损限价单（需要 stopPrice + price）
• TAKE_STOP_MARKET — 止盈／止损市价单（需要 stopPrice）
• TRIGGER_LIMIT — 触发限价单（需要 stopPrice + price）
• TRIGGER_MARKET — 触发市价单（需要 stopPrice）

步骤 5 — 收集数量和价格

• 市价买入：询问 quoteOrderQty（要花费的 USDT）或 quantity（基础资产数量）
• 市价卖出：询问 quantity（要卖出的基础资产数量）
• 限价单：询问 quantity 和 price；确认 timeInForce（默认为 GTC）
• 止损限价单 / 触发限价单：询问 quantity、stopPrice（触发价）和 price（执行价）
• 止损市价单 / 触发市价单：询问 quantity 和 stopPrice

步骤 6 — 确认（仅限 prod-live）

对于 prod-live，提供摘要并询问：

你即将在 Production Live 上下达以下订单：

• 交易对：BTC-USDT
• 方向：BUY
• 类型：MARKET
• 金额：100 USDT

输入 CONFIRM 以继续，或输入其他内容取消。

步骤 7 — 执行并报告

执行 API 调用，并向用户返回订单 ID、状态和成交数量。

---

取消订单流程

1. 如果尚未提供，请询问 symbol 和 orderId（或 clientOrderID）。
2. 对于 prod-live：要求输入 CONFIRM。
3. 执行 POST /openApi/spot/v1/trade/cancel。

取消所有未结订单流程

1. 询问 symbol（可选 — 省略则取消所有交易对的订单）。
2. 对于 prod-live：要求输入 CONFIRM。
3. 执行 POST /openApi/spot/v1/trade/cancelOpenOrders。

OCO 订单流程

OCO（一个取消另一个）将限价单与止损限价单配对；其中一个成交或触发时，另一个会自动取消。

1. 询问 symbol、side、quantity。
2. 询问 limitPrice（限价单执行价格）。
3. 询问 triggerPrice（止损限价单触发价格）。
4. 询问 orderPrice（触发后止损限价单的执行价格）。
5. 对于 prod-live：要求输入 CONFIRM。
6. 执行 POST /openApi/spot/v1/oco/order。