bingx-coinm-trade

BingX Coin-M (CSwap) 取引

BingX Coin-M インバース無期限先物の認証済み取引エンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

Coin-M 契約はコインマージン（基軸資産（例：BTC）で決済）です。シンボル形式は BASE-USD（例：BTC-USD、ETH-USD）です。

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

---

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/cswap/v1/trade/order	POST	新しい注文を発注	必要
/openApi/cswap/v1/trade/cancelOrder	DELETE	注文をキャンセル	必要
/openApi/cswap/v1/trade/allOpenOrders	POST	シンボルのすべての未約定注文をキャンセル	必要
/openApi/cswap/v1/trade/closeAllPositions	POST	すべてのポジションを決済	必要
/openApi/cswap/v1/trade/openOrders	GET	未約定注文を照会	必要
/openApi/cswap/v1/trade/orderDetail	GET	ID を指定して単一の注文を照会	必要
/openApi/cswap/v1/trade/orderHistory	GET	過去の注文を照会	必要
/openApi/cswap/v1/trade/allFillOrders	GET	取引約定履歴を照会	必要
/openApi/cswap/v1/trade/forceOrders	GET	強制決済／ADL 注文を照会	必要
/openApi/cswap/v1/trade/leverage	GET	現在のレバレッジを照会	必要
/openApi/cswap/v1/trade/leverage	POST	レバレッジを設定	必要
/openApi/cswap/v1/trade/marginType	GET	マージンタイプを照会	必要
/openApi/cswap/v1/trade/marginType	POST	マージンタイプを設定（ISOLATED/CROSSED）	必要
/openApi/cswap/v1/trade/positionMargin	POST	分離マージンのポジションを調整	必要
/openApi/cswap/v1/user/commissionRate	GET	取引手数料率を照会	必要
/openApi/cswap/v1/user/balance	GET	口座資産を照会	必要
/openApi/cswap/v1/user/positions	GET	現在のポジションを照会	必要

---

パラメーター

注文パラメーター

• symbol：BASE-USD 形式の取引ペア（例：BTC-USD、ETH-USD）。注：Coin-M では USDT ではなく USD を使用します。
• side：注文方向 — BUY または SELL
• positionSide：ポジション方向 — LONG または SHORT（ヘッジモード）／BOTH（ワンウェイモード）
• type：注文タイプ（列挙値を参照）
• quantity：コントラクト単位の注文数量（整数。例：1 コントラクト = 名目価値 $10）
• price：指値価格（LIMIT タイプで必須）
• stopPrice：トリガー価格（STOP_MARKET、STOP、TAKE_PROFIT_MARKET、TAKE_PROFIT タイプで必須）
• timeInForce：GTC | IOC | FOK | PostOnly — デフォルトは GTC。LIMIT タイプで必須
• clientOrderId：カスタム注文 ID、1～40 文字
• recvWindow：リクエストの有効期間（ミリ秒、最大 60000）
• orderId：システム注文 ID（キャンセル／照会操作用）
• workingType：条件付き注文の価格ソース — MARK_PRICE または CONTRACT_PRICE（デフォルト）
• stopGuaranteed：true | false — ストップロスの執行が保証されるかどうか
• closePosition：true | false — トリガー時にポジション全体を決済します。quantity と併用できません
• reduceOnly：true | false — ポジションサイズを減らすことのみ可能な注文
• takeProfit：JSON 文字列のクエリパラメーター — MARKET／LIMIT 注文にテイクプロフィットを付加します。ネストされたオブジェクトを検証してから、JSON.stringify を厳密に 1 回だけ呼び出してください。
• stopLoss：JSON 文字列のクエリパラメーター — MARKET／LIMIT 注文にストップロスを付加します。ネストされたオブジェクトを検証してから、JSON.stringify を厳密に 1 回だけ呼び出してください。

ポジションパラメーター

