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

package/dist/index.js

@@ -2300,14 +2300,16 @@ var OKX_INST_TYPES = [
 function publicRateLimit(key, rps = 20) {
   return {
     key: `public:${key}`,
-    capacity: rps,
+    capacity: Math.max(1, rps),
+    // capacity >= 1 so the token bucket can fire at least once before refilling
     refillPerSecond: rps
   };
 }
 function privateRateLimit(key, rps = 10) {
   return {
     key: `private:${key}`,
-    capacity: rps,
+    capacity: Math.max(1, rps),
+    // capacity >= 1 so the token bucket can fire at least once before refilling
     refillPerSecond: rps
   };
 }
@@ -9677,6 +9679,58 @@ function registerMarketFilterTools() {
         );
         return normalizeResponse(response);
       }
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // market_get_pair_spread — /api/v5/aigc/mcp/pair-spread
+    // ─────────────────────────────────────────────────────────────────────────
+    {
+      name: "market_get_pair_spread",
+      module: "market",
+      description: "Compute spread statistics between two instruments over a lookback window. Returns absolute and ratio spread (mean / stdDev / median / min / max) plus an optional realtime spread snapshot. Use to size pairs trades, detect mean-reversion setups, or compare cross-listed contracts. Results are cached ~60s per (pair, bar, window) tuple. Read-only, no credentials required.\nDo NOT use to fetch raw candles (use market_get_candles) or single-instrument OI/funding (use market_get_oi_history / market_filter_oi_change).",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          instIdA: {
+            type: "string",
+            description: "First instrument ID, e.g. BTC-USDT-SWAP"
+          },
+          instIdB: {
+            type: "string",
+            description: "Second instrument ID; must differ from instIdA"
+          },
+          bar: {
+            type: "string",
+            enum: ["5m", "15m"],
+            description: "Bar size for the spread series. Default 15m. 1m is not supported."
+          },
+          window: {
+            type: "string",
+            description: "Lookback window. Format <n><unit>, units m/H/D/W (case-sensitive), max 1W. Default 1W."
+          },
+          backtestTime: {
+            type: "number",
+            description: "Anchor timestamp (ms epoch) for backtest mode. When provided, realtime is omitted."
+          }
+        },
+        required: ["instIdA", "instIdB"]
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const body = compactObject({
+          instIdA: requireString(args, "instIdA"),
+          instIdB: requireString(args, "instIdB"),
+          bar: readString(args, "bar"),
+          window: readString(args, "window"),
+          backtestTime: readNumber(args, "backtestTime")
+        });
+        const response = await context.client.publicPost(
+          "/api/v5/aigc/mcp/pair-spread",
+          body,
+          publicRateLimit("market_get_pair_spread", 5)
+        );
+        return normalizeResponse(response);
+      }
     }
   ];
 }
@@ -9685,6 +9739,219 @@ var NEWS_DETAIL = "/api/v5/orbit/news-detail";
 var NEWS_DOMAINS = "/api/v5/orbit/news-platform";
 var SENTIMENT_QUERY = "/api/v5/orbit/currency-sentiment-query";
 var SENTIMENT_RANKING = "/api/v5/orbit/currency-sentiment-ranking";
