bingx-swap-trade

BingX Swap Trade

BingX 永续期货的身份验证交易端点。所有端点均需要 HMAC SHA256 签名身份验证。

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

---

快速参考

端点	方法	描述	身份验证
/openApi/swap/v2/trade/order	POST	下新订单	是
/openApi/swap/v2/trade/order/test	POST	测试下单（不成交）	是
/openApi/swap/v2/trade/batchOrders	POST	下多个订单（批量，最多 5 个）	是
/openApi/swap/v2/trade/order	DELETE	取消订单	是
/openApi/swap/v2/trade/batchOrders	DELETE	取消多个订单	是
/openApi/swap/v2/trade/allOpenOrders	DELETE	取消所有未结订单	是
/openApi/swap/v2/trade/cancelAllAfter	POST	自动取消倒计时（紧急停止开关）	是
/openApi/swap/v2/trade/closeAllPositions	POST	平掉所有仓位	是
/openApi/swap/v1/trade/closePosition	POST	按 positionId 平仓	是
/openApi/swap/v2/trade/positionMargin	POST	调整逐仓保证金金额	是
/openApi/swap/v1/positionMargin/history	GET	查询保证金调整历史记录	是
/openApi/swap/v2/trade/openOrders	GET	查询未结订单	是
/openApi/swap/v2/trade/openOrder	GET	查询单个未结订单	是
/openApi/swap/v2/trade/order	GET	按 ID 查询订单	是
/openApi/swap/v1/trade/fullOrder	GET	查询完整订单详情	是
/openApi/swap/v2/trade/allOrders	GET	查询所有历史订单	是
/openApi/swap/v2/trade/forceOrders	GET	查询强平/ADL 订单	是
/openApi/swap/v2/trade/allFillOrders	GET	查询成交历史记录	是
/openApi/swap/v2/trade/fillHistory	GET	查询历史成交详情	是
/openApi/swap/v1/twap/openOrders	GET	查询未结 TWAP 订单	是
/openApi/swap/v1/twap/historyOrders	GET	查询 TWAP 订单历史记录	是
/openApi/swap/v1/twap/orderDetail	GET	查询 TWAP 订单详情	是
/openApi/swap/v1/twap/order	POST	创建 TWAP 订单	是
/openApi/swap/v1/twap/cancelOrder	POST	取消 TWAP 订单	是
/openApi/swap/v1/trade/positionHistory	GET	查询仓位历史记录	是
/openApi/swap/v1/maintMarginRatio	GET	查询维持保证金率	是
/openApi/swap/v2/trade/marginType	GET	查询保证金类型	是
/openApi/swap/v2/trade/marginType	POST	设置保证金类型（ISOLATED/CROSSED）	是
/openApi/swap/v2/trade/leverage	GET	查询当前杠杆	是
/openApi/swap/v2/trade/leverage	POST	设置杠杆	是
/openApi/swap/v1/positionSide/dual	GET	查询持仓模式	是
/openApi/swap/v1/positionSide/dual	POST	设置持仓模式	是
/openApi/swap/v1/trade/assetMode	GET	查询资产模式（单资产/多资产）	是
/openApi/swap/v1/trade/assetMode	POST	设置资产模式（单资产/多资产）	是
/openApi/swap/v1/trade/multiAssetsRules	GET	查询多资产保证金规则	是
/openApi/swap/v1/user/marginAssets	GET	查询多资产模式的保证金资产	是
/openApi/swap/v1/trade/autoAddMargin	POST	设置仓位自动追加保证金	是
/openApi/swap/v1/trade/reverse	POST	反转仓位（一键翻转）	是
/openApi/swap/v1/trade/cancelReplace	POST	取消并替换订单（原子操作）	是
/openApi/swap/v1/trade/batchCancelReplace	POST	批量取消并替换订单	是
/openApi/swap/v1/trade/amend	POST	修改现有未结订单	是
/openApi/swap/v2/trade/getVst	POST	获取 VST（虚拟模拟交易）	是

---

参数

订单参数