• leverage：整数のレバレッジ倍率（例：10、20）
• marginType：ISOLATED または CROSSED
• positionSide：LONG または SHORT（positionMargin および leverage の SET で使用）
• amount：基軸資産単位のマージン調整額（positionMargin で使用）
• direction_type：1（マージンを追加）または 2（マージンを減額）（positionMargin で使用）

列挙型

type（注文タイプ）：

• MARKET — 成行注文。ここに stopLoss／takeProfit オブジェクトを付加します
• LIMIT — 指値注文。price と timeInForce が必要です。ここに stopLoss／takeProfit オブジェクトを付加します
• STOP_MARKET — ストップロス成行注文（stopPrice で発動し、成行で執行されます）
• STOP — ストップロス指値注文（stopPrice で発動し、price で指値執行されます）
• TAKE_PROFIT_MARKET — テイクプロフィット成行注文（stopPrice で発動し、成行で執行されます）
• TAKE_PROFIT — テイクプロフィット指値注文（stopPrice で発動し、price で指値執行されます）

side：BUY | SELL

positionSide：LONG | SHORT | BOTH

marginType：ISOLATED | CROSSED

timeInForce：GTC | IOC | FOK | PostOnly

workingType：MARK_PRICE | CONTRACT_PRICE

ストップロス／テイクプロフィットオブジェクト

MARKET または LIMIT 注文に stopLoss または takeProfit を付加する場合：

{
  "takeProfit": {
    "type": "TAKE_PROFIT_MARKET",
    "stopPrice": 75000,
    "workingType": "MARK_PRICE",
    "stopGuaranteed": false
  },
  "stopLoss": {
    "type": "STOP_MARKET",
    "stopPrice": 60000,
    "workingType": "MARK_PRICE",
    "stopGuaranteed": false
  }
}

外側の stopLoss と takeProfit の値は、JSON 文字列を含むクエリパラメーターです。その JSON 内では、stopPrice と省略可能な price は引用符で囲まれた数値文字列ではなく、JSON の数値である必要があります。

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

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