+var ECONOMIC_CALENDAR = "/api/v5/public/economic-calendar";
+var CALENDAR_REGIONS = [
+  "afghanistan",
+  "albania",
+  "algeria",
+  "andorra",
+  "angola",
+  "antigua_and_barbuda",
+  "argentina",
+  "armenia",
+  "aruba",
+  "australia",
+  "austria",
+  "azerbaijan",
+  "bahamas",
+  "bahrain",
+  "bangladesh",
+  "barbados",
+  "belarus",
+  "belgium",
+  "belize",
+  "benin",
+  "bermuda",
+  "bhutan",
+  "bolivia",
+  "bosnia_and_herzegovina",
+  "botswana",
+  "brazil",
+  "brunei",
+  "bulgaria",
+  "burkina_faso",
+  "burundi",
+  "cambodia",
+  "cameroon",
+  "canada",
+  "cape_verde",
+  "cayman_islands",
+  "central_african_republic",
+  "chad",
+  "chile",
+  "china",
+  "colombia",
+  "comoros",
+  "congo",
+  "costa_rica",
+  "croatia",
+  "cuba",
+  "cyprus",
+  "czech_republic",
+  "denmark",
+  "djibouti",
+  "dominica",
+  "dominican_republic",
+  "east_timor",
+  "ecuador",
+  "egypt",
+  "el_salvador",
+  "equatorial_guinea",
+  "eritrea",
+  "estonia",
+  "ethiopia",
+  "euro_area",
+  "european_union",
+  "faroe_islands",
+  "fiji",
+  "finland",
+  "france",
+  "g20",
+  "g7",
+  "gabon",
+  "gambia",
+  "georgia",
+  "germany",
+  "ghana",
+  "greece",
+  "greenland",
+  "grenada",
+  "guatemala",
+  "guinea",
+  "guinea_bissau",
+  "guyana",
+  "haiti",
+  "honduras",
+  "hong_kong",
+  "hungary",
+  "iceland",
+  "imf",
+  "india",
+  "indonesia",
+  "iran",
+  "iraq",
+  "ireland",
+  "isle_of_man",
+  "israel",
+  "italy",
+  "ivory_coast",
+  "jamaica",
+  "japan",
+  "jordan",
+  "kazakhstan",
+  "kenya",
+  "kiribati",
+  "kosovo",
+  "kuwait",
+  "kyrgyzstan",
+  "laos",
+  "latvia",
+  "lebanon",
+  "lesotho",
+  "liberia",
+  "libya",
+  "liechtenstein",
+  "lithuania",
+  "luxembourg",
+  "macau",
+  "macedonia",
+  "madagascar",
+  "malawi",
+  "malaysia",
+  "maldives",
+  "mali",
+  "malta",
+  "mauritania",
+  "mauritius",
+  "mexico",
+  "micronesia",
+  "moldova",
+  "monaco",
+  "mongolia",
+  "montenegro",
+  "morocco",
+  "mozambique",
+  "myanmar",
+  "namibia",
+  "nepal",
+  "netherlands",
+  "new_caledonia",
+  "new_zealand",
+  "nicaragua",
+  "niger",
+  "nigeria",
+  "north_korea",
+  "northern_mariana_islands",
+  "norway",
+  "oman",
+  "opec",
+  "pakistan",
+  "palau",
+  "palestine",
+  "panama",
+  "papua_new_guinea",
+  "paraguay",
+  "peru",
+  "philippines",
+  "poland",
+  "portugal",
+  "puerto_rico",
+  "qatar",
+  "republic_of_the_congo",
+  "romania",
+  "russia",
+  "rwanda",
+  "samoa",
+  "san_marino",
+  "sao_tome_and_principe",
+  "saudi_arabia",
+  "senegal",
+  "serbia",
+  "seychelles",
+  "sierra_leone",
+  "singapore",
+  "slovakia",
+  "slovenia",
+  "solomon_islands",
+  "somalia",
+  "south_africa",
+  "south_korea",
+  "south_sudan",
+  "spain",
+  "sri_lanka",
+  "st_kitts_and_nevis",
+  "st_lucia",
+  "sudan",
+  "suriname",
+  "swaziland",
+  "sweden",
+  "switzerland",
+  "syria",
+  "taiwan",
+  "tajikistan",
+  "tanzania",
+  "thailand",
+  "togo",
+  "tonga",
+  "trinidad_and_tobago",
+  "tunisia",
+  "turkey",
+  "turkmenistan",
+  "uganda",
+  "ukraine",
+  "united_arab_emirates",
+  "united_kingdom",
+  "united_states",
+  "uruguay",
+  "uzbekistan",
+  "vanuatu",
+  "venezuela",
+  "vietnam",
+  "world",
+  "yemen",
+  "zambia",
+  "zimbabwe"
+];
 var NEWS_LANGUAGE = ["en-US", "zh-CN"];
 function langHeader(lang) {
   if (lang === "zh-CN" || lang === "zh_CN") return { "Accept-Language": "zh-CN" };
@@ -9982,12 +10249,61 @@ function registerNewsTools() {
         );
         return normalizeResponse(response);
       }
