bingx-fund-account

BingX 資金口座

BingX 資金口座管理用の認証済みエンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

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

---

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/spot/v1/account/balance	GET	資金口座の資産残高を照会	はい
/openApi/account/v1/allAccountBalance	GET	すべての口座タイプの資産概要	はい
/openApi/api/asset/v1/transfer	POST	口座タイプ間で資産を振替	はい
/openApi/api/v3/asset/transfer	GET	資産振替履歴を照会	はい
/openApi/wallets/v1/capital/innerTransfer/apply	POST	別の BingX ユーザーへの内部 P2P 振替	はい
/openApi/wallets/v1/capital/innerTransfer/records	GET	内部振替履歴を照会	はい

---

パラメーター

資産振替パラメーター

• type：振替方向（TransferDirection enum を参照）— 必須
• asset：コイン名（例：USDT、BTC）— 必須
• amount：振替額 — 必須
• tranId：取引 ID（履歴の照会用。type とは相互排他）
• startTime：期間の開始時刻（ミリ秒）
• endTime：期間の終了時刻（ミリ秒）
• current：ページネーションのページ番号（デフォルト 1）
• size：ページネーションのページサイズ（デフォルト 10、最大 100）
• recvWindow：リクエストの有効期間（ミリ秒、最大 60000）

内部振替パラメーター

• coin：振替するコインの名前（例：USDT）— 必須
• userAccountType：受取人アカウントの識別子タイプ — 必須（UserAccountType enum を参照）
• userAccount：受取人アカウントの値（UID、電話番号、またはメールアドレス）— 必須
• amount：振替額 — 必須
• walletType：送金元の口座タイプ — 必須（WalletType enum を参照）
• callingCode：国際電話番号の国番号（userAccountType が 2 の場合に必須）
• transferClientId：振替用のカスタムクライアント ID（任意、冪等性のために使用）
• recvWindow：リクエストの有効期間（ミリ秒、最大 60000）

資産概要パラメーター

• accountType：口座タイプで絞り込み（AccountType enum を参照）。省略するとすべての口座を返します
• recvWindow：リクエストの有効期間（ミリ秒）

列挙型

TransferDirection（資産振替の type）：

• FUND_SFUTURES — 資金口座 → 標準先物
• SFUTURES_FUND — 標準先物 → 資金口座
• FUND_PFUTURES — 資金口座 → 無期限先物
• PFUTURES_FUND — 無期限先物 → 資金口座
• SFUTURES_PFUTURES — 標準先物 → 無期限先物
• PFUTURES_SFUTURES — 無期限先物 → 標準先物

AccountType（資産概要の accountType）：

• sopt — 現物／資金口座
• stdFutures — 標準先物口座
• coinMPerp — コイン建て無期限口座
• USDTMPerp — USDT 建て無期限口座
• copyTrading — コピートレード口座
• grid — グリッド取引口座
• eran — 資産運用口座
• c2c — C2C 口座

UserAccountType（内部振替の userAccountType）：

• 1 — UID
• 2 — 電話番号（callingCode が必要）
• 3 — メールアドレス

WalletType（内部振替元の walletType）：

• 1 — 資金口座
• 2 — 標準契約口座

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

不要な API エラーを避けるため、リクエストを送信する前にクライアント側でパラメーターを検証してください。

• asset / coin：大文字の英字と数字のみ。パターンは ^[A-Z0-9]{1,20}$ です（例：USDT、BTC）
• amount：正の数（> 0）である必要があります。精度は資産によって異なります
• type：TransferDirection 列挙型の値のいずれかと完全に一致する必要があります（例：FUND_PFUTURES）
• userAccount：空でない文字列である必要があります。形式は userAccountType によって異なります（UID（数字）、メールアドレス、または電話番号）
• callingCode：userAccountType が 2（電話）の場合に必須です。有効な国際電話番号の国番号である必要があります（例：86、1）
• size：整数で、1～100。デフォルトは 10 です
• startTime / endTime：ミリ秒単位の Unix タイムスタンプです。endTime は startTime 以上である必要があります
• recvWindow：1～5000 ミリ秒の整数です。できるだけ小さくしてください（リプレイ攻撃対策を参照）
• 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.parse ではなく json-bigint（JSONBigParse.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 overview = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/account/v1/allAccountBalance"
);
// overview[].accountType, overview[].usdtBalance

ファンドアカウントから無期限先物へ資産を振り替える：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/api/v3/asset/transfer", {
    type: "FUND_PFUTURES",
    asset: "USDT",
    amount: 100,
  }
);
// result.tranId — transaction ID

資産振替履歴を照会する：

const records = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/v3/asset/transfer", {
    type: "FUND_PFUTURES",
    current: 1,
    size: 20,
  }
);
// records.total, records.rows[].asset, records.rows[].amount, records.rows[].status, records.rows[].tranId

別のユーザーへの内部 P2P 振替（UID 指定）：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/wallets/v1/capital/innerTransfer/apply", {
    coin: "USDT",
    userAccountType: 1,
    userAccount: "123456789",  // recipient UID
    amount: 50,
    walletType: 1,
  }
);
// result.id — internal transfer record ID

内部振替履歴を照会する：

const records = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/wallets/v1/capital/innerTransfer/records", {
    coin: "USDT",
    limit: 20,
  }
);
// records.data[].id, records.data[].coin, records.data[].amount, records.data[].status, records.data[].receiver

追加リソース

パラメーターの詳しい説明とレスポンススキーマについては、api-reference.mdを参照してください。

---

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

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

書き込み操作（POST による資産振替および内部振替）では、prod-live で CONFIRM が必要です。読み取り専用の照会では不要です。

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

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

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

何を行いますか？

• ファンドアカウントの残高を確認する
• 資産概要を表示する（すべてのアカウント種別）
• アカウント間で資産を振り替える（例：現物 ↔ 先物）
• 資産振替履歴を表示する
• 別の BingX ユーザーに内部振替を送る
• 内部振替履歴を表示する

ステップ 2 — 操作に応じた詳細情報の収集

資産振替の場合：

1. 振替方向を尋ねます：

   振替方向：

   • 現物 → 無期限先物（FUND_PFUTURES）
   • 無期限先物 → 現物（PFUTURES_FUND）
   • 現物 → 標準契約（FUND_SFUTURES）
   • 標準契約 → 現物（SFUTURES_FUND）
   • 標準契約 → 無期限先物（SFUTURES_PFUTURES）
   • 無期限先物 → 標準契約（PFUTURES_SFUTURES）

2. コイン（例：USDT）と数量を尋ねます。

内部振替の場合：

1. コインと数量を尋ねます。
2. 受取人のアカウント種別を尋ねます：

   受取人の識別子：

   • 1 — UID
   • 2 — 電話番号
   • 3 — メールアドレス

3. 受取人のアカウント情報（UID／電話番号／メールアドレス）を尋ねます。
4. 電話番号の場合は、国番号（例：中国の86）を尋ねます。
5. 送金元のウォレットを尋ねます：

   送金元アカウント：

   • 1 — 資金アカウント
   • 2 — 標準契約アカウント

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

Production Liveで {amount} {coin} を振り替えようとしています：

• 方向：{transfer direction or recipient info}
• 送金元：{wallet type}

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

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

API 呼び出しを実行し、主な結果フィールドをユーザーに返します：

• 資産振替：tranId
• 内部振替：id（内部振替レコード ID）
• 残高照会：free と locked の残高を含む資産一覧
• 資産概要：USDT 換算額を含むアカウント種別の一覧