bingx-swap-market

BingX スワップ市場データ

BingX 無期限先物の公開市場データです。API キーや HMAC 署名は不要です。取引ルールと過去の取引履歴に限り、最新の timestamp が必要です。すべてのリクエストに追加する必要はありません。非公開の取引およびアカウントエンドポイントには、引き続き認証が必要です。

クイックリファレンス

エンドポイント	メソッド	説明	必須	任意
/openApi/swap/v2/quote/contracts	GET	すべてのコントラクト仕様	なし	symbol
/openApi/swap/v1/tradingRules	GET	取引ルールと仕様	timestamp, symbol	recvWindow
/openApi/swap/v2/quote/depth	GET	板の買い注文と売り注文	symbol	limit, timestamp, recvWindow
/openApi/swap/v2/quote/trades	GET	直近の公開取引	symbol	limit, timestamp, recvWindow
/openApi/swap/v1/market/historicalTrades	GET	過去の取引履歴の取得	timestamp	symbol, limit, fromId, recvWindow
/openApi/swap/v2/quote/premiumIndex	GET	マーク価格とプレミアム指数	なし	symbol, timestamp, recvWindow
/openApi/swap/v2/quote/fundingRate	GET	現在および次回の資金調達率	なし	symbol, startTime, endTime, limit, timestamp, recvWindow
/openApi/swap/v3/quote/klines	GET	OHLCV ローソク足データ	symbol, interval	startTime, endTime, limit, timestamp, recvWindow
/openApi/swap/v1/market/markPriceKlines	GET	マーク価格のローソク足データ	symbol, interval	startTime, endTime, limit, timestamp, recvWindow
/openApi/swap/v2/quote/openInterest	GET	未決済建玉の合計	symbol	timestamp, recvWindow
/openApi/swap/v2/quote/ticker	GET	24 時間の価格変動統計	なし	symbol, timestamp, recvWindow
/openApi/swap/v1/ticker/price	GET	最新価格ティッカー	なし	symbol, timestamp, recvWindow
/openApi/swap/v2/quote/bookTicker	GET	最良買い気配／売り気配価格と数量	symbol	timestamp, recvWindow
/openApi/swap/v2/server/time	GET	サーバー時刻の照会	なし	なし

---

パラメーター

共通パラメーター

• timestamp：ミリ秒単位の現在の Unix 時刻です。取引ルールと過去の取引履歴でのみ必須で、上記に記載されている場合のみ任意です。ヘルパーは、必須となる 2 つのエンドポイント用に動的に生成します。
• symbol：BASE-QUOTE 形式の取引ペア（例：BTC-USDT、ETH-USDT、SOL-USDT）
• limit：返す結果の件数です。デフォルト値と最大値はエンドポイントによって異なります。
• startTime：ミリ秒単位の開始タイムスタンプ（例：1735693200000）
• endTime：ミリ秒単位の終了タイムスタンプ（例：1735693200000）
• interval：ローソク足の時間間隔（以下の列挙値を参照）
• recvWindow：リクエストの有効期間（ミリ秒単位。任意、デフォルトは 5000、最大は 60000）

列挙値

• interval：1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M

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

• symbol：^[A-Z0-9]+-[A-Z]+$ に一致する必要があります。最大 20 文字です（例：BTC-USDT）。
• limit：正の整数です。デフォルト値と最大値はエンドポイントによって異なります（通常は 500～1000）。
• startTime／endTime：ミリ秒単位の Unix タイムスタンプです。endTime は startTime 以上である必要があります。
• interval：上記の列挙値のいずれかと完全に一致する必要があります。
• recvWindow：整数で、1～5000 ms です（リプレイ攻撃対策を参照）。
• timestamp：ミリ秒単位の Unix 時刻です。サーバー時刻との差が recvWindow の範囲内である必要があります。

---

クイックスタート

ベース URL： references/base-urls.mdを参照してください。

TypeScript ヘルパー：

制約：コードを生成する際は、以下の fetchSwapMarket 関数をそのままコピーする必要があります。 リクエストまたは JSON の解析ロジックを書き換えないでください。 変更できるのは、（1）カスタム環境用の BASE URL エントリ、 （2）fetchSwapMarket に渡すビジネスパラメーターのみです。このヘルパーは 公開 GET 市場エンドポイント専用であり、非公開の取引 API またはアカウント API には使用できません。