• symbol：采用 BASE-QUOTE 格式的交易对（例如，BTC-USDT、ETH-USDT）
• side：订单方向——BUY 或 SELL
• positionSide：持仓方向——LONG 或 SHORT（对冲模式）／BOTH（单向模式）
• type：订单类型（参见枚举值）
• quantity：订单数量，单位为币（例如，BTC-USDT 的 0.01）；当 closePosition: true 时，STOP_MARKET 和 TAKE_PROFIT_MARKET 仍必须提供此参数
• price：限价（LIMIT、STOP、TAKE_PROFIT 类型必填）
• stopPrice：触发价格（STOP_MARKET、STOP、TAKE_PROFIT_MARKET、TAKE_PROFIT 类型必填）
• timeInForce：GTC | IOC | FOK | PostOnly——默认值为 GTC；LIMIT 类型必填
• clientOrderId：自定义订单 ID，长度为 1–40 个字符（会转换为小写）
• recvWindow：请求有效期窗口，单位为毫秒（最大值为 60000）
• orderId：系统订单 ID（用于撤销／查询操作）
• workingType：用于触发条件订单的价格来源——MARK_PRICE（标记价格）或 CONTRACT_PRICE（最新成交价，默认值）
• stopGuaranteed：true | false——是否保证止损执行；保证止损可能会产生额外费用
• closePosition：true | false——触发时平掉全部持仓数量。仅支持 STOP_MARKET 和 TAKE_PROFIT_MARKET；仍必须提供 quantity 和 stopPrice。不要与 reduceOnly 一起使用。
• reduceOnly：true | false——订单只能减少（不能增加）持仓规模。对冲模式下不要发送此参数。
• activationPrice：TRAILING_STOP_MARKET 订单的激活价格（可选；省略时默认为当前市场价格）
• priceRate：TRAILING_STOP_MARKET / TRAILING_TP_SL 订单的回调率（例如，0.05 = 5%）
• stopLoss：JSON 字符串查询参数——为 MARKET / LIMIT 订单附加止损。先构建并验证嵌套对象，然后恰好调用一次 JSON.stringify。
• takeProfit：JSON 字符串查询参数——为 MARKET / LIMIT 订单附加止盈。先构建并验证嵌套对象，然后恰好调用一次 JSON.stringify。

持仓参数

• leverage：整数杠杆倍数（例如，10、20、50）
• marginType：ISOLATED 或 CROSSED
• dualSidePosition："true"（对冲模式）或 "false"（单向模式）
• positionId：持仓 ID 字符串。常规对冲模式订单无需提供；在独立逐仓模式下平仓时，以及明确指定持仓的端点调用时必填。
• amount：USDT 保证金调整金额（用于 positionMargin 端点）
• direction_type：1（增加保证金）或 2（减少保证金）（用于 positionMargin 端点）

枚举值

type（订单类型）：

• MARKET — 市价单（以最佳价格立即成交；可在此附加 stopLoss / takeProfit 对象）
• LIMIT — 限价单（需要 price 和 timeInForce；可在此附加 stopLoss / takeProfit 对象）
• STOP_MARKET — 市价止损单（在 stopPrice 触发，以市价执行）
• STOP — 限价止损单（在 stopPrice 触发，以 price 限价执行）
• TAKE_PROFIT_MARKET — 市价止盈单（在 stopPrice 触发，以市价执行）
• TAKE_PROFIT — 限价止盈单（在 stopPrice 触发，以 price 限价执行）
• TRAILING_STOP_MARKET — 跟踪止损市价单；使用 priceRate（必填）和可选的 activationPrice
• TRAILING_TP_SL — 针对现有持仓的跟踪止盈／止损；通过 symbol + positionSide 关联持仓；使用 priceRate

side：BUY | SELL

positionSide：LONG | SHORT | BOTH

marginType：ISOLATED | CROSSED

timeInForce：GTC | IOC | FOK | PostOnly

workingType（条件订单的触发价格来源）：

• MARK_PRICE — 使用标记价格判断触发条件
• CONTRACT_PRICE — 使用最新成交价（默认值）

止损 / 止盈对象结构

在 MARKET 或 LIMIT 订单上附加 stopLoss 或 takeProfit 时：

