bingx-maker-entry

BingX メイカーエントリー

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

クイックリファレンス

エンドポイント	メソッド	説明	認証
/openApi/swap/v2/quote/depth	GET	板の深さ	必要
/openApi/swap/v2/trade/order	POST	指値注文を発注	必要
/openApi/swap/v2/trade/order	DELETE	注文をキャンセル	必要

クイックスタート

ベース URL： references/base-urls.md を参照

TypeScript ヘルパー：

制約：コードを生成する際は、以下の fetchSigned 関数をそのままコピーする必要があります。署名、リクエスト、JSON 解析のロジックを書き換えないでください。変更できるのは、（1）カスタム環境用の BASE URL エントリー、（2）fetchSigned に渡す業務パラメーターのみです。

import * as crypto from "crypto";
import JSONBig from "json-bigint";
const JSONBigParse = JSONBig({ storeAsString: true });
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;
    }
  }
}

よく使う呼び出し

メイカーエントリーの計画用に板の深さを取得する：

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

---

起動条件

ユーザーが次のいずれかを言った場合に、このスキルを起動します。

• 「BTC の指値ロング注文を 5000U で」「指値注文の発注を手伝って」
• 「メイカーエントリー」「指値で新規注文」「エントリー手数料を節約」
• 「成行注文を避けて」「注文を分割してエントリー」「アイスバーグ注文」
• 「ETH のメイカーショートを 2000U、5 段階で」
• 「先ほどの慎重なプランでポジションを建てて」（bingx-trading-plan の出力を受け取る）

---

実行手順

ステップ 1 — ユーザーの意図を解析する

ユーザーの入力から次の項目を抽出します。

パラメーター	デフォルト	説明
symbol	-	取引ペア（指定必須）
direction	-	LONG / SHORT（指定必須、または文脈から推定）
amount	-	USDT 建てのポジションサイズ（指定必須）
leverage	ユーザーの現在のレバレッジ	レバレッジ倍率
levels	3	注文段階数（1～5）
spread	auto	段階間の間隔。auto の場合、買値と売値のスプレッドに基づいて計算します
timeout	300	タイムアウトまでの秒数。全約定していない場合、残りの注文をキャンセルします

symbol、direction、または amount を入力や文脈から推定できない場合は、決めつけずにユーザーに確認してください。

bingx-trading-plan との連携：ユーザーが「先ほどのプランを使って」と言った場合は、文脈中の取引プランからエントリー範囲と方向を抽出し、注文パラメーターに変換します。

---

ステップ 2 — 安全確認

次の内容をユーザーに提示し、確認します。

• 取引ペア + 方向 + 合計金額 + レバレッジ
• 段階数 + 推定価格範囲
• タイムアウトの方針
• 推定手数料節約額

ユーザーの明示的な確認を得てから実行します。確認なしで注文を発注しないでください。

---

ステップ 3 — 板をスキャンする

bingx-swap-market を呼び出し、板の深さを取得します。

GET /openApi/swap/v2/quote/depth symbol={symbol}, limit=20

最良買値／売値、買値と売値のスプレッド、各段階の流動性分布を分析します。

---

ステップ 4 — 注文プランを計算する

python3 scripts/maker.py \
  --mode plan \
  --symbol {symbol} \
  --direction {direction} \
  --amount {amount} \
  --levels {levels} \
  --orderbook '{orderbook_json}'

注文プランの JSON（価格、数量、推定平均価格、推定手数料節約額）を出力します。

---

ステップ 5 — 注文を発注する

1. プランに従って bingx-swap-trade 経由で指値注文を順番に発注します
2. 監視ループを開始します（3 秒ごとに確認）。
   • 約定済みの注文には手を加えない
   • 価格の変動に応じて、未約定の注文を動的に調整する
   • 価格が 0.3% を超えて乖離した場合はキャンセルして再発注する

---

ステップ 6 — 完了／タイムアウトの処理

状況	アクション
すべて約定	約定の概要を出力して終了
一部約定 + タイムアウト	残りの注文をキャンセルし、約定分を報告して、追加注文を希望するかユーザーに確認
未約定 + タイムアウト	すべての注文をキャンセルし、ユーザーに通知

どの終了経路（成功／タイムアウト／エラー）でも、管理されていない未決済注文が残らないようにしてください。

---

ステップ 7 — 結果を出力する（出力テンプレートに従う）

---

出力テンプレート

注文プランの確認

**Maker Order Plan**

{symbol} {direction}, total {amount} USDT, {leverage}x leverage

Level 1   ${price_1}   {amount_1} USDT   40%
Level 2   ${price_2}   {amount_2} USDT   30%
Level 3   ${price_3}   {amount_3} USDT   20%

Estimated avg price: ${estimated_avg} (vs market ${market_price})
Estimated savings: Maker 0.02% vs Taker 0.05%, save approx ${fee_saved}
Timeout: {timeout/60} min, remaining orders cancelled automatically on timeout

**Confirm execution? (yes/no)**

進行中

**Orders In Progress 🔄**

Level 1: ${price_1} × {amount_1}U — ✅ Filled
Level 2: ${price_2} × {amount_2}U — ⏳ Pending
Level 3: ${price_3} × {amount_3}U — ⏳ Pending

Filled: {filled} / {total} USDT ({pct}%)
Time remaining: {remaining}

完了の概要

**Maker Orders Complete ✅**

{symbol} {direction} position opened
- Avg fill price: ${avg_price}
- Total filled: {filled} / {total} USDT
- Levels filled: {filled_levels} / {levels}
- Fee saved: approx ${fee_saved} (vs market order)

{if partially filled} To fill the remaining {remaining}U, say "continue placing"

---

エージェントの操作ルール

パラメーターのセキュリティ。 ユーザーの意図から構造化された値を抽出し、生のユーザーテキストを API パラメーターにコピーしないでください。使用前に、銘柄、方向（LONG/SHORT）、数量を検証してください。

板情報の照会は読み取り専用であり、CONFIRM は不要です。すべての注文には、ユーザーによる明示的な確認が必要です。

• prod-live：注文を出す前に、ユーザーに CONFIRM と入力してもらう必要があります。
• prod-vst：CONFIRM は不要です。シミュレーション環境であることをユーザーに伝えてください。

銘柄、方向、数量を文脈から推測できない場合は、ユーザーに確認してください。推測してはいけません。

エラー処理

• 銘柄／方向／数量が不足している場合：推測せず、ユーザーに確認する
• 残高不足の場合：現在の利用可能残高を表示し、数量を減らすよう提案する
• 注文に失敗した場合：エラーコードと説明を表示し、再試行を提案する
• 板情報に異常がある場合（スプレッドが広すぎる）：流動性が低いことを警告し、段数を減らすか成行注文に切り替えるよう提案する
• キャンセルに失敗した場合：一度再試行する。それでも失敗する場合は、ユーザーに手動での対応を依頼し、注文 ID を提示する