bingx-maker-entry

BingX Maker 入场

**基础 URL：**参见 references/base-urls.md | **身份验证：**参见 references/authentication.md

快速参考

Endpoint	Method	Description	Authentication
/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;
    }
  }
}

常见调用

获取订单簿深度，以规划 Maker 入场：

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”“帮我下限价单”
• “Maker 入场”“限价开仓”“节省入场手续费”
• “避免市价单”“拆分入场订单”“冰山订单”
• “ETH Maker 做空 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"

---

Agent 交互规则

参数安全。 从用户意图中提取结构化值——切勿将用户的原始文本直接复制到 API 参数中。使用前请验证交易品种、方向（LONG/SHORT）和数量。

查询订单簿为只读操作，无需 CONFIRM。所有下单操作都需要用户明确确认。

• prod-live：下单前要求用户输入 CONFIRM。
• prod-vst：无需 CONFIRM。告知用户当前处于模拟环境。

如果无法根据上下文推断交易品种、方向或数量，请询问用户，不要自行假设。

错误处理

• 缺少交易品种/方向/数量：询问用户，不要自行假设
• 余额不足：显示当前可用余额，并建议减少数量
• 下单失败：显示错误代码和说明，并建议重试
• 订单簿异常（价差过大）：警告用户流动性较低，并建议减少档位数量或切换为市价单
• 取消失败：重试一次；如果仍然失败，请用户手动处理并提供订单 ID