bingx-spot-account

BingX 現物アカウント

BingX 現物取引とアカウント管理の認証済みエンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

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

---

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/spot/v1/account/balance	GET	現物アカウントの資産／残高を照会	はい
/openApi/fund/v1/account/balance	GET	ファンドアカウントの残高を照会	はい
/openApi/account/v1/allAccountBalance	GET	資産の概要（すべてのアカウントタイプ）	はい
/openApi/api/asset/v1/transfer	POST	アカウント間で資産を振替	はい
/openApi/api/v3/asset/transfer	GET	資産振替記録を照会	はい
/openApi/api/v3/asset/transferRecord	GET	資産振替記録を照会（新形式）	はい
/openApi/api/asset/v1/transfer/supportCoins	GET	振替に対応するコインを照会	はい
/openApi/wallets/v1/capital/innerTransfer/apply	POST	アカウント間の内部 P2P 振替	はい
/openApi/wallets/v1/capital/innerTransfer/records	GET	メインアカウントの内部振替記録	はい

---

パラメーター

注文パラメーター

• symbol：BASE-QUOTE 形式の取引ペア（例：BTC-USDT、ETH-USDT）
• side：注文方向 — BUY または SELL
• type：注文タイプ（Enums を参照）
• quantity：ベース資産での注文数量（例：BTC-USDT の場合は 0.1）
• quoteOrderQty：クオート資産での注文数量（例：100 USDT）。両方が指定された場合は quantity が優先されます
• price：指値価格（LIMIT タイプで必須）
• stopPrice：トリガー価格（TAKE_STOP_LIMIT、TAKE_STOP_MARKET、TRIGGER_LIMIT、TRIGGER_MARKET タイプで必須）
• timeInForce：GTC | IOC | FOK | PostOnly — デフォルトは GTC。LIMIT タイプで必須
• newClientOrderId：カスタム注文 ID、1～40 文字
• recvWindow：リクエストの有効期間（ミリ秒、最大 60000）
• orderId：システム注文 ID（キャンセル／照会操作用）
• clientOrderID：カスタム注文 ID（キャンセル／照会操作用）

アカウントパラメーター

• asset / coin：資産名（例：USDT、BTC）
• amount：振替数量
• type（振替）：振替方向（TransferType enum を参照）
• accountType：資産概要のアカウントタイプ（AccountType enum を参照）

列挙型

type（注文タイプ）：

• MARKET — 成行注文（利用可能な最良価格で即時に約定します）
• LIMIT — 指値注文（price と timeInForce が必要です）
• TAKE_STOP_LIMIT — 利益確定／損切り指値注文（stopPrice と price が必要です）
• TAKE_STOP_MARKET — 利益確定／損切り成行注文（stopPrice が必要です）
• TRIGGER_LIMIT — トリガー指値注文（stopPrice と price が必要です）
• TRIGGER_MARKET — トリガー成行注文（stopPrice が必要です）

side：BUY | SELL

timeInForce：GTC | IOC | FOK | PostOnly

TransferType（資産の振替方向）：

• FUND_SFUTURES — 資金アカウント → 標準先物
• SFUTURES_FUND — 標準先物 → 資金アカウント
• FUND_PFUTURES — 資金アカウント → 無期限先物
• PFUTURES_FUND — 無期限先物 → 資金アカウント
• SFUTURES_PFUTURES — 標準先物 → 無期限先物
• PFUTURES_SFUTURES — 無期限先物 → 標準先物

CancelReplaceMode：

• STOP_ON_FAILURE — キャンセルに失敗した場合、新しい注文を中止します
• ALLOW_FAILURE — キャンセルに失敗しても新しい注文を発注します

cancelRestrictions（ステータスによるキャンセル制限）：

• NEW — 新規注文のみキャンセルします
• PENDING — 保留中の注文のみキャンセルします
• PARTIALLY_FILLED — 一部約定した注文のみキャンセルします

AccountType（資産の概要用）：

• sopt — 現物（資金アカウント）
• stdFutures — 標準先物
• coinMPerp — コインマージン無期限先物
• USDTMPerp — USDTマージン無期限先物
• copyTrading — コピー取引
• grid — グリッド取引
• eran — 資産運用
• c2c — C2Cアカウント

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

• symbol：^[A-Z0-9]+-[A-Z]+$ に一致する必要があります。最大20文字です（例：BTC-USDT）
• quantity：正の数（> 0）である必要があります。精度はシンボルによって異なります
• quoteOrderQty：指定する場合は、正の数（> 0）である必要があります
• price：指定する場合は、正の数（> 0）である必要があります
• stopPrice：指定する場合は、正の数（> 0）である必要があります
• newClientOrderId：1～40文字です。特殊文字は使用しないでください
• amount：振替の場合、正の数（> 0）である必要があります
• type：TransferType 列挙型の値のいずれかと完全に一致する必要があります
• 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 balance = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/account/balance"
);
// balance.balances[].asset, balance.balances[].free, balance.balances[].locked

資金アカウント残高を照会する：

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

すべてのアカウント残高を照会する（概要）：

const allBalances = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/account/v1/allAccountBalance"
);
// allBalances[].asset, allBalances[].balance

資産を振り替える（現物 → 無期限先物）：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/api/asset/v1/transfer", {
    type: "FUND_PFUTURES",
    asset: "USDT",
    amount: 100,
  }
);

資産振替記録を照会する：

const transfers = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/v3/asset/transferRecord", {
    type: "FUND_PFUTURES",
    startTime: 1700000000000,
    endTime: 1702731787011,
  }
);
// transfers[].asset, transfers[].amount, transfers[].type, transfers[].timestamp

振替に対応しているコインを照会する：

const coins = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/api/asset/v1/transfer/supportCoins"
);
// coins[].coin, coins[].name

追加リソース

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

---

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

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

資産の送金操作では、prod-live 環境でCONFIRMが必要です。残高や送金記録などの読み取り専用クエリでは必要ありません。

• prod-live：資産を送金する前に、ユーザーにCONFIRMと入力してもらってください。
• prod-vst：CONFIRM は不要です。ユーザーに「本番シミュレーション（VST）環境で操作しています。」と伝えてください。

ステップ 1 — 操作の特定

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

何をしますか？

• 口座残高の確認（現物／資金／全口座）
• 口座間での資産の送金
• 送金記録の照会
• 送金に対応しているコインの照会
• 内部 P2P 送金

ステップ 2 — 口座残高の照会

残高を照会する場合は、口座の種類を尋ねてください。

どの口座の残高を確認しますか？

• 現物口座の残高
• 資金口座の残高
• 全口座の概要

ステップ 3 — 資産の送金フロー

1. 送金方向を尋ねてください。

   送金方向：

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

2. asset（例：USDT）と amount を尋ねてください。
3. prod-live の場合は、CONFIRMを求めてください。
4. POST /openApi/api/asset/v1/transfer を実行してください。

ステップ 4 — 送金記録の照会

1. 必要に応じて、type（送金方向）と期間を尋ねてください。
2. GET /openApi/api/v3/asset/transferRecord を実行してください。
3. 結果を、資産、金額、種類、タイムスタンプ、ステータスの表形式で提示してください。