bingx-copytrade-swap

BingX Copy Trade USDT-M 無期限契約

BingX Copy Trade USDT-M（USDT 建て）無期限先物の認証済みエンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

このスキルは、USDT-M 無期限先物のコピー取引における**トレーダー（シグナルプロバイダー）**側を対象としており、未決済注文の管理、ポジションの決済、TP/SL の設定、パフォーマンスデータの照会、手数料率の設定、および利用可能なコピー取引ペアの閲覧を行います。

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

注： Copy Trade USDT-M Perpetual Contracts のエンドポイントは https://bingx-api.github.io/docs-v3/#/en/Copy%20Trade/USDT-M%20Perpetual%20Contracts/ に記載されています。予期しないエラーが発生した場合は、公式ドキュメントで正確なパスを確認してください。

---

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/copyTrading/v1/swap/trace/currentTrack	GET	トレーダーの現在の（未決済）注文	はい
/openApi/copyTrading/v1/swap/trace/closeTrackOrder	POST	注文番号でポジションを決済	はい
/openApi/copyTrading/v1/swap/trace/setTPSL	POST	注文番号で利確と損切りを設定	はい
/openApi/copyTrading/v1/PFutures/traderDetail	GET	個人取引概要	はい
/openApi/copyTrading/v1/PFutures/profitHistorySummarys	GET	利益概要	はい
/openApi/copyTrading/v1/PFutures/profitDetail	GET	利益の詳細（ページ分割）	はい
/openApi/copyTrading/v1/PFutures/setCommission	POST	手数料率を設定	はい
/openApi/copyTrading/v1/PFutures/tradingPairs	GET	トレーダーがコピー取引ペアを取得	はい

---

パラメーター

注文決済パラメーター

• orderId：決済するコピー取引の注文番号（必須）
• recvWindow：リクエストの有効期間（ミリ秒）（任意、最大 60000）

TP/SL パラメーター

• orderId：TP/SL を設定するコピー取引の注文番号（必須）
• takeProfit：文字列形式の小数による利確価格（任意）
• stopLoss：文字列形式の小数による損切り価格（任意）
• recvWindow：リクエストの有効期間（ミリ秒）（任意、最大 60000）

クエリパラメーター（概要、利益、および現在の注文エンドポイントで共通）

• symbol：BASE-USDT 形式の取引ペアフィルター。例：BTC-USDT（任意）
• startTime：開始タイムスタンプ（ミリ秒）（任意）
• endTime：終了タイムスタンプ（ミリ秒）（任意）
• pageIndex：ページ番号。0 より大きい値を指定する必要があります（任意、デフォルトは 1）
• pageSize：1 ページあたりのレコード数（任意、デフォルト値はエンドポイントによって異なります）
• recvWindow：リクエストの有効期間（ミリ秒）（任意）

手数料率パラメーター

• commissionRate："0.001" のような小数の文字列形式の手数料率（必須）

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

• orderId：決済／TP-SL 操作で必須。有効な注文 ID 文字列である必要があります
• takeProfit／stopLoss：指定する場合は、文字列形式の小数で正の数（> 0）である必要があります
• symbol：指定する場合は、^[A-Z0-9]+-USDT$ に一致する必要があります（例：BTC-USDT）
• commissionRate：小数の文字列。0 以上である必要があります（例："0.001"）
• pageIndex：正の整数。0 より大きい値である必要があります
• pageSize：正の整数。0 より大きい値である必要があります。値はエンドポイントによって異なります
• startTime／endTime：ミリ秒単位の Unix タイムスタンプ。endTime は startTime 以上である必要があります
• 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 result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/swap/trace/currentTrack", {
    symbol: "BTC-USDT",
  }
);
// result.list — array of current open copy trade orders
// result.total — total count

注文番号でポジションを決済する：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/copyTrading/v1/swap/trace/closeTrackOrder", {
    orderId: "1736011869418901234",
  }
);
// result — confirmation of the close order

