@okx_ai/okx-trade-mcp 1.3.2 → 1.3.3-beta.1

package/dist/index.js

@@ -1816,6 +1816,16 @@ function readBoolean(args, key) {
   }
   return value;
 }
+function readStringArray(args, key) {
+  const value = args[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new ValidationError(`Parameter "${key}" must be an array of strings.`);
+  }
+  return value;
+}
 function requireString(args, key) {
   const value = readString(args, key);
   if (!value || value.length === 0) {
@@ -1856,12 +1866,170 @@ function validateSwapInstId(instId) {
     );
   }
 }
+var TP_ORD_KIND_SCHEMA = {
+  type: "string",
+  enum: ["condition", "limit"],
+  description: "condition(default)=trigger-based TP; limit=immediate limit order (no trigger phase)"
+};
+var TP_TRIGGER_PX_TYPE_SCHEMA = {
+  type: "string",
+  enum: ["last", "index", "mark"],
+  description: "TP trigger price source: last(default)|index|mark"
+};
+var SL_TRIGGER_PX_TYPE_SCHEMA = {
+  type: "string",
+  enum: ["last", "index", "mark"],
+  description: "SL trigger price source: last(default)|index|mark"
+};
+var STP_MODE_SCHEMA = {
+  type: "string",
+  enum: ["cancel_maker", "cancel_taker", "cancel_both"],
+  description: "Self-trade prevention: cancel_maker|cancel_taker|cancel_both"
+};
+var CXL_ON_CLOSE_POS_SCHEMA = {
+  type: "boolean",
+  description: "Auto-cancel TP/SL when associated position closes (algo only)"
+};
+var PHASE1_PLACE_FLAGS_SCHEMA = {
+  tpOrdKind: TP_ORD_KIND_SCHEMA,
+  tpTriggerPxType: TP_TRIGGER_PX_TYPE_SCHEMA,
+  slTriggerPxType: SL_TRIGGER_PX_TYPE_SCHEMA,
+  stpMode: STP_MODE_SCHEMA
+};
+var PHASE1_ALGO_FLAGS_SCHEMA = {
+  ...PHASE1_PLACE_FLAGS_SCHEMA,
+  cxlOnClosePos: CXL_ON_CLOSE_POS_SCHEMA
+};
+var TRIGGER_FLAGS_SCHEMA = {
+  triggerPx: {
+    type: "string",
+    description: "Activation price; order submits when market hits this level (trigger only)"
+  },
+  orderPx: {
+    type: "string",
+    description: "Order price submitted when trigger fires; -1=market (trigger only)"
+  },
+  advanceOrdType: {
+    type: "string",
+    enum: ["fok", "ioc"],
+    description: "Execution qualifier for triggered order: fok=fill-or-kill, ioc=immediate-or-cancel (trigger only)"
+  },
+  triggerPxType: {
+    type: "string",
+    enum: ["last", "index", "mark"],
+    description: "Price type used to evaluate trigger: last(default)|index|mark (trigger only)"
+  }
+};
+var CHASE_FLAGS_SCHEMA = {
+  chaseType: {
+    type: "string",
+    enum: ["distance", "ratio"],
+    description: "Chase unit: distance=price ticks, ratio=proportion of price (chase only, default distance)"
+  },
+  chaseVal: {
+    type: "string",
+    description: "Chase amount matching chaseType (e.g. 0.5 ticks for distance, 0.001 for ratio) (chase only)"
+  },
+  maxChaseType: {
+    type: "string",
+    enum: ["distance", "ratio"],
+    description: "Upper-bound unit for chase (chase only)"
+  },
+  maxChaseVal: {
+    type: "string",
+    description: "Upper-bound value for chase (chase only)"
+  }
+};
+var ICEBERG_TWAP_FLAGS_SCHEMA = {
+  pxVar: {
+    type: "string",
+    description: "Price variance % [0.0001, 0.01]; provide pxVar OR pxSpread (iceberg/twap only)"
+  },
+  pxSpread: {
+    type: "string",
+    description: "Price variance constant >= 0; provide pxVar OR pxSpread (iceberg/twap only)"
+  },
+  szLimit: {
+    type: "string",
+    description: "Average per-child-order size (iceberg/twap only)"
+  },
+  pxLimit: {
+    type: "string",
+    description: "Order price ceiling >= 0 (iceberg/twap only)"
+  },
+  timeInterval: {
+    type: "string",
+    description: "Seconds between child orders (iceberg/twap only)"
+  }
+};
+function buildTriggerOrdTypeBody(args) {
+  return compactObject({
+    triggerPx: readString(args, "triggerPx"),
+    orderPx: readString(args, "orderPx"),
+    advanceOrdType: readString(args, "advanceOrdType"),
+    triggerPxType: readString(args, "triggerPxType"),
+    attachAlgoOrds: buildAttachAlgoOrds(args)
+  });
+}
+function buildChaseOrdTypeBody(args) {
+  return compactObject({
+    chaseType: readString(args, "chaseType"),
+    chaseVal: readString(args, "chaseVal"),
+    maxChaseType: readString(args, "maxChaseType"),
+    maxChaseVal: readString(args, "maxChaseVal")
+  });
+}
+function buildIcebergTwapOrdTypeBody(args) {
+  return compactObject({
+    pxVar: readString(args, "pxVar"),
+    pxSpread: readString(args, "pxSpread"),
+    szLimit: readString(args, "szLimit"),
+    pxLimit: readString(args, "pxLimit"),
+    timeInterval: readString(args, "timeInterval")
+  });
+}
+function buildAlgoConditionalCommonFields(args) {
+  return {
+    tpTriggerPx: readString(args, "tpTriggerPx"),
+    tpOrdPx: readString(args, "tpOrdPx"),
+    tpOrdKind: readString(args, "tpOrdKind"),
+    tpTriggerPxType: readString(args, "tpTriggerPxType"),
+    tpTriggerRatio: readString(args, "tpTriggerRatio"),
+    slTriggerPx: readString(args, "slTriggerPx"),
+    slOrdPx: readString(args, "slOrdPx"),
+    slTriggerPxType: readString(args, "slTriggerPxType"),
+    slTriggerRatio: readString(args, "slTriggerRatio"),
+    closeFraction: readString(args, "closeFraction"),
+    activePx: readString(args, "activePx")
+  };
+}
 function buildAttachAlgoOrds(source) {
+  const tpLevels = source["tpLevels"];
+  if (Array.isArray(tpLevels) && tpLevels.length > 0) {
+    return tpLevels.map(
+      (level) => compactObject(level)
+    );
+  }
   const tpTriggerPx = readString(source, "tpTriggerPx");
   const tpOrdPx = readString(source, "tpOrdPx");
   const slTriggerPx = readString(source, "slTriggerPx");
   const slOrdPx = readString(source, "slOrdPx");
-  const entry = compactObject({ tpTriggerPx, tpOrdPx, slTriggerPx, slOrdPx });
+  const tpOrdKind = readString(source, "tpOrdKind");
+  const tpTriggerPxType = readString(source, "tpTriggerPxType");
+  const slTriggerPxType = readString(source, "slTriggerPxType");
+  const tpTriggerRatio = readString(source, "tpTriggerRatio");
+  const slTriggerRatio = readString(source, "slTriggerRatio");
+  const entry = compactObject({
+    tpTriggerPx,
+    tpOrdPx,
+    slTriggerPx,
+    slOrdPx,
+    tpOrdKind,
+    tpTriggerPxType,
+    slTriggerPxType,
+    tpTriggerRatio,
+    slTriggerRatio
+  });
   return Object.keys(entry).length > 0 ? [entry] : void 0;
 }
 var OKX_CANDLE_BARS = [
@@ -2908,7 +3076,7 @@ function registerAlgoTradeTools() {
     {
       name: "swap_place_algo_order",
       module: "swap",
-      description: "Place a SWAP/FUTURES algo order: TP/SL (conditional/oco) or trailing stop (move_order_stop). [CAUTION] Executes real trades. conditional: single TP, single SL, or both on one order. oco: TP+SL simultaneously \u2014 first trigger cancels the other. move_order_stop: provide callbackRatio (e.g. '0.01'=1%) OR callbackSpread, and optionally activePx. Set tpOrdPx='-1' or slOrdPx='-1' for market execution.",
+      description: "Place a SWAP/FUTURES algo order. [CAUTION] Executes real trades. conditional: single TP, single SL, or both on one order. oco: TP+SL simultaneously \u2014 first trigger cancels the other. move_order_stop: trailing stop (callbackRatio or callbackSpread). trigger: pending order activated when triggerPx is hit (provide triggerPx + orderPx). chase: smart-follow best bid/ask. iceberg: split large order into child orders at intervals. twap: time-weighted average price order splitting.",
       isWrite: true,
       inputSchema: {
         type: "object",
@@ -2934,8 +3102,8 @@ function registerAlgoTradeTools() {
           },
           ordType: {
             type: "string",
-            enum: ["conditional", "oco", "move_order_stop"],
-            description: "conditional=single TP/SL or both; oco=TP+SL pair (first trigger cancels other); move_order_stop=trailing stop"
+            enum: ["conditional", "oco", "move_order_stop", "trigger", "chase", "iceberg", "twap"],
+            description: "conditional=single TP/SL or both; oco=TP+SL pair; move_order_stop=trailing stop; trigger=pending order; chase=follow best bid/ask; iceberg=split order; twap=time-weighted split"
           },
           sz: {
             type: "string",
@@ -2949,11 +3117,8 @@ function registerAlgoTradeTools() {
             type: "string",
             description: "TP order price; -1=market (conditional/oco only)"
           },
-          tpTriggerPxType: {
-            type: "string",
-            enum: ["last", "index", "mark"],
-            description: "last(default)|index|mark (conditional/oco only)"
-          },
+          tpOrdKind: TP_ORD_KIND_SCHEMA,
+          tpTriggerPxType: TP_TRIGGER_PX_TYPE_SCHEMA,
           slTriggerPx: {
             type: "string",
             description: "SL trigger price (conditional/oco only)"
@@ -2962,11 +3127,9 @@ function registerAlgoTradeTools() {
             type: "string",
             description: "SL order price; -1=market (recommended) (conditional/oco only)"
           },
-          slTriggerPxType: {
-            type: "string",
-            enum: ["last", "index", "mark"],
-            description: "last(default)|index|mark (conditional/oco only)"
-          },
+          slTriggerPxType: SL_TRIGGER_PX_TYPE_SCHEMA,
+          stpMode: STP_MODE_SCHEMA,
+          cxlOnClosePos: CXL_ON_CLOSE_POS_SCHEMA,
           callbackRatio: {
             type: "string",
             description: "Callback ratio (e.g. '0.01'=1%); provide either ratio or spread (move_order_stop only)"
@@ -2979,6 +3142,9 @@ function registerAlgoTradeTools() {
             type: "string",
             description: "Activation price; tracking starts after market reaches this level (move_order_stop only)"
           },
+          ...TRIGGER_FLAGS_SCHEMA,
+          ...CHASE_FLAGS_SCHEMA,
+          ...ICEBERG_TWAP_FLAGS_SCHEMA,
           tgtCcy: {
             type: "string",
             enum: ["base_ccy", "quote_ccy", "margin"],
@@ -2998,6 +3164,8 @@ function registerAlgoTradeTools() {
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
         const reduceOnly = args.reduceOnly;
+        const cxlOnClosePos = args.cxlOnClosePos;
+        const ordType = requireString(args, "ordType");
         const resolved = await resolveQuoteCcySz(
           requireString(args, "instId"),
           requireString(args, "sz"),
@@ -3006,29 +3174,44 @@ function registerAlgoTradeTools() {
           context.client,
           readString(args, "tdMode")
         );
+        const base = compactObject({
+          instId: requireString(args, "instId"),
+          tdMode: requireString(args, "tdMode"),
+          side: requireString(args, "side"),
+          posSide: readString(args, "posSide"),
+          ordType,
+          sz: resolved.sz,
+          tgtCcy: resolved.tgtCcy,
+          stpMode: readString(args, "stpMode"),
+          cxlOnClosePos: typeof cxlOnClosePos === "boolean" ? String(cxlOnClosePos) : void 0,
+          reduceOnly: typeof reduceOnly === "boolean" ? String(reduceOnly) : void 0,
+          clOrdId: readString(args, "clOrdId"),
+          // Phase 3a+c CLI power-user flags (issue #182, CLI-only no MCP/skill exposure)
+          pxAmendType: readString(args, "pxAmendType"),
+          tag: context.config.sourceTag
+        });
+        switch (ordType) {
+          case "trigger":
+            Object.assign(base, buildTriggerOrdTypeBody(args));
+            break;
+          case "chase":
+            Object.assign(base, buildChaseOrdTypeBody(args));
+            break;
+          case "iceberg":
+          case "twap":
+            Object.assign(base, buildIcebergTwapOrdTypeBody(args));
+            break;
+          default:
+            Object.assign(base, compactObject({
+              ...buildAlgoConditionalCommonFields(args),
+              callBackRatio: readString(args, "callbackRatio"),
+              callBackSpread: readString(args, "callbackSpread")
+            }));
+            break;
+        }
         const response = await context.client.privatePost(
           "/api/v5/trade/order-algo",
-          compactObject({
-            instId: requireString(args, "instId"),
-            tdMode: requireString(args, "tdMode"),
-            side: requireString(args, "side"),
-            posSide: readString(args, "posSide"),
-            ordType: requireString(args, "ordType"),
-            sz: resolved.sz,
-            tgtCcy: resolved.tgtCcy,
-            tpTriggerPx: readString(args, "tpTriggerPx"),
-            tpOrdPx: readString(args, "tpOrdPx"),
-            tpTriggerPxType: readString(args, "tpTriggerPxType"),
-            slTriggerPx: readString(args, "slTriggerPx"),
-            slOrdPx: readString(args, "slOrdPx"),
-            slTriggerPxType: readString(args, "slTriggerPxType"),
-            callBackRatio: readString(args, "callbackRatio"),
-            callBackSpread: readString(args, "callbackSpread"),
-            activePx: readString(args, "activePx"),
-            reduceOnly: typeof reduceOnly === "boolean" ? String(reduceOnly) : void 0,
-            clOrdId: readString(args, "clOrdId"),
-            tag: context.config.sourceTag
-          }),
+          base,
           privateRateLimit("swap_place_algo_order", 20)
         );
         const result = normalizeResponse(response);
@@ -3253,7 +3436,7 @@ function registerFuturesAlgoTools() {
     {
       name: "futures_place_algo_order",
       module: "futures",
-      description: "Place a FUTURES delivery algo order: TP/SL (conditional/oco) or trailing stop (move_order_stop). [CAUTION] Executes real trades. conditional: single TP, single SL, or both on one order. oco: TP+SL simultaneously \u2014 first trigger cancels the other. move_order_stop: provide callbackRatio (e.g. '0.01'=1%) OR callbackSpread, and optionally activePx. Set tpOrdPx='-1' or slOrdPx='-1' for market execution.",
+      description: "Place a FUTURES delivery algo order. [CAUTION] Executes real trades. conditional: single TP, single SL, or both on one order. oco: TP+SL simultaneously \u2014 first trigger cancels the other. move_order_stop: trailing stop (callbackRatio or callbackSpread). trigger: pending order activated when triggerPx is hit (provide triggerPx + orderPx). chase: smart-follow best bid/ask. iceberg: split large order into child orders at intervals. twap: time-weighted average price order splitting.",
       isWrite: true,
       inputSchema: {
         type: "object",
@@ -3279,8 +3462,8 @@ function registerFuturesAlgoTools() {
           },
           ordType: {
             type: "string",
-            enum: ["conditional", "oco", "move_order_stop"],
-            description: "conditional=single TP/SL or both; oco=TP+SL pair; move_order_stop=trailing stop"
+            enum: ["conditional", "oco", "move_order_stop", "trigger", "chase", "iceberg", "twap"],
+            description: "conditional=single TP/SL or both; oco=TP+SL pair; move_order_stop=trailing stop; trigger=pending order; chase=follow best bid/ask; iceberg=split order; twap=time-weighted split"
           },
           sz: {
             type: "string",
@@ -3294,11 +3477,8 @@ function registerFuturesAlgoTools() {
             type: "string",
             description: "TP order price; -1=market (conditional/oco only)"
           },
-          tpTriggerPxType: {
-            type: "string",
-            enum: ["last", "index", "mark"],
-            description: "last(default)|index|mark (conditional/oco only)"
-          },
+          tpOrdKind: TP_ORD_KIND_SCHEMA,
+          tpTriggerPxType: TP_TRIGGER_PX_TYPE_SCHEMA,
           slTriggerPx: {
             type: "string",
             description: "SL trigger price (conditional/oco only)"
@@ -3307,11 +3487,9 @@ function registerFuturesAlgoTools() {
             type: "string",
             description: "SL order price; -1=market (conditional/oco only)"
           },
-          slTriggerPxType: {
-            type: "string",
-            enum: ["last", "index", "mark"],
-            description: "last(default)|index|mark (conditional/oco only)"
-          },
+          slTriggerPxType: SL_TRIGGER_PX_TYPE_SCHEMA,
+          stpMode: STP_MODE_SCHEMA,
+          cxlOnClosePos: CXL_ON_CLOSE_POS_SCHEMA,
           callbackRatio: {
             type: "string",
             description: "Callback ratio (e.g. '0.01'=1%); provide either ratio or spread (move_order_stop only)"
@@ -3324,6 +3502,9 @@ function registerFuturesAlgoTools() {
             type: "string",
             description: "Activation price; tracking starts after market reaches this level (move_order_stop only)"
           },
+          ...TRIGGER_FLAGS_SCHEMA,
+          ...CHASE_FLAGS_SCHEMA,
+          ...ICEBERG_TWAP_FLAGS_SCHEMA,
           tgtCcy: {
             type: "string",
             enum: ["base_ccy", "quote_ccy", "margin"],
@@ -3343,6 +3524,8 @@ function registerFuturesAlgoTools() {
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
         const reduceOnly = args.reduceOnly;
+        const cxlOnClosePos = args.cxlOnClosePos;
+        const ordType = requireString(args, "ordType");
         const resolved = await resolveQuoteCcySz(
           requireString(args, "instId"),
           requireString(args, "sz"),
@@ -3351,29 +3534,44 @@ function registerFuturesAlgoTools() {
           context.client,
           readString(args, "tdMode")
         );
+        const base = compactObject({
+          instId: requireString(args, "instId"),
+          tdMode: requireString(args, "tdMode"),
+          side: requireString(args, "side"),
+          posSide: readString(args, "posSide"),
+          ordType,
+          sz: resolved.sz,
+          tgtCcy: resolved.tgtCcy,
+          stpMode: readString(args, "stpMode"),
+          cxlOnClosePos: typeof cxlOnClosePos === "boolean" ? String(cxlOnClosePos) : void 0,
+          reduceOnly: typeof reduceOnly === "boolean" ? String(reduceOnly) : void 0,
+          clOrdId: readString(args, "clOrdId"),
+          // Phase 3a+c CLI power-user flags (issue #182, CLI-only no MCP/skill exposure)
+          pxAmendType: readString(args, "pxAmendType"),
+          tag: context.config.sourceTag
+        });
+        switch (ordType) {
+          case "trigger":
+            Object.assign(base, buildTriggerOrdTypeBody(args));
+            break;
+          case "chase":
+            Object.assign(base, buildChaseOrdTypeBody(args));
+            break;
+          case "iceberg":
+          case "twap":
+            Object.assign(base, buildIcebergTwapOrdTypeBody(args));
+            break;
+          default:
+            Object.assign(base, compactObject({
+              ...buildAlgoConditionalCommonFields(args),
+              callBackRatio: readString(args, "callbackRatio"),
+              callBackSpread: readString(args, "callbackSpread")
+            }));
+            break;
+        }
         const response = await context.client.privatePost(
           "/api/v5/trade/order-algo",
-          compactObject({
-            instId: requireString(args, "instId"),
-            tdMode: requireString(args, "tdMode"),
-            side: requireString(args, "side"),
-            posSide: readString(args, "posSide"),
-            ordType: requireString(args, "ordType"),
-            sz: resolved.sz,
-            tgtCcy: resolved.tgtCcy,
-            tpTriggerPx: readString(args, "tpTriggerPx"),
-            tpOrdPx: readString(args, "tpOrdPx"),
-            tpTriggerPxType: readString(args, "tpTriggerPxType"),
-            slTriggerPx: readString(args, "slTriggerPx"),
-            slOrdPx: readString(args, "slOrdPx"),
-            slTriggerPxType: readString(args, "slTriggerPxType"),
-            callBackRatio: readString(args, "callbackRatio"),
-            callBackSpread: readString(args, "callbackSpread"),
-            activePx: readString(args, "activePx"),
-            reduceOnly: typeof reduceOnly === "boolean" ? String(reduceOnly) : void 0,
-            clOrdId: readString(args, "clOrdId"),
-            tag: context.config.sourceTag
-          }),
+          base,
           privateRateLimit("futures_place_algo_order", 20)
         );
         const result = normalizeResponse(response);
@@ -5800,6 +5998,23 @@ function resolveOutcome(value) {
   }
   return resolved;
 }
+async function withConcurrency(items, maxConcurrency, fn) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  async function runNext() {
+    while (nextIndex < items.length) {
+      const idx = nextIndex++;
+      try {
+        results[idx] = { status: "fulfilled", value: await fn(items[idx]) };
+      } catch (err) {
+        results[idx] = { status: "rejected", reason: err };
+      }
+    }
+  }
+  const workers = Array.from({ length: Math.min(maxConcurrency, items.length) }, runNext);
+  await Promise.all(workers);
+  return results;
+}
 function filterBrowseCandidates(allSeries, underlyingFilter) {
   const isHumanReadable = (id) => /^(BTC|ETH|TRX|EOS|SOL|IOTA|KISHU|SUSHI|BTG|XTZ|SOLVU)-/.test(id);
   const seen = /* @__PURE__ */ new Set();
@@ -5940,6 +6155,7 @@ function handlePlaceOrderError(base, rawArgs, endpoint) {
   }
   throw new OkxApiError(`[${sCode}] ${sMsg}`, { code: sCode, endpoint });
 }
+var MAX_CONCURRENT_MARKET_FETCHES = 8;
 var OUTCOME_SCHEMA = {
   type: "string",
   enum: ["UP", "YES", "DOWN", "NO"],
@@ -5979,10 +6195,15 @@ function registerEventContractTools() {
         const normalizedSeries = normalizeResponse(seriesResp);
         const allSeries = Array.isArray(normalizedSeries["data"]) ? normalizedSeries["data"] : [];
         const candidates = filterBrowseCandidates(allSeries, underlyingFilter);
-        const marketResults = await Promise.all(
-          candidates.map((s) => fetchActiveContractsForSeries(context.client, s))
+        const settled = await withConcurrency(
+          candidates,
+          MAX_CONCURRENT_MARKET_FETCHES,
+          (s) => fetchActiveContractsForSeries(context.client, s)
         );
-        const results = marketResults.filter(Boolean);
+        const fulfilled = settled.filter(
+          (r) => r.status === "fulfilled" && r.value !== null
+        );
+        const results = fulfilled.map((r) => r.value);
         return {
           data: results,
           total: results.reduce((n, r) => n + (r?.contracts?.length ?? 0), 0)
@@ -6402,379 +6623,1106 @@ function registerEventContractTools() {
     }
   ];
 }
+var SMARTMONEY_RPS = 5;
 var PATH_LEADERBOARD = "/api/v5/orbit/public/leaderboard";
 var PATH_POSITION_CURRENT = "/api/v5/orbit/public/position-current";
+var PATH_POSITION_HISTORY = "/api/v5/orbit/public/position-history";
 var PATH_TRADE_RECORDS = "/api/v5/orbit/public/trade-records";
+var PATH_TOP_TRADER_SEARCH = "/api/v5/orbit/top-trader-search";
 var PATH_OVERVIEW = "/api/v5/journal/smartmoney/overview";
-var PATH_SIGNAL = "/api/v5/journal/smartmoney/signal";
 var PATH_SIGNAL_HISTORY = "/api/v5/journal/smartmoney/signal-history";
+var PERIOD_DAYS = ["3", "7", "30", "90"];
 var SIGNAL_POOL_FILTER_PROPS = {
-  sortType: {
+  sortBy: {
     type: "string",
-    description: "Pool ranking: pnl|pnlRatio (default pnl)"
+    enum: ["pnl", "pnlRatio"],
+    default: "pnl",
+    description: "Ranking key used to pick traders into the aggregation pool. `pnl` = absolute USD profit (favors high-AUM whales); `pnlRatio` = percentage return (favors small-but-efficient traders)."
   },
   period: {
     type: "string",
-    description: "Win-rate window days: 3|7|30|90 (default 90). Not snapshot range."
+    enum: PERIOD_DAYS,
+    default: "7",
+    description: 'Lookback window in days. Pass as a quoted string: `"3"` / `"7"` / `"30"` / `"90"` (NOT integer 7). Drives capability metrics (avgLongWinRate / avgShortWinRate) and the `winRateTier` filter. Does NOT affect signal fields (which always use the latest snapshot).'
   },
-  pnl: {
+  pnlTier: {
     type: "string",
-    description: "Top N% by PnL: PNL_ANY|PNL_TOP50|PNL_TOP20|PNL_TOP5 (default PNL_ANY)"
+    enum: ["PNL_ANY", "PNL_TOP50", "PNL_TOP20", "PNL_TOP5"],
+    default: "PNL_ANY",
+    description: "PnL percentile gate applied on top of `sortBy`. ANY = no filter; TOP50 = PnL \u2265 P50 (median); TOP20 = \u2265 P80; TOP5 = \u2265 P95. PnL distribution is long-tailed \u2014 use percentile, not absolute thresholds."
   },
-  winRatio: {
+  winRateTier: {
     type: "string",
-    description: "Min win-rate: WR_ANY|WR_GE_50|WR_GE_80 (default WR_ANY)"
+    enum: ["WR_ANY", "WR_GE_50", "WR_GE_80"],
+    default: "WR_ANY",
+    description: "Minimum win-rate gate (fixed thresholds). ANY = no filter; WR_GE_50 = \u2265 50%; WR_GE_80 = \u2265 80%."
   },
-  maxRetreat: {
+  maxDrawdownTier: {
     type: "string",
-    description: "Max drawdown: MR_ANY|MR_LE_20|MR_LE_50 (default MR_ANY)"
+    enum: ["MR_ANY", "MR_LE_20", "MR_LE_50"],
+    default: "MR_ANY",
+    description: "Maximum-drawdown gate (fixed thresholds; smaller drawdown = lower risk). ANY = no filter; MR_LE_20 = drawdown \u2264 20%; MR_LE_50 = \u2264 50%."
   },
-  asset: {
+  aumTier: {
     type: "string",
-    description: "Top N% by AUM: AUM_ANY|AUM_TOP50|AUM_TOP20|AUM_TOP5 (default AUM_ANY)"
+    enum: ["AUM_ANY", "AUM_TOP50", "AUM_TOP20", "AUM_TOP5"],
+    default: "AUM_ANY",
+    description: "AUM (Assets Under Management) percentile gate. ANY = no filter; TOP50 = AUM \u2265 P50; TOP20 = \u2265 P80; TOP5 = \u2265 P95. AUM is long-tailed \u2014 use percentile, not absolute USD."
   }
 };
 var LEADERBOARD_POOL_FILTER_PROPS = {
-  sortType: {
+  sortBy: {
     type: "string",
-    description: "pnl or pnl_ratio"
+    enum: ["pnl", "pnlRatio"],
+    default: "pnl",
+    description: "Leaderboard sort key. `pnl` = absolute USD profit; `pnlRatio` = percentage return."
   },
   period: {
     type: "string",
-    description: "3|7|30|90 days, empty=all"
+    enum: PERIOD_DAYS,
+    default: "90",
+    description: 'Performance lookback window in days. Pass as a quoted string: `"3"` / `"7"` / `"30"` / `"90"` (NOT integer 90). Default `"90"` (matches leaderboard UI). Filters AND ranks traders by their PnL over that window.'
   },
-  pnl: {
+  minPnl: {
     type: "string",
-    description: "Min PnL USD"
+    description: 'Minimum absolute PnL in USD. Pass as a quoted numeric string, e.g. `"10000"` (NOT integer 10000) \u2192 traders with PnL \u2265 $10,000. Numeric threshold \u2014 distinct from the signal-side `pnlTier` percentile enum.'
   },
-  winRatio: {
+  minWinRate: {
     type: "string",
-    description: "Min ratio (0.8=80%)"
+    description: 'Minimum win-rate as decimal in 0~1 range. Pass as a quoted numeric string, e.g. `"0.8"` (NOT number 0.8) \u2192 traders with win-rate \u2265 80%. Numeric threshold \u2014 distinct from the signal-side `winRateTier` enum.'
   },
-  maxRetreat: {
+  maxDrawdown: {
     type: "string",
-    description: "Max DD (0.1=10%)"
+    description: 'Maximum drawdown as decimal. Pass as a quoted numeric string, e.g. `"0.1"` (NOT number 0.1) \u2192 traders with drawdown \u2264 10%. Lower = lower risk. Numeric threshold \u2014 distinct from the signal-side `maxDrawdownTier` enum.'
   },
-  asset: {
+  minAum: {
     type: "string",
-    description: "Min AUM USD"
+    description: 'Minimum AUM (Assets Under Management) in USD. Pass as a quoted numeric string, e.g. `"1000"` (NOT integer 1000) \u2192 traders with AUM \u2265 $1,000. Numeric threshold \u2014 distinct from the signal-side `aumTier` percentile enum.'
   }
 };
-var POOL_FILTER_KEYS = ["sortType", "period", "pnl", "winRatio", "maxRetreat", "asset"];
+var LEADERBOARD_FILTER_UPSTREAM_NAMES = {
+  sortBy: "sortBy",
+  period: "period",
+  minPnl: "pnl",
+  minWinRate: "winRate",
+  maxDrawdown: "maxDrawdown",
+  minAum: "asset"
+};
 function readPoolFilters(args) {
   const result = {};
-  for (const key of POOL_FILTER_KEYS) {
+  for (const [publicKey, upstreamKey] of Object.entries(LEADERBOARD_FILTER_UPSTREAM_NAMES)) {
+    const val = readString(args, publicKey);
+    if (val !== void 0 && val !== "") result[upstreamKey] = val;
+  }
+  return result;
+}
+function readSignalPoolFilters(args) {
+  const result = {};
+  for (const key of Object.keys(SIGNAL_POOL_FILTER_PROPS)) {
     const val = readString(args, key);
     if (val) result[key] = val;
   }
   return result;
 }
-function extractLeaderboardData(data) {
-  if (Array.isArray(data)) return data;
+function extractLeaderboardEnvelope(data) {
+  if (Array.isArray(data)) return { items: data };
   if (data && typeof data === "object") {
-    const inner = data.data;
-    if (Array.isArray(inner)) return inner;
+    const obj = data;
+    const inner = obj.data;
+    const updateTime = typeof obj.updateTime === "string" ? obj.updateTime : void 0;
+    if (Array.isArray(inner)) return { items: inner, updateTime };
+  }
+  return { items: [] };
+}
+function deriveDirection(posSide, pos) {
+  if (posSide === "long") return "long";
+  if (posSide === "short") return "short";
+  if (posSide === "both" && typeof pos === "string" && pos !== "") {
+    const n = Number(pos);
+    if (Number.isFinite(n) && n !== 0) return n > 0 ? "long" : "short";
+  }
+  return void 0;
+}
+function extractPositionData(data) {
+  if (!Array.isArray(data) || data.length === 0) return [];
+  const first = data[0];
+  if (first && typeof first === "object") {
+    const posData = first.posData;
+    if (Array.isArray(posData)) {
+      return posData.map((row) => {
+        if (!row || typeof row !== "object") return row;
+        const r = row;
+        const direction = deriveDirection(r.posSide, r.pos);
+        return direction ? { ...r, direction } : r;
+      });
+    }
   }
   return [];
 }
+function buildPagination(data, effectiveLimit, cursorField) {
+  const hasMore = data.length >= effectiveLimit;
+  const last = data.length > 0 ? data[data.length - 1] : void 0;
+  const nextAfter = hasMore && last && typeof last === "object" && last !== null ? last[cursorField] : void 0;
+  return nextAfter !== void 0 ? { hasMore, nextAfter } : { hasMore };
+}
+function extractBaseCcy(instId) {
+  if (!instId) return void 0;
+  const idx = instId.indexOf("-");
+  const base = idx === -1 ? instId : instId.slice(0, idx);
+  return base || void 0;
+}
+function actionableError(message, hint) {
+  return new ValidationError(`${message} ${hint}`);
+}
+function readArrayAsCsv(args, key) {
+  const arr = readStringArray(args, key);
+  if (!arr || arr.length === 0) return void 0;
+  return arr.join(",");
+}
+function envelope(dataSchema, extras = {}) {
+  return {
+    type: "object",
+    properties: {
+      endpoint: {
+        type: "string",
+        description: "Upstream API path that produced this payload (debug/audit aid)."
+      },
+      requestTime: { type: "string", description: "ISO-8601 timestamp when the request was issued." },
+      data: dataSchema,
+      ...extras
+    },
+    required: ["endpoint", "data"]
+  };
+}
+var PAGINATION_PROP = {
+  type: "object",
+  description: "Cursor pagination metadata. Only emitted on list tools that support paging.",
+  properties: {
+    hasMore: {
+      type: "boolean",
+      description: "True when `data.length` reached the requested `limit` (more pages likely). False guarantees there are no more results after this page."
+    },
+    nextAfter: {
+      type: "string",
+      description: "Cursor to pass back as `after` on the next call to fetch the following page. Absent/empty when `hasMore` is false."
+    }
+  }
+};
+var TRADER_ITEM_PROPS = {
+  authorId: { type: "string", description: "Trader's unique ID \u2014 pass to other smartmoney_get_trader_* tools." },
+  nickName: { type: "string", description: "Display nickname." },
+  pnl: { type: "string", description: "Absolute PnL in USD over the requested `period` (numeric string)." },
+  pnlRatio: { type: "string", description: 'PnL as a decimal ratio over the requested `period` (e.g. "0.35" = +35%).' },
+  asset: { type: "string", description: "AUM (Assets Under Management) in USD \u2014 same field that the input `minAum` filter applies to." },
+  winRate: { type: "string", description: "Lifetime win-rate as a decimal (0~1)." },
+  maxDrawdown: { type: "string", description: 'Max drawdown as a decimal (e.g. "0.2" = 20%). Lower = lower risk.' },
+  onboardDuration: { type: "string", description: "Days the trader has been onboarded on the leaderboard (numeric string)." },
+  portrait: { type: "string", description: "Avatar image URL." },
+  rates: {
+    type: "array",
+    description: "Equity-curve / PnL-rate time series (one entry per day).",
+    items: {
+      type: "object",
+      properties: {
+        statTime: { type: "string", description: 'Date stamp in `YYMMDD` (e.g. "240726" = 2024-07-26).' },
+        value: { type: "string", description: "Cumulative PnL ratio at that day (decimal)." }
+      }
+    }
+  }
+};
+var SIGNAL_ITEM_PROPS = {
+  ccy: { type: "string", description: "Instrument ID e.g. BTC-USDT-SWAP (outer identifier; the field name is `ccy`, not `instId`)." },
+  dataVersion: {
+    type: "string",
+    description: "Snapshot version key in `yyyyMMddHH` UTC (10 digits, e.g. `2026043014` = 2026-04-30 14:00 UTC; floored to the hour)."
+  },
+  tradersWithPosition: {
+    type: "integer",
+    description: "Pool traders holding this asset at latest_snap (double-sided counted once). Higher = stronger consensus."
+  },
+  tradersQualified: {
+    type: "integer",
+    description: "Pool size after applying tier filters (incl. those without positions on this instrument)."
+  },
+  longTraders: { type: "integer", description: "Number of pool traders currently long this asset (incl. double-sided)." },
+  shortTraders: { type: "integer", description: "Number of pool traders currently short this asset (incl. double-sided)." },
+  notional: {
+    type: "object",
+    description: "Notional / capital-flow group.",
+    properties: {
+      longNotionalUsdt: { type: "string", description: "Sum of long-side notional in USDT." },
+      shortNotionalUsdt: { type: "string", description: "Sum of short-side notional in USDT." },
+      netNotionalUsdt: { type: "string", description: "Net directional notional in USDT = long \u2212 short." },
+      totalNotionalUsdt: { type: "string", description: "Gross notional in USDT = long + short." },
+      totalNotionalVs24h: {
+        type: "string",
+        description: "Capital-flow change ratio vs 24h: (curr \u2212 hist_24h) / hist_24h. Positive = smart money adding exposure; negative = retreating. NULL when hist=0."
+      },
+      smartMoneyLongAvgEntry: {
+        type: "string",
+        description: "Long-side notional-weighted average entry price (USDT). NULL when no long. Compare to current price to judge whether following the longs is cheap/expensive now."
+      },
+      smartMoneyShortAvgEntry: {
+        type: "string",
+        description: "Short-side notional-weighted average entry price (USDT). NULL when no short."
+      }
+    }
+  },
+  longShortRatio: {
+    type: "object",
+    description: "Long/short ratio + historical-delta group.",
+    properties: {
+      longRatioVs1h: { type: "string", description: "longRatio \u2212 hist_1h.longRatio. NULL when no hist." },
+      longRatioVs24h: { type: "string", description: "longRatio \u2212 hist_24h.longRatio. NULL when no hist." },
+      longRatioVs7d: { type: "string", description: "longRatio \u2212 hist_7d.longRatio. NULL when no hist." },
+      longRatio: { type: "string", description: "Headcount long ratio = longTraders / tradersWithPosition. NULL when no traders." },
+      shortRatio: { type: "string", description: "1 \u2212 longRatio. NULL when no traders." },
+      weightedLongRatio: {
+        type: "string",
+        description: "Notional-weighted long ratio = \u03A3(long_notional) / \u03A3(notional). NULL when no notional."
+      },
+      weightedShortRatio: {
+        type: "string",
+        description: "Notional-weighted short ratio = \u03A3(short_notional) / \u03A3(notional). NULL when no notional."
+      }
+    }
+  },
+  winRate: {
+    type: "object",
+    description: "Capability (historical performance) group; driven by the `period` window.",
+    properties: {
+      avgLongWinRate: {
+        type: "string",
+        description: "Mean closed-position win-rate (full-market) over `period` days for users currently long. NULL when closed-position sample size is below the configured minimum."
+      },
+      avgShortWinRate: {
+        type: "string",
+        description: "Mean closed-position win-rate (full-market) over `period` days for users currently short. NULL when sample is below threshold."
+      }
+    }
+  }
+};
+var SIGNAL_HISTORY_ITEM_PROPS = {
+  ccy: { type: "string", description: "Base currency / instrument key for this bucket." },
+  longRatio: {
+    type: "string",
+    description: "Headcount long ratio at this bucket. Decimal 0~1."
+  },
+  shortRatio: {
+    type: "string",
+    description: "Headcount short ratio at this bucket = 1 \u2212 longRatio. Decimal 0~1."
+  },
+  weightedLongRatio: {
+    type: "string",
+    description: "Notional-weighted long ratio at this bucket. Decimal 0~1."
+  },
+  weightedShortRatio: {
+    type: "string",
+    description: "Notional-weighted short ratio at this bucket. Decimal 0~1."
+  },
+  longTraders: {
+    type: "integer",
+    description: "Number of traders with long exposure at this bucket (includes dual-side traders)."
+  },
+  shortTraders: {
+    type: "integer",
+    description: "Number of traders with short exposure at this bucket (includes dual-side traders)."
+  },
+  tradersWithPosition: {
+    type: "integer",
+    description: "Pool traders holding this asset at this bucket. Few traders = unreliable signal."
+  },
+  netNotionalUsdt: {
+    type: "string",
+    description: "Net directional notional in USDT at this bucket = long notional \u2212 short notional."
+  },
+  totalNotionalUsdt: {
+    type: "string",
+    description: "Gross notional in USDT at this bucket = long notional + short notional. Tracks total capital deployed (rising = adding, falling = retreating)."
+  },
+  tradersQualified: { type: "integer", description: "Pool size after applying tier filters (includes traders without a position)." },
+  dataVersion: { type: "string", description: "Snapshot version key in `yyyyMMddHH` UTC (10-digit, e.g. `2026042820`)." }
+};
 function registerSmartmoneyTools() {
   const tools = [
-    /* ---------- 1. Overview ---------- */
+    /* ===================================================== */
+    /*  Trader family (6)                                     */
+    /* ===================================================== */
+    /* ---------- T1. Top traders (leaderboard rank) ---------- */
     {
-      name: "smartmoney_get_overview",
+      name: "smartmoney_get_traders_by_filter",
       module: "smartmoney",
-      description: "Multi-currency smart money overview, ranked by tradersWithPosition DESC (most-watched first). Requires either ts (recommended, Date.now()) or dataVersion (yyyyMMddHHmm UTC) \u2014 at least one must be set; ts wins when both are sent. For single-currency signal with entry prices and trend, use smartmoney_get_signal.",
+      description: "Leaderboard ranking of OKX smart-money traders, filtered by pool conditions and ranked by `sortBy`. Use when: discovering top performers by criteria (PnL / win-rate / drawdown / AUM). See also: `smartmoney_get_performance_by_trader` (lookup by ID), `smartmoney_search_trader` (lookup by nickname). Note: `updateTime` is 12-digit `yyyyMMddHHmm` UTC+8, different from signal tools' 10-digit UTC `asOfTime`/`dataVersion` \u2014 do not cross-pass.",
       isWrite: false,
+      outputSchema: envelope(
+        { type: "array", items: { type: "object", properties: TRADER_ITEM_PROPS } },
+        {
+          updateTime: {
+            type: "string",
+            description: "Snapshot version of the leaderboard, in `yyyyMMddHHmm` (UTC+8, e.g. `202604301815`). Lives at the response top level (shared by every item in `data`), NOT inside each trader row. Refreshed approximately every 5 minutes."
+          },
+          pagination: PAGINATION_PROP
+        }
+      ),
       inputSchema: {
         type: "object",
         properties: {
-          ts: {
-            type: "string",
-            description: "Recommended. Timestamp ms \u2014 use Date.now() for latest."
-          },
-          dataVersion: {
-            type: "string",
-            description: "Alternative. yyyyMMddHHmm UTC for prior snapshot. If both sent, ts wins."
-          },
-          instType: {
-            type: "string",
-            description: "SPOT|MARGIN|FUTURES|SWAP|OPTION (default SWAP)"
-          },
-          ...SIGNAL_POOL_FILTER_PROPS,
-          lmtNum: {
+          updateTime: {
             type: "string",
-            description: "Trader pool size 1-500 (default 100)"
+            description: 'Snapshot version key. Pass as a quoted 12-digit string `yyyyMMddHHmm` (UTC+8), e.g. `"202604301815"` (NOT integer). Omit to query the latest snapshot (refreshed every ~5 min).'
           },
-          instCcyList: {
+          ...LEADERBOARD_POOL_FILTER_PROPS,
+          after: {
             type: "string",
-            description: "Comma-separated currency codes e.g. BTC,ETH,SOL (prefix-matched against instId)"
+            description: "Cursor for paginating backwards (older page). Pass the `authorId` of the last item from the previous page verbatim as a quoted string (NOT a number). Cursor anchors on `authorId` while preserving the current `sortBy` order."
           },
-          instCcy: {
+          before: {
             type: "string",
-            description: "Single currency e.g. BTC; alias for instCcyList (instCcyList wins if both set)"
+            description: "Cursor for paginating forwards (newer page). Pass the `authorId` of the first item from the previous page verbatim as a quoted string. Cursor anchors on `authorId` while preserving the current `sortBy` order."
           },
-          topInstruments: {
-            type: "string",
-            description: "Top N instruments 1-100 (default 20)"
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 100,
+            default: 10,
+            description: "Max results per page (default 10, max 100)."
           }
         }
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
-        const dv = readString(args, "dataVersion");
-        const ts = readString(args, "ts");
-        if (!dv && !ts) {
-          throw new ValidationError('Either "dataVersion" or "ts" is required for smartmoney_get_overview.');
-        }
+        const limit = readNumber(args, "limit");
         const response = await context.client.privateGet(
-          PATH_OVERVIEW,
+          PATH_LEADERBOARD,
           compactObject({
-            dataVersion: dv,
-            ts,
-            instType: readString(args, "instType"),
+            updateTime: readString(args, "updateTime"),
             ...readPoolFilters(args),
-            lmtNum: readString(args, "lmtNum"),
-            instCcyList: readString(args, "instCcyList"),
-            instCcy: readString(args, "instCcy"),
-            topInstruments: readString(args, "topInstruments")
+            after: readString(args, "after"),
+            before: readString(args, "before"),
+            limit
           }),
-          publicRateLimit("smartmoney_get_overview", 5)
+          publicRateLimit("smartmoney_get_traders_by_filter", SMARTMONEY_RPS)
         );
-        return normalizeResponse(response);
+        const normalized = normalizeResponse(response);
+        const { items, updateTime } = extractLeaderboardEnvelope(normalized.data);
+        return {
+          ...normalized,
+          data: items,
+          ...updateTime ? { updateTime } : {},
+          pagination: buildPagination(items, limit ?? 10, "authorId")
+        };
       }
     },
-    /* ---------- 2. Signal ---------- */
+    /* ---------- T2. Trader performance (by authorIds) ---------- */
     {
-      name: "smartmoney_get_signal",
+      name: "smartmoney_get_performance_by_trader",
       module: "smartmoney",
-      description: "Single-currency consensus signal: long/short ratio, entry prices, trend, capital flow. Requires either instId (e.g. BTC-USDT-SWAP, recommended) or instCcy (SPOT/SWAP only) \u2014 instId wins when both are sent. Requires either ts (recommended, Date.now()) or dataVersion (yyyyMMddHHmm UTC) \u2014 at least one must be set; ts wins when both are sent. For multi-currency overview, use smartmoney_get_overview. For timeline, use smartmoney_get_signal_history.",
+      description: "PnL / win-rate / drawdown profile for one or more traders looked up by `authorIds`. Use when: caller already has trader IDs and needs their performance metrics. See also: `smartmoney_search_trader` (resolve nickname \u2192 authorId), `smartmoney_get_traders_by_filter` (criteria-based discovery). Note: response `updateTime` is 12-digit `yyyyMMddHHmm` UTC+8 \u2014 do not pass to signal-side tools' `asOfTime` (10-digit UTC).",
       isWrite: false,
+      outputSchema: envelope(
+        { type: "array", items: { type: "object", properties: TRADER_ITEM_PROPS } },
+        {
+          updateTime: {
+            type: "string",
+            description: "Snapshot version of the leaderboard, in `yyyyMMddHHmm` (UTC+8, e.g. `202604301815`). Lives at the response top level (shared by every item in `data`), NOT inside each trader row."
+          }
+        }
+      ),
       inputSchema: {
         type: "object",
         properties: {
-          instId: {
-            type: "string",
-            description: "Recommended. e.g. BTC-USDT-SWAP"
-          },
-          instCcy: {
-            type: "string",
-            description: "e.g. BTC (SPOT/SWAP only); instId takes precedence if both set"
-          },
-          ts: {
-            type: "string",
-            description: "Recommended. Timestamp ms \u2014 use Date.now() for latest."
-          },
-          dataVersion: {
-            type: "string",
-            description: "Alternative. yyyyMMddHHmm UTC for prior snapshot. If both sent, ts wins."
-          },
-          ...SIGNAL_POOL_FILTER_PROPS,
-          lmtNum: {
-            type: "string",
-            description: "Trader pool size 1-500 (default 100)"
-          },
           authorIds: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            description: 'Trader IDs to look up, e.g. `["1001", "1002"]`. Required.'
+          },
+          period: {
             type: "string",
-            description: "Comma-separated user IDs e.g. 1001,1002 \u2014 restricts the trader pool to these IDs only (precise filter)"
+            enum: PERIOD_DAYS,
+            default: "90",
+            description: 'Performance lookback window in days. Pass as a quoted string: `"3"` / `"7"` / `"30"` / `"90"` (NOT integer). Default `"90"`.'
           }
-        }
+        },
+        required: ["authorIds"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
-        const instId = readString(args, "instId");
-        const instCcy = readString(args, "instCcy");
-        if (!instId && !instCcy) {
-          throw new ValidationError('Either "instId" or "instCcy" is required for smartmoney_get_signal.');
-        }
-        const dv = readString(args, "dataVersion");
-        const ts = readString(args, "ts");
-        if (!dv && !ts) {
-          throw new ValidationError('Either "dataVersion" or "ts" is required for smartmoney_get_signal.');
+        const authorIds = readArrayAsCsv(args, "authorIds");
+        if (!authorIds) {
+          throw actionableError(
+            '"authorIds" is required and must be a non-empty array.',
+            'Discover trader IDs via `smartmoney_get_traders_by_filter`, then pass them as an array (e.g. ["1001", "1002"]).'
+          );
         }
         const response = await context.client.privateGet(
-          PATH_SIGNAL,
+          PATH_LEADERBOARD,
           compactObject({
-            instId,
-            instCcy,
-            dataVersion: dv,
-            ts,
-            ...readPoolFilters(args),
-            lmtNum: readString(args, "lmtNum"),
-            authorIds: readString(args, "authorIds")
+            authorIds,
+            period: readString(args, "period")
           }),
-          publicRateLimit("smartmoney_get_signal", 5)
+          publicRateLimit("smartmoney_get_performance_by_trader", SMARTMONEY_RPS)
         );
-        return normalizeResponse(response);
+        const normalized = normalizeResponse(response);
+        const { items, updateTime } = extractLeaderboardEnvelope(normalized.data);
+        return {
+          ...normalized,
+          data: items,
+          ...updateTime ? { updateTime } : {}
+        };
       }
     },
-    /* ---------- 3. Signal History ---------- */
+    /* ---------- T3. Trader current positions ---------- */
     {
-      name: "smartmoney_get_signal_history",
+      name: "smartmoney_get_trader_positions",
       module: "smartmoney",
-      description: "Signal history timeline sorted by ts DESC for trend analysis. Requires instId. Requires either ts (recommended, Date.now()) or dataVersion (yyyyMMddHHmm UTC) \u2014 at least one must be set; ts wins when both are sent. For current snapshot, use smartmoney_get_signal.",
+      description: "Currently-open positions held by a single trader (direction, size, leverage, entry, conviction). Use when: inspecting what a top trader is holding RIGHT NOW. See also: `smartmoney_get_trader_positions_history` (closed positions), `smartmoney_search_trader` (nickname \u2192 authorId), `smartmoney_get_traders_by_filter` (discover trader).",
       isWrite: false,
+      outputSchema: envelope({
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            posId: { type: "string", description: "Unique position ID. Stable across the position's lifetime." },
+            instId: { type: "string", description: "Instrument ID e.g. BTC-USDT-SWAP." },
+            instType: {
+              type: "string",
+              description: "Instrument business line: `SWAP` (perpetual) | `SPOT` | `FUTURES` (delivery) | `MARGIN` | `OPTION`."
+            },
+            posSide: {
+              type: "string",
+              description: "Raw upstream position direction. `long` = long-side position (buy-to-open); `short` = short-side position (sell-to-open); `both` = net/one-way position mode where the sign of `pos` encodes direction. Prefer the derived `direction` field below for agent logic."
+            },
+            direction: {
+              type: "string",
+              enum: ["long", "short"],
+              description: 'Derived clean direction (`long` | `short`) \u2014 handler computes this from `posSide` + sign of `pos` so agents do not have to branch on the `posSide="both"` net-mode case.'
+            },
+            posCcy: { type: "string", description: 'Position currency \u2014 the asset being held, e.g. "BTC".' },
+            quoteCcy: { type: "string", description: 'Quote currency the position is priced/settled in, e.g. "USDT".' },
+            pos: {
+              type: "string",
+              description: "Position size (numeric string). Unit depends on instType: coins for SPOT/MARGIN, contracts (\u5F20) for SWAP/FUTURES/OPTION."
+            },
+            lever: { type: "string", description: 'Leverage multiplier (numeric string; "1" for spot).' },
+            avgPx: { type: "string", description: "Volume-weighted average entry price (numeric string)." },
+            last: { type: "string", description: "Latest market/mark price for the instrument (numeric string)." },
+            notionalUsd: { type: "string", description: "Current position notional value in USD." },
+            upl: { type: "string", description: "Unrealized (floating) PnL, denominated in `quoteCcy`." },
+            pnl: { type: "string", description: "Realized PnL accrued on this position so far, denominated in `quoteCcy`." },
+            cTime: { type: "string", description: "Position open time as Unix milliseconds (numeric string)." },
+            positionIntensity: {
+              type: "string",
+              description: "Conviction metric = notionalUsd / trader.asset (this position's notional as a share of the trader's AUM). Higher = the trader is betting a larger fraction of their book on this position."
+            }
+          }
+        }
+      }),
       inputSchema: {
         type: "object",
         properties: {
-          instId: {
+          authorId: {
             type: "string",
-            description: "e.g. BTC-USDT-SWAP"
+            description: "Trader's unique ID (obtain from `smartmoney_get_traders_by_filter`)."
           },
-          ts: {
+          instId: {
+            type: "string",
+            description: 'Optional instrument filter. Accepts either full instId (e.g. "BTC-USDT-SWAP") or bare base currency (e.g. "BTC") \u2014 the handler extracts the base currency for the upstream filter.'
+          }
+        },
+        required: ["authorId"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const authorId = readString(args, "authorId");
+        if (!authorId) {
+          throw actionableError(
+            '"authorId" is required.',
+            "Discover trader IDs via `smartmoney_get_traders_by_filter` and pass one ID here."
+          );
+        }
+        const response = await context.client.privateGet(
+          PATH_POSITION_CURRENT,
+          compactObject({
+            authorId,
+            instCcy: extractBaseCcy(readString(args, "instId"))
+          }),
+          publicRateLimit("smartmoney_get_trader_positions", SMARTMONEY_RPS)
+        );
+        const normalized = normalizeResponse(response);
+        return { ...normalized, data: extractPositionData(normalized.data) };
+      }
+    },
+    /* ---------- T4. Trader closed-position history ---------- */
+    {
+      name: "smartmoney_get_trader_positions_history",
+      module: "smartmoney",
+      description: "Closed-position history of a single trader, paginated by `posId` cursor. Use when: studying realized PnL pattern, holding duration, win/loss streaks, or how positions ended (closed vs liquidated). See also: `smartmoney_get_trader_positions` (currently-open), `smartmoney_search_trader` (nickname \u2192 authorId), `smartmoney_get_traders_by_filter` (discover trader).",
+      isWrite: false,
+      outputSchema: envelope(
+        {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              posId: { type: "string", description: "Unique closed-position ID. Use as the `after` / `before` cursor when paginating." },
+              instId: { type: "string", description: "Instrument ID e.g. BTC-USDT-SWAP." },
+              instType: {
+                type: "string",
+                description: "Instrument business line: `SWAP` (perpetual) | `FUTURES` (delivery) | `MARGIN` | `SPOT`."
+              },
+              ctVal: {
+                type: "string",
+                description: "Contract face value \u2014 USD value of a single contract (\u5F20). Numeric string. Empty/0 for non-contract instruments."
+              },
+              posSide: {
+                type: "string",
+                description: "Position direction at close. `long` = was long-side; `short` = was short-side."
+              },
+              lever: { type: "string", description: "Leverage multiplier used for this position (numeric string)." },
+              mgnMode: {
+                type: "string",
+                description: "Margin mode used for this position. `cross` = cross-margin (shared collateral pool); `isolated` = isolated-margin (per-position collateral)."
+              },
+              marginCcy: {
+                type: "string",
+                description: 'Margin currency held as collateral for this position, e.g. "BTC" or "USDT".'
+              },
+              quoteCcy: { type: "string", description: 'Quote currency the position settled in, e.g. "USDT".' },
+              openAvgPx: { type: "string", description: "Volume-weighted average price across all open fills (numeric string)." },
+              closeAvgPx: { type: "string", description: "Volume-weighted average price across all close fills (numeric string)." },
+              openMaxAmount: {
+                type: "string",
+                description: "Peak position size held during the position's lifetime, in contracts (\u5F20)."
+              },
+              closeAmount: {
+                type: "string",
+                description: "Total amount closed across all close fills, in contracts for SWAP/FUTURES or in base currency for SPOT/MARGIN (numeric string)."
+              },
+              realizedPnl: { type: "string", description: "Cumulative realized PnL during the position's lifetime, in `quoteCcy` units." },
+              pnl: {
+                type: "string",
+                description: "Total realized PnL for this position including fees and funding, denominated in quoteCcy (numeric string). Differs from `realizedPnl` which may exclude fees."
+              },
+              pnlRatio: {
+                type: "string",
+                description: 'Realized PnL as a decimal ratio of cost basis (e.g. "0.15" = +15%, "-0.20" = \u221220%).'
+              },
+              fee: {
+                type: "string",
+                description: "Cumulative trading fee paid over the position's lifetime, denominated in quoteCcy (numeric string, negative = cost)."
+              },
+              fundingFee: {
+                type: "string",
+                description: "Cumulative funding fee paid or received over the position's lifetime, denominated in quoteCcy (numeric string; negative = paid, positive = received)."
+              },
+              liquidationStatus: {
+                type: "string",
+                description: 'Whether the position was liquidated. `"0"` = normal close (not liquidated); `"1"` = liquidated. Use this dedicated field for liquidation checks; `closeType` may also encode liquidation via the `liquidateClose` / `liquidateReceive` / `adl` values.'
+              },
+              closeType: {
+                type: "string",
+                description: "How the position was closed. `allClose` = entire position closed in one action; `partClose` = partially closed (position reduced but not fully exited); `liquidateClose` = forced liquidation; `liquidateReceive` = received liquidation transfer; `adl` = auto-deleveraging."
+              },
+              cTime: { type: "string", description: "Position open time as Unix milliseconds (numeric string)." },
+              uTime: { type: "string", description: "Position close time as Unix milliseconds (numeric string)." }
+            }
+          }
+        },
+        { pagination: PAGINATION_PROP }
+      ),
+      inputSchema: {
+        type: "object",
+        properties: {
+          authorId: {
             type: "string",
-            description: "Recommended. Timestamp ms \u2014 use Date.now() for latest."
+            description: "Trader's unique ID (obtain from `smartmoney_get_traders_by_filter`)."
           },
-          dataVersion: {
+          instId: {
             type: "string",
-            description: "Alternative. yyyyMMddHHmm UTC for prior snapshot. If both sent, ts wins."
+            description: 'Optional instrument filter. Accepts either full instId (e.g. "BTC-USDT-SWAP") or bare base currency (e.g. "BTC") \u2014 the handler extracts the base currency for the upstream filter.'
           },
-          granularity: {
+          after: {
             type: "string",
-            description: "1h or 1d (default 1h)"
+            description: "Cursor: returns positions with `posId` smaller than this value (older \u2014 paginate backwards). Pass as quoted string (the `posId` value verbatim, NOT a number \u2014 `posId` is a 19-digit ID and number coercion can lose precision)."
           },
-          limit: {
+          before: {
             type: "string",
-            description: "Data points 1-500 (default 24)"
+            description: "Cursor: returns positions with `posId` greater than this value (newer \u2014 paginate forwards). Pass as quoted string."
           },
-          ...SIGNAL_POOL_FILTER_PROPS
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 100,
+            default: 10,
+            description: "Max positions per page (default 10, max 100)."
+          }
         },
-        required: ["instId"]
+        required: ["authorId"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
-        const dv = readString(args, "dataVersion");
-        const ts = readString(args, "ts");
-        if (!dv && !ts) {
-          throw new ValidationError('Either "dataVersion" or "ts" is required for smartmoney_get_signal_history.');
+        const authorId = readString(args, "authorId");
+        if (!authorId) {
+          throw actionableError(
+            '"authorId" is required.',
+            "Discover trader IDs via `smartmoney_get_traders_by_filter`."
+          );
         }
+        const limit = readNumber(args, "limit");
         const response = await context.client.privateGet(
-          PATH_SIGNAL_HISTORY,
+          PATH_POSITION_HISTORY,
           compactObject({
-            instId: requireString(args, "instId"),
-            dataVersion: dv,
-            ts,
-            granularity: readString(args, "granularity"),
-            limit: readString(args, "limit"),
-            ...readPoolFilters(args)
+            authorId,
+            instCcy: extractBaseCcy(readString(args, "instId")),
+            after: readString(args, "after"),
+            before: readString(args, "before"),
+            limit
           }),
-          publicRateLimit("smartmoney_get_signal_history", 5)
+          publicRateLimit("smartmoney_get_trader_positions_history", SMARTMONEY_RPS)
         );
-        return normalizeResponse(response);
+        const normalized = normalizeResponse(response);
+        const data = Array.isArray(normalized.data) ? normalized.data : [];
+        return {
+          ...normalized,
+          data,
+          pagination: buildPagination(data, limit ?? 10, "posId")
+        };
       }
     },
-    /* ---------- 4. Traders (list) ---------- */
+    /* ---------- T5. Trader order history ---------- */
     {
-      name: "smartmoney_get_traders",
+      name: "smartmoney_get_trader_orders_history",
       module: "smartmoney",
-      description: "List/filter leaderboard traders. For single trader detail: smartmoney_get_trader_detail.",
+      description: "Recent orders/fills placed by a single trader (direction, size, price, leverage), paginated by `ordId` cursor. Aligned with the cross-module `*_get_orders` family. Use when: tracking a top trader's latest trade activity. See also: `smartmoney_search_trader` (nickname \u2192 authorId), `smartmoney_get_traders_by_filter` (discover trader).",
       isWrite: false,
+      outputSchema: envelope(
+        {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              ordId: { type: "string", description: "Unique order ID. Use as the `after` / `before` cursor when paginating." },
+              instId: { type: "string", description: "Instrument ID e.g. BTC-USDT-SWAP." },
+              displayId: { type: "string", description: "Display-form instrument ID used in OKX UI." },
+              instType: {
+                type: "string",
+                description: "Instrument business line: `SWAP` (perpetual contract) | `SPOT`."
+              },
+              baseName: { type: "string", description: 'Base currency symbol, e.g. "BTC".' },
+              quoteName: { type: "string", description: 'Quote currency symbol, e.g. "USD".' },
+              tradeQuoteCcy: { type: "string", description: "Quote currency the fill actually settled in." },
+              side: {
+                type: "string",
+                description: "Order side. `buy` = open long / close short; `sell` = open short / close long."
+              },
+              posSide: {
+                type: "string",
+                description: "Position direction the order applies to: `long` | `short`. Indicates whether the trader was opening/closing a long-side or short-side position."
+              },
+              ordType: {
+                type: "string",
+                description: "Order type. `limit` = price-protected limit order; `market` = immediate at best available price."
+              },
+              lever: { type: "string", description: 'Leverage multiplier used for this order (numeric string; "1" for spot).' },
+              px: { type: "string", description: "Submitted order price (numeric string). For market orders this may be empty/0." },
+              avgPx: { type: "string", description: "Volume-weighted average fill price (numeric string)." },
+              sz: {
+                type: "string",
+                description: "Order size. Unit depends on instType: coins (\u5E01) for SPOT, contracts (\u5F20) for SWAP/FUTURES."
+              },
+              value: {
+                type: "string",
+                description: "Order notional value, denominated in `quoteName` units."
+              },
+              cTime: { type: "string", description: "Order creation time as Unix milliseconds (numeric string)." },
+              fillTime: {
+                type: "string",
+                description: "Timestamp when the order was last filled, as Unix milliseconds (numeric string)."
+              },
+              uTime: {
+                type: "string",
+                description: "Timestamp when the order record was last updated, as Unix milliseconds (numeric string)."
+              }
+            }
+          }
+        },
+        { pagination: PAGINATION_PROP }
+      ),
       inputSchema: {
         type: "object",
         properties: {
-          dataVersion: {
+          authorId: {
             type: "string",
-            description: "yyyyMMddHHmm, omit=latest"
+            description: "Trader's unique ID (obtain from `smartmoney_get_traders_by_filter`)."
           },
-          ...LEADERBOARD_POOL_FILTER_PROPS,
-          authorIds: {
+          instId: {
             type: "string",
-            description: "Comma-separated author IDs"
+            description: 'Optional instrument filter. Accepts either full instId (e.g. "BTC-USDT-SWAP") or bare base currency (e.g. "BTC") \u2014 the handler extracts the base currency for the upstream filter.'
           },
           after: {
             type: "string",
-            description: "Cursor after this authorId"
+            description: "Cursor: returns trades with `ordId` smaller than this value (older \u2014 paginate backwards). Pass as quoted string (the `ordId` value verbatim, NOT a number \u2014 `ordId` is a 19-digit ID and number coercion can lose precision)."
           },
           before: {
             type: "string",
-            description: "Cursor before this authorId"
+            description: "Cursor: returns trades with `ordId` greater than this value (newer \u2014 paginate forwards). Pass as quoted string."
           },
           limit: {
-            type: "string",
-            description: "Max results 1-100"
+            type: "integer",
+            minimum: 1,
+            maximum: 100,
+            default: 10,
+            description: "Max trades per page (default 10, max 100)."
           }
-        }
+        },
+        required: ["authorId"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
+        const authorId = readString(args, "authorId");
+        if (!authorId) {
+          throw actionableError(
+            '"authorId" is required.',
+            "Discover trader IDs via `smartmoney_get_traders_by_filter`."
+          );
+        }
+        const limit = readNumber(args, "limit");
         const response = await context.client.privateGet(
-          PATH_LEADERBOARD,
+          PATH_TRADE_RECORDS,
           compactObject({
-            dataVersion: readString(args, "dataVersion"),
-            ...readPoolFilters(args),
-            authorIds: readString(args, "authorIds"),
+            authorId,
+            instCcy: extractBaseCcy(readString(args, "instId")),
             after: readString(args, "after"),
             before: readString(args, "before"),
-            limit: readString(args, "limit")
+            limit
           }),
-          publicRateLimit("smartmoney_get_traders", 5)
+          publicRateLimit("smartmoney_get_trader_orders_history", SMARTMONEY_RPS)
         );
         const normalized = normalizeResponse(response);
-        return { ...normalized, data: extractLeaderboardData(normalized.data) };
+        const data = Array.isArray(normalized.data) ? normalized.data : [];
+        return {
+          ...normalized,
+          data,
+          pagination: buildPagination(data, limit ?? 10, "ordId")
+        };
       }
     },
-    /* ---------- 5. Trader Detail (composite) ---------- */
+    /* ---------- T6. Search top traders by nickname keyword ---------- */
     {
-      name: "smartmoney_get_trader_detail",
+      name: "smartmoney_search_trader",
       module: "smartmoney",
-      description: "Trader portrait: profile + positions + trades. Requires authorId from smartmoney_get_traders. Do NOT use for listing \u2014 use smartmoney_get_traders.",
+      description: "Search Top Traders by nickname keyword, ranked by OKX-platform follower count DESC. Returns up to 10 matches; intersects KOL full-text recall with the Top Trader set. Use when: resolving a nickname or partial name to `authorId`(s) before calling other `smartmoney_get_trader_*` tools. See also: `smartmoney_get_traders_by_filter` (discover top performers by criteria), `smartmoney_get_performance_by_trader` (lookup by known authorId).",
       isWrite: false,
+      outputSchema: envelope({
+        type: "array",
+        description: "Matched Top Traders (\u226410), sorted by `followerCount` DESC. Empty array when no recall intersects the Top Trader set.",
+        items: {
+          type: "object",
+          properties: {
+            authorId: { type: "string", description: "Trader's unique ID \u2014 pass to other `smartmoney_get_trader_*` tools." },
+            nickName: { type: "string", description: "Display nickname matched against the keyword." },
+            followerCount: { type: "string", description: "OKX-platform follower count (numeric string; Twitter followers excluded). Sort key." }
+          }
+        }
+      }),
       inputSchema: {
         type: "object",
         properties: {
-          authorId: {
+          keyword: {
             type: "string",
-            description: "Trader author ID"
+            description: "Nickname search keyword. Required, must be non-empty / non-whitespace. Matched candidates are intersected with the Top Trader set."
+          }
+        },
+        required: ["keyword"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const keyword = readString(args, "keyword");
+        if (!keyword || keyword.trim() === "") {
+          throw actionableError(
+            '"keyword" is required and must be non-empty.',
+            'Pass a nickname fragment (e.g. "alice", "\u5C0F\u660E"). For known author IDs use `smartmoney_get_performance_by_trader` instead.'
+          );
+        }
+        const response = await context.client.privateGet(
+          PATH_TOP_TRADER_SEARCH,
+          compactObject({ keyword }),
+          publicRateLimit("smartmoney_search_trader", SMARTMONEY_RPS)
+        );
+        const normalized = normalizeResponse(response);
+        const data = Array.isArray(normalized.data) ? normalized.data : [];
+        return { ...normalized, data };
+      }
+    },
+    /* ===================================================== */
+    /*  Signal/Coin family (4)                                */
+    /* ===================================================== */
+    /* ---------- S1. Signal overview by filter (multi-asset, tier-filtered pool) ---------- */
+    {
+      name: "smartmoney_get_signal_overview_by_filter",
+      module: "smartmoney",
+      description: "Multi-asset smart-money consensus signals (long/short ratio, weighted entry, capital flow, deltas vs 1h/24h/7d), aggregated over a tier-filtered trader pool (PnL / win-rate / drawdown / AUM). Pick instruments via `topInstruments` OR `instCcyList` \u2014 exactly one. Snapshot time auto-resolved to current hour. Use when: latest cross-asset consensus from a criteria-defined pool. See also: `smartmoney_get_signal_overview_by_trader` (restrict pool to specific traders), `smartmoney_get_signal_trend_by_filter` (time-series instead of latest snapshot).",
+      isWrite: false,
+      outputSchema: envelope({
+        type: "array",
+        description: "Per-instrument snapshot, one element per requested coin.",
+        items: { type: "object", properties: SIGNAL_ITEM_PROPS }
+      }),
+      inputSchema: {
+        type: "object",
+        properties: {
+          topInstruments: {
+            type: "integer",
+            minimum: 1,
+            maximum: 100,
+            default: 20,
+            description: "Top-N hottest instruments to aggregate (sorted by `tradersWithPosition` DESC). Mutually exclusive with `instCcyList`; one of the two is required (default 20 if neither provided)."
           },
-          period: {
-            type: "string",
-            description: "3|7|30|90 days, omit=all"
+          instCcyList: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            description: 'Base currencies to aggregate, e.g. `["BTC", "ETH", "SOL"]`. Mutually exclusive with `topInstruments`.'
           },
+          ...SIGNAL_POOL_FILTER_PROPS,
+          lmtNum: {
+            type: "integer",
+            minimum: 1,
+            maximum: 2e3,
+            default: 100,
+            description: "Top-N traders to pull into the aggregation pool, ranked by `sortBy` (DESC). Larger pool = stronger signal but slower. Default 100 is fine for most cases."
+          }
+        }
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const instCcyList = readArrayAsCsv(args, "instCcyList");
+        const topInstrumentsRaw = readNumber(args, "topInstruments");
+        if (instCcyList && topInstrumentsRaw !== void 0) {
+          throw actionableError(
+            '"topInstruments" and "instCcyList" are mutually exclusive.',
+            "Pass exactly one \u2014 `topInstruments` for top-N hottest coins, or `instCcyList` for specific coins."
+          );
+        }
+        const response = await context.client.privateGet(
+          PATH_OVERVIEW,
+          compactObject({
+            ...instCcyList ? { instCcyList } : { topInstruments: topInstrumentsRaw ?? 20 },
+            ...readSignalPoolFilters(args),
+            lmtNum: readNumber(args, "lmtNum")
+          }),
+          publicRateLimit("smartmoney_get_signal_overview_by_filter", SMARTMONEY_RPS)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    /* ---------- S2. Signal overview by trader (multi-asset, authorIds-restricted) ---------- */
+    {
+      name: "smartmoney_get_signal_overview_by_trader",
+      module: "smartmoney",
+      description: "Multi-asset smart-money signals aggregated over a hand-picked set of traders (`authorIds`). Pick instruments via `topInstruments` OR `instCcyList`. Pool sizing / ranking / capability filters not exposed \u2014 backend uses defaults for direct-lookup scenarios. Use when: caller already knows which traders to follow and wants their cross-asset consensus at the latest hour. See also: `smartmoney_get_signal_overview_by_filter` (criteria-defined pool), `smartmoney_get_signal_trend_by_trader` (time-series), `smartmoney_get_traders_by_filter` / `smartmoney_search_trader` (discover authorIds).",
+      isWrite: false,
+      outputSchema: envelope({
+        type: "array",
+        description: "Per-instrument snapshot, one element per requested coin.",
+        items: { type: "object", properties: SIGNAL_ITEM_PROPS }
+      }),
+      inputSchema: {
+        type: "object",
+        properties: {
+          authorIds: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            description: 'Trader IDs to aggregate over, e.g. `["1001", "1002"]`. Required.'
+          },
+          topInstruments: {
+            type: "integer",
+            minimum: 1,
+            maximum: 100,
+            default: 20,
+            description: "Top-N hottest instruments held by the given traders (sorted by `tradersWithPosition` DESC). Mutually exclusive with `instCcyList`; one of the two is required (default 20 if neither provided)."
+          },
+          instCcyList: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            description: 'Base currencies to aggregate, e.g. `["BTC", "ETH", "SOL"]`. Mutually exclusive with `topInstruments`.'
+          }
+        },
+        required: ["authorIds"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const authorIds = readArrayAsCsv(args, "authorIds");
+        if (!authorIds) {
+          throw actionableError(
+            '"authorIds" is required and must be a non-empty array.',
+            'Pass IDs from `smartmoney_get_traders_by_filter` as an array (e.g. ["1001", "1002"]).'
+          );
+        }
+        const instCcyList = readArrayAsCsv(args, "instCcyList");
+        const topInstrumentsRaw = readNumber(args, "topInstruments");
+        if (instCcyList && topInstrumentsRaw !== void 0) {
+          throw actionableError(
+            '"topInstruments" and "instCcyList" are mutually exclusive.',
+            "Pass exactly one \u2014 `topInstruments` for top-N hottest coins, or `instCcyList` for specific coins."
+          );
+        }
+        const response = await context.client.privateGet(
+          PATH_OVERVIEW,
+          compactObject({
+            authorIds,
+            ...instCcyList ? { instCcyList } : { topInstruments: topInstrumentsRaw ?? 20 }
+          }),
+          publicRateLimit("smartmoney_get_signal_overview_by_trader", SMARTMONEY_RPS)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    /* ---------- S3. Signal trend by filter (single-asset, tier-filtered pool, asOfTime anchor) ---------- */
+    {
+      name: "smartmoney_get_signal_trend_by_filter",
+      module: "smartmoney",
+      description: "Time-series of single-asset smart-money signal across hourly/daily buckets, aggregated over a tier-filtered trader pool. Returns the latest `limit` buckets ending at `asOfTime` (defaults to current UTC hour). Use when: tracking how long/short conviction and capital evolve over time (smart money adding exposure or retreating). See also: `smartmoney_get_signal_overview_by_filter` (latest snapshot only), `smartmoney_get_signal_trend_by_trader` (restrict to specific traders). Note: `asOfTime` is 10-digit `yyyyMMddHH` UTC, different from leaderboard tools' 12-digit UTC+8 `updateTime` \u2014 do not cross-pass.",
+      isWrite: false,
+      outputSchema: envelope({
+        type: "array",
+        description: "Time-bucket series for the requested instrument, sorted by time DESC (newest first).",
+        items: { type: "object", properties: SIGNAL_HISTORY_ITEM_PROPS }
+      }),
+      inputSchema: {
+        type: "object",
+        properties: {
           instCcy: {
             type: "string",
-            description: "Currency filter e.g. BTC"
+            description: 'Base currency to scope the time-series, e.g. "BTC". Required.'
           },
-          tradeLimit: {
+          asOfTime: {
             type: "string",
-            description: "Max trades 1-100"
+            description: 'Anchor snapshot time. Pass as a quoted 10-digit string `yyyyMMddHH` UTC, e.g. `"2026050100"` (NOT integer 2026050100). Returns the latest `limit` buckets ending at this anchor. Omit to use the current UTC hour.'
+          },
+          granularity: {
+            type: "string",
+            enum: ["1h", "1d"],
+            default: "1h",
+            description: "Time-bucket size. `1h` = hourly snapshots (intraday/short-term trend), `1d` = daily snapshots (multi-day trend)."
+          },
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 500,
+            default: 24,
+            description: "Number of buckets to return (newest first), ending at `asOfTime`. Default 24, max 500."
+          },
+          ...SIGNAL_POOL_FILTER_PROPS,
+          lmtNum: {
+            type: "integer",
+            minimum: 1,
+            maximum: 2e3,
+            default: 100,
+            description: "Top-N traders to pull into the aggregation pool, ranked by `sortBy` (DESC). Default 100, max 2000."
           }
         },
-        required: ["authorId"]
+        required: ["instCcy"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
-        const authorId = requireString(args, "authorId");
-        const period = readString(args, "period");
         const instCcy = readString(args, "instCcy");
-        const tradeLimit = readString(args, "tradeLimit");
-        const [profileRes, positionsRes, tradesRes] = await Promise.all([
-          context.client.privateGet(
-            PATH_LEADERBOARD,
-            compactObject({ authorIds: authorId, period }),
-            publicRateLimit("smartmoney_get_traders", 5)
-          ),
-          context.client.privateGet(
-            PATH_POSITION_CURRENT,
-            compactObject({ authorId, instCcy }),
-            publicRateLimit("smartmoney_trader_positions", 5)
-          ),
-          context.client.privateGet(
-            PATH_TRADE_RECORDS,
-            compactObject({ authorId, instCcy, limit: tradeLimit }),
-            publicRateLimit("smartmoney_trade_records", 5)
-          )
-        ]);
-        const profileNorm = normalizeResponse(profileRes);
-        const positionsNorm = normalizeResponse(positionsRes);
-        const tradesNorm = normalizeResponse(tradesRes);
-        return {
-          endpoint: "smartmoney_get_trader_detail (composite)",
-          requestTime: (/* @__PURE__ */ new Date()).toISOString(),
-          data: {
-            profile: extractLeaderboardData(profileNorm.data),
-            positions: positionsNorm.data,
-            trades: tradesNorm.data
+        if (!instCcy) {
+          throw actionableError(
+            '"instCcy" is required.',
+            'Pass a base currency, e.g. "BTC".'
+          );
+        }
+        const response = await context.client.privateGet(
+          PATH_SIGNAL_HISTORY,
+          compactObject({
+            instCcy,
+            asOfTime: readString(args, "asOfTime"),
+            granularity: readString(args, "granularity"),
+            limit: readNumber(args, "limit"),
+            ...readSignalPoolFilters(args),
+            lmtNum: readNumber(args, "lmtNum")
+          }),
+          publicRateLimit("smartmoney_get_signal_trend_by_filter", SMARTMONEY_RPS)
+        );
+        return normalizeResponse(response);
+      }
+    },
+    /* ---------- S4. Signal trend by trader (single-asset, authorIds-restricted) ---------- */
+    {
+      name: "smartmoney_get_signal_trend_by_trader",
+      module: "smartmoney",
+      description: "Time-series of single-asset smart-money signal aggregated over a hand-picked set of traders (`authorIds`). Returns the latest `limit` buckets ending at `asOfTime` (defaults to current UTC hour). Pool sizing / ranking / capability filters not exposed \u2014 backend uses defaults for direct-lookup scenarios. Use when: tracking how a specific group of traders has evolved their long/short consensus over time on one coin. See also: `smartmoney_get_signal_trend_by_filter` (criteria-defined pool), `smartmoney_get_signal_overview_by_trader` (latest snapshot only), `smartmoney_get_traders_by_filter` / `smartmoney_search_trader` (discover authorIds). Note: `asOfTime` is 10-digit `yyyyMMddHH` UTC, different from leaderboard tools' 12-digit UTC+8 `updateTime` \u2014 do not cross-pass.",
+      isWrite: false,
+      outputSchema: envelope({
+        type: "array",
+        description: "Time-bucket series for the requested instrument, sorted by time DESC (newest first).",
+        items: { type: "object", properties: SIGNAL_HISTORY_ITEM_PROPS }
+      }),
+      inputSchema: {
+        type: "object",
+        properties: {
+          authorIds: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            description: 'Trader IDs to aggregate over, e.g. `["1001", "1002"]`. Required.'
+          },
+          instCcy: {
+            type: "string",
+            description: 'Base currency to scope the time-series, e.g. "BTC". Required.'
+          },
+          asOfTime: {
+            type: "string",
+            description: 'Anchor snapshot time. Pass as a quoted 10-digit string `yyyyMMddHH` UTC, e.g. `"2026050100"` (NOT integer 2026050100). Returns the latest `limit` buckets ending at this anchor. Omit to use the current UTC hour.'
+          },
+          granularity: {
+            type: "string",
+            enum: ["1h", "1d"],
+            default: "1h",
+            description: "Time-bucket size. `1h` = hourly snapshots (intraday/short-term trend), `1d` = daily snapshots (multi-day trend)."
+          },
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 500,
+            default: 24,
+            description: "Number of buckets to return (newest first), ending at `asOfTime`. Default 24, max 500."
           }
-        };
+        },
+        required: ["authorIds", "instCcy"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const authorIds = readArrayAsCsv(args, "authorIds");
+        const instCcy = readString(args, "instCcy");
+        if (!authorIds) {
+          throw actionableError(
+            '"authorIds" is required and must be a non-empty array.',
+            'Pass IDs from `smartmoney_get_traders_by_filter` as an array (e.g. ["1001", "1002"]).'
+          );
+        }
+        if (!instCcy) {
+          throw actionableError(
+            '"instCcy" is required.',
+            'Pass a base currency, e.g. "BTC".'
+          );
+        }
+        const response = await context.client.privateGet(
+          PATH_SIGNAL_HISTORY,
+          compactObject({
+            authorIds,
+            instCcy,
+            asOfTime: readString(args, "asOfTime"),
+            granularity: readString(args, "granularity"),
+            limit: readNumber(args, "limit")
+          }),
+          publicRateLimit("smartmoney_get_signal_trend_by_trader", SMARTMONEY_RPS)
+        );
+        return normalizeResponse(response);
       }
     }
   ];
@@ -6833,8 +7781,12 @@ function buildContractTradeTools(cfg) {
           clOrdId: { type: "string", description: "Client order ID (max 32 chars)" },
           tpTriggerPx: { type: "string", description: "TP trigger price" },
           tpOrdPx: { type: "string", description: "TP order price; -1=market" },
+          tpOrdKind: TP_ORD_KIND_SCHEMA,
+          tpTriggerPxType: TP_TRIGGER_PX_TYPE_SCHEMA,
           slTriggerPx: { type: "string", description: "SL trigger price" },
-          slOrdPx: { type: "string", description: "SL order price; -1=market" }
+          slOrdPx: { type: "string", description: "SL order price; -1=market" },
+          slTriggerPxType: SL_TRIGGER_PX_TYPE_SCHEMA,
+          stpMode: STP_MODE_SCHEMA
         },
         required: ["instId", "tdMode", "side", "ordType", "sz"]
       },
@@ -6863,6 +7815,9 @@ function buildContractTradeTools(cfg) {
             px: readString(args, "px"),
             reduceOnly: typeof reduceOnly === "boolean" ? String(reduceOnly) : void 0,
             clOrdId: readString(args, "clOrdId"),
+            stpMode: readString(args, "stpMode"),
+            // Phase 3c CLI power-user flag (issue #182, CLI-only no MCP/skill exposure)
+            pxAmendType: readString(args, "pxAmendType"),
             tag: context.config.sourceTag,
             attachAlgoOrds
           }),
@@ -8862,6 +9817,8 @@ function registerOptionTools() {
             type: "string",
             description: "TP order price; -1=market"
           },
+          tpOrdKind: TP_ORD_KIND_SCHEMA,
+          tpTriggerPxType: TP_TRIGGER_PX_TYPE_SCHEMA,
           slTriggerPx: {
             type: "string",
             description: "SL trigger price"
@@ -8869,7 +9826,9 @@ function registerOptionTools() {
           slOrdPx: {
             type: "string",
             description: "SL order price; -1=market"
-          }
+          },
+          slTriggerPxType: SL_TRIGGER_PX_TYPE_SCHEMA,
+          stpMode: STP_MODE_SCHEMA
         },
         required: ["instId", "tdMode", "side", "ordType", "sz"]
       },
@@ -8897,6 +9856,7 @@ function registerOptionTools() {
             px: readString(args, "px"),
             reduceOnly: typeof reduceOnly === "boolean" ? String(reduceOnly) : void 0,
             clOrdId: readString(args, "clOrdId"),
+            stpMode: readString(args, "stpMode"),
             tag: context.config.sourceTag,
             attachAlgoOrds
           }),
@@ -9265,6 +10225,8 @@ function registerSpotTradeTools() {
             type: "string",
             description: "TP order price, -1=market"
           },
+          tpOrdKind: TP_ORD_KIND_SCHEMA,
+          tpTriggerPxType: TP_TRIGGER_PX_TYPE_SCHEMA,
           slTriggerPx: {
             type: "string",
             description: "SL trigger price"
@@ -9272,13 +10234,16 @@ function registerSpotTradeTools() {
           slOrdPx: {
             type: "string",
             description: "SL order price, -1=market"
-          }
+          },
+          slTriggerPxType: SL_TRIGGER_PX_TYPE_SCHEMA,
+          stpMode: STP_MODE_SCHEMA
         },
         required: ["instId", "tdMode", "side", "ordType", "sz"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
         const attachAlgoOrds = buildAttachAlgoOrds(args);
+        const banAmend = args.banAmend;
         const response = await context.client.privatePost(
           "/api/v5/trade/order",
           compactObject({
@@ -9290,6 +10255,11 @@ function registerSpotTradeTools() {
             tgtCcy: readString(args, "tgtCcy"),
             px: readString(args, "px"),
             clOrdId: readString(args, "clOrdId"),
+            stpMode: readString(args, "stpMode"),
+            // Phase 3c CLI power-user flags (issue #182, CLI-only no MCP/skill exposure)
+            tradeQuoteCcy: readString(args, "tradeQuoteCcy"),
+            banAmend: typeof banAmend === "boolean" ? String(banAmend) : void 0,
+            pxAmendType: readString(args, "pxAmendType"),
             tag: context.config.sourceTag,
             attachAlgoOrds
           }),
@@ -9454,7 +10424,7 @@ function registerSpotTradeTools() {
     {
       name: "spot_place_algo_order",
       module: "spot",
-      description: "Place a spot algo order: TP/SL (conditional/oco) or trailing stop (move_order_stop). [CAUTION] Executes real trades.",
+      description: "Place a spot algo order. [CAUTION] Executes real trades. conditional: single TP/SL. oco: TP+SL pair. move_order_stop: trailing stop. trigger: pending order at triggerPx. chase: follow best bid/ask. iceberg: split large order into child orders. twap: time-weighted split.",
       isWrite: true,
       inputSchema: {
         type: "object",
@@ -9474,8 +10444,8 @@ function registerSpotTradeTools() {
           },
           ordType: {
             type: "string",
-            enum: ["conditional", "oco", "move_order_stop"],
-            description: "conditional=single TP/SL, oco=TP+SL pair, move_order_stop=trailing stop"
+            enum: ["conditional", "oco", "move_order_stop", "trigger", "chase", "iceberg", "twap"],
+            description: "conditional=single TP/SL, oco=TP+SL pair, move_order_stop=trailing stop, trigger=pending order, chase=follow best bid/ask, iceberg=split order, twap=time-weighted split"
           },
           sz: {
             type: "string",
@@ -9489,6 +10459,8 @@ function registerSpotTradeTools() {
             type: "string",
             description: "TP order price, -1=market (conditional/oco only)"
           },
+          tpOrdKind: TP_ORD_KIND_SCHEMA,
+          tpTriggerPxType: TP_TRIGGER_PX_TYPE_SCHEMA,
           slTriggerPx: {
             type: "string",
             description: "SL trigger price (conditional/oco only)"
@@ -9497,6 +10469,8 @@ function registerSpotTradeTools() {
             type: "string",
             description: "SL order price, -1=market (conditional/oco only)"
           },
+          slTriggerPxType: SL_TRIGGER_PX_TYPE_SCHEMA,
+          stpMode: STP_MODE_SCHEMA,
           tgtCcy: {
             type: "string",
             enum: ["base_ccy", "quote_ccy"],
@@ -9513,30 +10487,50 @@ function registerSpotTradeTools() {
           activePx: {
             type: "string",
             description: "Activation price, trailing starts when market hits this (move_order_stop only)"
-          }
+          },
+          ...TRIGGER_FLAGS_SCHEMA,
+          ...CHASE_FLAGS_SCHEMA,
+          ...ICEBERG_TWAP_FLAGS_SCHEMA
         },
         required: ["instId", "side", "ordType", "sz"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
+        const ordType = requireString(args, "ordType");
+        const base = compactObject({
+          instId: requireString(args, "instId"),
+          tdMode: readString(args, "tdMode") ?? "cash",
+          side: requireString(args, "side"),
+          ordType,
+          sz: requireString(args, "sz"),
+          tgtCcy: readString(args, "tgtCcy"),
+          stpMode: readString(args, "stpMode"),
+          // Phase 3a+c CLI power-user flags (issue #182, CLI-only no MCP/skill exposure)
+          pxAmendType: readString(args, "pxAmendType"),
+          tag: context.config.sourceTag
+        });
+        switch (ordType) {
+          case "trigger":
+            Object.assign(base, buildTriggerOrdTypeBody(args));
+            break;
+          case "chase":
+            Object.assign(base, buildChaseOrdTypeBody(args));
+            break;
+          case "iceberg":
+          case "twap":
+            Object.assign(base, buildIcebergTwapOrdTypeBody(args));
+            break;
+          default:
+            Object.assign(base, compactObject({
+              ...buildAlgoConditionalCommonFields(args),
+              callbackRatio: readString(args, "callbackRatio"),
+              callbackSpread: readString(args, "callbackSpread")
+            }));
+            break;
+        }
         const response = await context.client.privatePost(
           "/api/v5/trade/order-algo",
-          compactObject({
-            instId: requireString(args, "instId"),
-            tdMode: readString(args, "tdMode") ?? "cash",
-            side: requireString(args, "side"),
-            ordType: requireString(args, "ordType"),
-            sz: requireString(args, "sz"),
-            tgtCcy: readString(args, "tgtCcy"),
-            tpTriggerPx: readString(args, "tpTriggerPx"),
-            tpOrdPx: readString(args, "tpOrdPx"),
-            slTriggerPx: readString(args, "slTriggerPx"),
-            slOrdPx: readString(args, "slOrdPx"),
-            callbackRatio: readString(args, "callbackRatio"),
-            callbackSpread: readString(args, "callbackSpread"),
-            activePx: readString(args, "activePx"),
-            tag: context.config.sourceTag
-          }),
+          base,
           privateRateLimit("spot_place_algo_order", 20)
         );
         return normalizeResponse(response);
@@ -10130,6 +11124,7 @@ function toMcpTool(tool) {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
+    ...tool.outputSchema ? { outputSchema: tool.outputSchema } : {},
     annotations: {
       readOnlyHint: !tool.isWrite,
       destructiveHint: tool.isWrite,
@@ -10563,7 +11558,7 @@ var _require = createRequire(import.meta.url);
 var pkg = _require("../package.json");
 var SERVER_NAME = "okx-trade-mcp";
 var SERVER_VERSION = pkg.version;
-var GIT_HASH = true ? "1bb94dcd" : "dev";
+var GIT_HASH = true ? "d0f8ad6" : "dev";
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";