bingx-spot-trade

BingX スポット取引

BingX スポット市場の認証済み取引エンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

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

---

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/spot/v1/trade/order	POST	単一注文を発注	はい
/openApi/spot/v1/trade/batchOrders	POST	複数の注文を発注（最大 5 件）	はい
/openApi/spot/v1/trade/cancel	POST	注文をキャンセル	はい
/openApi/spot/v1/trade/cancelOrders	POST	複数の注文をキャンセル	はい
/openApi/spot/v1/trade/cancelOpenOrders	POST	指定したシンボルのすべての未約定注文をキャンセル	はい
/openApi/spot/v1/trade/cancelAllAfter	POST	自動キャンセルのカウントダウン（キルスイッチ）	はい
/openApi/spot/v1/trade/order/cancelReplace	POST	注文をキャンセルして置き換え	はい
/openApi/spot/v1/trade/query	GET	注文の詳細を照会	はい
/openApi/spot/v1/trade/openOrders	GET	現在の未約定注文を照会	はい
/openApi/spot/v1/trade/historyOrders	GET	注文履歴を照会	はい
/openApi/spot/v1/trade/myTrades	GET	取引の詳細（約定）を照会	はい
/openApi/spot/v1/user/commissionRate	GET	取引手数料率を照会	はい
/openApi/spot/v1/oco/order	POST	OCO 注文を作成	はい
/openApi/spot/v1/oco/cancel	POST	OCO 注文をキャンセル	はい
/openApi/spot/v1/oco/orderList	GET	OCO 注文リストを照会	はい
/openApi/spot/v1/oco/openOrderList	GET	すべての未約定 OCO 注文を照会	はい
/openApi/spot/v1/oco/historyOrderList	GET	OCO 注文履歴リストを照会	はい

---

パラメーター

注文パラメーター

• symbol：BASE-QUOTE 形式の取引ペア（例：BTC-USDT、ETH-USDT）
• side：注文方向 — BUY または SELL
• type：注文タイプ（列挙値を参照）
• quantity：ベース資産での注文数量（例：BTC-USDT の場合は BTC を 0.1）
• quoteOrderQty：クオート資産での注文金額（例：100 USDT）。両方が指定された場合は quantity が優先されます
• price：指値価格（LIMIT、TAKE_STOP_LIMIT、TRIGGER_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（キャンセル／照会用）

列挙値

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

cancelReplaceMode：

• STOP_ON_FAILURE — キャンセル処理が失敗した場合は中止
• ALLOW_FAILURE — キャンセルが失敗しても新しい注文を発注

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

• NEW | PENDING | PARTIALLY_FILLED

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

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

• symbol：^[A-Z0-9]+-[A-Z]+$ に一致する必要があります。最大 20 文字です（例：BTC-USDT）。
• quantity：正の数（> 0）である必要があります。精度はシンボルのロットサイズフィルターによって異なります。
• quoteOrderQty：指定する場合は、正の数（> 0）である必要があります。見積もり資産の金額を表します。
• price：指定する場合は、正の数（> 0）である必要があります。
• stopPrice：指定する場合は、正の数（> 0）である必要があります。
• newClientOrderId：1～40 文字です。インジェクションとして解釈される可能性がある特殊文字は避けてください。
• 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 チェックを削除しないでください。

---

よくある呼び出し

成行買い注文を出す（100 USDT を使う）：

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/spot/v1/trade/order", {
    symbol: "BTC-USDT",
    side: "BUY",
    type: "MARKET",
    quoteOrderQty: 100,
  }
);
// order.orderId, order.status, order.executedQty, order.cummulativeQuoteQty

指値売り注文を出す：

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/spot/v1/trade/order", {
    symbol: "BTC-USDT",
    side: "SELL",
    type: "LIMIT",
    quantity: 0.001,
    price: 100000,
    timeInForce: "GTC",
  }
);

注文をキャンセルする：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/spot/v1/trade/cancel", {
    symbol: "BTC-USDT",
    orderId: 123456789,
  }
);