+    },
+    // -----------------------------------------------------------------------
+    // Economic calendar
+    // -----------------------------------------------------------------------
+    {
+      name: "news_list_calendar_regions",
+      module: "news",
+      description: "List all valid region values for the economic calendar. Returns a string array of snake_case region codes. Call this when economic-calendar returns empty results to verify the region value, or to help the user pick a valid region. Do NOT use to list news source platforms \u2014 use news_get_domains instead.",
+      isWrite: false,
+      inputSchema: { type: "object", properties: {}, required: [] },
+      handler: async () => ({ data: CALENDAR_REGIONS })
+    },
+    {
+      name: "news_get_economic_calendar",
+      module: "news",
+      description: "Get macro-economic calendar data (GDP, CPI, NFP, interest rate decisions, PMI, etc.). Returns scheduled and released economic events with forecast, previous, and actual values. Use when user asks about economic calendar, macro data, or specific indicators like NFP/CPI/GDP/FOMC. Do NOT use for news articles or sentiment \u2014 use news_get_latest or news_search instead.",
+      isWrite: false,
+      inputSchema: {
+        type: "object",
+        properties: {
+          region: { type: "string", description: "Country/region filter in snake_case (e.g. united_states, euro_area, japan). Invalid values return empty results silently. If empty results, call news_list_calendar_regions to verify the value." },
+          importance: { type: "string", enum: ["1", "2", "3"], description: "Importance level: 1=low, 2=medium, 3=high. Omit for all levels." },
+          before: { type: "string", description: "Lower time bound \u2014 returns events NEWER than this timestamp (reversed semantics). Pair with 'after' for future-event windows. Unix ms." },
+          after: { type: "string", description: "Upper time bound \u2014 returns events OLDER than this timestamp (reversed semantics). Default=now (returns past events). Pair with 'before' for a bounded window. Unix ms." },
+          limit: { type: "number", minimum: 1, maximum: 100, description: "Number of results (default 100, max 100)." }
+        },
+        required: []
+      },
+      handler: async (rawArgs, context) => {
+        const args = asRecord(rawArgs);
+        const rawLimit = readNumber(args, "limit");
+        const limit = rawLimit !== void 0 ? Math.min(rawLimit, 100) : void 0;
+        const response = await context.client.privateGet(
+          ECONOMIC_CALENDAR,
+          compactObject({
+            region: readString(args, "region"),
+            importance: readString(args, "importance"),
+            before: readString(args, "before"),
+            after: readString(args, "after"),
+            limit
+          }),
+          publicRateLimit("news_get_economic_calendar", 0.2)
+        );
+        return normalizeResponse(response);
+      }
     }
   ];
-  const domainsIdx = tools.findIndex((t) => t.name === "news_get_domains");
-  if (domainsIdx === -1) throw new Error("news_get_domains not found in tools list");
-  const [domainsTool] = tools.splice(domainsIdx, 1);
-  return [...tools.map(withNewsDemoGuard), domainsTool];
+  const exempt = /* @__PURE__ */ new Set(["news_get_domains", "news_list_calendar_regions"]);
+  const exempted = [];
+  const guarded = [];
+  for (const t of tools) {
+    if (exempt.has(t.name)) exempted.push(t);
+    else guarded.push(t);
+  }
+  return [...guarded.map(withNewsDemoGuard), ...exempted];
 }
 var NEWS_DEMO_MESSAGE = "News features are not available in demo/simulated trading mode.";
 var NEWS_DEMO_SUGGESTION = "Switch to a live profile to use News features.";
