bingx-standard-trade

BingX 标准合约交易

用于获取 BingX 标准合约（标准期货）数据的身份验证端点。所有端点都需要 HMAC SHA256 签名身份验证。

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

---

快速参考

端点	方法	描述	身份验证
/openApi/contract/v1/allPosition	GET	查询当前持仓	是
/openApi/contract/v1/allOrders	GET	查询历史订单	是
/openApi/contract/v1/balance	GET	查询标准合约余额	是

---

1. 查询持仓

GET /openApi/contract/v1/allPosition

查询标准合约账户中的所有当前持仓。

参数： 除通用签名参数（timestamp、recvWindow）外，无其他参数。

响应 data（数组）：

字段	类型	描述
symbol	字符串	交易对，例如 BTC-USDT
initialMargin	数字	保证金
leverage	数字	杠杆
unrealizedProfit	数字	未实现盈亏
isolated	布尔值	true = 逐仓保证金模式
entryPrice	数字	平均入场价格
positionSide	字符串	持仓方向：LONG 或 SHORT
positionAmt	数字	持仓数量
currentPrice	数字	当前价格
time	int64	开仓时间（毫秒）

---

2. 查询历史订单

GET /openApi/contract/v1/allOrders

查询标准合约交易对的历史订单。

参数：

参数	类型	必填	描述
symbol	字符串	是	交易对，例如 BTC-USDT
orderId	int64	否	订单 ID 筛选条件
startTime	int64	否	开始时间（毫秒）
endTime	int64	否	结束时间（毫秒）
limit	int64	否	数量，可选
recvWindow	int64	否	请求有效时间窗口（毫秒）

响应 data（数组）：

字段	类型	描述
orderId	数字	系统订单 ID
symbol	字符串	交易对
positionSide	字符串	持仓方向：LONG 或 SHORT
status	字符串	订单状态，例如 CLOSED
avgPrice	数字	平均成交价格
cumQuote	数字	成交金额
executedQty	数字	已成交数量
margin	数字	保证金
leverage	数字	杠杆
isolated	布尔值	true = 逐仓保证金模式
closePrice	数字	平仓价格
positionId	int64	持仓 ID
time	int64	订单时间（毫秒）
updateTime	int64	最后更新时间（毫秒）

---

3. 查询标准合约余额

GET /openApi/contract/v1/balance

查询标准合约账户余额。

参数： 除通用签名参数（timestamp、recvWindow）外，无其他参数。

响应 data：

字段	类型	描述
asset	字符串	资产名称
balance	字符串	总余额
crossWalletBalance	字符串	全仓钱包余额
crossUnPnl	字符串	全仓未实现盈亏
availableBalance	字符串	可用于下单的余额
maxWithdrawAmount	字符串	最大可划转金额
marginAvailable	布尔值	是否可用作保证金
updateTime	数字	最后更新时间戳

参数验证规则

• symbol：必须匹配 ^[A-Z0-9]+-[A-Z]+$；最多 20 个字符（例如，BTC-USDT）
• orderId：提供时必须为正整数
• startTime / endTime：Unix 毫秒时间戳；endTime 必须 ≥ startTime
• limit：正整数
• 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 positions = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/contract/v1/allPosition"
);
// positions[].symbol, positions[].positionAmt, positions[].unrealizedProfit, positions[].entryPrice

查询 BTC-USDT 的历史订单：

const orders = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/contract/v1/allOrders", { symbol: "BTC-USDT", limit: 50 }
);
// orders[].orderId, orders[].status, orders[].avgPrice, orders[].executedQty

查询账户余额：

const balance = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/contract/v1/balance"
);
// balance.balance, balance.availableBalance, balance.crossUnPnl

其他资源

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

---

Agent 交互规则

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

所有标准交易端点均为只读（GET）。无需 CONFIRM——它们绝不会修改账户状态。

需要凭据。如果未指定账户，则默认使用 main 账户。

第 1 步 — 确认查询内容

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

请选择要查询的信息类型：

• 当前持仓／未实现盈亏 — positions
• 历史订单 — allOrders
• 账户余额／可用保证金 — balance

第 2 步 — 收集参数

对于 allOrders，必须提供 symbol。如果用户询问某个特定币种，请推断 symbol（例如，“BTC 订单” -> BTC-USDT）。可选筛选条件包括 startTime、endTime 和 limit。

对于 allPosition 和 balance，无需参数。

第 3 步 — 执行并报告

执行 API 调用，并以易读的格式呈现结果：

• positions：为每个持仓显示一张表格，包含：symbol、方向、数量、入场价格、未实现盈亏、杠杆。
• allOrders：显示一张表格，包含：订单 ID、symbol、方向、状态、平均成交价格、数量、时间。
• balance：显示总余额、可用余额、全仓未实现盈亏。