bingx-copytrade-spot

BingX Copy Trade Spot

BingX Copy Trade Spot 取引の認証済みエンドポイントです。すべてのエンドポイントで HMAC SHA256 署名認証が必要です。

このスキルでは、スポットのコピートレードにおける**トレーダー（シグナルプロバイダー）**側の操作を扱います。コピーされた買い注文で購入した資産の売却と、取引実績データの照会ができます。

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

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

---

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/copyTrading/v1/spot/trader/sellOrder	POST	買い注文番号に基づいてトレーダーがスポット資産を売却	はい
/openApi/copyTrading/v1/spot/traderDetail	GET	個人取引概要	はい
/openApi/copyTrading/v1/spot/profitHistorySummarys	GET	損益サマリー	はい
/openApi/copyTrading/v1/spot/profitDetail	GET	損益詳細	はい
/openApi/copyTrading/v1/spot/historyOrder	GET	過去の注文を照会	はい

---

パラメーター

ポジション売却パラメーター

• orderId：売却対象の買い注文 ID — 元となるコピートレードの買い注文番号（必須）
• recvWindow：リクエストの有効期間（ミリ秒）（任意、最大 60000）

クエリパラメーター（概要、損益、履歴エンドポイントで共通）

• startTime：開始タイムスタンプ（ミリ秒）（任意）
• endTime：終了タイムスタンプ（ミリ秒）（任意）
• pageIndex：ページ番号 — 0 より大きい値である必要があります（任意、デフォルトは 1）
• pageSize：1 ページあたりのレコード数（任意、デフォルト値はエンドポイントによって異なります）
• recvWindow：リクエストの有効期間（ミリ秒）（任意）

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

• orderId：売却操作で必須です。有効な買い注文 ID 文字列である必要があります
• pageIndex：正の整数で、0 より大きい値である必要があります
• pageSize：正の整数で、0 より大きい値である必要があります
• startTime / endTime：ミリ秒単位の Unix タイムスタンプです。endTime は startTime 以上である必要があります
• 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 result = await fetchSigned("prod-live", API_KEY, SECRET, "POST",
  "/openApi/copyTrading/v1/spot/trader/sellOrder", {
    orderId: "1736011869418901234",
  }
);
// result — confirmation of the sell order placed

個人取引概要の照会：

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

指定期間の損益サマリーの照会：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/spot/profitHistorySummarys", {
    startTime: 1704067200000,
    endTime:   1706745600000,
  }
);
// result — aggregated profit summary

損益詳細の照会（ページネーションあり）：

const result = await fetchSigned("prod-live", API_KEY, SECRET, "GET",
  "/openApi/copyTrading/v1/spot/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, "GET",
  "/openApi/copyTrading/v1/spot/historyOrder", {
    pageIndex: 1,
    pageSize:  50,
  }
);
// result.list — list of historical spot copy trade orders
// result.total — total count

追加リソース

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

---

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

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

売却エンドポイント（POST /openApi/copyTrading/v1/spot/trader/sellOrder）は書き込み操作であり、prod-live ではCONFIRMが必要です。すべての GET エンドポイントは読み取り専用で、確認は不要です。

• prod-live：売却操作を実行する前に、ユーザーにCONFIRMと入力するよう求めてください。
• prod-vst：CONFIRM は不要です。ユーザーに「Production Simulated（VST）環境で操作しています。」と伝えてください。

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

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

何をしますか？

• コピー取引の買い注文に基づいて現物資産を売却する
• 自分の取引概要を表示する
• 利益の概要を表示する
• 利益の詳細を表示する
• 過去の注文を表示する

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

売却操作の場合：

売却する買い注文の ID を入力してください。

• orderId（必須）：元となるコピー取引の買い注文番号

利益／履歴の照会の場合：

期間を指定してください（任意）。

• 開始時刻（Unix ミリ秒）
• 終了時刻（Unix ミリ秒）

ステップ 3 — 確認する（prod-live での売却のみ）

Production Liveで現物資産を売却しようとしています。

• 注文 ID：{orderId}

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

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

API 呼び出しを実行し、主なフィールドをユーザーに返してください。

• 売却の場合：注文ステータスと確認の詳細
• 概要の場合：総利益、勝率、取引件数
• 利益の概要の場合：集計された利益額
• 利益の詳細の場合：銘柄、利益、タイムスタンプを含む注文ごとの内訳
• 過去の注文の場合：ステータスと約定の詳細を含む注文リスト