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 に対応するエージェントユーザー情報を照会します	はい
/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	ユーザーが上位エージェントかどうかを確認します	はい

---

パラメーター

ページネーションパラメーター

• 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チェックを削除しないでください

---

よく使う呼び出し

招待したすべてのユーザーを照会する（1ページ目）：

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のエージェントユーザー情報を照会する：

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を参照してください。

---

エージェントとのやり取りに関するルール

**パラメーターのセキュリティ。**ユーザーの意図から構造化された値を抽出してください。ユーザーの生のテキストをAPIパラメーターにコピーすることは絶対に避けてください。APIを呼び出す前に、各値がドキュメントに記載されたパターン（正規表現／列挙型／範囲）に合致することを検証してください。&、=、?、#、または改行文字を含む値は拒否してください。

すべてのAgentエンドポイントは読み取り専用（GET）です。どの環境でもCONFIRMは不要です。

• prod-live：CONFIRMは不要です（読み取り専用）。そのまま処理を進めてください。
• prod-vst：CONFIRMは不要です。ユーザーに「Production Simulated（VST）環境で操作しています」と伝えてください。

ステップ1 — 操作を特定する

ユーザーの意図が不明確な場合は、選択肢を提示してください：

何をしますか？

• 招待／紹介したユーザーの一覧を照会する
• 日次コミッションの詳細（招待関係）を照会する
• 特定のユーザーUIDのエージェント関係情報を確認する
• API取引コミッション（招待関係なし）を照会する
• パートナー情報を照会する

ステップ2 — 期間を収集する（該当する場合）

コミッションとパートナーのエンドポイントの場合：

日付範囲を指定してください（最大30日間）：

• 開始日（例：20240101）
• 終了日（例：20240131）

招待したユーザーの一覧では、タイムスタンプの単位はミリ秒です：

期間を指定してください（任意、最大30日間）：

• 開始時刻（Unixミリ秒）。全期間を対象とする場合は空欄にしてください

ステップ3 — 任意のフィルターを収集する

• コミッションの照会：特定の招待ユーザーUIDで絞り込むことができます
• APIコミッションの照会：commissionBizType（81=無期限、82=現物）を確認してください
• 大規模なデータセット（10,000件超）：ページネーションにはlastUidカーソルを使用してください

ステップ4 — 実行して結果を報告する

API呼び出しを実行し、主な項目をユーザーに返してください：

• 招待したユーザー：合計件数、現在のページ、ユーザー詳細の概要
• コミッションデータ：合計レコード数、現在のエージェントUID、コミッション額の合計
• ユーザー情報：招待関係、KYCステータス、入金／取引ステータス、特典情報