利確と損切りを設定する：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/copyTrading/v1/swap/trace/setTPSL", {
    orderId: "1736011869418901234",
    takeProfit: "70000",
    stopLoss:   "60000",
  }
);
// result — confirmation that TP/SL was set

個人の取引概要を照会する：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/PFutures/traderDetail"
);
// result.totalProfit, result.winRate, result.totalFollowers, etc.

指定した期間の損益概要を照会する：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/PFutures/profitHistorySummarys", {
    startTime: 1704067200000,
    endTime:   1706745600000,
  }
);
// result.netProfit, result.winRate, result.totalOrders, etc.

損益の詳細を照会する（ページネーション対応）：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/PFutures/profitDetail", {
    startTime: 1704067200000,
    endTime:   1706745600000,
    pageIndex: 1,
    pageSize:  50,
  }
);
// result.list — per-order profit breakdown
// result.total — total count

コミッション率を設定する：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/copyTrading/v1/PFutures/setCommission", {
    commissionRate: "0.001",
  }
);
// result — confirmation of commission rate update

コピートレードの取引ペアを取得する：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/PFutures/tradingPairs"
);
// result.list — array of available copy trading pair objects

追加リソース

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

---

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

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

書き込み操作（closePosition、setTPSL、setCommissionRate）を prod-live で実行する場合は、CONFIRM が必要です。すべての GET エンドポイントは読み取り専用のため、確認は不要です。

• prod-live：書き込み操作を実行する前に、ユーザーに CONFIRM と入力するよう求めてください。
• prod-vst：CONFIRM は不要です。「本番シミュレーション（VST）環境で操作しています」とユーザーに伝えてください。

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

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

何をしますか？

• 現在の未決済コピートレード注文を表示する
• ポジションを決済する（注文番号を指定）
• 注文に利確／損切りを設定する
• 個人の取引概要を表示する
• 損益概要を表示する
• 損益の詳細を表示する
• コミッション率を設定する
• 利用可能なコピートレードの取引ペアを取得する

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

ポジションの決済または TP/SL の設定の場合：

注文 ID を入力してください。

• orderId（必須）：コピートレード注文番号

TP/SL の設定では、さらに次の情報が必要です。

TP/SL 価格を入力してください（少なくとも 1 つ必要です）。

• takeProfit：利確のトリガー価格
• stopLoss：損切りのトリガー価格

コミッション率の設定の場合：

コミッション率を入力してください（例：0.1% の場合は 0.001）。

• commissionRate（必須）

損益／現在の注文の照会の場合：

シンボルや期間を指定してください（任意）。

• シンボル（例：BTC-USDT）
• 開始時刻（Unix ミリ秒）
• 終了時刻（Unix ミリ秒）

ステップ 3 — 確認する（prod-live の書き込み操作のみ）

ポジションの決済：

本番環境でコピートレードのポジションを決済しようとしています。

• 注文 ID：{orderId}

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

TP/SL の設定：

本番環境で TP/SL を設定しようとしています。

• 注文 ID：{orderId}
• 利確：{takeProfit}
• 損切り：{stopLoss}

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

コミッション率の設定：

本番環境でコミッション率を {commissionRate} に設定しようとしています。

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

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

API 呼び出しを実行し、主要なフィールドをユーザーに返します。

• ポジションを決済する場合：注文ステータスと確認の詳細
• TP/SL を設定する場合：新しい TP/SL 値の確認
• コミッション率を設定する場合：新しいレートの確認
• 取引の概要：総利益、勝率、フォロワー数、AUM
• 利益の概要：純利益、勝率、注文の総数
• 利益の詳細：注文ごとの内訳（シンボル、利益、タイムスタンプ）
• 現在の注文：未決済注文の一覧（シンボル、売買方向、サイズ、エントリー価格）
• コピー取引のペア：コピー取引で利用可能なシンボルの一覧