@okx_ai/okx-trade-cli 1.3.3-beta.1 → 1.3.3-beta.2

package/dist/index.js

@@ -880,32 +880,29 @@ import * as path3 from "path";
 import * as os3 from "os";
 import { execFileSync } from "child_process";
 import {
-  createWriteStream as createWriteStream3,
   mkdirSync as mkdirSync9,
   chmodSync as chmodSync2,
   existsSync as existsSync7,
-  unlinkSync as unlinkSync4,
+  unlinkSync as unlinkSync5,
   renameSync as renameSync4
 } from "fs";
 import { homedir as homedir9, platform as platform2 } from "os";
 import { join as join11, dirname as dirname7 } from "path";
-import { get as httpsGet2 } from "https";
-import { get as httpGet2 } from "http";
+import { createWriteStream as createWriteStream2, unlinkSync as unlinkSync3 } from "fs";
+import { get as httpsGet } from "https";
+import { get as httpGet } from "http";
 import {
   readFileSync as readFileSync7,
-  createWriteStream as createWriteStream2,
   mkdirSync as mkdirSync8,
   chmodSync,
   existsSync as existsSync6,
-  unlinkSync as unlinkSync3,
+  unlinkSync as unlinkSync4,
   renameSync as renameSync3
 } from "fs";
 import { createHash } from "crypto";
 import { homedir as homedir8, platform, arch } from "os";
 import { join as join10, dirname as dirname6 } from "path";
-import { get as httpsGet } from "https";
-import { get as httpGet } from "http";
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync7, mkdirSync as mkdirSync10, unlinkSync as unlinkSync5, existsSync as existsSync8 } from "fs";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync7, mkdirSync as mkdirSync10, unlinkSync as unlinkSync6, existsSync as existsSync8 } from "fs";
 import { join as join12 } from "path";
 import { homedir as homedir10 } from "os";
 var EXEC_TIMEOUT_MS = 3e4;
