bingx-fund-account

BingX 资金账户

用于管理 BingX 资金账户的身份验证端点。所有端点均需要 HMAC SHA256 签名身份验证。

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

---

快速参考

端点	方法	描述	身份验证
/openApi/spot/v1/account/balance	GET	查询资金账户资产余额	是
/openApi/account/v1/allAccountBalance	GET	查看所有账户类型的资产总览	是
/openApi/api/asset/v1/transfer	POST	在不同账户类型之间划转资产	是
/openApi/api/v3/asset/transfer	GET	查询资产划转记录	是
/openApi/wallets/v1/capital/innerTransfer/apply	POST	向其他 BingX 用户进行内部 P2P 划转	是
/openApi/wallets/v1/capital/innerTransfer/records	GET	查询内部划转历史记录	是

---

参数

资产划转参数

• type：划转方向（参见 TransferDirection 枚举）——必填
• asset：币种名称（例如，USDT、BTC）——必填
• amount：划转金额——必填
• tranId：交易 ID（用于查询记录；不能与 type 同时使用）
• startTime：时间范围的起始时间，单位为毫秒
• endTime：时间范围的结束时间，单位为毫秒
• current：分页页码（默认值为 1）
• size：分页大小（默认值为 10，最大值为 100）
• recvWindow：请求有效时间窗口，单位为毫秒（最大值为 60000）

内部划转参数

• coin：划转币种名称（例如，USDT）——必填
• userAccountType：收款方账户标识符类型——必填（参见 UserAccountType 枚举）
• userAccount：收款方账户值（UID、电话号码或电子邮箱）——必填
• amount：划转金额——必填
• walletType：来源账户类型——必填（参见 WalletType 枚举）
• callingCode：电话区号（当 userAccountType 为 2 时必填）
• transferClientId：划转的自定义客户端 ID（可选，用于实现幂等性）
• recvWindow：请求有效时间窗口，单位为毫秒（最大值为 60000）

资产总览参数

• accountType：按账户类型筛选（参见 AccountType 枚举）；省略时返回所有账户
• recvWindow：请求有效时间窗口，单位为毫秒

枚举

TransferDirection（资产划转的 type）：

• FUND_SFUTURES — 资金账户 → 标准合约
• SFUTURES_FUND — 标准合约 → 资金账户
• FUND_PFUTURES — 资金账户 → 永续期货
• PFUTURES_FUND — 永续期货 → 资金账户
• SFUTURES_PFUTURES — 标准合约 → 永续期货
• PFUTURES_SFUTURES — 永续期货 → 标准合约

AccountType（资产总览的 accountType）：

• sopt — 现货／资金账户
• stdFutures — 标准期货账户
• coinMPerp — 币本位永续合约账户
• USDTMPerp — USDT 本位永续合约账户
• copyTrading — 跟单交易账户
• grid — 网格交易账户
• eran — 理财账户
• c2c — C2C 账户

UserAccountType（内部划转的 userAccountType）：

• 1 — UID
• 2 — 电话号码（需要 callingCode）
• 3 — 电子邮箱地址

WalletType（内部划转来源的 walletType）：

• 1 — 资金账户
• 2 — 标准合约账户

参数验证规则

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

• asset / coin：仅允许大写字母和数字；模式为 ^[A-Z0-9]{1,20}$（例如，USDT、BTC）
• amount：必须为正数（> 0）；精度取决于资产
• type：必须与 TransferDirection 枚举值之一完全匹配（例如，FUND_PFUTURES）
• userAccount：非空字符串；格式取决于 userAccountType — UID（数字）、电子邮箱或电话号码
• callingCode：当 userAccountType 为 2（电话）时必填；必须是有效的国际拨号代码（例如，86、1）
• size：整数，范围为 1–100；默认值为 10
• 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 balance = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/account/balance"
);
// balance.balances[].asset, balance.balances[].free, balance.balances[].locked

获取所有账户的资产概览：

const overview = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/account/v1/allAccountBalance"
);
// overview[].accountType, overview[].usdtBalance

将资产从资金账户划转到永续合约：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/api/v3/asset/transfer", {
    type: "FUND_PFUTURES",
    asset: "USDT",
    amount: 100,
  }
);
// result.tranId — transaction ID

查询资产划转记录：

const records = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/v3/asset/transfer", {
    type: "FUND_PFUTURES",
    current: 1,
    size: 20,
  }
);
// records.total, records.rows[].asset, records.rows[].amount, records.rows[].status, records.rows[].tranId

向另一位用户进行内部 P2P 划转（通过 UID）：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/wallets/v1/capital/innerTransfer/apply", {
    coin: "USDT",
    userAccountType: 1,
    userAccount: "123456789",  // recipient UID
    amount: 50,
    walletType: 1,
  }
);
// result.id — internal transfer record ID

查询内部划转记录：

const records = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/wallets/v1/capital/innerTransfer/records", {
    coin: "USDT",
    limit: 20,
  }
);
// records.data[].id, records.data[].coin, records.data[].amount, records.data[].status, records.data[].receiver

其他资源

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

---

Agent 交互规则

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

写入操作（POST 资产划转和内部划转）在 prod-live 环境中需要确认。只读查询则不需要。

• prod-live：执行任何资产划转或内部划转前，请用户输入 CONFIRM。
• prod-vst：无需确认。告知用户：“您正在 Production Simulated (VST) 环境中操作。”

步骤 1 — 确定操作

如果用户意图不明确，请列出选项：

您想进行什么操作？

• 查看资金账户余额
• 查看资产概览（所有账户类型）
• 在账户之间划转资产（例如，现货 ↔ 合约）
• 查看资产划转历史记录
• 向另一位 BingX 用户进行内部划转
• 查看内部划转历史记录

步骤 2 — 根据操作收集详情

资产划转：

1. 询问划转方向：

   划转方向：

   • 现货 → 永续合约（FUND_PFUTURES）
   • 永续合约 → 现货（PFUTURES_FUND）
   • 现货 → 标准合约（FUND_SFUTURES）
   • 标准合约 → 现货（SFUTURES_FUND）
   • 标准合约 → 永续合约（SFUTURES_PFUTURES）
   • 永续合约 → 标准合约（PFUTURES_SFUTURES）

2. 询问币种（例如 USDT）和金额。

内部划转：

1. 询问币种和金额。
2. 询问收款方账户类型：

   收款方标识：

   • 1 — UID
   • 2 — 手机号码
   • 3 — 电子邮箱地址

3. 询问收款方账户信息（UID / 手机号码 / 电子邮箱）。
4. 如果是手机号码：询问国际区号（例如，中国为 86）。
5. 询问来源钱包：

   来源账户：

   • 1 — 资金账户
   • 2 — 标准合约账户

步骤 3 — 确认（仅适用于 prod-live 写入操作）

即将在 Production Live 上划转 {amount} {coin}：

• 方向：{transfer direction or recipient info}
• 来源：{wallet type}

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

步骤 4 — 执行并报告

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

• 资产划转：tranId
• 内部划转：id（内部划转记录 ID）
• 余额查询：资产列表及其 free 和 locked 余额
• 资产概览：账户类型列表及其等值 USDT 金额