bingx-sub-account

BingX サブアカウント管理

BingX サブアカウントを管理するための認証済みエンドポイントです（マスターアカウントの操作）。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。一部の書き込みエンドポイントでは、標準のフォームエンコーディングではなく Content-Type: application/json が必要です。以下のクイックスタートのヘルパーを参照してください。

ベース URL： references/base-urls.md を参照 | 認証： references/authentication.md を参照

---

クイックリファレンス

エンドポイント	メソッド	説明	認証	ボディタイプ
/openApi/account/v1/uid	GET	アカウント UID の照会	はい	—
/openApi/v1/account/apiPermissions	GET	API キーの権限の照会	はい	—
/openApi/v1/account/apiPermissions	GET	API キーの制限の照会	はい	—
/openApi/account/v1/apiKey/query	GET	API キー情報の照会（自身またはサブアカウント）	はい	—
/openApi/subAccount/v1/create	POST	サブアカウントの作成	はい	JSON
/openApi/subAccount/v1/list	GET	サブアカウント一覧の取得	はい	—
/openApi/subAccount/v1/assets	GET	サブアカウントの資金資産の照会	はい	—
/openApi/subAccount/v1/updateStatus	POST	サブアカウントの凍結／凍結解除	はい	JSON
/openApi/subAccount/v1/allAccountBalance	GET	サブアカウントの資産概要の一括照会	はい	—
/openApi/subAccount/v1/apiKey/create	POST	サブアカウント用 API キーの作成	はい	JSON
/openApi/subAccount/v1/apiKey/edit	POST	サブアカウントの API キーの編集	はい	JSON
/openApi/subAccount/v1/apiKey/del	POST	サブアカウントの API キーの削除	はい	JSON
/openApi/account/v1/innerTransfer/authorizeSubAccount	POST	サブアカウントの内部振替の許可	はい	form
/openApi/wallets/v1/capital/subAccountInnerTransfer/apply	POST	サブアカウントの内部振替	はい	form
/openApi/wallets/v1/capital/subAccount/deposit/address	GET	サブアカウントの入金アドレスの取得	はい	—
/openApi/wallets/v1/capital/deposit/subHisrec	GET	サブアカウントの入金記録の取得	はい	—
/openApi/wallets/v1/capital/subAccount/innerTransfer/records	GET	サブアカウントの内部振替記録の照会	はい	—
/openApi/account/transfer/v1/subAccount/asset/transferHistory	GET	サブアカウントの振替履歴の照会	はい	—
/openApi/account/transfer/v1/subAccount/transferAsset/supportCoins	POST	振替可能額の照会	はい	form
/openApi/account/transfer/v1/subAccount/transferAsset	POST	サブアカウントの資産振替	はい	form
/openApi/v1/account/apiRestrictions	GET	サブアカウントの API キー権限の照会	はい	—
/openApi/wallets/v1/capital/deposit/createSubAddress	POST	サブアカウント用入金アドレスの作成	はい	form

---

パラメーター

サブアカウントのパラメーター

• subAccountString：サブアカウントのユーザー名。先頭は英字で、数字を含み、6 文字を超える必要があります
• subUid：サブアカウントの UID（長整数）
• note：サブアカウントまたは API キーの備考文字列
• isFeeze：ブール値。凍結状態でサブアカウントを絞り込みます（注：API パラメーター名は isFreeze ではなく isFeeze です）
• page：ページ番号。1 から始まります
• limit：ページサイズ。最大 1000
• freeze：ブール値。凍結する場合は true、凍結解除する場合は false

API キーのパラメーター

• apiKey：サブアカウントの API キー文字列
• uid：ユーザー UID（API キー情報の照会時に使用）
• permissions：整数の配列。割り当てる権限（列挙値を参照）
• ipAddresses：ホワイトリストに登録する IP アドレス文字列の配列（任意）

振替パラメーター

• coin：通貨／資産名（例：USDT）
• amount / transferAmount：振替額（浮動小数点数）
• userAccountType：1=UID、2=電話番号、3=メールアドレス
• userAccount：受取人の識別子（UID、電話番号、またはメールアドレス）
• walletType / fromAccountType / toAccountType：アカウントタイプ（「列挙値」を参照）
• fromUid / toUid：送信者／受信者のUID
• fromType / toType：1=マスターアカウント、2=サブアカウント
• subUids：UIDをカンマ区切りで並べた文字列（一括承認に使用）
• transferable：ブール値 — 内部振替を許可する場合は true、禁止する場合は false
• transferClientId：クライアント側で指定するカスタム振替ID文字列

