bingx-swap-account

BingX Swap 账户

用于读取 BingX 永续期货账户数据的只读认证端点。所有端点都需要 HMAC SHA256 签名认证。

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

---

快速参考

端点	方法	说明	认证
/openApi/swap/v3/user/balance	GET	账户余额、权益和保证金信息	是
/openApi/swap/v2/user/positions	GET	当前未平仓仓位，以及盈亏和强平价格	是
/openApi/swap/v2/user/commissionRate	GET	用户吃单/挂单费率	是
/openApi/swap/v2/user/income	GET	资金流水历史（盈亏、资金费、交易费等）	是
/openApi/swap/v2/user/income/export	GET	将资金流水导出为 Excel 文件	是

---

参数

通用参数

• symbol：采用 BASE-QUOTE 格式的交易对（例如 BTC-USDT）。大多数账户端点中为可选参数。
• timestamp：请求时间戳，单位为毫秒（所有认证端点都必填）。
• recvWindow：请求有效时间窗口，单位为毫秒（可选，最大值为 60000）。
• startTime / endTime：时间范围筛选条件，单位为毫秒（收入端点使用）。
• limit：返回结果数量（收入端点使用；默认值为 100，最大值为 1000）。

incomeType 枚举（用于收入端点）

值	说明
TRANSFER	转账
REALIZED_PNL	已实现盈亏
FUNDING_FEE	资金费
TRADING_FEE	交易费
INSURANCE_CLEAR	强平
TRIAL_FUND	体验金
ADL	自动减仓
SYSTEM_DEDUCTION	系统扣款
GTD_PRICE	保证价格

参数验证规则

• symbol：提供时，必须匹配 ^[A-Z0-9]+-[A-Z]+$；最多 20 个字符（例如 BTC-USDT）
• incomeType：提供时，必须与上述某个枚举值完全匹配
• startTime / endTime：Unix 时间戳，单位为毫秒；endTime 必须 ≥ startTime
• limit：正整数，范围为 1–1000；默认值为 100
• 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 data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v3/user/balance"
);
// data.balance.balance, data.balance.equity, data.balance.availableMargin

查询所有未平仓仓位：

const positions = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/positions"
);
// positions[].symbol, positions[].positionAmt, positions[].unrealizedProfit, positions[].liquidationPrice

查询指定交易对的仓位：

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

查询用户费率：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/commissionRate"
);
// data.commission.takerCommissionRate, data.commission.makerCommissionRate

查询近期资金流水（最近 7 天，所有类型）：

const income = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/income", { limit: 100 }
);
// income[].incomeType, income[].income, income[].asset, income[].time

查询指定时间范围内 BTC-USDT 的资金费：

const income = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/income", {
    symbol: "BTC-USDT",
    incomeType: "FUNDING_FEE",
    startTime: 1700000000000,
    endTime: 1702731787011,
    limit: 200,
  }
);

附加资源

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

---

Agent 交互规则

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

所有 swap-account 端点均为只读（GET）。任何环境下均无需 CONFIRM，因为这些端点不会修改账户状态。

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

步骤 1 — 确定查询内容

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

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

• 账户余额／权益／保证金 — balance
• 当前持仓／未实现盈亏／强平价格 — positions
• 手续费率 — commissionRate
• 资金流水（盈亏／资金费／交易手续费等）— income
• 导出资金流水（Excel）— income/export

步骤 2 — 收集交易对（如适用）

对于 positions 和 income 端点，交易对为可选项。如果用户询问特定币种，请自动推断交易对（例如，“BTC 持仓” → BTC-USDT）。

如果未指定，则查询所有交易对，并告知用户。

步骤 3 — 收集时间范围（适用于 income 端点）

• 如果未提供 startTime 和 endTime，API 将返回最近 7 天的数据。请告知用户。
• 仅提供最近 3 个月的数据。
• 如果用户指定了日期范围，请将其转换为毫秒。

步骤 4 — 收集 incomeType（适用于 income 端点）

如果用户指定了类型（例如，“资金费”“交易手续费”“盈亏”），请映射到正确的 incomeType 枚举值：

用户说法	incomeType
已实现盈亏／盈亏	REALIZED_PNL
资金费／资金费率	FUNDING_FEE
交易手续费／手续费	TRADING_FEE
强平	INSURANCE_CLEAR
ADL／自动减仓	ADL
转账	TRANSFER

如果未指定，请省略 incomeType 以返回所有类型。

步骤 5 — 执行并报告

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

• balance：以汇总表格展示权益、可用保证金、已用保证金和未实现盈亏。
• positions：为每个持仓展示一张表格，包含交易对、方向、数量、平均价格、未实现盈亏、强平价格和杠杆。
• commissionRate：以百分比展示吃单和挂单费率（乘以 100）。
• income：以表格展示最近的记录，包括时间、类型、交易对、金额和资产。