bingx-swap-account

BingX Swap アカウント

BingX 無期限先物のアカウントデータを取得する、認証が必要な読み取り専用エンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

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

---

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/swap/v3/user/balance	GET	アカウント残高、エクイティ、証拠金情報	はい
/openApi/swap/v2/user/positions	GET	損益と清算価格を含む現在のオープンポジション	はい
/openApi/swap/v2/user/commissionRate	GET	ユーザーのテイカー／メイカー手数料率	はい
/openApi/swap/v2/user/income	GET	資金フロー履歴（損益、資金調達料、取引手数料など）	はい
/openApi/swap/v2/user/income/export	GET	資金フローを Excel ファイルとしてエクスポート	はい

---

パラメーター

共通パラメーター

• symbol：BASE-QUOTE 形式の取引ペア（例：BTC-USDT）。ほとんどのアカウントエンドポイントでは任意です。
• timestamp：リクエストのタイムスタンプ（ミリ秒）。すべての認証が必要なエンドポイントで必須です。
• recvWindow：リクエストの有効期間（ミリ秒）。任意で、最大値は 60000 です。
• startTime / endTime：期間のフィルター（ミリ秒）。income エンドポイントで使用されます。
• limit：返す結果の件数。income エンドポイントで使用されます。デフォルトは 100、最大は 1000 です。

incomeType 列挙型（income エンドポイント用）

値	説明
TRANSFER	資金移動
REALIZED_PNL	実現損益
FUNDING_FEE	資金調達料
TRADING_FEE	取引手数料
INSURANCE_CLEAR	清算
TRIAL_FUND	トライアル資金
ADL	自動デレバレッジ
SYSTEM_DEDUCTION	システム控除
GTD_PRICE	価格保証

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

• symbol：指定する場合、^[A-Z0-9]+-[A-Z]+$ に一致する必要があります。最大 20 文字です（例：BTC-USDT）。
• incomeType：指定する場合、上記の列挙値のいずれかと完全に一致する必要があります。
• startTime / endTime：Unix タイムスタンプ（ミリ秒）。endTime は startTime 以上である必要があります。
• limit：1～1000 の正の整数。デフォルトは 100 です。
• 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-bigint（JSONBigParse.parse）を使用してください。JSON.parse は使用しないでください。
• 必須：すべてのリクエストに X-SOURCE-KEY: BX-AI-SKILL ヘッダーを含めてください。
• 禁止：ドメインのフォールバックループまたは isNetworkOrTimeout チェックを削除しないでください。

---

よく使う呼び出し

アカウント残高を照会：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v3/user/balance"
);
// data.balance.balance, data.balance.equity, data.balance.availableMargin

すべてのオープンポジションを照会：

const positions = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/positions"
);
// positions[].symbol, positions[].positionAmt, positions[].unrealizedProfit, positions[].liquidationPrice

特定の銘柄のポジションを照会：

const positions = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/positions", { symbol: "BTC-USDT" }
);

ユーザーの手数料率を照会：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/commissionRate"
);
// data.commission.takerCommissionRate, data.commission.makerCommissionRate

最近の資金フローを照会（過去 7 日間、すべての種類）：

const income = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/income", { limit: 100 }
);
// income[].incomeType, income[].income, income[].asset, income[].time

期間を指定して BTC-USDT の資金調達料を照会：

const income = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/swap/v2/user/income", {
    symbol: "BTC-USDT",
    incomeType: "FUNDING_FEE",
    startTime: 1700000000000,
    endTime: 1702731787011,
    limit: 200,
  }
);

追加リソース

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

---

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

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

すべてのスワップアカウントエンドポイントは読み取り専用（GET）です。アカウントの状態を変更することはないため、どの環境でも CONFIRM は必要ありません。

認証情報が必要です。アカウントが指定されていない場合は、main アカウントをデフォルトとして使用してください。

ステップ 1 — クエリを特定する

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

クエリを実行するアカウント情報の種類を選択してください：

• アカウント残高／エクイティ／証拠金 — balance
• 現在のポジション／未実現損益／清算価格 — positions
• 取引手数料率 — commissionRate
• 資金フロー（損益／資金調達料／取引手数料など）— income
• 資金フローのエクスポート（Excel）— income/export

ステップ 2 — シンボルを収集する（該当する場合）

positions および income エンドポイントでは、シンボルは任意です。特定のコインについて尋ねられた場合は、シンボルを自動的に推定してください（例：「BTC のポジション」→ BTC-USDT）。

指定されていない場合は、すべてのシンボルをクエリし、その旨をユーザーに伝えてください。

ステップ 3 — 期間を収集する（income エンドポイントの場合）

• startTime と endTime のどちらも指定されていない場合、API は過去 7 日間のデータを返します。その旨をユーザーに伝えてください。
• 取得できるのは過去3 か月間のデータのみです。
• ユーザーが特定の期間を尋ねた場合は、ミリ秒に変換してください。

ステップ 4 — incomeType を収集する（income エンドポイントの場合）

ユーザーが種類（例：「資金調達料」「取引手数料」「損益」）を指定した場合は、正しい incomeType の列挙値に対応付けてください。

ユーザーの指定	incomeType
実現損益／損益	REALIZED_PNL
資金調達料／資金調達率	FUNDING_FEE
取引手数料／コミッション	TRADING_FEE
清算	INSURANCE_CLEAR
ADL／自動デレバレッジ	ADL
振替	TRANSFER

指定されていない場合は、すべての種類を返すために incomeType を省略してください。

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

API 呼び出しを実行し、読みやすい形式で結果を提示してください。

• balance：エクイティ、利用可能証拠金、使用済み証拠金、未実現損益を要約テーブルに表示します。
• positions：各ポジションについて、シンボル、売買方向、数量、平均価格、未実現損益、清算価格、レバレッジをテーブルに表示します。
• commissionRate：テイカーとメイカーの手数料率に 100 を掛け、パーセンテージで表示します。
• income：最近の記録を、時刻、種類、シンボル、金額、資産のテーブルに表示します。