import JSONBig from "json-bigint";
const JSONBigParse = JSONBig({ storeAsString: true });
// 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 fetchSwapMarket(env: string,
  path: string, params: Record<string, string | number> = {}
) {
  const urls = BASE[env] ?? BASE["prod-live"];
  const requiresTimestamp = path === "/openApi/swap/v1/tradingRules"
    || path === "/openApi/swap/v1/market/historicalTrades";
  const all = requiresTimestamp ? { ...params, timestamp: Date.now() } : { ...params };
  validateParams(all);
  const qs = new URLSearchParams(
    Object.entries(all).map(([k, v]) => [k, String(v)])
  ).toString();
  for (const base of urls) {
    try {
      const url = `${base}${path}${qs ? `?${qs}` : ""}`;
      const res = await fetch(url, {
        method: "GET",
        headers: { "X-SOURCE-KEY": "BX-AI-SKILL" },
        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;
    }
  }
}

コード使用ルール

• 必ず fetchSwapMarket をそのままコピーしてください。簡略化したり書き換えたりしないでください。
• 必ず レスポンスの解析に json-bigint（JSONBigParse.parse）を使用してください。JSON.parse は使用しないでください。
• 必ず すべてのリクエストに X-SOURCE-KEY: BX-AI-SKILL ヘッダーを含めてください。
• ドメインのフォールバックループや isNetworkOrTimeout チェックを削除してはいけません。

一般的な呼び出し

BTC-USDT の24時間ティッカー価格：

const ticker = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/ticker", { symbol: "BTC-USDT" }
);
// ticker.lastPrice, ticker.priceChangePercent, ticker.volume

板の深さ（上位20段）：

const depth = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/depth", { symbol: "BTC-USDT", limit: 20 }
);
// depth.bids: [price, qty][], depth.asks: [price, qty][]

1時間足のKライン（直近100本）：

const klines = await fetchSwapMarket("prod-live",
  "/openApi/swap/v3/quote/klines", { symbol: "BTC-USDT", interval: "1h", limit: 100 }
);
// Each item: [openTime, open, high, low, close, volume, closeTime]

現在の資金調達率：

const funding = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/fundingRate", { symbol: "BTC-USDT" }
);
// funding.fundingRate, funding.nextFundingTime

最良買値／最良売値：

const bookTicker = await fetchSwapMarket("prod-live",
  "/openApi/swap/v2/quote/bookTicker", { symbol: "BTC-USDT" }
);
// bookTicker.bidPrice, bookTicker.askPrice

取引ルールと過去の取引（ヘルパーが生成したタイムスタンプ）：

const rules = await fetchSwapMarket("prod-live",
  "/openApi/swap/v1/tradingRules", { symbol: "BTC-USDT" }
);
const historicalTrades = await fetchSwapMarket("prod-live",
  "/openApi/swap/v1/market/historicalTrades", { symbol: "BTC-USDT", limit: 10 }
);

追加リソース

パラメーターの詳しい説明、省略可能なフィールド、レスポンススキーマ全体については、api-reference.md を参照してください。

---

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

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

swap-market は読み取り専用の公開市場データを提供します。API キーを要求したり、これらのリクエストに署名したりしないでください。取引ルールと過去の取引には、引き続き動的な timestamp が必要です。CONFIRM は不要です。 やり取りの目的は、クエリパラメーターを収集することです。

操作の特定

ユーザーのリクエストが曖昧な場合（例：「市場を確認して」「BTCを見て」）、まず、どの種類のデータを照会したいのかを特定してください。

市場データの種類を選択してください：

• 価格／24時間変動 — ticker
• 最良買値／最良売値（板の最上位） — bookTicker
• 板の深さ — depth
• Kライン／ローソク足 — klines
• 資金調達率 — fundingRate
• マーク価格／プレミアムインデックス — premiumIndex
• 未決済建玉 — openInterest
• コントラクト仕様一覧 — contracts

シンボルが指定されていない場合

対象エンドポイント：depth、trades、fundingRate、klines、openInterest

取引ペアを選択してください（または別のペアを入力してください）：

• BTC-USDT
• ETH-USDT
• SOL-USDT
• BNB-USDT
• その他（手動で入力、形式：BASE-USDT）

文脈から取引ペアを推測できる場合（例：「今日のBTC市場」「Ethereumの資金調達率」）、再度質問せずに自動で推測してください。

インターバルが指定されていない場合（klines エンドポイントのみ）

Kラインのインターバルを選択してください：

• 1m（1分）
• 5m（5分）
• 15m（15分）
• 1h（1時間）
• 4h（4時間）
• 1d（1日）
• 1w（1週間）

limit の扱い

• klines：デフォルトは100です。質問する必要はありません。「デフォルトでは直近100本のKラインを返します」とユーザーに伝えてください。
• depth：デフォルトは20です。質問する必要はありません。

symbol が省略可能なエンドポイント

ticker と premiumIndex では symbol は省略可能です（省略するとすべてのコントラクトが返されます）。bookTicker では symbol が必須です。ユーザーが ticker／premiumIndex の取引ペアを指定しない場合は、すべてのコントラクトを照会してその旨を伝えてください。取引ペアが指定されている場合は、そのペアのみを照会してください。