bingx-spot-wallet

BingX 现货钱包

用于查询 BingX 钱包充值和提现的身份验证端点。所有端点均需要使用 HMAC SHA256 签名进行身份验证。

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

---

快速参考

端点	方法	描述	身份验证	权限
/openApi/api/v3/capital/deposit/hisrec	GET	查询充值历史记录	是	读取
/openApi/api/v3/capital/withdraw/history	GET	查询提现历史记录	是	读取
/openApi/wallets/v1/capital/config/getall	GET	查询币种充值/提现配置（网络、限额、手续费）	是	读取
/openApi/wallets/v1/capital/withdraw/apply	POST	发起提现	是	提现
/openApi/wallets/v1/capital/deposit/address	GET	查询主账户充值地址	是	读取
/openApi/wallets/v1/capital/deposit/riskRecords	GET	查询充值风控记录	是	读取

---

参数

充值历史记录参数

• coin：币种名称（例如 USDT、BTC）；可选——省略时返回所有币种
• status：按充值状态筛选（参见 DepositStatus 枚举）
• startTime：时间范围的起始时间，单位为毫秒（例如 1658748648396）
• endTime：时间范围的结束时间，单位为毫秒
• offset：分页偏移量，默认为 0
• limit：每页条数，默认为 1000；最大值为 1000
• txId：按区块链交易 ID 筛选
• recvWindow：请求有效时限，单位为毫秒（最大值为 60000）

提现历史记录参数

• id：唯一提现记录 ID
• coin：币种名称；可选
• withdrawOrderId：提交时指定的自定义提现 ID
• status：按提现状态筛选（参见 WithdrawalStatus 枚举）
• startTime / endTime：时间范围，单位为毫秒
• offset：分页偏移量，默认为 0
• limit：每页条数，默认为 1000
• txId：按区块链交易 ID 筛选

提现申请参数

• coin：币种名称（必填，例如 USDT）
• network：网络名称（例如 BEP20、ERC20）；省略时使用默认网络
• address：提现目标地址（必填）
• addressTag：需要填写此项的币种所用的备注或标签（例如 XRP、EOS）
• amount：提现金额（必填）
• walletType：来源账户类型（必填；参见 WalletType 枚举）
• withdrawOrderId：自定义提现 ID（可选，用于保证幂等性）
• vaspEntityId：支付平台信息（可选，用于遵守 Travel Rule）
• recipientLastName / recipientFirstName：收款人的英文姓名（可选，Travel Rule）
• dateOfbirth：收款人的出生日期，格式为 YYYY-MM-DD（可选，Travel Rule）

充值地址参数

• coin：币种名称（必填）
• offset：起始记录编号，默认为 0
• limit：每页条数，默认为 100；最大值为 1000

枚举

DepositStatus（充值记录状态）：

• 0 — 处理中
• 1 — 未入账
• 2 — 金额错误
• 6 — 链上已确认 / 已完成

WithdrawalStatus（提现记录状态）：

• 4 — 审核中
• 5 — 失败
• 6 — 已完成

WalletType（提现来源账户）：

• 1 — 资金账户（现货）
• 2 — 标准合约账户
• 3 — 永续合约账户

参数验证规则

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

• coin：仅允许大写字母和数字；匹配模式 ^[A-Z0-9]{1,20}$（例如，USDT、BTC）
• address：非空字符串；最多 200 个字符；必须是目标网络的有效区块链地址
• amount：必须是正数（> 0）；必须达到该币种／网络的最低提现金额（通过币种网络配置端点查询）
• network：大写网络标识符（例如，ERC20、BEP20、TRC20）；必须与该币种支持的网络匹配
• addressTag：如果该币种要求填写（例如，XRP、EOS），则必须是非空字符串；最多 128 个字符
• limit：整数，范围为 1–1000；历史记录的默认值为 1000，地址的默认值为 100
• startTime / endTime：以毫秒为单位的 Unix 时间戳；endTime 必须 ≥ startTime；最大范围为 90 天
• 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 检查

---

常见调用

查询过去 7 天的充值历史（USDT）：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/v3/capital/deposit/hisrec", {
    coin: "USDT",
    startTime: Date.now() - 7 * 24 * 60 * 60 * 1000,
    endTime: Date.now(),
    limit: 100,
  }
);
// data[].amount, data[].coin, data[].status, data[].txId, data[].insertTime

查询提现历史：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/v3/capital/withdraw/history", {
    coin: "USDT",
    limit: 50,
  }
);
// data[].id, data[].amount, data[].coin, data[].status, data[].address, data[].txId

查询某币种支持的网络和手续费：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/wallets/v1/capital/config/getall", {
    coin: "USDT",
  }
);
// data[].coin, data[].networkList[].network, data[].networkList[].withdrawFee
// data[].networkList[].withdrawMin, data[].networkList[].depositEnable

获取 USDT 充值地址：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/wallets/v1/capital/deposit/address", {
    coin: "USDT",
    limit: 10,
  }
);
// data.data[].address, data.data[].coin, data.data[].network, data.data[].tag

发起提现：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/wallets/v1/capital/withdraw/apply", {
    coin: "USDT",
    network: "BEP20",
    address: "0xYourAddress",
    amount: 100,
    walletType: 1,
  }
);
// result.id — the unique withdrawal record ID

更多资源

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

---

Agent 交互规则

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

提现端点（POST /openApi/wallets/v1/capital/withdraw/apply）是写入操作，在 prod-live 环境中需要确认。其他所有端点均为只读。

• prod-live：发起任何提现前，要求用户输入 CONFIRM。
• prod-vst：无需确认。告知用户：“您正在 Production Simulated（VST）环境中操作。”

步骤 1 — 确定操作

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

您想进行什么操作？

• 查看充值历史
• 查看提现历史
• 检查币种网络信息（手续费、限额、已启用的网络）
• 获取某币种的充值地址
• 发起提现
• 查看充值风险控制记录

步骤 2 — 收集币种（如适用）

请输入币种名称（例如，USDT、BTC、ETH）：

步骤 3 — 收集时间范围（用于历史记录查询，可选）

您可以选择提供时间范围：

• 过去 24 小时
• 过去 7 天
• 过去 30 天
• 自定义范围（提供以毫秒为单位的 startTime 和 endTime）

步骤 4 — 收集提现详情（仅提现时）

1. 询问 币种（例如，USDT）
2. 询问 网络（例如，BEP20、ERC20、TRC20）。建议先获取 /capital/config/getall，查看可用网络和手续费。
3. 询问 地址（目标钱包地址）
4. 如果币种需要备注/标签（例如，XRP、EOS、XLM），询问 addressTag
5. 询问 金额
6. 询问 walletType（来源账户）：

   来源账户：

   • 1 — 资金账户（现货）
   • 2 — 标准合约
   • 3 — 永续合约

步骤 5 — 确认（仅限 prod-live 提现）

即将在 Production Live 发起以下提现：

• 币种：USDT
• 网络：BEP20
• 地址：0x...
• 金额：100
• 来源：资金账户（walletType=1）

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

步骤 6 — 执行并报告

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

• 充值/提现历史：记录数量、状态、金额、txIds
• 币种配置：可用网络、手续费、最低/最高限额
• 充值地址：地址字符串和网络
• 提现：返回的 id（唯一提现记录 ID）