bingx-copytrade-swap

BingX 跟单交易 USDT-M 永续合约

BingX 跟单交易 USDT-M（USDT 本位）永续期货的身份验证端点。所有端点都需要 HMAC SHA256 签名身份验证。

本技能涵盖 USDT-M 永续期货跟单交易中**交易员（信号提供者）**一侧的操作：管理未平仓订单、平仓、设置 TP/SL、查询业绩数据、配置佣金率，以及浏览可跟单交易对。

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

注意： 跟单交易 USDT-M 永续合约端点的文档位于 https://bingx-api.github.io/docs-v3/#/en/Copy%20Trade/USDT-M%20Perpetual%20Contracts/。如果遇到意外错误，请根据官方文档核对确切路径。

---

快速参考

端点	方法	描述	身份验证
/openApi/copyTrading/v1/swap/trace/currentTrack	GET	交易员当前（未平仓）订单	是
/openApi/copyTrading/v1/swap/trace/closeTrackOrder	POST	按订单号平仓	是
/openApi/copyTrading/v1/swap/trace/setTPSL	POST	按订单号设置止盈和止损	是
/openApi/copyTrading/v1/PFutures/traderDetail	GET	个人交易概览	是
/openApi/copyTrading/v1/PFutures/profitHistorySummarys	GET	盈利概览	是
/openApi/copyTrading/v1/PFutures/profitDetail	GET	盈利详情（分页）	是
/openApi/copyTrading/v1/PFutures/setCommission	POST	设置佣金率	是
/openApi/copyTrading/v1/PFutures/tradingPairs	GET	交易员获取可跟单交易对	是

---

参数

平仓参数

• orderId：要平仓的跟单交易订单号（必填）
• recvWindow：请求有效时间窗口，单位为毫秒（可选，最大 60000）

TP/SL 参数

• orderId：要设置 TP/SL 的跟单交易订单号（必填）
• takeProfit：止盈价格，字符串格式的小数（可选）
• stopLoss：止损价格，字符串格式的小数（可选）
• recvWindow：请求有效时间窗口，单位为毫秒（可选，最大 60000）

查询参数（概览、盈利和当前订单端点通用）

• symbol：交易对筛选条件，格式为 BASE-USDT，例如 BTC-USDT（可选）
• startTime：起始时间戳，单位为毫秒（可选）
• endTime：结束时间戳，单位为毫秒（可选）
• pageIndex：页码 — 必须大于 0（可选，默认值为 1）
• pageSize：每页记录数（可选，默认值因端点而异）
• recvWindow：请求有效时间窗口，单位为毫秒（可选）

佣金率参数

• commissionRate：佣金率值，字符串格式的小数，例如 "0.001"（必填）

参数验证规则

• orderId：平仓/TP-SL 操作必填；必须是有效的订单 ID 字符串
• takeProfit / stopLoss：提供时必须是大于 0 的正数，且为字符串格式的小数
• symbol：提供时必须匹配 ^[A-Z0-9]+-USDT$（例如，BTC-USDT）
• commissionRate：字符串格式的小数，必须 ≥ 0（例如，"0.001"）
• pageIndex：正整数，必须 > 0
• pageSize：正整数，必须 > 0；具体要求因端点而异
• startTime / endTime：以毫秒为单位的 Unix 时间戳；endTime 必须 ≥ startTime
• recvWindow：整数，1–5000 ms（请参阅重放保护）
• timestamp：以毫秒为单位的 Unix 时间；必须在服务器时间的 recvWindow 范围内

---

快速入门

CONSTRAINT：生成代码时，必须原样复制下面的 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 检查

---

常见调用

查询交易员当前的未平仓订单：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/swap/trace/currentTrack", {
    symbol: "BTC-USDT",
  }
);
// result.list — array of current open copy trade orders
// result.total — total count

按订单编号平仓：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/copyTrading/v1/swap/trace/closeTrackOrder", {
    orderId: "1736011869418901234",
  }
);
// result — confirmation of the close order

设置止盈和止损：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/copyTrading/v1/swap/trace/setTPSL", {
    orderId: "1736011869418901234",
    takeProfit: "70000",
    stopLoss:   "60000",
  }
);
// result — confirmation that TP/SL was set

查询个人交易概览：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/PFutures/traderDetail"
);
// result.totalProfit, result.winRate, result.totalFollowers, etc.

查询指定日期范围的利润概览：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/PFutures/profitHistorySummarys", {
    startTime: 1704067200000,
    endTime:   1706745600000,
  }
);
// result.netProfit, result.winRate, result.totalOrders, etc.

查询利润详情（分页）：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/PFutures/profitDetail", {
    startTime: 1704067200000,
    endTime:   1706745600000,
    pageIndex: 1,
    pageSize:  50,
  }
);
// result.list — per-order profit breakdown
// result.total — total count

设置佣金率：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/copyTrading/v1/PFutures/setCommission", {
    commissionRate: "0.001",
  }
);
// result — confirmation of commission rate update

获取跟单交易对：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/PFutures/tradingPairs"
);
// result.list — array of available copy trading pair objects

更多资源

有关完整的参数说明和响应架构，请参阅 api-reference.md。

---

Agent 交互规则

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

写操作（closePosition、setTPSL、setCommissionRate）在 prod-live 环境中需要确认。所有 GET 端点均为只读，无需确认。

• prod-live：执行任何写操作前，请用户输入 CONFIRM。
• prod-vst：无需输入 CONFIRM。告知用户：“您当前使用的是 Production Simulated（VST）环境。”

步骤 1 — 确定操作

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

您想要进行什么操作？

• 查看我当前未平仓的跟单交易订单
• 平仓（按订单编号）
• 为订单设置止盈／止损
• 查看我的个人交易概览
• 查看利润概览
• 查看利润详情
• 设置我的佣金率
• 获取可用的跟单交易对

步骤 2 — 收集参数

平仓或设置 TP/SL：

请提供订单 ID：

• orderId（必填）：跟单交易订单编号

此外，设置 TP/SL 时：

请提供 TP/SL 价格（至少填写一项）：

• takeProfit：止盈触发价格
• stopLoss：止损触发价格

设置佣金率：

请提供佣金率（例如，0.001 表示 0.1%）：

• commissionRate（必填）

查询利润／当前订单：

请指定交易对和／或时间范围（可选）：

• 交易对（例如 BTC-USDT）
• 开始时间（Unix 毫秒）
• 结束时间（Unix 毫秒）

步骤 3 — 确认（仅限 prod-live 写操作）

平仓：

您即将在 Production Live 环境中平掉一个跟单交易仓位：

• 订单 ID：{orderId}

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

设置 TP/SL：

您即将在 Production Live 环境中为订单设置 TP/SL：

• 订单 ID：{orderId}
• 止盈：{takeProfit}
• 止损：{stopLoss}

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

设置佣金率：

您即将在 Production Live 环境中将佣金率设置为 {commissionRate}。

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

第 4 步 — 执行并报告

执行 API 调用，并向用户返回关键字段：

• 对于平仓：订单状态和确认详情
• 对于设置 TP/SL：新 TP/SL 值的确认信息
• 对于设置佣金率：新费率的确认信息
• 对于交易概览：总利润、胜率、跟随者数量和 AUM
• 对于利润概览：净利润、胜率和订单总数
• 对于利润详情：按订单列出的明细，包含交易对、利润和时间戳
• 对于当前订单：未平仓订单列表，包含交易对、方向、规模和入场价
• 对于跟单交易交易对：可用于跟单交易的交易对列表