列挙値

permissions（APIキーの権限フラグ）：

• 1 — 現物取引
• 2 — 読み取り
• 3 — 無期限先物取引
• 4 — 汎用振替
• 5 — 出金
• 7 — サブアカウントの内部振替を許可

walletType / accountType（アカウントタイプコード）：

• 1 — 資金アカウント
• 2 — 標準先物アカウント
• 3 — 無期限先物アカウント（USDⓢ-M）

status（入金レコードのステータス）：

• 0 — 処理中
• 1 — 完了
• 6 — チェーンにアップロード済み

パラメーターの検証ルール

• subAccountString：英字で始まり、数字を少なくとも1つ含み、6文字より長い必要があります
• subUid：正の整数（long）
• coin：大文字の英字と数字のみ。パターン ^[A-Z0-9]{1,20}$（例：USDT）
• amount / transferAmount：正の数（> 0）である必要があります
• permissions：整数の配列。各値は 1, 2, 3, 4, 5, 7 のいずれかである必要があります
• ipAddresses：指定する場合、各値は有効なIPv4アドレスである必要があります
• page：1から始まる正の整数
• limit：正の整数、1～1000
• recvWindow：整数、1～5000 ms（リプレイ保護を参照）
• timestamp：ミリ秒単位のUnix時刻。サーバー時刻との差が recvWindow 以内である必要があります

---

クイックスタート

重要： サブアカウントの書き込みエンドポイントの一部では、パラメーターをJSON本文として送信する Content-Type: application/json が必要です。これらの呼び出しでは bodyType: "json" を渡してください。それ以外のPOSTエンドポイントでは、標準のフォームエンコード（bodyType: "form"）を使用します。

制約： コードを生成する際は、以下の 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 = Array.isArray(v) ? JSON.stringify(v) : 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", path: string, params: Record<string, unknown> = {},
  bodyType: "form" | "json" = "form"
) {
  const urls = BASE[env] ?? BASE["prod-live"];
  const all = { ...params, timestamp: Date.now() };
  validateParams(all);
  const qs = Object.keys(all).sort().map(k => {
    const v = all[k]; return `${k}=${Array.isArray(v) ? JSON.stringify(v) : v}`;
  }).join("&");
  const sig = crypto.createHmac("sha256", secretKey).update(qs).digest("hex");
  for (const base of urls) {
    try {
      if (method === "GET") {
        const r = await fetch(`${base}${path}?${qs}&signature=${sig}`,
          { headers: { "X-BX-APIKEY": apiKey, "X-SOURCE-KEY": "BX-AI-SKILL" },
            signal: AbortSignal.timeout(10000) });
        const j = JSONBigParse.parse(await r.text()); if (j.code !== 0) throw new Error(`BingX error ${j.code}: ${j.msg}`);
        return j.data;
      }
      const ct = bodyType === "json" ? "application/json" : "application/x-www-form-urlencoded";
      const body = bodyType === "json" ? JSON.stringify({ ...all, signature: sig }) : `${qs}&signature=${sig}`;
      const r = await fetch(`${base}${path}`, { method: "POST",
        headers: { "X-BX-APIKEY": apiKey, "X-SOURCE-KEY": "BX-AI-SKILL", "Content-Type": ct }, body,
        signal: AbortSignal.timeout(10000) });
      const j = JSONBigParse.parse(await r.text()); if (j.code !== 0) throw new Error(`BingX error ${j.code}: ${j.msg}`);
      return j.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 チェックを削除してはいけません

---

一般的な呼び出し

アカウントUIDを照会：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/account/v1/uid"
);
// data.uid

サブアカウントを作成：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/subAccount/v1/create",
  { subAccountString: "alice001", note: "trading sub" },
  "json"  // must use JSON body
);
// data.subUid, data.subAccountString

サブアカウントを一覧表示（ページネーション）：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/subAccount/v1/list",
  { page: 1, limit: 100 }
);
// data.subAccountList[].uid, .subAccountString, .isFreeze