• symbol：^[A-Z0-9]+-USD$ に一致する必要があります。最大 20 文字です（例：BTC-USD）。Coin-M では USDT ではなく USD を使用します
• quantity：正の整数（契約数）である必要があります。各契約には固定の想定元本額があります（例：$10）
• price：指定する場合、正の数（> 0）である必要があります
• stopPrice：指定する場合、正の数（> 0）である必要があります。現在の市場価格とは異なる値にしてください
• stopLoss.stopPrice / takeProfit.stopPrice：JSON の数値が必須です。Number(...) で変換し、有限値かつ 0 より大きいことを確認してください
• stopLoss.price / takeProfit.price：省略可能な JSON の数値です。指定する場合は Number(...) で変換し、有限値かつ 0 より大きいことを確認してください
• stopLoss / takeProfit のシリアライズ：シリアライズする前に、ネストされたオブジェクトを検証してください。署名対象のクエリ値は、JSON.stringify(...) の結果と完全に一致する必要があります
• leverage：正の整数である必要があります。範囲はシンボルによって異なります（通常は 1～125）
• clientOrderId：英数字のみで、1～40 文字です。パターンは ^[a-zA-Z0-9]{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 toPositiveNumber(value: unknown, field: string): number {
  const numberValue = Number(value);
  if (!Number.isFinite(numberValue) || numberValue <= 0) {
    throw new Error(`${field} must be a finite positive number`);
  }
  return numberValue;
}
function normalizeAttachedOrder(
  key: "stopLoss" | "takeProfit", value: unknown
): string {
  let parsed: unknown = value;
  if (typeof value === "string") {
    try { parsed = JSON.parse(value); }
    catch { throw new Error(`${key} must be valid JSON`); }
  }
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
    throw new Error(`${key} must be an object or a JSON object string`);
  }
  const nested = { ...(parsed as Record<string, unknown>) };
  const allowedTypes = key === "stopLoss"
    ? new Set(["STOP_MARKET", "STOP"])
    : new Set(["TAKE_PROFIT_MARKET", "TAKE_PROFIT"]);
  if (typeof nested.type !== "string" || !allowedTypes.has(nested.type)) {
    throw new Error(`${key}.type is invalid`);
  }
  nested.stopPrice = toPositiveNumber(nested.stopPrice, `${key}.stopPrice`);
  if (nested.price !== undefined) {
    nested.price = toPositiveNumber(nested.price, `${key}.price`);
  }
  if (nested.workingType !== undefined &&
      nested.workingType !== "MARK_PRICE" &&
      nested.workingType !== "CONTRACT_PRICE") {
    throw new Error(`${key}.workingType is invalid`);
  }
  if (nested.stopGuaranteed !== undefined &&
      typeof nested.stopGuaranteed !== "boolean") {
    throw new Error(`${key}.stopGuaranteed must be a boolean`);
  }
  return JSON.stringify(nested);
}
function normalizeParams(params: Record<string, unknown>): Record<string, unknown> {
  const normalized = { ...params };
  if (normalized.price !== undefined) {
    normalized.price = toPositiveNumber(normalized.price, "price");
  }
  for (const key of ["stopLoss", "takeProfit"] as const) {
    if (normalized[key] !== undefined) {
      normalized[key] = normalizeAttachedOrder(key, normalized[key]);
    }
  }
  return normalized;
}
function serializeParamValue(value: unknown): string {
  if (value !== null && typeof value === "object") return JSON.stringify(value);
  return String(value);
}
function validateParams(params: Record<string, unknown>): void {
  const FORBIDDEN = /[&=?#\r\n]/;
  for (const [k, v] of Object.entries(params)) {
    const s = serializeParamValue(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 normalized = normalizeParams(params);
  const all = { ...normalized, timestamp: Date.now() };
  validateParams(all);
  const qs = Object.keys(all).sort()
    .map(k => `${k}=${serializeParamValue(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 チェックを削除しないでください
• 必須：タイムスタンプと署名を作成する前に、すべてのビジネスパラメーターを正規化してシリアライズしてください。パラメーターが変更された場合は、以前のタイムスタンプと署名を破棄し、新しいリクエストに署名してください
• 禁止：オブジェクトの値を ${params[k]} で直接埋め込まないでください。オブジェクトの値は JSON.stringify でシリアライズする必要があります。そうしないと [object Object] になります

一般的な呼び出し

成行買い注文を発注する（ロングを建てる）：

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/cswap/v1/trade/order", {
    symbol: "BTC-USD",
    side: "BUY",
    positionSide: "LONG",
    type: "MARKET",
    quantity: 1,
  }
);
// order.orderId, order.symbol, order.side, order.type

指値売り注文を発注する（ショートを建てる）：

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/cswap/v1/trade/order", {
    symbol: "BTC-USD",
    side: "SELL",
    positionSide: "SHORT",
    type: "LIMIT",
    quantity: 1,
    price: 75000,
    timeInForce: "GTC",
  }
);

損切り注文を付けて成行買い注文を発注する：

const rawStopPrice = "60000";
const stopPrice = Number(rawStopPrice);
if (!Number.isFinite(stopPrice) || stopPrice <= 0) {
  throw new Error("stopLoss.stopPrice must be a finite positive number");
}

const order = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/cswap/v1/trade/order", {
    symbol: "BTC-USD",
    side: "BUY",
    positionSide: "LONG",
    type: "MARKET",
    quantity: 1,
    stopLoss: JSON.stringify({
      type: "STOP_MARKET",
      stopPrice,
      workingType: "MARK_PRICE",
    }),
  }
);

注文をキャンセルする：

await fetchSigned("prod-live", API_KEY, SECRET, "DELETE",
  "/openApi/cswap/v1/trade/cancelOrder", {
    symbol: "BTC-USD",
    orderId: 1809841379603398656,
  }
);

銘柄のすべての未約定注文をキャンセルする：

await fetchSigned("prod-live", API_KEY, SECRET, "DELETE",
  "/openApi/cswap/v1/trade/allOpenOrders", {
    symbol: "BTC-USD",
  }
);

未約定注文を照会する：

const data = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/cswap/v1/trade/openOrders", {
    symbol: "BTC-USD",
  }
);
// data.orders: array of open order objects

レバレッジを設定する：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/cswap/v1/trade/leverage", {
    symbol: "BTC-USD",
    side: "LONG",
    leverage: 10,
  }
);

証拠金タイプを設定する：

await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/cswap/v1/trade/marginType", {
    symbol: "BTC-USD",
    marginType: "ISOLATED",
  }
);

手数料率を照会する：

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

追加リソース

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

---

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

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

prod-live でのすべての書き込み操作には CONFIRM が必要です。読み取り専用の照会には必要ありません。

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

注： Coin-M の銘柄形式は BASE-USD です（例：BTC-USD）。BASE-USDT ではありません。

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

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

どの操作を行いますか？

• 新しい注文を発注する
• 注文をキャンセルする／すべての注文をキャンセルする
• すべてのポジションを決済する
• 未約定注文を確認する
• 注文の詳細または履歴を照会する
• 約定を照会する
• レバレッジを設定する
• 証拠金タイプを設定する（ISOLATED / CROSSED）
• 手数料率を照会する

ステップ 2 — 銘柄を確認する（未指定の場合）

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

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

ステップ 3 — 売買方向を確認する（注文発注の場合）

注文の方向：

• BUY
• SELL

ステップ 4 — positionSide を確認する

ポジションの方向：

• LONG（ロングを建てる／追加する）
• SHORT（ショートを建てる／追加する）
• BOTH（ワンウェイモード）

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

注文タイプ：

• MARKET — 市場価格ですぐに執行
• LIMIT — 指定価格で執行（price と timeInForce が必要）
• STOP_MARKET — 損切り成行注文（stopPrice で発動）
• STOP — 損切り指値注文（stopPrice で発動し、price で執行）
• TAKE_PROFIT_MARKET — 利確成行注文（stopPrice で発動）
• TAKE_PROFIT — 利確指値注文（stopPrice で発動し、price で執行）

ステップ 6 — 数量と価格を確認する

• 数量はコントラクト数で尋ねてください（整数。例：1 コントラクト ≈ 想定元本 $10）。closePosition: true を使用する場合は省略します。
• タイプが LIMIT、STOP、または TAKE_PROFIT の場合は、price も尋ねてください。
• トリガーを伴うタイプの場合は、stopPrice も尋ねてください。
• タイプが MARKET または LIMIT の場合は、stopLoss および／または takeProfit オブジェクトを付加するかどうかを任意で確認してください。ネストされた数値フィールドを検証してから、正確な JSON.stringify(...) の結果を渡してください。

ステップ 7 — 確認する（prod-live のみ）

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

• 銘柄：BTC-USD
• 売買方向：BUY / LONG
• タイプ：MARKET
• 数量：1 コントラクト

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

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

API 呼び出しを実行し、注文 ID とステータスをユーザーに返してください。

---

注文キャンセルのフロー

1. 未指定の場合は、orderId（または clientOrderId）を尋ねます。
2. prod-live の場合は、CONFIRM を求めます。
3. DELETE /openApi/cswap/v1/trade/cancelOrder を実行します。

レバレッジ設定のフロー

1. 未指定の場合は、銘柄を尋ねます。
2. ポジションの方向（LONG / SHORT）を尋ねます。
3. レバレッジ値を尋ねます（例：BTC-USD の場合は 1–50）。
4. prod-live の場合は、CONFIRM を求めます。
5. POST /openApi/cswap/v1/trade/leverage を実行します。

証拠金タイプ設定のフロー

1. 未指定の場合は、銘柄を尋ねます。
2. ISOLATED または CROSSED の選択肢を提示します。
3. prod-live の場合は、CONFIRM を求めます。
4. POST /openApi/cswap/v1/trade/marginType を実行します。