bingx-spot-account

BingX 现货账户

用于 BingX 现货交易和账户管理的认证端点。所有端点均需要 HMAC SHA256 签名认证。

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

---

快速参考

端点	方法	描述	认证
/openApi/spot/v1/account/balance	GET	查询现货账户资产／余额	是
/openApi/fund/v1/account/balance	GET	查询资金账户余额	是
/openApi/account/v1/allAccountBalance	GET	资产概览（所有账户类型）	是
/openApi/api/asset/v1/transfer	POST	在账户之间转移资产	是
/openApi/api/v3/asset/transfer	GET	查询资产转移记录	是
/openApi/api/v3/asset/transferRecord	GET	查询资产转移记录（新格式）	是
/openApi/api/asset/v1/transfer/supportCoins	GET	查询支持转移的币种	是
/openApi/wallets/v1/capital/innerTransfer/apply	POST	账户之间的内部 P2P 转账	是
/openApi/wallets/v1/capital/innerTransfer/records	GET	主账户内部转账记录	是

---

参数

订单参数

• symbol：BASE-QUOTE 格式的交易对（例如，BTC-USDT、ETH-USDT）
• side：订单方向——BUY 或 SELL
• type：订单类型（参见枚举）
• quantity：以基础资产计价的订单数量（例如，BTC-USDT 的数量为 0.1）
• quoteOrderQty：以计价资产计价的订单金额（例如，100 USDT）；如果同时提供 quantity，则优先使用 quantity
• price：限价（LIMIT 类型必填）
• stopPrice：触发价格（TAKE_STOP_LIMIT、TAKE_STOP_MARKET、TRIGGER_LIMIT、TRIGGER_MARKET 类型必填）
• timeInForce：GTC | IOC | FOK | PostOnly——默认为 GTC；LIMIT 类型必填
• newClientOrderId：自定义订单 ID，1–40 个字符
• recvWindow：请求有效期窗口，单位为毫秒（最大值为 60000）
• orderId：系统订单 ID（用于取消／查询操作）
• clientOrderID：自定义订单 ID（用于取消／查询操作）

账户参数

• asset / coin：资产名称（例如，USDT、BTC）
• amount：转账金额
• type（转账）：转账方向（参见 TransferType 枚举）
• accountType：资产概览的账户类型（参见 AccountType 枚举）

枚举

type（订单类型）：

• MARKET — 市价单（以当前最优可用价格立即成交）
• LIMIT — 限价单（需要 price 和 timeInForce）
• TAKE_STOP_LIMIT — 止盈／止损限价单（需要 stopPrice 和 price）
• TAKE_STOP_MARKET — 止盈／止损市价单（需要 stopPrice）
• TRIGGER_LIMIT — 触发限价单（需要 stopPrice 和 price）
• TRIGGER_MARKET — 触发市价单（需要 stopPrice）

side：BUY | SELL

timeInForce：GTC | IOC | FOK | PostOnly

TransferType（资产转账方向）：

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

CancelReplaceMode：

• STOP_ON_FAILURE — 取消失败时中止新订单
• ALLOW_FAILURE — 即使取消失败也下新订单

cancelRestrictions（按状态限制取消）：

• NEW — 仅取消新订单
• PENDING — 仅取消待处理订单
• PARTIALLY_FILLED — 仅取消部分成交订单

AccountType（资产概览）：

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

参数验证规则

• symbol：必须匹配 ^[A-Z0-9]+-[A-Z]+$；最多 20 个字符（例如 BTC-USDT）
• quantity：必须为正数（> 0）；精度取决于交易对
• quoteOrderQty：提供时必须为正数（> 0）
• price：提供时必须为正数（> 0）
• stopPrice：提供时必须为正数（> 0）
• newClientOrderId：1–40 个字符；避免使用特殊字符
• amount：转账时必须为正数（> 0）
• type：必须与某个 TransferType 枚举值完全一致
• 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 fundBalance = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/fund/v1/account/balance"
);
// fundBalance.data.balance

查询所有账户余额（概览）：

const allBalances = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/account/v1/allAccountBalance"
);
// allBalances[].asset, allBalances[].balance

转移资产（现货 → 永续合约）：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/api/asset/v1/transfer", {
    type: "FUND_PFUTURES",
    asset: "USDT",
    amount: 100,
  }
);

查询资产转账记录：

const transfers = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/v3/asset/transferRecord", {
    type: "FUND_PFUTURES",
    startTime: 1700000000000,
    endTime: 1702731787011,
  }
);
// transfers[].asset, transfers[].amount, transfers[].type, transfers[].timestamp

查询支持转账的币种：

const coins = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/asset/v1/transfer/supportCoins"
);
// coins[].coin, coins[].name

更多资源

完整参数说明、响应架构和全部 9 个端点，请参阅 api-reference.md。

---

Agent 交互规则

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

在 prod-live 上执行资产转账操作必须获得 CONFIRM。只读查询（余额、转账记录）则不需要。

• prod-live：执行任何资产转账前，请用户输入 CONFIRM。
• prod-vst：无需 CONFIRM。告知用户：“您正在 Production Simulated（VST）环境中操作。”

步骤 1 — 确认操作

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

您想进行什么操作？

• 查询账户余额（现货／资金／所有账户）
• 在账户之间转账
• 查询转账记录
• 查询支持转账的币种
• 内部 P2P 转账

步骤 2 — 查询账户余额

查询余额时，询问账户类型：

您想查询哪种账户余额？

• 现货账户余额
• 资金账户余额
• 所有账户概览

步骤 3 — 资产转账流程

1. 询问转账方向：

   转账方向：

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

2. 询问 asset（例如 USDT）和 amount。
3. 对于 prod-live：请求 CONFIRM。
4. 执行 POST /openApi/api/asset/v1/transfer。

步骤 4 — 查询转账记录

1. 可选询问 type（转账方向）和时间范围。
2. 执行 GET /openApi/api/v3/asset/transferRecord。
3. 以表格形式呈现结果：币种、金额、类型、时间戳、状态。