{
  "stopLoss": {
    "type": "STOP_MARKET",       // "STOP_MARKET" or "STOP"
    "stopPrice": 29000,          // required: trigger price
    "price": 28900,              // required only for type "STOP" (limit execution price)
    "workingType": "MARK_PRICE", // "MARK_PRICE" or "CONTRACT_PRICE"
    "stopGuaranteed": false      // true = guaranteed execution (extra fee may apply)
  },
  "takeProfit": {
    "type": "TAKE_PROFIT_MARKET",  // "TAKE_PROFIT_MARKET" or "TAKE_PROFIT"
    "stopPrice": 35000,            // required: trigger price
    "price": 35100,                // required only for type "TAKE_PROFIT" (limit execution price)
    "workingType": "MARK_PRICE",
    "stopGuaranteed": false
  }
}

限制： stopLoss / takeProfit 对象仅支持 MARKET 或 LIMIT 订单类型。它们不能与 STOP_MARKET、STOP、TAKE_PROFIT_MARKET、TAKE_PROFIT、TRAILING_STOP_MARKET 或 TRAILING_TP_SL 一起使用。

外层的 stopLoss 和 takeProfit 值是包含 JSON 字符串的查询参数。在该 JSON 中，stopPrice 和可选的 price 必须是 JSON 数字，不能是带引号的数字字符串。切勿发送 {"stopPrice":"63538.3"}。

参数验证规则

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