サブアカウントのAPIキーを作成：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/subAccount/v1/apiKey/create",
  {
    subUid: 16477999,
    note: "read-only key",
    permissions: [2],           // 2 = Read only
    ipAddresses: ["1.2.3.4"],
  },
  "json"  // must use JSON body
);
// data.apiKey, data.secretKey

サブアカウントを凍結：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/subAccount/v1/updateStatus",
  { subUid: 16477999, freeze: true },
  "json"  // must use JSON body
);

サブアカウント間で資産を振替（マスターのみ）：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/account/transfer/v1/subAccount/transferAsset",
  {
    assetName: "USDT",
    transferAmount: 100,
    fromUid: 11111111,
    fromType: 1,           // 1 = master account
    fromAccountType: 1,    // 1 = fund account
    toUid: 22222222,
    toType: 2,             // 2 = sub-account
    toAccountType: 1,
    remark: "funding sub",
  }
  // default form body
);
// data.tranId

追加リソース

21個すべてのエンドポイントのパラメーターの詳細とレスポンススキーマについては、api-reference.mdを参照してください。

---

エージェントとのやり取りのルール

パラメーターのセキュリティ。 ユーザーの意図から構造化された値を抽出してください。ユーザーの生のテキストをAPIパラメーターにコピーしてはいけません。APIを呼び出す前に、すべての値を文書化されたパターン（正規表現／列挙値／範囲）に照らして検証してください。&、=、?、#、または改行文字を含む値は拒否してください。

すべての書き込み操作では、prod-live でCONFIRMが必要です。読み取り専用のクエリでは必要ありません。

• prod-live：作成、編集、削除、凍結、または振替の操作を行う前に、ユーザーにCONFIRMと入力するよう求めてください。
• prod-vst：CONFIRMは不要です。ユーザーに「Production Simulated（VST）環境で操作しています」と伝えてください。

ステップ 1 — 操作の特定

ユーザーの意図が不明確な場合は、選択肢を提示します。

何を行いますか？

• アカウント UID または API Key の権限を照会する
• 新しいサブアカウントを作成する
• サブアカウントの一覧を取得する
• サブアカウントの資産／資産概要を照会する
• サブアカウントを凍結または凍結解除する
• サブアカウントの API Key を作成／編集／削除する
• サブアカウントの API Key を照会する
• サブアカウント間の内部送金を許可する
• アカウント間で資産を送金する
• 入金アドレスまたは入金記録を照会する
• 送金履歴を照会する

ステップ 2 — サブアカウント識別子の取得（該当する場合）

サブアカウントの UID、または新規作成の場合はサブアカウントのユーザー名を入力してください。

ステップ 3 — 操作固有のパラメーターを取得する

サブアカウントの作成： subAccountString（英字で始まり、数字を含み、6 文字を超える必要があります）を尋ねます。任意で note も尋ねます。

API Key の作成／編集： 次の項目を尋ねます。

• subUid（サブアカウントの UID）
• note（ラベル）
• permissions（次の一覧を提示します：1=現物、2=読み取り、3=無期限先物、4=汎用送金、5=出金、7=内部送金）
• ipAddresses（任意の IP ホワイトリスト）

凍結／凍結解除： 凍結する（true）か、凍結解除する（false）かを尋ねます。

資産の送金： 次の項目を尋ねます。

• assetName（例：USDT）
• transferAmount
• 送金元の UID と口座タイプ
• 送金先の UID と口座タイプ

ステップ 4 — 確認（prod-live の書き込み操作のみ）

Production Live で {action} を実行しようとしています。

• {パラメーターの概要}

続行するには CONFIRM と入力してください。それ以外を入力するとキャンセルされます。

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

ヘルパー関数を使って API 呼び出しを実行します（create、updateStatus、apiKey/create、apiKey/edit、apiKey/del には bodyType: "json" を使用し、それ以外のすべての POST エンドポイントにはデフォルトの "form" を使用します）。

主要なフィールド（例：subUid、apiKey、tranId）をユーザーに返します。

---

JSON ボディを使用するエンドポイント（再確認）

次のパスでは、必ず bodyType: "json" を渡してください。

• POST /openApi/subAccount/v1/create
• POST /openApi/subAccount/v1/updateStatus
• POST /openApi/subAccount/v1/apiKey/create
• POST /openApi/subAccount/v1/apiKey/edit
• POST /openApi/subAccount/v1/apiKey/del

その他すべての POST エンドポイントでは、デフォルトのフォームエンコーディングを使用します。