bingx-standard-trade

BingX Standard Contract Trading

BingX 標準コントラクト（標準先物）データを取得するための認証済みエンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

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

---

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/contract/v1/allPosition	GET	現在のポジションを照会	はい
/openApi/contract/v1/allOrders	GET	過去の注文を照会	はい
/openApi/contract/v1/balance	GET	標準コントラクトの残高を照会	はい

---

1. ポジションを照会

GET /openApi/contract/v1/allPosition

標準コントラクト口座の現在のすべてのポジションを照会します。

パラメーター： 共通の署名パラメーター（timestamp、recvWindow）以外に追加のパラメーターはありません。

レスポンス data（配列）：

フィールド	型	説明
symbol	string	取引ペア（例：BTC-USDT）
initialMargin	number	証拠金
leverage	number	レバレッジ
unrealizedProfit	number	未実現損益
isolated	bool	true = 分離マージンモード
entryPrice	number	平均建値
positionSide	string	ポジションの方向：LONG または SHORT
positionAmt	number	ポジション数量
currentPrice	number	現在価格
time	int64	建玉時刻（ms）

---

2. 過去の注文を照会

GET /openApi/contract/v1/allOrders

標準コントラクト取引ペアの過去の注文を照会します。

パラメーター：

パラメーター	型	必須	説明
symbol	string	はい	取引ペア（例：BTC-USDT）
orderId	int64	いいえ	注文 ID フィルター
startTime	int64	いいえ	開始時刻（ミリ秒）
endTime	int64	いいえ	終了時刻（ミリ秒）
limit	int64	いいえ	件数（任意）
recvWindow	int64	いいえ	リクエストの有効期間（ミリ秒）

レスポンス data（配列）：

フィールド	型	説明
orderId	number	システム注文 ID
symbol	string	取引ペア
positionSide	string	ポジションの方向：LONG または SHORT
status	string	注文ステータス（例：CLOSED）
avgPrice	number	平均約定価格
cumQuote	number	取引金額
executedQty	number	約定数量
margin	number	証拠金
leverage	number	レバレッジ
isolated	bool	true = 分離マージンモード
closePrice	number	決済価格
positionId	int64	ポジション ID
time	int64	注文時刻（ms）
updateTime	int64	最終更新時刻（ms）

---

3. 標準コントラクトの残高を照会

GET /openApi/contract/v1/balance

標準コントラクト口座の残高を照会します。

パラメーター： 共通の署名パラメーター（timestamp、recvWindow）以外に追加のパラメーターはありません。

レスポンス data：

フィールド	型	説明
asset	string	資産名
balance	string	総残高
crossWalletBalance	string	クロスマージンのウォレット残高
crossUnPnl	string	クロスマージンの未実現損益
availableBalance	string	注文に使用可能な残高
maxWithdrawAmount	string	最大振替可能額
marginAvailable	bool	証拠金として使用可能かどうか
updateTime	number	最終更新タイムスタンプ

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

• symbol：^[A-Z0-9]+-[A-Z]+$ に一致する必要があります。最大20文字です（例：BTC-USDT）
• orderId：指定する場合は、正の整数である必要があります
• startTime / endTime：ミリ秒単位のUnixタイムスタンプです。endTime は startTime 以上である必要があります
• limit：正の整数です
• 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 positions = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/contract/v1/allPosition"
);
// positions[].symbol, positions[].positionAmt, positions[].unrealizedProfit, positions[].entryPrice

BTC-USDT の過去の注文を照会：

const orders = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/contract/v1/allOrders", { symbol: "BTC-USDT", limit: 50 }
);
// orders[].orderId, orders[].status, orders[].avgPrice, orders[].executedQty

口座残高を照会：

const balance = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/contract/v1/balance"
);
// balance.balance, balance.availableBalance, balance.crossUnPnl

追加リソース

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

---

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

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

標準取引エンドポイントはすべて読み取り専用（GET）です。アカウントの状態を変更することはないため、CONFIRM は不要です。

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

ステップ 1 — 照会内容を特定する

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

照会する情報の種類を選択してください：

• 現在のポジション／未実現損益 — positions
• 過去の注文 — allOrders
• 口座残高／利用可能証拠金 — balance

ステップ 2 — パラメーターを収集する

allOrders では、symbol が必須です。ユーザーが特定のコインについて尋ねた場合は、銘柄を推測してください（例：「BTC の注文」→ BTC-USDT）。startTime、endTime、limit は省略可能なフィルターです。

allPosition と balance では、パラメーターは不要です。

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

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

• positions：ポジションごとに、symbol、side、amount、entry price、未実現損益、レバレッジを表で表示します。
• allOrders：注文 ID、symbol、side、ステータス、平均約定価格、数量、時刻を表で表示します。
• balance：合計残高、利用可能残高、クロスの未実現損益を表示します。