@@ -13487,7 +13803,7 @@ async function cmdDiagnoseMcp(options = {}) {
 
 // src/commands/diagnose.ts
 var CLI_VERSION = readCliVersion();
-var GIT_HASH = true ? "e6ad1d1e" : "dev";
+var GIT_HASH = true ? "0566db8f" : "dev";
 function maskKey2(key) {
   if (!key) return "(not set)";
   if (key.length <= 8) return "****";
@@ -14063,6 +14379,11 @@ var CLI_REGISTRY = {
         toolName: "market_filter_oi_change",
         usage: "okx market oi-change --instType <SWAP|FUTURES> [--bar <5m|15m|1H|4H|1D>] [--sortBy <oiUsd|oiDeltaUsd|oiDeltaPct|absOiDeltaPct|volUsd24h|fundingRate|last>] [--sortOrder <asc|desc>] [--limit <1-100>] [--minOiUsd <n>] [--minVolUsd24h <n>] [--minAbsOiDeltaPct <n>]",
         description: "Find instruments with largest OI changes over a bar window (accumulation/distribution scanner)"
+      },
+      "pair-spread": {
+        toolName: "market_get_pair_spread",
+        usage: "okx market pair-spread <instIdA> <instIdB> [--bar <5m|15m>] [--window <window>] [--backtest-time <ms>] [--json]",
+        description: "Compute spread statistics (abs + ratio) between two instruments over a lookback window"
       }
     },
     subgroups: {
@@ -14943,6 +15264,16 @@ var CLI_REGISTRY = {
       "sentiment-rank": {
         toolName: "news_get_sentiment_ranking",
         usage: "okx news sentiment-rank [--period 24h] [--sort-by 0] [--limit 20]"
+      },
+      "economic-calendar": {
+        toolName: "news_get_economic_calendar",
+        usage: "okx news economic-calendar [--region <country>] [--importance <1|2|3>] [--before <ms>] [--after <ms>] [--limit <n>]",
+        description: "Get macro-economic calendar data (GDP, CPI, NFP, FOMC, etc.)"
+      },
+      "list-regions": {
+        toolName: "news_list_calendar_regions",
+        usage: "okx news list-regions",
+        description: "List all valid --region values for economic-calendar"
       }
     }
   },
@@ -15353,6 +15684,49 @@ async function cmdNewsSentimentRank(run, opts) {
     })
   );
 }
+async function cmdNewsEconomicCalendar(run, opts) {
+  if (!opts.json && opts.limit !== void 0 && opts.limit > 100) {
+    errorLine(`Warning: --limit ${opts.limit} exceeds API max 100, capped to 100`);
+  }
+  const result = await run("news_get_economic_calendar", {
+    region: opts.region,
+    importance: opts.importance,
+    before: opts.before,
+    after: opts.after,
+    limit: opts.limit !== void 0 ? Math.min(opts.limit, 100) : void 0
+  });
+  const items = getData(result) ?? [];
+  if (opts.json) return printJson(items);
+  printTable(
+    items.map((e) => {
+      const unit = String(e["unit"] ?? "").trim();
+      const appendUnit = (v) => {
+        const s = String(v ?? "");
+        if (!s || s === "-") return s || "-";
+        if (unit && !s.includes(unit)) return `${s} ${unit}`;
+        return s;
+      };
+      return {
+        time: formatTime(e["date"]),
+        region: e["region"],
+        category: e["category"] || "-",
+        event: String(e["event"] ?? "").slice(0, 50),
+        importance: e["importance"] === "3" ? "HIGH" : e["importance"] === "2" ? "MED" : "LOW",
+        refDate: formatTime(e["refDate"]),
+        forecast: appendUnit(e["forecast"] ?? "-"),
+        previous: appendUnit(e["previous"] ?? "-"),
+        actual: e["actual"] ? appendUnit(e["actual"]) : "(pending)"
+      };
+    })
+  );
+}
+async function cmdNewsListCalendarRegions(run, opts) {
+  const result = await run("news_list_calendar_regions", {});
+  const regions = result.data;
+  if (opts.json) return printJson(regions);
+  outputLine(`Valid economic-calendar regions (${regions.length}):`);
+  outputLine(regions.join(", "));
+}
 
 // src/config/loader.ts
 async function loadProfileConfig(opts) {
@@ -15466,6 +15840,12 @@ function printSubgroupHelp(moduleName, subgroupName) {
   }
   const subgroup = group.subgroups?.[subgroupName];
   if (!subgroup) {
+    const cmd = group.commands?.[subgroupName];
+    if (cmd) {
+      const lines2 = ["", `  ${cmd.description}`, `  Usage: ${cmd.usage}`, ""];
+      output(lines2.join(EOL2));
+      return;
+    }
     errorLine(`Unknown subgroup: ${moduleName} ${subgroupName}`);
     process.exitCode = 1;
     return;
@@ -15708,6 +16088,8 @@ var CLI_OPTIONS = {
   params: { type: "string" },
   list: { type: "boolean", default: false },
   "backtest-time": { type: "string" },
+  // pair-spread
+  window: { type: "string" },
   // news
   coins: { type: "string" },
   sentiment: { type: "string" },
@@ -15718,6 +16100,7 @@ var CLI_OPTIONS = {
   period: { type: "string" },
   points: { type: "string" },
   "sort-by": { type: "string" },
+  region: { type: "string" },
   // skill marketplace
   categories: { type: "string" },
   dir: { type: "string" },
@@ -16230,6 +16613,42 @@ async function cmdMarketOiChangeFilter(run, opts) {
     }))
   );
 }