未約定注文を照会する：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/trade/openOrders", {
    symbol: "BTC-USDT",
  }
);
// data.orders[].orderId, data.orders[].price, data.orders[].status

注文履歴を照会する：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/trade/historyOrders", {
    symbol: "BTC-USDT",
    pageIndex: 1,
    pageSize: 20,
  }
);

注文の取引約定を照会する：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/trade/myTrades", {
    symbol: "BTC-USDT",
    orderId: 123456789,
  }
);
// data.fills[].price, data.fills[].qty, data.fills[].commission

手数料率を照会する：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/spot/v1/user/commissionRate", {
    symbol: "BTC-USDT",
  }
);
// data.takerCommissionRate, data.makerCommissionRate

追加リソース

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

---

エージェントの対話ルール

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

すべての書き込み操作（注文の発注、注文のキャンセル、OCO の作成／キャンセル）では、prod-live 上で CONFIRM が必要です。読み取り専用の照会では不要です。

• prod-live：注文の発注またはキャンセルの前に、ユーザーに CONFIRM と入力するよう求めてください。
• prod-vst：CONFIRM は不要です。「Production Simulated (VST) 環境で操作しています。」とユーザーに伝えてください。

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

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

何をしますか？

• 新しい注文を出す
• 注文をキャンセルする／すべての注文をキャンセルする
• 未約定注文を確認する
• 注文履歴を確認する
• 取引約定（取引の詳細）を確認する
• 取引手数料率を確認する
• OCO 注文（作成／キャンセル／照会）

ステップ 2 — symbol を確認する（指定されていない場合）

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

• BTC-USDT
• ETH-USDT
• SOL-USDT
• BNB-USDT
• その他（形式：BASE-USDT）

ステップ 3 — side を確認する（注文を出す場合）

注文方向：

• BUY
• SELL

ステップ 4 — 注文タイプを確認する

注文タイプ：

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

Step 5 — 数量と価格を収集する

• MARKET BUY：quoteOrderQty（使用するUSDT）またはquantity（ベース資産の数量）を尋ねます
• MARKET SELL：売却するquantity（ベース資産の数量）を尋ねます
• LIMIT：quantityとpriceを尋ねます。timeInForceを確認します（デフォルトはGTC）
• TAKE_STOP_LIMIT / TRIGGER_LIMIT：quantity、stopPrice（トリガー価格）、price（約定価格）を尋ねます
• TAKE_STOP_MARKET / TRIGGER_MARKET：quantityとstopPriceを尋ねます

Step 6 — 確認する（prod-liveのみ）

prod-liveの場合は、概要を提示して次のように尋ねます。

Production Liveで次の注文を発注しようとしています：

• シンボル：BTC-USDT
• 売買：BUY
• 種類：MARKET
• 金額：100 USDT

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

Step 7 — 実行して報告する

API呼び出しを実行し、注文ID、ステータス、約定数量をユーザーに返します。

---

注文のキャンセルフロー

1. symbolとorderId（またはclientOrderID）が指定されていない場合は、尋ねます。
2. prod-liveの場合は、CONFIRMを求めます。
3. POST /openApi/spot/v1/trade/cancelを実行します。

未約定注文をすべてキャンセルするフロー

1. symbolを尋ねます（省略可。省略するとすべての通貨ペアの注文をキャンセルします）。
2. prod-liveの場合は、CONFIRMを求めます。
3. POST /openApi/spot/v1/trade/cancelOpenOrdersを実行します。

OCO注文フロー

OCO（One-Cancels-the-Other）は指値注文とストップリミット注文を組み合わせたもので、片方が約定または発動すると、もう片方は自動的にキャンセルされます。

1. symbol、side、quantityを尋ねます。
2. limitPrice（指値注文の約定価格）を尋ねます。
3. triggerPrice（ストップリミット注文の発動価格）を尋ねます。
4. orderPrice（トリガー発動後のストップリミット注文の約定価格）を尋ねます。
5. prod-liveの場合は、CONFIRMを求めます。
6. POST /openApi/spot/v1/oco/orderを実行します。