@@ -1634,7 +1631,7 @@ var OkxRestClient = class _OkxRestClient {
     headers.set("OK-ACCESS-TIMESTAMP", timestamp);
   }
   throwOkxError(code, msg, reqConfig, traceId) {
-    const message = msg || "OKX API request failed.";
+    const message = msg && msg.trim() !== "" ? msg : `OKX API rejected request (code ${code}).`;
     const endpoint = `${reqConfig.method} ${reqConfig.path}`;
     if (code === "50111" || code === "50112" || code === "50113") {
       throw new AuthenticationError(
@@ -6999,31 +6996,31 @@ var SIGNAL_POOL_FILTER_PROPS = {
     type: "string",
     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).'
+    description: 'Lookback window in days. One of `"3"` / `"7"` / `"30"` / `"90"`. Drives capability metrics (avgLongWinRate / avgShortWinRate) and the `winRateTier` filter. Does NOT affect signal fields (which always use the latest snapshot).'
   },
   pnlTier: {
     type: "string",
     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."
+    description: "PnL percentile gate applied on top of `sortBy`. Naming: `TOP{N}` = top N% percentile (NOT an absolute PnL value). PNL_ANY = no filter; PNL_TOP50 = PnL \u2265 P50 (median); PNL_TOP20 = \u2265 P80; PNL_TOP5 = \u2265 P95. PnL distribution is long-tailed \u2014 use percentile, not absolute thresholds."
   },
   winRateTier: {
     type: "string",
     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%."
+    description: "Minimum win-rate gate (absolute thresholds, NOT percentile). Naming: `GE_{N}` = career win-rate \u2265 N% \u2014 distinct from `pnlTier`/`aumTier` `TOP{N}` which are percentiles. WR_ANY = no filter; WR_GE_50 = \u2265 50%; WR_GE_80 = \u2265 80%."
   },
   maxDrawdownTier: {
     type: "string",
     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%."
+    description: "Maximum-drawdown gate (absolute thresholds, NOT percentile; smaller drawdown = lower risk). Naming: `LE_{N}` = drawdown \u2264 N% \u2014 distinct from `pnlTier`/`aumTier` `TOP{N}` which are percentiles. MR_ANY = no filter; MR_LE_20 = drawdown \u2264 20%; MR_LE_50 = \u2264 50%."
   },
   aumTier: {
     type: "string",
     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."
+    description: "AUM (Assets Under Management) percentile gate. Naming: `TOP{N}` = top N% percentile (NOT an absolute USD amount). AUM_ANY = no filter; AUM_TOP50 = AUM \u2265 P50; AUM_TOP20 = \u2265 P80; AUM_TOP5 = \u2265 P95. AUM is long-tailed \u2014 use percentile, not absolute USD."
   }
 };
 var LEADERBOARD_POOL_FILTER_PROPS = {
@@ -7031,29 +7028,29 @@ var LEADERBOARD_POOL_FILTER_PROPS = {
     type: "string",
     enum: ["pnl", "pnlRatio"],
     default: "pnl",
-    description: "Leaderboard sort key. `pnl` = absolute USD profit; `pnlRatio` = percentage return."
+    description: 'Required. Leaderboard sort key. `pnl` = absolute USD profit; `pnlRatio` = percentage return. Default `"pnl"`.'
   },
   period: {
     type: "string",
     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.'
+    description: 'Required. Performance lookback window in days. One of `"3"` / `"7"` / `"30"` / `"90"`. Default `"90"` (matches leaderboard UI). Filters AND ranks traders by their PnL over that window.'
   },
   minPnl: {
     type: "string",
-    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.'
+    description: 'Minimum absolute PnL in USD as a string, e.g. `"10000"` \u2192 traders with PnL \u2265 $10,000. Numeric threshold \u2014 distinct from the signal-side `pnlTier` percentile enum.'
   },
   minWinRate: {
     type: "string",
-    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.'
+    description: 'Minimum win-rate as a decimal in 0~1 range, passed as a string, e.g. `"0.8"` \u2192 traders with win-rate \u2265 80%. Numeric threshold \u2014 distinct from the signal-side `winRateTier` enum.'
   },
   maxDrawdown: {
     type: "string",
-    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.'
+    description: 'Maximum drawdown as a decimal, passed as a string, e.g. `"0.1"` \u2192 traders with drawdown \u2264 10%. Lower = lower risk. Numeric threshold \u2014 distinct from the signal-side `maxDrawdownTier` enum.'
   },
   minAum: {
     type: "string",
-    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.'
+    description: 'Minimum AUM (Assets Under Management) in USD as a string, e.g. `"1000"` \u2192 traders with AUM \u2265 $1,000. Numeric threshold \u2014 distinct from the signal-side `aumTier` percentile enum.'
   }
 };
 var LEADERBOARD_FILTER_UPSTREAM_NAMES = {
@@ -7065,19 +7062,25 @@ var LEADERBOARD_FILTER_UPSTREAM_NAMES = {
   minAum: "asset"
 };
 function readPoolFilters(args) {
+  assertPoolFilterEnums(args, LEADERBOARD_POOL_FILTER_PROPS);
   const result = {};
   for (const [publicKey, upstreamKey] of Object.entries(LEADERBOARD_FILTER_UPSTREAM_NAMES)) {
     const val = readString(args, publicKey);
     if (val !== void 0 && val !== "") result[upstreamKey] = val;
   }
+  if (result.sortBy === void 0) result.sortBy = "pnl";
+  if (result.period === void 0) result.period = "90";
   return result;
 }
 function readSignalPoolFilters(args) {
+  assertPoolFilterEnums(args, SIGNAL_POOL_FILTER_PROPS);
   const result = {};
   for (const key of Object.keys(SIGNAL_POOL_FILTER_PROPS)) {
     const val = readString(args, key);
     if (val) result[key] = val;
   }
+  if (result.sortBy === void 0) result.sortBy = "pnl";
+  if (result.period === void 0) result.period = "7";
   return result;
 }
 function extractLeaderboardEnvelope(data) {
@@ -7093,7 +7096,7 @@ function extractLeaderboardEnvelope(data) {
 function deriveDirection(posSide, pos) {
   if (posSide === "long") return "long";
   if (posSide === "short") return "short";
-  if (posSide === "both" && typeof pos === "string" && pos !== "") {
+  if ((posSide === "net" || posSide === "both") && typeof pos === "string" && pos !== "") {
     const n = Number(pos);
     if (Number.isFinite(n) && n !== 0) return n > 0 ? "long" : "short";
   }
@@ -7130,6 +7133,22 @@ function extractBaseCcy(instId) {
 function actionableError(message, hint) {
   return new ValidationError(`${message} ${hint}`);
 }
+function assertEnum2(args, key, allowed) {
+  const val = readString(args, key);
+  if (val === void 0 || val === "") return;
+  if (!allowed.includes(val)) {
+    throw actionableError(
+      `Invalid value for "${key}": ${JSON.stringify(val)}.`,
+      `Allowed values: ${allowed.map((v) => JSON.stringify(v)).join(", ")}.`
+    );
+  }
+}
+function assertPoolFilterEnums(args, props) {
+  for (const [key, spec] of Object.entries(props)) {
+    const enumList = spec.enum;
+    if (Array.isArray(enumList)) assertEnum2(args, key, enumList);
+  }
+}
 function readArrayAsCsv(args, key) {
   const arr = readStringArray(args, key);
   if (!arr || arr.length === 0) return void 0;
@@ -7206,21 +7225,33 @@ var SIGNAL_ITEM_PROPS = {
     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." },
+      longNotionalUsdt: {
+        type: "string",
+        description: "Sum of long-side notional in USDT, weighted by each trader's ENTRY PRICE (price_avg), not mark price. Moves only when positions are opened / closed / scaled \u2014 stays constant when positions are unchanged."
+      },
+      shortNotionalUsdt: {
+        type: "string",
+        description: "Sum of short-side notional in USDT, weighted by each trader's ENTRY PRICE (price_avg), not mark price. Moves only when positions are opened / closed / scaled \u2014 stays constant when positions are unchanged."
+      },
+      netNotionalUsdt: {
+        type: "string",
+        description: "Net directional notional in USDT = long \u2212 short. Weighted by each trader's ENTRY PRICE (price_avg), not mark price \u2014 reflects position scaling, not underlying price movement."
+      },
+      totalNotionalUsdt: {
+        type: "string",
+        description: "Gross notional in USDT = long + short. Weighted by each trader's ENTRY PRICE (price_avg), not mark price \u2014 reflects position scaling (open / close / add), not underlying price movement. Stays constant across buckets when traders hold positions unchanged."
+      },
       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."
+        description: 'Long-side notional-weighted average entry price (USDT). Empty string `""` 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."
+        description: 'Short-side notional-weighted average entry price (USDT). Empty string `""` when no short.'
       }
     }
   },
@@ -7232,14 +7263,17 @@ var SIGNAL_ITEM_PROPS = {
       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." },
+      shortRatio: {
+        type: "string",
+        description: "Headcount short ratio = shortTraders / tradersWithPosition. NULL when no traders."
+      },
       weightedLongRatio: {
         type: "string",
-        description: "Notional-weighted long ratio = \u03A3(long_notional) / \u03A3(notional). NULL when no notional."
+        description: "Notional-weighted long ratio = \u03A3(long_notional) / \u03A3(notional). Notional uses each trader's ENTRY PRICE (price_avg), not mark price \u2014 ratio shifts only when positions are scaled. NULL when no notional."
       },
       weightedShortRatio: {
         type: "string",
-        description: "Notional-weighted short ratio = \u03A3(short_notional) / \u03A3(notional). NULL when no notional."
+        description: "Notional-weighted short ratio = \u03A3(short_notional) / \u03A3(notional). Notional uses each trader's ENTRY PRICE (price_avg), not mark price. NULL when no notional."
       }
     }
   },
@@ -7266,15 +7300,15 @@ var SIGNAL_HISTORY_ITEM_PROPS = {
   },
   shortRatio: {
     type: "string",
-    description: "Headcount short ratio at this bucket = 1 \u2212 longRatio. Decimal 0~1."
+    description: "Headcount short ratio at this bucket = shortTraders / tradersWithPosition. Decimal 0~1."
   },
   weightedLongRatio: {
     type: "string",
-    description: "Notional-weighted long ratio at this bucket. Decimal 0~1."
+    description: "Notional-weighted long ratio at this bucket = \u03A3(long_notional) / \u03A3(notional). Decimal 0~1. Notional uses each trader's ENTRY PRICE (price_avg), not mark price \u2014 ratio shifts only when positions are scaled."
   },
   weightedShortRatio: {
     type: "string",
-    description: "Notional-weighted short ratio at this bucket. Decimal 0~1."
+    description: "Notional-weighted short ratio at this bucket = \u03A3(short_notional) / \u03A3(notional). Decimal 0~1. Notional uses each trader's ENTRY PRICE (price_avg), not mark price."
   },
   longTraders: {
     type: "integer",
@@ -7290,11 +7324,11 @@ var SIGNAL_HISTORY_ITEM_PROPS = {
   },
   netNotionalUsdt: {
     type: "string",
-    description: "Net directional notional in USDT at this bucket = long notional \u2212 short notional."
+    description: "Net directional notional in USDT at this bucket = long notional \u2212 short notional. Weighted by each trader's ENTRY PRICE (price_avg), not mark price \u2014 reflects position scaling, not underlying price movement."
   },
   totalNotionalUsdt: {
     type: "string",
-    description: "Gross notional in USDT at this bucket = long notional + short notional. Tracks total capital deployed (rising = adding, falling = retreating)."
+    description: "Gross notional in USDT at this bucket = long notional + short notional. Weighted by each trader's ENTRY PRICE (price_avg), not mark price \u2014 tracks capital deployed (rising = adding, falling = retreating). Stays constant across buckets when traders hold positions unchanged."
   },
   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`)." }
@@ -7325,16 +7359,16 @@ function registerSmartmoneyTools() {
         properties: {
           updateTime: {
             type: "string",
-            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).'
+            description: 'Snapshot version key \u2014 12-digit `yyyyMMddHHmm` (UTC+8) as a string, e.g. `"202604301815"`. Omit to query the latest snapshot (refreshed every ~5 min).'
           },
           ...LEADERBOARD_POOL_FILTER_PROPS,
           after: {
             type: "string",
-            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."
+            description: 'Pagination cursor (older page) \u2014 pass the `authorId` of the last item from the previous page as a string, e.g. `"872913470357110787"`. Cursor anchors on `authorId` while preserving the current `sortBy` order.'
           },
           before: {
             type: "string",
-            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."
+            description: 'Pagination cursor (newer page) \u2014 pass the `authorId` of the first item from the previous page as a string, e.g. `"872913470357110787"`. Cursor anchors on `authorId` while preserving the current `sortBy` order.'
           },
           limit: {
             type: "integer",
@@ -7343,7 +7377,8 @@ function registerSmartmoneyTools() {
             default: 10,
             description: "Max results per page (default 10, max 100)."
           }
-        }
+        },
+        required: ["sortBy", "period"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
@@ -7393,17 +7428,25 @@ function registerSmartmoneyTools() {
             minItems: 1,
             description: 'Trader IDs to look up, e.g. `["1001", "1002"]`. Required.'
           },
+          sortBy: {
+            type: "string",
+            enum: ["pnl", "pnlRatio"],
+            default: "pnl",
+            description: 'Required. Result sort key. `pnl` = absolute USD profit; `pnlRatio` = percentage return. Default `"pnl"`.'
+          },
           period: {
             type: "string",
             enum: PERIOD_DAYS,
             default: "90",
-            description: 'Performance lookback window in days. Pass as a quoted string: `"3"` / `"7"` / `"30"` / `"90"` (NOT integer). Default `"90"`.'
+            description: 'Required. Performance lookback window in days. One of `"3"` / `"7"` / `"30"` / `"90"`. Default `"90"`.'
           }
         },
-        required: ["authorIds"]
+        required: ["authorIds", "sortBy", "period"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
+        assertEnum2(args, "sortBy", ["pnl", "pnlRatio"]);
+        assertEnum2(args, "period", PERIOD_DAYS);
         const authorIds = readArrayAsCsv(args, "authorIds");
         if (!authorIds) {
           throw actionableError(
@@ -7415,7 +7458,10 @@ function registerSmartmoneyTools() {
           PATH_LEADERBOARD,
           compactObject({
             authorIds,
-            period: readString(args, "period")
+            // Apply schema defaults explicitly so behavior does not depend on backend defaults
+            // (CLI bypasses MCP `required` validation, so handler is the only deterministic layer).
+            sortBy: readString(args, "sortBy") ?? "pnl",
+            period: readString(args, "period") ?? "90"
           }),
           publicRateLimit("smartmoney_get_performance_by_trader", SMARTMONEY_RPS)
         );
@@ -7447,12 +7493,12 @@ function registerSmartmoneyTools() {
             },
             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."
+              description: "Raw upstream position direction. `long` = long-side position (buy-to-open); `short` = short-side position (sell-to-open); `net` (or legacy `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.'
+              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="net"` 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".' },
@@ -7600,11 +7646,11 @@ function registerSmartmoneyTools() {
           },
           after: {
             type: "string",
-            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)."
+            description: 'Pagination cursor (older) \u2014 returns positions with `posId` smaller than this value. Pass the `posId` as a string, e.g. `"872913470357110787"`.'
           },
           before: {
             type: "string",
-            description: "Cursor: returns positions with `posId` greater than this value (newer \u2014 paginate forwards). Pass as quoted string."
+            description: 'Pagination cursor (newer) \u2014 returns positions with `posId` greater than this value. Pass the `posId` as a string, e.g. `"872913470357110787"`.'
           },
           limit: {
             type: "integer",
@@ -7718,11 +7764,11 @@ function registerSmartmoneyTools() {
           },
           after: {
             type: "string",
-            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)."
+            description: 'Pagination cursor (older) \u2014 returns trades with `ordId` smaller than this value. Pass the `ordId` as a string, e.g. `"872913470357110787"`.'
           },
           before: {
             type: "string",
-            description: "Cursor: returns trades with `ordId` greater than this value (newer \u2014 paginate forwards). Pass as quoted string."
+            description: 'Pagination cursor (newer) \u2014 returns trades with `ordId` greater than this value. Pass the `ordId` as a string, e.g. `"872913470357110787"`.'
           },
           limit: {
             type: "integer",
@@ -7818,7 +7864,7 @@ function registerSmartmoneyTools() {
     {
       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).",
+      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. **Linear (USDT/USDS-margined) contracts only \u2014 coin-margined (`-USD-SWAP` / `-USD-DELIVERY`) positions are excluded by upstream and silently omitted from the aggregation.** 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",
@@ -7839,7 +7885,7 @@ function registerSmartmoneyTools() {
             type: "array",
             items: { type: "string" },
             minItems: 1,
-            description: 'Base currencies to aggregate, e.g. `["BTC", "ETH", "SOL"]`. Mutually exclusive with `topInstruments`.'
+            description: 'Base currencies to aggregate, e.g. `["BTC", "ETH", "SOL"]`. Mutually exclusive with `topInstruments`. Scope: only USDT-margined and USDS-margined (linear) instruments \u2014 e.g. `BTC` covers `BTC-USDT-SWAP` + `BTC-USDS-SWAP`. Coin-margined contracts (`BTC-USD-SWAP`, `BTC-USD-DELIVERY`) are NOT included; positions a trader holds in those instruments are silently dropped from the aggregation.'
           },
           ...SIGNAL_POOL_FILTER_PROPS,
           lmtNum: {
@@ -7849,7 +7895,8 @@ function registerSmartmoneyTools() {
             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."
           }
-        }
+        },
+        required: ["sortBy", "period"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
@@ -7877,7 +7924,7 @@ function registerSmartmoneyTools() {
     {
       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).",
+      description: "Multi-asset smart-money signals aggregated over a hand-picked set of traders (`authorIds`). Pick instruments via `topInstruments` OR `instCcyList`. Capability tier filters (pnlTier / winRateTier / etc.) not exposed \u2014 backend uses defaults for direct-lookup scenarios. **Linear (USDT/USDS-margined) contracts only \u2014 a trader's coin-margined (`-USD-SWAP` / `-USD-DELIVERY`) positions are silently excluded from the aggregation, even when those positions are large.** Use `smartmoney_get_trader_positions` if the full position book is needed. 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",
@@ -7904,13 +7951,27 @@ function registerSmartmoneyTools() {
             type: "array",
             items: { type: "string" },
             minItems: 1,
-            description: 'Base currencies to aggregate, e.g. `["BTC", "ETH", "SOL"]`. Mutually exclusive with `topInstruments`.'
+            description: 'Base currencies to aggregate, e.g. `["BTC", "ETH", "SOL"]`. Mutually exclusive with `topInstruments`. Scope: only USDT-margined and USDS-margined (linear) instruments \u2014 e.g. `BTC` covers `BTC-USDT-SWAP` + `BTC-USDS-SWAP`. Coin-margined contracts (`BTC-USD-SWAP`, `BTC-USD-DELIVERY`) are NOT included; the trader\'s positions in those instruments are silently dropped.'
+          },
+          sortBy: {
+            type: "string",
+            enum: ["pnl", "pnlRatio"],
+            default: "pnl",
+            description: 'Required. Ranking key for the trader set. `pnl` = absolute USD profit; `pnlRatio` = percentage return. Default `"pnl"`.'
+          },
+          period: {
+            type: "string",
+            enum: PERIOD_DAYS,
+            default: "7",
+            description: 'Required. Lookback window in days for capability metrics (`winRate.avgLongWinRate` / `avgShortWinRate`). One of `"3"` / `"7"` / `"30"` / `"90"`. Default `"7"`. Does NOT affect signal fields.'
           }
         },
-        required: ["authorIds"]
+        required: ["authorIds", "sortBy", "period"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
+        assertEnum2(args, "sortBy", ["pnl", "pnlRatio"]);
+        assertEnum2(args, "period", PERIOD_DAYS);
         const authorIds = readArrayAsCsv(args, "authorIds");
         if (!authorIds) {
           throw actionableError(
@@ -7930,7 +7991,11 @@ function registerSmartmoneyTools() {
           PATH_OVERVIEW,
           compactObject({
             authorIds,
-            ...instCcyList ? { instCcyList } : { topInstruments: topInstrumentsRaw ?? 20 }
+            ...instCcyList ? { instCcyList } : { topInstruments: topInstrumentsRaw ?? 20 },
+            // Apply schema defaults explicitly so behavior does not depend on backend defaults
+            // (CLI bypasses MCP `required` validation, so handler is the only deterministic layer).
+            sortBy: readString(args, "sortBy") ?? "pnl",
+            period: readString(args, "period") ?? "7"
           }),
           publicRateLimit("smartmoney_get_signal_overview_by_trader", SMARTMONEY_RPS)
         );
@@ -7941,7 +8006,7 @@ function registerSmartmoneyTools() {
     {
       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.",
+      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). **Linear (USDT/USDS-margined) contracts only \u2014 coin-margined (`-USD-SWAP` / `-USD-DELIVERY`) positions are excluded by upstream and silently omitted.** 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",
@@ -7953,11 +8018,11 @@ function registerSmartmoneyTools() {
         properties: {
           instCcy: {
             type: "string",
-            description: 'Base currency to scope the time-series, e.g. "BTC". Required.'
+            description: 'Base currency to scope the time-series, e.g. "BTC". Required. Scope: USDT-margined and USDS-margined (linear) instruments only \u2014 coin-margined (`-USD-SWAP` / `-USD-DELIVERY`) positions are NOT included.'
           },
           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.'
+            description: 'Anchor snapshot time \u2014 10-digit `yyyyMMddHH` UTC as a string, e.g. `"2026050100"`. Returns the latest `limit` buckets ending at this anchor. Omit to use the current UTC hour.'
           },
           granularity: {
             type: "string",
@@ -7981,10 +8046,11 @@ function registerSmartmoneyTools() {
             description: "Top-N traders to pull into the aggregation pool, ranked by `sortBy` (DESC). Default 100, max 2000."
           }
         },
-        required: ["instCcy"]
+        required: ["instCcy", "granularity", "sortBy", "period"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
+        assertEnum2(args, "granularity", ["1h", "1d"]);
         const instCcy = readString(args, "instCcy");
         if (!instCcy) {
           throw actionableError(
@@ -7997,7 +8063,8 @@ function registerSmartmoneyTools() {
           compactObject({
             instCcy,
             asOfTime: readString(args, "asOfTime"),
-            granularity: readString(args, "granularity"),
+            // Apply schema default explicitly (CLI bypasses MCP `required` validation).
+            granularity: readString(args, "granularity") ?? "1h",
             limit: readNumber(args, "limit"),
             ...readSignalPoolFilters(args),
             lmtNum: readNumber(args, "lmtNum")
@@ -8011,7 +8078,7 @@ function registerSmartmoneyTools() {
     {
       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.",
+      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). Capability tier filters (pnlTier / winRateTier / etc.) not exposed \u2014 backend uses defaults for direct-lookup scenarios. **Linear (USDT/USDS-margined) contracts only \u2014 a trader's coin-margined (`-USD-SWAP` / `-USD-DELIVERY`) positions on the requested base ccy are silently excluded from each bucket.** Use `smartmoney_get_trader_positions` to inspect the full position book. 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",
@@ -8029,11 +8096,11 @@ function registerSmartmoneyTools() {
           },
           instCcy: {
             type: "string",
-            description: 'Base currency to scope the time-series, e.g. "BTC". Required.'
+            description: 'Base currency to scope the time-series, e.g. "BTC". Required. Scope: USDT-margined and USDS-margined (linear) instruments only \u2014 coin-margined (`-USD-SWAP` / `-USD-DELIVERY`) positions held by the trader set are NOT included.'
           },
           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.'
+            description: 'Anchor snapshot time \u2014 10-digit `yyyyMMddHH` UTC as a string, e.g. `"2026050100"`. Returns the latest `limit` buckets ending at this anchor. Omit to use the current UTC hour.'
           },
           granularity: {
             type: "string",
@@ -8047,12 +8114,27 @@ function registerSmartmoneyTools() {
             maximum: 500,
             default: 24,
             description: "Number of buckets to return (newest first), ending at `asOfTime`. Default 24, max 500."
+          },
+          sortBy: {
+            type: "string",
+            enum: ["pnl", "pnlRatio"],
+            default: "pnl",
+            description: 'Required. Ranking key for the trader set. `pnl` = absolute USD profit; `pnlRatio` = percentage return. Default `"pnl"`.'
+          },
+          period: {
+            type: "string",
+            enum: PERIOD_DAYS,
+            default: "7",
+            description: 'Required. Lookback window in days. One of `"3"` / `"7"` / `"30"` / `"90"`. Default `"7"`. Does NOT affect signal fields (which always use the latest snapshot).'
           }
         },
-        required: ["authorIds", "instCcy"]
+        required: ["authorIds", "instCcy", "granularity", "sortBy", "period"]
       },
       handler: async (rawArgs, context) => {
         const args = asRecord(rawArgs);
+        assertEnum2(args, "granularity", ["1h", "1d"]);
+        assertEnum2(args, "sortBy", ["pnl", "pnlRatio"]);
+        assertEnum2(args, "period", PERIOD_DAYS);
         const authorIds = readArrayAsCsv(args, "authorIds");
         const instCcy = readString(args, "instCcy");
         if (!authorIds) {
@@ -8073,8 +8155,12 @@ function registerSmartmoneyTools() {
             authorIds,
             instCcy,
             asOfTime: readString(args, "asOfTime"),
-            granularity: readString(args, "granularity"),
-            limit: readNumber(args, "limit")
+            // Apply schema defaults explicitly so behavior does not depend on backend defaults
+            // (CLI bypasses MCP `required` validation, so handler is the only deterministic layer).
+            granularity: readString(args, "granularity") ?? "1h",
+            limit: readNumber(args, "limit"),
+            sortBy: readString(args, "sortBy") ?? "pnl",
+            period: readString(args, "period") ?? "7"
           }),
           publicRateLimit("smartmoney_get_signal_trend_by_trader", SMARTMONEY_RPS)
         );
@@ -11925,6 +12011,78 @@ function runSetup(options) {
 `);
   }
 }
+function isRedirect(statusCode) {
+  return statusCode !== void 0 && statusCode >= 300 && statusCode < 400;
+}
+function validateRedirect(res, requestUrl, redirectCount, maxRedirects) {
+  if (redirectCount > maxRedirects) {
+    throw new Error(`Too many redirects (${maxRedirects})`);
+  }
+  const location = res.headers.location;
+  if (requestUrl.startsWith("https") && !location.startsWith("https")) {
+    throw new Error("Refused HTTPS \u2192 HTTP redirect downgrade");
+  }
+  return location;
+}
+function fetchResponse(url, timeoutMs) {
+  return new Promise((resolve3, reject) => {
+    let redirects = 0;
+    const maxRedirects = 5;
+    function doRequest(requestUrl) {
+      const reqFn = requestUrl.startsWith("https") ? httpsGet : httpGet;
+      const req = reqFn(requestUrl, { timeout: timeoutMs }, (res) => {
+        if (isRedirect(res.statusCode) && res.headers.location) {
+          redirects++;
+          try {
+            const location = validateRedirect(res, requestUrl, redirects, maxRedirects);
+            res.resume();
+            doRequest(location);
+          } catch (err) {
+            reject(err);
+          }
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`HTTP ${res.statusCode ?? "unknown"}`));
+          return;
+        }
+        resolve3(res);
+      });
+      req.on("error", reject);
+      req.on("timeout", () => {
+        req.destroy();
+        reject(new Error("Download timed out"));
+      });
+    }
+    doRequest(url);
+  });
+}
+function download(url, destPath, timeoutMs) {
+  return fetchResponse(url, timeoutMs).then(
+    (res) => new Promise((resolve3, reject) => {
+      const file = createWriteStream2(destPath);
+      res.pipe(file);
+      file.on("finish", () => file.close(() => resolve3()));
+      file.on("error", (err) => {
+        try {
+          unlinkSync3(destPath);
+        } catch {
+        }
+        reject(err);
+      });
+    })
+  );
+}
+function downloadText(url, timeoutMs) {
+  return fetchResponse(url, timeoutMs).then(
+    (res) => new Promise((resolve3, reject) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve3(Buffer.concat(chunks).toString("utf8")));
+      res.on("error", reject);
+    })
+  );
+}
 var CDN_SOURCES = [
   { host: "static.jingyunyilian.com", protocol: "https" },
   { host: "static.okx.com", protocol: "https" },
@@ -12038,7 +12196,7 @@ async function downloadAndVerify(host, protocol, binaryPath, tmpPath, checksum,
 function atomicReplace(tmpPath, resolvedDest) {
   if (platform() === "win32") {
     try {
-      unlinkSync3(resolvedDest);
+      unlinkSync4(resolvedDest);
     } catch {
     }
   }
@@ -12094,7 +12252,7 @@ async function installPilotBinary(destPath, sources = CDN_SOURCES, onProgress) {
       return { status: "installed", source: host };
     } catch (err) {
       try {
-        unlinkSync3(tmpPath);
+        unlinkSync4(tmpPath);
       } catch {
       }
       const msg = err instanceof Error ? err.message : String(err);
@@ -12108,7 +12266,7 @@ ${errors.join("\n")}` };
 function removePilotBinary(binaryPath) {
   const resolvedPath = binaryPath ?? getPilotBinaryPath();
   try {
-    unlinkSync3(resolvedPath);
+    unlinkSync4(resolvedPath);
     return { status: "removed" };
   } catch (err) {
     if (err.code === "ENOENT") {
@@ -12118,78 +12276,6 @@ function removePilotBinary(binaryPath) {
     throw new Error(`Failed to remove ${resolvedPath}: ${msg}`);
   }
 }
-function isRedirect(statusCode) {
-  return statusCode !== void 0 && statusCode >= 300 && statusCode < 400;
-}
-function validateRedirect(res, requestUrl, redirectCount, maxRedirects) {
-  if (redirectCount > maxRedirects) {
-    throw new Error(`Too many redirects (${maxRedirects})`);
-  }
-  const location = res.headers.location;
-  if (requestUrl.startsWith("https") && !location.startsWith("https")) {
-    throw new Error("Refused HTTPS \u2192 HTTP redirect downgrade");
-  }
-  return location;
-}
-function fetchResponse(url, timeoutMs) {
-  return new Promise((resolve3, reject) => {
-    let redirects = 0;
-    const maxRedirects = 5;
-    function doRequest(requestUrl) {
-      const reqFn = requestUrl.startsWith("https") ? httpsGet : httpGet;
-      const req = reqFn(requestUrl, { timeout: timeoutMs }, (res) => {
-        if (isRedirect(res.statusCode) && res.headers.location) {
-          redirects++;
-          try {
-            const location = validateRedirect(res, requestUrl, redirects, maxRedirects);
-            res.resume();
-            doRequest(location);
-          } catch (err) {
-            reject(err);
-          }
-          return;
-        }
-        if (res.statusCode !== 200) {
-          reject(new Error(`HTTP ${res.statusCode ?? "unknown"}`));
-          return;
-        }
-        resolve3(res);
-      });
-      req.on("error", reject);
-      req.on("timeout", () => {
-        req.destroy();
-        reject(new Error("Download timed out"));
-      });
-    }
-    doRequest(url);
-  });
-}
-function download(url, destPath, timeoutMs) {
-  return fetchResponse(url, timeoutMs).then(
-    (res) => new Promise((resolve3, reject) => {
-      const file = createWriteStream2(destPath);
-      res.pipe(file);
-      file.on("finish", () => file.close(() => resolve3()));
-      file.on("error", (err) => {
-        try {
-          unlinkSync3(destPath);
-        } catch {
-        }
-        reject(err);
-      });
-    })
-  );
-}
-function downloadText(url, timeoutMs) {
-  return fetchResponse(url, timeoutMs).then(
-    (res) => new Promise((resolve3, reject) => {
-      const chunks = [];
-      res.on("data", (chunk) => chunks.push(chunk));
-      res.on("end", () => resolve3(Buffer.concat(chunks).toString("utf8")));
-      res.on("error", reject);
-    })
-  );
-}
 var AUTH_CDN_PATH_PREFIX = "/upgradeapp/tools/oauth";
 function getAuthBinaryName() {
   return platform2() === "win32" ? "okx-auth.exe" : "okx-auth";
@@ -12213,7 +12299,7 @@ async function fetchAuthCdnChecksum(sources = CDN_SOURCES, timeoutMs = DOWNLOAD_
   for (const { host, protocol } of sources) {
     try {
       const url = `${protocol}://${host}${checksumPath}`;
-      const raw = await downloadText2(url, timeoutMs);
+      const raw = await downloadText(url, timeoutMs);
       const data = JSON.parse(raw);
       if (typeof data.sha256 !== "string" || typeof data.size !== "number" || typeof data.target !== "string") {
         continue;
@@ -12227,7 +12313,7 @@ async function fetchAuthCdnChecksum(sources = CDN_SOURCES, timeoutMs = DOWNLOAD_
 async function fetchAndValidateChecksum2(host, protocol, checksumPath, platformDir, timeoutMs, onProgress) {
   const checksumUrl = `${protocol}://${host}${checksumPath}`;
   onProgress?.(`Fetching checksum from ${host}...`);
-  const raw = await downloadText2(checksumUrl, timeoutMs);
+  const raw = await downloadText(checksumUrl, timeoutMs);
   const checksum = JSON.parse(raw);
   if (typeof checksum.sha256 !== "string" || typeof checksum.size !== "number" || typeof checksum.target !== "string") {
     throw new Error("Invalid checksum.json: missing sha256, size, or target");
@@ -12240,7 +12326,7 @@ async function fetchAndValidateChecksum2(host, protocol, checksumPath, platformD
 async function downloadAndVerify2(host, protocol, binaryPath, tmpPath, checksum, timeoutMs, onProgress) {
   const binaryUrl = `${protocol}://${host}${binaryPath}`;
   onProgress?.(`Downloading binary from ${host}...`);
-  await download2(binaryUrl, tmpPath, timeoutMs);
+  await download(binaryUrl, tmpPath, timeoutMs);
   const actual = hashFile(tmpPath);
   if (actual.size !== checksum.size) {
     throw new Error(`Size mismatch: expected ${checksum.size}, got ${actual.size}`);
@@ -12252,7 +12338,7 @@ async function downloadAndVerify2(host, protocol, binaryPath, tmpPath, checksum,
 function atomicReplace2(tmpPath, resolvedDest) {
   if (platform2() === "win32") {
     try {
-      unlinkSync4(resolvedDest);
+      unlinkSync5(resolvedDest);
     } catch {
     }
   }
@@ -12308,7 +12394,7 @@ async function installAuthBinary(destPath, sources = CDN_SOURCES, onProgress) {
       return { status: "installed", source: host };
     } catch (err) {
       try {
-        unlinkSync4(tmpPath);
+        unlinkSync5(tmpPath);
       } catch {
       }
       const msg = err instanceof Error ? err.message : String(err);
@@ -12322,7 +12408,7 @@ ${errors.join("\n")}` };
 function removeAuthBinary(binaryPath) {
   const resolvedPath = binaryPath ?? getAuthBinaryPath();
   try {
-    unlinkSync4(resolvedPath);
+    unlinkSync5(resolvedPath);
     return { status: "removed" };
   } catch (err) {
     if (err.code === "ENOENT") {
@@ -12332,78 +12418,6 @@ function removeAuthBinary(binaryPath) {
     throw new Error(`Failed to remove ${resolvedPath}: ${msg}`);
   }
 }
-function isRedirect2(statusCode) {
-  return statusCode !== void 0 && statusCode >= 300 && statusCode < 400;
-}
-function validateRedirect2(res, requestUrl, redirectCount, maxRedirects) {
-  if (redirectCount > maxRedirects) {
-    throw new Error(`Too many redirects (${maxRedirects})`);
-  }
-  const location = res.headers.location;
-  if (requestUrl.startsWith("https") && !location.startsWith("https")) {
-    throw new Error("Refused HTTPS \u2192 HTTP redirect downgrade");
-  }
-  return location;
-}
-function fetchResponse2(url, timeoutMs) {
-  return new Promise((resolve3, reject) => {
-    let redirects = 0;
-    const maxRedirects = 5;
-    function doRequest(requestUrl) {
-      const reqFn = requestUrl.startsWith("https") ? httpsGet2 : httpGet2;
-      const req = reqFn(requestUrl, { timeout: timeoutMs }, (res) => {
-        if (isRedirect2(res.statusCode) && res.headers.location) {
-          redirects++;
-          try {
-            const location = validateRedirect2(res, requestUrl, redirects, maxRedirects);
-            res.resume();
-            doRequest(location);
-          } catch (err) {
-            reject(err);
-          }
-          return;
-        }
-        if (res.statusCode !== 200) {
-          reject(new Error(`HTTP ${res.statusCode ?? "unknown"}`));
-          return;
-        }
-        resolve3(res);
-      });
-      req.on("error", reject);
-      req.on("timeout", () => {
-        req.destroy();
-        reject(new Error("Download timed out"));
-      });
-    }
-    doRequest(url);
-  });
-}
-function download2(url, destPath, timeoutMs) {
-  return fetchResponse2(url, timeoutMs).then(
-    (res) => new Promise((resolve3, reject) => {
-      const file = createWriteStream3(destPath);
-      res.pipe(file);
-      file.on("finish", () => file.close(() => resolve3()));
-      file.on("error", (err) => {
-        try {
-          unlinkSync4(destPath);
-        } catch {
-        }
-        reject(err);
-      });
-    })
-  );
-}
-function downloadText2(url, timeoutMs) {
-  return fetchResponse2(url, timeoutMs).then(
-    (res) => new Promise((resolve3, reject) => {
-      const chunks = [];
-      res.on("data", (chunk) => chunks.push(chunk));
-      res.on("end", () => resolve3(Buffer.concat(chunks).toString("utf8")));
-      res.on("error", reject);
-    })
-  );
-}
 var CACHE_PATH = join12(homedir10(), ".okx", "auth-binary-check.json");
 var CHECK_INTERVAL_MS2 = 2 * 60 * 60 * 1e3;
 function readCache3() {
@@ -12452,7 +12466,7 @@ function updateAuthBinaryCache(sha256) {
 }
 function clearAuthBinaryCache() {
   try {
-    unlinkSync5(CACHE_PATH);
+    unlinkSync6(CACHE_PATH);
   } catch {
   }
 }
@@ -13368,7 +13382,7 @@ async function cmdDiagnoseMcp(options = {}) {
 
 // src/commands/diagnose.ts
 var CLI_VERSION = readCliVersion();
-var GIT_HASH = true ? "d0f8ad6" : "dev";
+var GIT_HASH = true ? "e8a0930a" : "dev";
 function maskKey2(key) {
   if (!key) return "(not set)";
   if (key.length <= 8) return "****";
@@ -14676,12 +14690,12 @@ var CLI_REGISTRY = {
     commands: {
       "traders-by-filter": {
         toolName: "smartmoney_get_traders_by_filter",
-        usage: "okx smartmoney traders-by-filter [--updateTime <ts>] [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--minPnl <n>] [--minWinRate <r>] [--maxDrawdown <r>] [--minAum <n>] [--after <id>] [--before <id>] [--limit <n>] [--json]",
+        usage: "okx smartmoney traders-by-filter [--updateTime <yyyyMMddHHmmss UTC+8>] [--sortBy <pnl|pnlRatio, default pnl>] [--period <3|7|30|90, default 90>] [--minPnl <n>] [--minWinRate <r>] [--maxDrawdown <r>] [--minAum <n>] [--after <authorId>] [--before <authorId>] [--limit <n, default 10>] [--json]",
         description: "Leaderboard of top smart-money traders, ranked and filtered by pool conditions"
       },
       "performance-by-trader": {
         toolName: "smartmoney_get_performance_by_trader",
-        usage: "okx smartmoney performance-by-trader --authorIds <id1,id2> [--period <3|7|30|90>] [--json]",
+        usage: "okx smartmoney performance-by-trader --authorIds <id1,id2> [--sortBy <pnl|pnlRatio, default pnl>] [--period <3|7|30|90, default 90>] [--json]",
         description: "PnL / win-rate / drawdown profile for one or more traders by authorIds"
       },
       "trader-positions": {
@@ -14691,12 +14705,12 @@ var CLI_REGISTRY = {
       },
       "trader-positions-history": {
         toolName: "smartmoney_get_trader_positions_history",
-        usage: "okx smartmoney trader-positions-history --authorId <id> [--instId <id>] [--after <posId>] [--before <posId>] [--limit <n>] [--json]",
+        usage: "okx smartmoney trader-positions-history --authorId <id> [--instId <id>] [--after <posId>] [--before <posId>] [--limit <n, default 10>] [--json]",
         description: "Closed-position history of a single trader (paginated)"
       },
       "trader-orders-history": {
         toolName: "smartmoney_get_trader_orders_history",
-        usage: "okx smartmoney trader-orders-history --authorId <id> [--instId <id>] [--after <ordId>] [--before <ordId>] [--limit <n>] [--json]",
+        usage: "okx smartmoney trader-orders-history --authorId <id> [--instId <id>] [--after <ordId>] [--before <ordId>] [--limit <n, default 10>] [--json]",
         description: "Recent orders/fills placed by a single trader (paginated)"
       },
       "search-trader": {
@@ -14706,22 +14720,22 @@ var CLI_REGISTRY = {
       },
       "signal-overview-by-filter": {
         toolName: "smartmoney_get_signal_overview_by_filter",
-        usage: "okx smartmoney signal-overview-by-filter [--topInstruments <n> | --instCcyList <BTC,ETH,...>] [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--pnlTier <tier>] [--winRateTier <tier>] [--maxDrawdownTier <tier>] [--aumTier <tier>] [--lmtNum <n>] [--json]",
+        usage: "okx smartmoney signal-overview-by-filter [--topInstruments <n, default 20> | --instCcyList <BTC,ETH,...>] [--sortBy <pnl|pnlRatio, default pnl>] [--period <3|7|30|90, default 7>] [--pnlTier <tier>] [--winRateTier <tier>] [--maxDrawdownTier <tier>] [--aumTier <tier>] [--lmtNum <n, default 100>] [--json]",
         description: "Multi-asset smart-money consensus signal aggregated over a tier-filtered pool"
       },
       "signal-overview-by-trader": {
         toolName: "smartmoney_get_signal_overview_by_trader",
-        usage: "okx smartmoney signal-overview-by-trader --authorIds <id1,id2> [--topInstruments <n> | --instCcyList <BTC,ETH,...>] [--json]",
+        usage: "okx smartmoney signal-overview-by-trader --authorIds <id1,id2> [--topInstruments <n, default 20> | --instCcyList <BTC,ETH,...>] [--sortBy <pnl|pnlRatio, default pnl>] [--period <3|7|30|90, default 7>] [--json]",
         description: "Multi-asset smart-money signal aggregated over a hand-picked set of traders (authorIds-direct-lookup; pool filters not exposed)"
       },
       "signal-trend-by-filter": {
         toolName: "smartmoney_get_signal_trend_by_filter",
-        usage: "okx smartmoney signal-trend-by-filter --instCcy <ccy> [--asOfTime <yyyyMMddHH>] [--granularity <1h|1d>] [--limit <n>] [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--pnlTier <tier>] [--winRateTier <tier>] [--maxDrawdownTier <tier>] [--aumTier <tier>] [--lmtNum <n>] [--json]",
+        usage: "okx smartmoney signal-trend-by-filter --instCcy <ccy> [--asOfTime <yyyyMMddHH UTC>] [--granularity <1h|1d, default 1h>] [--limit <n, default 24>] [--sortBy <pnl|pnlRatio, default pnl>] [--period <3|7|30|90, default 7>] [--pnlTier <tier>] [--winRateTier <tier>] [--maxDrawdownTier <tier>] [--aumTier <tier>] [--lmtNum <n, default 100>] [--json]",
         description: "Single-coin smart-money signal time-series aggregated over a tier-filtered pool, anchored at asOfTime"
       },
       "signal-trend-by-trader": {
         toolName: "smartmoney_get_signal_trend_by_trader",
-        usage: "okx smartmoney signal-trend-by-trader --authorIds <id1,id2> --instCcy <ccy> [--asOfTime <yyyyMMddHH>] [--granularity <1h|1d>] [--limit <n>] [--json]",
+        usage: "okx smartmoney signal-trend-by-trader --authorIds <id1,id2> --instCcy <ccy> [--asOfTime <yyyyMMddHH UTC>] [--granularity <1h|1d, default 1h>] [--limit <n, default 24>] [--sortBy <pnl|pnlRatio, default pnl>] [--period <3|7|30|90, default 7>] [--json]",
         description: "Single-coin smart-money signal time-series aggregated over a hand-picked set of traders (authorIds-direct-lookup; pool filters not exposed)"
       }
     }
@@ -18140,6 +18154,7 @@ async function cmdSmartmoneyTradersByFilter(run, opts) {
 async function cmdSmartmoneyPerformanceByTrader(run, opts) {
   const result = await run("smartmoney_get_performance_by_trader", {
     authorIds: csvToArray(opts.authorIds),
+    sortBy: opts.sortBy,
     period: opts.period
   });
   if (opts.json) {
@@ -18280,7 +18295,9 @@ async function cmdSmartmoneySignalOverviewByTrader(run, opts) {
   const result = await run("smartmoney_get_signal_overview_by_trader", {
     authorIds: csvToArray(opts.authorIds),
     topInstruments: opts.topInstruments,
-    instCcyList: csvToArray(opts.instCcyList)
+    instCcyList: csvToArray(opts.instCcyList),
+    sortBy: opts.sortBy,
+    period: opts.period
   });
   if (opts.json) {
     printJson(result);
@@ -18325,7 +18342,9 @@ async function cmdSmartmoneySignalTrendByTrader(run, opts) {
     instCcy: opts.instCcy,
     asOfTime: opts.asOfTime,
     granularity: opts.granularity,
-    limit: opts.limit
+    limit: opts.limit,
+    sortBy: opts.sortBy,
+    period: opts.period
   });
   if (opts.json) {
     printJson(result);
@@ -19849,7 +19868,7 @@ async function cmdEventCancel(run, opts) {
 // src/index.ts
 var _require3 = createRequire3(import.meta.url);
 var CLI_VERSION2 = _require3("../package.json").version;
-var GIT_HASH2 = true ? "d0f8ad6" : "dev";
+var GIT_HASH2 = true ? "e8a0930a" : "dev";
 function handlePilotCommand(action, json, force, binaryPath) {
   if (action === "status") return cmdPilotStatus(json, binaryPath);
   if (action === "install") return cmdPilotInstall(json, binaryPath);
@@ -20887,6 +20906,7 @@ function handleSmartmoneyCommand(run, action, rest, v, json) {
     }
     return cmdSmartmoneyPerformanceByTrader(run, {
       authorIds: v.authorIds,
+      sortBy: v.sortBy,
       period: v.period,
       json
     });
@@ -20977,6 +20997,8 @@ function handleSmartmoneyCommand(run, action, rest, v, json) {
       authorIds: v.authorIds,
       topInstruments: v.topInstruments,
       instCcyList: v.instCcyList,
+      sortBy: v.sortBy,
+      period: v.period,
       json
     });
   }
@@ -21013,6 +21035,8 @@ function handleSmartmoneyCommand(run, action, rest, v, json) {
       asOfTime: v.asOfTime,
       granularity: v.granularity,
       limit: v.limit,
+      sortBy: v.sortBy,
+      period: v.period,
       json
     });
   }
@@ -21342,6 +21366,7 @@ async function main() {
 main().catch((error) => {
   const payload = toToolErrorPayload(error);
   errorLine(`Error: ${payload.message}`);
+  if (payload.code) errorLine(`Code: ${payload.code}`);
   if (payload.traceId) errorLine(`TraceId: ${payload.traceId}`);
   if (payload.suggestion) errorLine(`Hint: ${payload.suggestion}`);
   errorLine(`Version: @okx_ai/okx-trade-cli@${CLI_VERSION2}`);