+async function cmdMarketPairSpread(run, instIdA, instIdB, opts) {
+  const result = await run("market_get_pair_spread", {
+    instIdA,
+    instIdB,
+    bar: opts.bar,
+    window: opts.window,
+    backtestTime: opts.backtestTime
+  });
+  const data = getData2(result);
+  if (opts.json) return printJson(data);
+  const bar = data?.["bar"] ?? "15m";
+  const win = data?.["window"] ?? "1W";
+  const mode = data?.["mode"] ?? "live";
+  outputLine(`${instIdA} / ${instIdB}  bar=${bar} window=${win}  mode=${mode}`);
+  const rt = data?.["realtime"];
+  if (rt) {
+    outputLine(`realtime  lastA=${rt["lastPriceA"]}  lastB=${rt["lastPriceB"]}  abs=${rt["spreadAbs"]}  ratio=${rt["spreadRatio"]}`);
+  }
+  const stats = data?.["statistics"];
+  if (stats) {
+    const abs = stats["absolute"];
+    const ratio = stats["ratio"];
+    const meta = data?.["meta"];
+    outputLine(`samples  count=${meta?.["alignedBars"] ?? "?"}  start=${stats?.["windowStartTs"] ?? "?"}  end=${stats?.["windowEndTs"] ?? "?"}`);
+    printTable([
+      { stat: "mean", absolute: abs?.["mean"], ratio: ratio?.["mean"] },
+      { stat: "stdDev", absolute: abs?.["stdDev"], ratio: ratio?.["stdDev"] },
+      { stat: "median", absolute: abs?.["median"], ratio: ratio?.["median"] },
+      { stat: "min", absolute: abs?.["min"], ratio: ratio?.["min"] },
+      { stat: "max", absolute: abs?.["max"], ratio: ratio?.["max"] }
+    ]);
+    if (meta) {
+      outputLine(`meta  requested=${meta["requestedBars"]}  aligned=${meta["alignedBars"]}  dropped=${meta["droppedBars"]}  truncated=${meta["truncated"]}`);
+    }
+  }
+}
 
 // src/commands/account.ts
 import * as fs7 from "fs";
@@ -19973,7 +20392,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 ? "e6ad1d1e" : "dev";
+var GIT_HASH2 = true ? "0566db8f" : "dev";
 function handlePilotCommand(action, json, force, binaryPath) {
   if (action === "status") return cmdPilotStatus(json, binaryPath);
   if (action === "install") return cmdPilotInstall(json, binaryPath);
@@ -20078,6 +20497,15 @@ function handleMarketFilterCommand(run, action, rest, v, json) {
       limit,
       json
     });
+  if (action === "pair-spread") {
+    const backtestTime = v["backtest-time"] !== void 0 ? Number(v["backtest-time"]) : void 0;
+    return cmdMarketPairSpread(run, rest[0], rest[1], {
+      bar: v.bar,
+      window: v.window,
+      backtestTime,
+      json
+    });
+  }
 }
 function handleIndicatorAction(run, rest, v, json) {
   if (rest[0] === "list") return cmdMarketIndicatorList(json);
@@ -20126,7 +20554,8 @@ function handleMarketCommand(run, action, rest, v, json) {
     "filter",
     "oi-history",
     "oi-change",
-    "index-candles"
+    "index-candles",
+    "pair-spread"
   ]);
 }
 function handleAccountWriteCommand(run, action, v, json) {
@@ -21256,7 +21685,9 @@ function handleNewsCommand(run, action, rest, v, json) {
       const opts = { ...searchOpts, sortBy: sortBy ?? "latest" };
       return cmdNewsSearch(run, "", opts);
     },
-    "sentiment-rank": () => cmdNewsSentimentRank(run, { period, sortBy, limit, json })
+    "sentiment-rank": () => cmdNewsSentimentRank(run, { period, sortBy, limit, json }),
+    "economic-calendar": () => cmdNewsEconomicCalendar(run, { region: v.region, importance: v.importance, before: v.before, after, limit, json }),
+    "list-regions": () => cmdNewsListCalendarRegions(run, { json })
   };
   const handler = dispatch[action];
   if (handler) return handler();