bingx-agent

BingX Agent

BingX Agent（联盟/经纪商）数据的只读认证端点。所有端点均需要 HMAC SHA256 签名认证。

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

---

快速参考

端点	方法	描述	身份验证
/openApi/agent/v1/account/inviteAccountList	GET	查询受邀用户（分页）	是
/openApi/agent/v2/reward/commissionDataList	GET	每日佣金详情（邀请关系）	是
/openApi/agent/v1/account/inviteRelationCheck	GET	查询 UID 对应的 Agent 用户信息	是
/openApi/agent/v1/reward/third/commissionDataList	GET	API 交易佣金（非邀请关系）	是
/openApi/agent/v1/asset/partnerData	GET	查询合作伙伴信息	是
/openApi/agent/v1/asset/depositDetailList	GET	查询受邀用户的充值详情	是
/openApi/agent/v1/commissionDataList/referralCode	GET	查询邀请码佣金数据	是
/openApi/agent/v1/account/superiorCheck	GET	检查用户是否为上级 Agent	是

---

参数

分页参数

• pageIndex：页码 — 必须大于 0
• pageSize：页面大小 — 必须大于 0；最大值因端点而异（100 或 200）

受邀用户参数

• startTime：开始时间戳，单位为毫秒；最大查询时间范围为 30 天；省略则查询全部时间范围
• endTime：结束时间戳，单位为毫秒；最大查询时间范围为 30 天；省略则查询全部时间范围
• lastUid：查询数据超过 10,000 条时为必填项 — 后续每次请求均传入当前页的最后一个 UID
• recvWindow：请求有效时间窗口，单位为毫秒（默认 5 秒）

佣金参数

• startTime：开始时间，单位为天（日期字符串，例如 "20240101"）；最大查询时间范围为 30 天，范围为最近 365 天内的滑动区间
• endTime：结束时间，单位为天（日期字符串）；最大查询时间范围为 30 天
• uid：可选 — 按特定受邀用户 UID 筛选
• recvWindow：请求有效时间窗口，单位为毫秒

API 佣金（非邀请关系）参数

• commissionBizType：81 = 永续合约 API 佣金；82 = 现货交易 API 佣金
• startTime：开始时间，单位为天；支持查询 2023 年 12 月 1 日之后的数据
• endTime：结束时间，单位为天；支持查询 2023 年 12 月 1 日之后的数据
• uid：可选 — 交易用户的 UID（非邀请关系）

合作伙伴信息参数

• startTime：开始时间，单位为天；仅支持最近 3 个月的数据
• endTime：结束时间，单位为天；仅支持最近 3 个月的数据
• uid：可选 — 按特定合作伙伴 UID 筛选
• pageSize：此端点的最大值为 200

枚举值

commissionBizType：

• 81 — 永续合约 API 佣金
• 82 — 现货交易 API 佣金

参数验证规则

• pageIndex：正整数，必须 > 0
• pageSize：正整数，必须 > 0；最大值为 100 或 200，具体取决于端点
• startTime / endTime：格式因端点而异 — 受邀用户使用毫秒时间戳，佣金/合作伙伴端点使用日期字符串 "YYYYMMDD"；endTime 必须 ≥ startTime；最大查询时间范围为 30 天
• uid：提供时必须为正整数
• commissionBizType：必须为 81（永续合约）或 82（现货）
• lastUid：分页查询超过 10,000 条记录时，传入上一页的最后一个 UID
• 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 result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/agent/v1/account/inviteAccountList", {
    pageIndex: 1,
    pageSize: 100,
  }
);
// result.list — array of invited users
// result.total — total count
// result.currentAgentUid — current agent UID

按时间筛选查询受邀用户：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/agent/v1/account/inviteAccountList", {
    pageIndex: 1,
    pageSize: 100,
    startTime: 1704067200000,  // milliseconds
    endTime:   1706745600000,
  }
);

查询日期范围内的每日佣金：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/agent/v2/reward/commissionDataList", {
    startTime: "20240101",
    endTime:   "20240131",
    pageIndex: 1,
    pageSize:  100,
  }
);
// result.list — array of CommissionData per user per day
// result.total — total records

查询特定 UID 的 Agent 用户信息：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/agent/v1/account/inviteRelationCheck", {
    uid: 123456789,
  }
);
// result.uid, result.inviteResult, result.deposit, result.trade, etc.

查询 API 交易佣金（非邀请关系，永续）：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/agent/v1/reward/third/commissionDataList", {
    commissionBizType: 81,   // 81=perpetual, 82=spot
    startTime: "20240101",
    endTime:   "20240131",
    pageIndex: 1,
    pageSize:  100,
  }
);

查询合作伙伴信息：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/agent/v1/asset/partnerData", {
    startTime: 20240101,   // days
    endTime:   20240131,
    pageIndex: 1,
    pageSize:  200,
  }
);

其他资源

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

---

Agent 交互规则

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

所有 Agent 端点均为只读（GET）。任何环境都不需要 CONFIRM。

• prod-live：无需 CONFIRM（只读）。直接继续。
• prod-vst：无需 CONFIRM。告知用户：“你正在 Production Simulated（VST）环境中操作。”

步骤 1 — 确定操作

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

你想进行什么操作？

• 查询我的受邀／推荐用户列表
• 查询每日佣金明细（邀请关系）
• 查询特定用户 UID 的 Agent 关系信息
• 查询 API 交易佣金（非邀请关系）
• 查询合作伙伴信息

步骤 2 — 收集时间范围（如适用）

对于佣金和合作伙伴端点：

请指定日期范围（最多 30 天）：

• 开始日期（例如 20240101）
• 结束日期（例如 20240131）

对于受邀用户列表，时间戳以毫秒为单位：

请指定时间范围（可选，最多 30 天）：

• 开始时间（Unix 毫秒），或留空以查询全部时间

步骤 3 — 收集可选筛选条件

• 对于佣金查询：可按特定的受邀用户 UID筛选
• 对于 API 佣金查询：询问 commissionBizType（81=永续，82=现货）
• 对于大型数据集（>10,000 条记录）：使用 lastUid 游标进行分页

步骤 4 — 执行并报告

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

• 对于受邀用户：总数、当前页，以及用户详情摘要
• 对于佣金数据：记录总数、当前 Agent UID，以及汇总后的佣金金额
• 对于用户信息：邀请关系、KYC 状态、充值／交易状态，以及福利信息