• symbol：必须匹配 ^[A-Z0-9]+-[A-Z]+$；最多 20 个字符（例如，BTC-USDT）
• quantity：必须是正数（> 0）；精度上限取决于该交易对的合约规格
• price：提供时，必须是正数（> 0）
• stopPrice：提供时，必须是正数（> 0）；且必须不同于当前市场价格
• stopLoss.stopPrice / takeProfit.stopPrice：必须是 JSON 数字；使用 Number(...) 转换，然后要求值为有限且大于 0
• stopLoss.price / takeProfit.price：可选的 JSON 数字；提供时，使用 Number(...) 转换，然后要求值为有限且大于 0
• stopLoss / takeProfit 序列化：序列化前验证嵌套对象。签名查询参数值必须是精确的 JSON.stringify(...) 结果
• leverage：正整数；范围因交易对而异（BTC-USDT 通常为 1–125）
• clientOrderId：仅限字母数字，长度为 1–40 个字符；模式为 ^[a-zA-Z0-9]{1,40}$；不能包含特殊字符
• priceRate：追踪回调率；必须满足 0 < 值 ≤ 1（例如，0.05 = 5%）
• 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 toPositiveNumber(value: unknown, field: string): number {
  const numberValue = Number(value);
  if (!Number.isFinite(numberValue) || numberValue <= 0) {
    throw new Error(`${field} must be a finite positive number`);
  }
  return numberValue;
}
function normalizeAttachedOrder(
  key: "stopLoss" | "takeProfit", value: unknown
): string {
  let parsed: unknown = value;
  if (typeof value === "string") {
    try { parsed = JSON.parse(value); }
    catch { throw new Error(`${key} must be valid JSON`); }
  }
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
    throw new Error(`${key} must be an object or a JSON object string`);
  }
  const nested = { ...(parsed as Record<string, unknown>) };
  const allowedTypes = key === "stopLoss"
    ? new Set(["STOP_MARKET", "STOP"])
    : new Set(["TAKE_PROFIT_MARKET", "TAKE_PROFIT"]);
  if (typeof nested.type !== "string" || !allowedTypes.has(nested.type)) {
    throw new Error(`${key}.type is invalid`);
  }
  nested.stopPrice = toPositiveNumber(nested.stopPrice, `${key}.stopPrice`);
  if (nested.price !== undefined) {
    nested.price = toPositiveNumber(nested.price, `${key}.price`);
  }
  if (nested.workingType !== undefined &&
      nested.workingType !== "MARK_PRICE" &&
      nested.workingType !== "CONTRACT_PRICE") {
    throw new Error(`${key}.workingType is invalid`);
  }
  if (nested.stopGuaranteed !== undefined &&
      typeof nested.stopGuaranteed !== "boolean") {
    throw new Error(`${key}.stopGuaranteed must be a boolean`);
  }
  return JSON.stringify(nested);
}
function normalizeParams(params: Record<string, unknown>): Record<string, unknown> {
  const normalized = { ...params };
  if (normalized.price !== undefined) {
    normalized.price = toPositiveNumber(normalized.price, "price");
  }
  for (const key of ["stopLoss", "takeProfit"] as const) {
    if (normalized[key] !== undefined) {
      normalized[key] = normalizeAttachedOrder(key, normalized[key]);
    }
  }
  return normalized;
}
function serializeParamValue(value: unknown): string {
  if (value !== null && typeof value === "object") return JSON.stringify(value);
  return String(value);
}
function validateParams(params: Record<string, unknown>): void {
  const FORBIDDEN = /[&=?#\r\n]/;
  for (const [k, v] of Object.entries(params)) {
    const s = serializeParamValue(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 normalized = normalizeParams(params);
  const all = { ...normalized, timestamp: Date.now() };
  validateParams(all);
  const qs = Object.keys(all).sort()
    .map(k => `${k}=${serializeParamValue(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 检查
• 必须在创建时间戳和签名之前规范化并序列化所有业务参数。如果任何参数发生变化，则丢弃之前的时间戳 / 签名，并重新签署请求
• 不得使用 ${params[k]} 直接插入对象值；对象值必须使用 JSON.stringify 序列化，否则会变成 [object Object]

---

常见调用

下达市价买单：

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/swap/v2/trade/order", {
    symbol: "BTC-USDT",
    side: "BUY",
    positionSide: "LONG",
    type: "MARKET",
    quantity: 0.01,
  }
);
// order.orderId, order.status

下达附带止损的市价买单：

const rawStopPrice = "63538.3";
const stopPrice = Number(rawStopPrice);
if (!Number.isFinite(stopPrice) || stopPrice <= 0) {
  throw new Error("stopLoss.stopPrice must be a finite positive number");
}

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/swap/v2/trade/order", {
    symbol: "BTC-USDT",
    side: "BUY",
    positionSide: "BOTH",
    type: "MARKET",
    quantity: 0.0004,
    recvWindow: 5000,
    stopLoss: JSON.stringify({
      type: "STOP_MARKET",
      stopPrice,
      workingType: "MARK_PRICE",
    }),
  }
);

重要： /openApi/swap/v2/trade/order/test 不会强制执行真实 /openApi/swap/v2/trade/order 端点执行的所有验证。测试请求成功并不保证真实订单能够通过验证。尤其是，真实端点对嵌套的 stopLoss / takeProfit 字段类型执行更严格的验证。

取消订单：

await fetchSigned("prod-live", API_KEY, SECRET, "DELETE",
  "/openApi/swap/v2/trade/order", {
    symbol: "BTC-USDT",
    orderId: 123456789,
  }
);

查询未结订单：

const orders = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/trade/openOrders", {
    symbol: "BTC-USDT",
  }
);

设置杠杆：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/swap/v2/trade/leverage", {
    symbol: "BTC-USDT",
    side: "LONG",
    leverage: 10,
  }
);

设置保证金类型：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/swap/v2/trade/marginType", {
    symbol: "BTC-USDT",
    marginType: "ISOLATED",
  }
);

注意：要查询当前持仓，请使用 swap-account 技能，该技能提供持仓查询端点，并包含 PnL 和强平价格等完整详情。

其他资源

如需查看完整的参数说明、响应架构和全部 42 个端点，请参阅 api-reference.md。

---

Agent 交互规则

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

除 GET 查询外，所有 swap-trade 操作都是写操作。请遵循环境确认规则：

• prod-live：下单、取消订单或更改仓位／杠杆前，要求用户输入 CONFIRM。
• prod-vst：无需 CONFIRM。告知用户：“您正在 Production Simulated（VST）环境中操作。”

步骤 1 — 确定操作

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

您想进行什么操作？

• 下新订单
• 取消订单／取消所有订单
• 平仓／平掉所有仓位
• 查看未结订单
• 查看当前仓位
• 设置杠杆
• 设置保证金类型（ISOLATED／CROSSED）
• 设置仓位模式（Hedge／One-way）

步骤 2 — 收集 symbol（如果未提供）

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

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

步骤 3 — 收集 side（下单时）

订单方向：

• BUY
• SELL

步骤 4 — 收集 positionSide

仓位方向：

• LONG（开多／加多）
• SHORT（开空／加空）
• BOTH（单向模式）

步骤 5 — 收集订单类型

订单类型：

• MARKET — 按市价立即执行（可附加 stopLoss／takeProfit 对象）
• LIMIT — 按指定价格执行（可附加 stopLoss／takeProfit 对象）
• STOP_MARKET — 止损市价单（在 stopPrice 触发，按市价执行）
• STOP — 止损限价单（在 stopPrice 触发，按限价执行）
• TAKE_PROFIT_MARKET — 止盈市价单（在 stopPrice 触发）
• TAKE_PROFIT — 止盈限价单（在 stopPrice 触发，按限价执行）
• TRAILING_STOP_MARKET — 新仓位的追踪止损（需要 priceRate；activationPrice 为可选项）
• TRAILING_TP_SL — 现有仓位的追踪 TP／SL（通过 symbol + positionSide 关联；需要 priceRate）

步骤 6 — 收集数量和价格

• 询问以币为单位的数量（例如，BTC-USDT 的数量为 0.01 BTC）。对于 STOP_MARKET 和 TAKE_PROFIT_MARKET，使用 closePosition: true 时仍必须提供数量。
• 如果类型为 LIMIT、STOP 或 TAKE_PROFIT：还要询问 price。
• 如果类型为 STOP_MARKET、STOP、TAKE_PROFIT_MARKET 或 TAKE_PROFIT：还要询问 stopPrice。
• 如果类型为 TRAILING_STOP_MARKET 或 TRAILING_TP_SL：询问 priceRate（例如，0.05 = 5%），并可选询问 activationPrice。
• 如果类型为 MARKET 或 LIMIT：可选择询问是否附加 stopLoss 和／或 takeProfit 对象（询问触发价格和类型）。

可选高级参数（仅在相关或用户提及时询问）：

• workingType：触发价格来源 — MARK_PRICE 或 CONTRACT_PRICE（默认值）
• reduceOnly：设置为 true 可确保订单只减小仓位；Hedge Mode 下不要发送此参数
• closePosition：设置为 true 可在触发时平掉整个仓位；仅适用于 STOP_MARKET 和 TAKE_PROFIT_MARKET，且仍必须提供 quantity 和 stopPrice
• stopGuaranteed：设置为 true 可确保止损订单执行（可能会收取额外费用）

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

对于 prod-live 环境，请展示摘要并询问：

您即将在 Production Live 环境中下达以下订单：

• Symbol：BTC-USDT
• Side：BUY / LONG
• Type：MARKET
• Quantity：0.01

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

步骤 8 — 执行并报告

执行 API 调用，并向用户返回订单 ID 和状态。

---

取消订单流程

1. 如果未提供，请询问 orderId（或 clientOrderId）。
2. 对于 prod-live：请用户回复 CONFIRM。
3. 执行 DELETE /openApi/swap/v2/trade/order。

平仓流程

1. 如果未提供，请询问交易对。
2. 提供选项：平掉指定方向的仓位（LONG/SHORT）或平掉所有仓位。
3. 对于 prod-live：请用户回复 CONFIRM。
4. 使用 POST /openApi/swap/v2/trade/closeAllPositions，或下达反向 MARKET 订单。

杠杆设置流程

1. 如果未提供，请询问交易对。
2. 询问仓位方向（LONG / SHORT / both）。
3. 询问杠杆值（例如，1–125）。
4. 对于 prod-live：请用户回复 CONFIRM。
5. 执行 POST /openApi/swap/v2/trade/leverage。

保证金类型流程

1. 如果未提供，请询问交易对。
2. 提供选项：ISOLATED 或 CROSSED。
3. 对于 prod-live：请用户回复 CONFIRM。
4. 执行 POST /openApi/swap/v2/trade/marginType。

仓位模式流程

1. 提供选项：双向持仓模式（dualSidePosition: true）或单向持仓模式（dualSidePosition: false）。
2. 对于 prod-live：请用户回复 CONFIRM。
3. 执行 POST /openApi/swap/v1/positionSide/dual。