bingx-copytrade-spot

BingX Copy Trade Spot

用于 BingX Copy Trade Spot 交易的身份验证接口。所有接口均需要 HMAC SHA256 签名身份验证。

此技能涵盖现货跟单交易中**交易员（信号提供方）**一侧的操作：卖出跟单买入订单中的资产，以及查询交易表现数据。

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

注意： Copy Trade Spot 接口的文档位于 https://bingx-api.github.io/docs-v3/#/en/Copy%20Trade/Spot%20Trading/。如果遇到意外错误，请对照官方文档核实准确路径。

---

快速参考

接口	方法	说明	身份验证
/openApi/copyTrading/v1/spot/trader/sellOrder	POST	交易员根据买入订单编号卖出现货资产	是
/openApi/copyTrading/v1/spot/traderDetail	GET	个人交易概览	是
/openApi/copyTrading/v1/spot/profitHistorySummarys	GET	收益汇总	是
/openApi/copyTrading/v1/spot/profitDetail	GET	收益详情	是
/openApi/copyTrading/v1/spot/historyOrder	GET	查询历史订单	是

---

参数

卖出持仓参数

• orderId：要卖出的买入订单 ID，即原跟单买入订单编号（必填）
• recvWindow：请求有效期窗口，单位为毫秒（可选，最大值 60000）

查询参数（概览、收益和历史接口共用）

• startTime：起始时间戳，单位为毫秒（可选）
• endTime：结束时间戳，单位为毫秒（可选）
• pageIndex：页码，必须大于 0（可选，默认值为 1）
• pageSize：每页记录数（可选，默认值因接口而异）
• recvWindow：请求有效期窗口，单位为毫秒（可选）

参数校验规则

• orderId：卖出操作必填；必须是有效的买入订单 ID 字符串
• pageIndex：正整数，必须大于 0
• pageSize：正整数，必须大于 0
• startTime / endTime：Unix 时间戳，单位为毫秒；endTime 必须大于或等于 startTime
• 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 检查

---

常见调用

卖出买入订单中的现货资产（平仓跟单持仓）：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/copyTrading/v1/spot/trader/sellOrder", {
    orderId: "1736011869418901234",
  }
);
// result — confirmation of the sell order placed

查询个人交易概览：

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

查询日期范围内的收益汇总：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/spot/profitHistorySummarys", {
    startTime: 1704067200000,
    endTime:   1706745600000,
  }
);
// result — aggregated profit summary

查询收益详情（分页）：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/spot/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, "GET",
  "/openApi/copyTrading/v1/spot/historyOrder", {
    pageIndex: 1,
    pageSize:  50,
  }
);
// result.list — list of historical spot copy trade orders
// result.total — total count

其他资源

完整的参数说明和响应架构请参见 api-reference.md。

---

Agent 交互规则

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

卖出端点（POST /openApi/copyTrading/v1/spot/trader/sellOrder）属于写操作，在 prod-live 环境中需要确认。所有 GET 端点均为只读，无需确认。

• prod-live：执行卖出操作前，请用户输入 CONFIRM。
• prod-vst：无需 CONFIRM。告知用户：“您当前使用的是生产模拟（VST）环境。”

第 1 步 — 确定操作

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

您想进行什么操作？

• 根据跟单买入订单卖出现货资产
• 查看我的个人交易概览
• 查看利润摘要
• 查看利润详情
• 查看历史订单

第 2 步 — 收集参数

卖出操作：

请提供您要卖出的买入订单 ID：

• orderId（必填）：原始跟单买入订单号

利润／历史记录查询：

请指定时间范围（可选）：

• 开始时间（Unix 毫秒）
• 结束时间（Unix 毫秒）

第 3 步 — 确认（仅限 prod-live 卖出操作）

您即将在生产实盘环境中卖出现货资产：

• 订单 ID：{orderId}

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

第 4 步 — 执行并报告

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

• 卖出：订单状态和确认详情
• 概览：总利润、胜率和交易次数
• 利润摘要：汇总利润金额
• 利润详情：按订单列出的明细，包括交易对、利润和时间戳
• 历史订单：订单列表，包含状态和成交详情