nansen-cli 1.33.0 → 1.35.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.35.0
+
+### Minor Changes
+
+- [#469](https://github.com/nansen-ai/nansen-cli/pull/469) [`85b1934`](https://github.com/nansen-ai/nansen-cli/commit/85b1934ae25ed02d1726de8ebe92ea41a98f4454) Thanks [@gulshngill](https://github.com/gulshngill)! - Surface the API's credit and rate-limit response headers.
+
+  Failed calls now report quota state in their error details: an out-of-credits error carries your actual remaining balance, and a rate-limited error carries the limit, what is left, and how long the window needs to drain. Previously the only credit figure the CLI could show was the static per-endpoint estimate published in the API reference — a quote, not what you were charged.
+
+  A warning goes to stderr when your balance will not cover another call of the size just made, so it never interferes with the JSON on stdout.
+
+  Successful responses carry the same numbers under an exported `RESPONSE_META` symbol, and the client exposes `lastResponseMeta`. Both are additive: the JSON each command prints is unchanged.
+
+- [#470](https://github.com/nansen-ai/nansen-cli/pull/470) [`8159300`](https://github.com/nansen-ai/nansen-cli/commit/81593008f829cc83f1d4a6ee9e5c1a10237a9553) Thanks [@gulshngill](https://github.com/gulshngill)! - Surface the API's request id.
+
+  Failed calls now carry `details.requestId` — the value that identifies the call end to end. Quote it when reporting a problem; previously nothing identifying a failed request ever reached the user, which made server errors effectively unreportable. Successful responses expose it alongside the credit and rate-limit figures under the `RESPONSE_META` symbol.
+
+  Absent on deployments that do not send the header yet, in which case the field is simply omitted.
+
+## 1.34.0
+
+### Minor Changes
+
+- [#459](https://github.com/nansen-ai/nansen-cli/pull/459) [`37e6725`](https://github.com/nansen-ai/nansen-cli/commit/37e6725aeeb3b83eb29c4650908b8dbb522ed316) Thanks [@dependabot](https://github.com/apps/dependabot)! - Drop support for Node.js 18 (EOL since April 2025). The minimum supported version is now Node.js 20, matching our test toolchain (vitest 4.x requires Node 20+).
+
+- [#460](https://github.com/nansen-ai/nansen-cli/pull/460) [`aac4bbe`](https://github.com/nansen-ai/nansen-cli/commit/aac4bbe18312edb48c91df60ab555f9c1d8334ce) Thanks [@gulshngill](https://github.com/gulshngill)! - Add trader_type, sectors_filter, sm_label_filter, and trader_label_filter filters to `nansen research perp screener` (ECINT-6680).
+
+  New CLI options:
+
+  - `--trader-type <type>` — filter by trader type: all, sm, whale, public_figure, high_winrate_hl_perps_trader
+  - `--sectors-filter <sectors>` — comma-separated sector:subcategory pairs, e.g. "Crypto:AI,TradFi:Stocks"
+  - `--sm-label-filter <labels>` — comma-separated Nansen SM labels (applies when trader-type is all or sm)
+  - `--trader-label-filter <labels>` — comma-separated HL perps trader labels (applies when trader-type is all or sm)
+
 ## 1.33.0
 
 ### Minor Changes

package/README.md

@@ -177,17 +177,28 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 ```json
 { "success": true,  "data": <api_response> }
-{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401 }
+{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": { ... } }
 ```
 
 **Critical error codes:**
 
 | Code | Action |
 |------|--------|
-| `CREDITS_EXHAUSTED` | Stop all API calls immediately. Check [app.nansen.ai](https://app.nansen.ai). |
+| `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api](https://app.nansen.ai/api). |
 | `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
-| `RATE_LIMITED` | Auto-retried by CLI. |
+| `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
 | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
+| `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
+
+**Error metadata.** When the API reports them, `details` carries:
+
+| Field | Meaning |
+|-------|---------|
+| `requestId` | Identifies this call end to end. Quote it in any support report. Opaque — do not parse it. |
+| `credits` | `used`, `remaining` |
+| `rateLimit` | `limit`, `remaining`, `resetSeconds` |
+
+Any field may be absent or `null`, meaning unknown — never assume zero. A low-balance warning goes to **stderr**, so stdout stays pure JSON.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.33.0",
+  "version": "1.35.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",
@@ -59,7 +59,7 @@
   },
   "homepage": "https://github.com/nansen-ai/nansen-cli#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.1",

package/scripts/postinstall.js

@@ -41,9 +41,19 @@ function hasTTY() {
   return process.stdin.isTTY && process.stderr.isTTY;
 }
 
+// npx is a .cmd shim on Windows, and Node refuses to spawn .cmd/.bat without a
+// shell (CVE-2024-27980). Go through cmd.exe explicitly rather than enabling
+// `shell: true`, which would hand the whole command line to the shell parser.
+const IS_WIN = process.platform === "win32";
+
+function npxInvocation(args) {
+  return IS_WIN ? ["cmd.exe", ["/c", "npx", ...args]] : ["npx", args];
+}
+
 function hasNpx() {
   try {
-    execFileSync("npx", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+    const [cmd, cmdArgs] = npxInvocation(["--version"]);
+    execFileSync(cmd, cmdArgs, { stdio: "ignore", shell: false });
     return true;
   } catch {
     return false;
@@ -86,7 +96,7 @@ function prompt(question) {
 
 function runCommand(cmd, args) {
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+    const child = spawn(cmd, args, { stdio: "inherit", shell: false });
     child.on("close", (code) => resolve(code === 0));
     child.on("error", () => resolve(false));
   });
@@ -113,7 +123,7 @@ async function installSkill() {
   }
 
   log(`Installing Nansen skill...`);
-  const ok = await runCommand("npx", ["-y", "skills", "add", SKILL_REPO]);
+  const ok = await runCommand(...npxInvocation(["-y", "skills", "add", SKILL_REPO]));
   if (!ok) {
     log(`${YELLOW}Skill installation failed. You can retry with: npx skills add ${SKILL_REPO}${RESET}`);
   }

package/skills/nansen-perp-screener/SKILL.md

@@ -30,3 +30,62 @@ nansen research perp leaderboard --days 7 --limit 20
 nansen research smart-money perp-trades --limit 20
 # → token_symbol, side, action (Open/Close), value_usd, price_usd, trader_address_label
 ```
+
+## New Filters (ECINT-6680)
+
+### `--trader-type`
+Filter by trader type. Accepted values: `all` (default), `sm`, `whale`, `public_figure`, `high_winrate_hl_perps_trader`.
+
+```bash
+# Show only whale traders
+nansen research perp screener --trader-type whale --limit 10
+
+# Show only smart money traders
+nansen research perp screener --trader-type sm --limit 20
+
+# Show high win-rate HL perps traders
+nansen research perp screener --trader-type high_winrate_hl_perps_trader --limit 20
+```
+
+### `--sm-label-filter`
+Comma-separated Nansen SM labels to filter by. Only applies when `--trader-type` is `all` or `sm`.
+
+```bash
+# Filter to a specific SM label
+nansen research perp screener --trader-type sm --sm-label-filter "30D Smart Trader"
+
+# Multiple labels
+nansen research perp screener --sm-label-filter "30D Smart Trader,Smart LP"
+```
+
+### `--trader-label-filter`
+Comma-separated HL perps trader labels to filter by. Only applies when `--trader-type` is `all` or `sm`.
+
+```bash
+# Filter to HL Perps Whale label
+nansen research perp screener --trader-label-filter "HL Perps Whale"
+```
+
+### `--sectors-filter`
+Comma-separated `category:subcategory` pairs to filter coins by sector.
+
+```bash
+# Filter to AI and DeFi crypto sectors
+nansen research perp screener --sectors-filter "Crypto:AI,Crypto:DeFi" --trader-type whale
+
+# Combine with trader type and limit
+nansen research perp screener --sectors-filter "Crypto:AI,Crypto:DeFi" --trader-type whale --limit 10 --sort volume:desc
+```
+
+## Combined Examples
+
+```bash
+# Whale traders in AI crypto, sorted by volume
+nansen research perp screener --trader-type whale --sectors-filter "Crypto:AI" --sort volume:desc --limit 10
+
+# Smart money with specific label, last 7 days
+nansen research perp screener --trader-type sm --sm-label-filter "30D Smart Trader" --days 7 --limit 20
+
+# All traders in TradFi stocks sector
+nansen research perp screener --sectors-filter "TradFi:Stocks" --sort open_interest:desc --limit 20
+```

package/src/api.js

@@ -8,6 +8,16 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { EVM_CHAINS } from './chain-ids.js';
 import { getAnonymousId, TELEMETRY_DISABLED } from './telemetry.js';
+import { readResponseMeta } from './response-meta.js';
+
+/**
+ * Key for the credit/rate-limit metadata attached to a successful response.
+ *
+ * A symbol on purpose: JSON.stringify and Object.keys both skip it, so the JSON
+ * every command prints is byte-for-byte unchanged while callers that want the
+ * numbers can still read them off the returned object.
+ */
+export const RESPONSE_META = Symbol('nansenResponseMeta');
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -465,6 +475,15 @@ export class NansenAPI {
       ttl: options.cache?.ttl ?? DEFAULT_CACHE_TTL
     };
     this.defaultHeaders = options.defaultHeaders || {};
+    /**
+     * Credit/rate-limit metadata from the most recent response, or null.
+     *
+     * Survives any reshaping a command handler does to the response body, which
+     * the RESPONSE_META symbol on the returned object does not. Last write wins
+     * when a handler makes several calls — the freshest balance, which is what a
+     * low-credit warning wants.
+     */
+    this.lastResponseMeta = null;
   }
 
   static cleanBody(body) {
@@ -520,7 +539,11 @@ export class NansenAPI {
         }
       } catch { /* balance check is best-effort */ }
     }
-    return await paidResponse.json();
+    const data = await paidResponse.json();
+    const meta = readResponseMeta(paidResponse);
+    this.lastResponseMeta = meta;
+    if (meta && data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
+    return data;
   }
 
   async request(endpoint, body = {}, options = {}) {
@@ -581,11 +604,17 @@ export class NansenAPI {
         data = await response.json();
       } catch (_err) {
         // Non-JSON response (rare, usually server errors)
+        const meta = readResponseMeta(response);
+        this.lastResponseMeta = meta;
         const error = new NansenError(
           `Invalid response from API (status ${response.status})`,
           response.status >= 500 ? ErrorCode.SERVER_ERROR : ErrorCode.UNKNOWN,
           response.status,
-          { body: await response.text().catch(() => null), attempt: attempt + 1 }
+          {
+            body: await response.text().catch(() => null),
+            attempt: attempt + 1,
+            ...(meta?.requestId && { requestId: meta.requestId })
+          }
         );
         
         if (shouldRetry && attempt < maxRetries && response.status >= 500) {
@@ -702,10 +731,23 @@ export class NansenAPI {
           }
         }
 
+        // Quota state and the request id belong on the error above all: an
+        // out-of-credits or rate-limited failure is exactly when the caller
+        // needs the numbers, and a 5xx is worthless to support without the id.
+        // formatError() surfaces details, so this needs no plumbing.
+        //
+        // On a retried call this is the LAST attempt's id — each attempt gets
+        // its own server-side id, and the last one is the failure worth
+        // reporting.
+        const meta = readResponseMeta(response);
+        this.lastResponseMeta = meta;
         lastError = new NansenError(message, code, response.status, {
           ...data,
           attempt: attempt + 1,
-          retryAfterMs
+          retryAfterMs,
+          ...(meta?.requestId && { requestId: meta.requestId }),
+          ...(meta?.credits && { credits: meta.credits }),
+          ...(meta?.rateLimit && { rateLimit: meta.rateLimit })
         });
         
         // Retry on specific status codes
@@ -722,12 +764,21 @@ export class NansenAPI {
       if (attempt > 0) {
         data._meta = { ...(data._meta || {}), retriedAttempts: attempt };
       }
-      
+
       // Cache successful response
       if (useCache) {
         setCachedResponse(endpoint, body, data);
       }
-      
+
+      // Attach after caching so the cache stores the payload alone — quota
+      // numbers are per-response and would be stale on a cache hit.
+      // Guarded: a response body can be a primitive, which cannot take a property.
+      const meta = readResponseMeta(response);
+      this.lastResponseMeta = meta;
+      if (meta) {
+        if (data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
+      }
+
       return data;
     }
     
@@ -1187,13 +1238,18 @@ export class NansenAPI {
   // ============= Perp Endpoints =============
 
   async perpScreener(params = {}) {
-    const { filters = {}, orderBy, pagination, days = 30 } = params;
-    return this.request('/api/v1/perp-screener', {
+    const { filters = {}, orderBy, pagination, days = 30, traderType, sectorsFilter, smLabelFilter, traderLabelFilter } = params;
+    const body = {
       date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
-    });
+    };
+    if (traderType !== undefined) body.filters.trader_type = traderType;
+    if (sectorsFilter !== undefined) body.filters.sectors_filter = sectorsFilter;
+    if (smLabelFilter !== undefined) body.filters.sm_label_filter = smLabelFilter;
+    if (traderLabelFilter !== undefined) body.filters.trader_label_filter = traderLabelFilter;
+    return this.request('/api/v1/perp-screener', body);
   }
 
   async perpLeaderboard(params = {}) {

package/src/cli.js

@@ -14,6 +14,7 @@ import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
 import { refreshCostMapIfStale, getCostForEndpoint } from './cost-cache.js';
+import { creditWarning, noticeWarnings } from './response-meta.js';
 import { trackCommandSucceeded, trackCommandFailed } from './telemetry.js';
 import { createRequire } from 'module';
 import * as readline from 'readline';
@@ -1367,7 +1368,19 @@ export function buildCommands(deps = {}) {
       const days = options.days ? parseInt(options.days) : 30;
 
       const handlers = {
-        'screener': () => apiInstance.perpScreener({ filters, orderBy, pagination, days }),
+        'screener': () => {
+          const traderType = options['trader-type'];
+          const sectorsFilter = options['sectors-filter']
+            ? options['sectors-filter'].split(',').map(s => s.trim()).filter(Boolean)
+            : undefined;
+          const smLabelFilter = options['sm-label-filter']
+            ? options['sm-label-filter'].split(',').map(s => s.trim()).filter(Boolean)
+            : undefined;
+          const traderLabelFilter = options['trader-label-filter']
+            ? options['trader-label-filter'].split(',').map(s => s.trim()).filter(Boolean)
+            : undefined;
+          return apiInstance.perpScreener({ filters, orderBy, pagination, days, traderType, sectorsFilter, smLabelFilter, traderLabelFilter });
+        },
         'leaderboard': () => {
           const withLabels = resolveBooleanOption(options, flags, 'premium-labels');
           return apiInstance.perpLeaderboard({ filters, orderBy, pagination, days, withLabels });
@@ -1842,6 +1855,14 @@ export async function runCLI(rawArgs, deps = {}) {
     const api = new NansenAPIClass(undefined, undefined, { retry: retryOptions, cache: cacheOptions, defaultHeaders });
     let result = await commands[command](subArgs, api, flags, options);
 
+    // Credit balance warning, from the headers on the call just made. Goes to
+    // stderr so it never contaminates the JSON on stdout that agents parse.
+    // Placed before every return path below so it fires for operational
+    // commands too, which print their own output and return undefined.
+    const lowCredits = creditWarning(api.lastResponseMeta);
+    if (lowCredits) errorOutput(lowCredits);
+    for (const notice of noticeWarnings(api.lastResponseMeta)) errorOutput(notice);
+
     // Commands that handle their own output return undefined
     if (result === undefined) {
       await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });

package/src/response-meta.js

@@ -0,0 +1,123 @@
+/**
+ * Request-id, credit, rate-limit, and notice metadata, read from Nansen API
+ * response headers.
+ *
+ * The API reports what a call actually cost, what quota is left, and an id that
+ * identifies the call end to end. Until now the CLI dropped those headers on the
+ * floor and showed only the static per-endpoint estimate published in the
+ * OpenAPI spec (see cost-cache.js), which is a quote rather than a charge.
+ *
+ * readResponseMeta(response) — parse the headers, or null if none are present
+ * creditWarning(meta)        — stderr warning string when the balance is short, else null
+ *
+ * Every header is optional. Some auth rails charge no credits, some responses
+ * are served before quota is resolved, and older deployments may send neither
+ * the rate-limit triplet nor the request id — so a missing header means
+ * "unknown", never zero.
+ */
+
+/** Header names, as documented in the API reference. */
+const CREDITS_USED = 'x-nansen-credits-used';
+const CREDITS_REMAINING = 'x-nansen-credits-remaining';
+const RATE_LIMIT = 'x-ratelimit-limit';
+const RATE_REMAINING = 'x-ratelimit-remaining';
+const RATE_RESET = 'x-ratelimit-reset';
+const UPGRADE_HINT = 'x-nansen-upgrade-hint';
+const PLAN_NOTICE = 'x-nansen-plan-notice';
+const API_KEY_NOTICE = 'x-nansen-api-key-notice';
+const REQUEST_ID = 'x-request-id';
+
+/**
+ * Read a header as a non-negative integer, or null when absent/unparseable.
+ * Tolerates any header bag with a .get() — a real Headers, or a Map in tests.
+ */
+function intHeader(response, name) {
+  const raw = stringHeader(response, name);
+  if (raw === null) return null;
+  const value = Number.parseInt(raw, 10);
+  return Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+/**
+ * Read a header as a trimmed non-empty string, or null when absent.
+ * Tolerates any header bag with a .get() — a real Headers, or a Map in tests.
+ */
+function stringHeader(response, name) {
+  const raw = response?.headers?.get?.(name);
+  if (raw == null) return null;
+  const value = String(raw).trim();
+  return value === '' ? null : value;
+}
+
+/**
+ * Extract request-id, credit, rate-limit, and notice metadata from a fetch Response.
+ * Returns null when the response carries none of it, so callers can skip
+ * attaching an object full of nulls.
+ */
+export function readResponseMeta(response) {
+  const used = intHeader(response, CREDITS_USED);
+  const remaining = intHeader(response, CREDITS_REMAINING);
+  const limit = intHeader(response, RATE_LIMIT);
+  const rateRemaining = intHeader(response, RATE_REMAINING);
+  const resetSeconds = intHeader(response, RATE_RESET);
+  const upgradeHint = stringHeader(response, UPGRADE_HINT);
+  const planNotice = stringHeader(response, PLAN_NOTICE);
+  const apiKeyNotice = stringHeader(response, API_KEY_NOTICE);
+  const requestId = stringHeader(response, REQUEST_ID);
+
+  const meta = {};
+  if (requestId !== null) {
+    // The single value that identifies this call to Nansen support. Opaque —
+    // never parse it or assume a format.
+    meta.requestId = requestId;
+  }
+  if (used !== null || remaining !== null) {
+    meta.credits = { used, remaining };
+  }
+  if (limit !== null || rateRemaining !== null || resetSeconds !== null) {
+    // resetSeconds is a delta in seconds — how long the tripped window needs to
+    // drain — not a wall-clock timestamp.
+    meta.rateLimit = { limit, remaining: rateRemaining, resetSeconds };
+  }
+  if (upgradeHint !== null || planNotice !== null || apiKeyNotice !== null) {
+    meta.notices = {
+      ...(upgradeHint !== null && { upgradeHint }),
+      ...(planNotice !== null && { planNotice }),
+      ...(apiKeyNotice !== null && { apiKeyNotice }),
+    };
+  }
+  return Object.keys(meta).length > 0 ? meta : null;
+}
+
+/**
+ * Yield notice strings for any server-set advisory headers.
+ * Each yields a `⚠️  <message>` line for stderr.
+ * Order: apiKeyNotice (most urgent) → upgradeHint → planNotice.
+ */
+export function noticeWarnings(meta) {
+  const notices = meta?.notices;
+  if (!notices) return [];
+  const out = [];
+  if (notices.apiKeyNotice) out.push(`⚠️  ${notices.apiKeyNotice}`);
+  if (notices.upgradeHint) out.push(`ℹ️  ${notices.upgradeHint}`);
+  if (notices.planNotice) out.push(`ℹ️  ${notices.planNotice}`);
+  return out;
+}
+
+/**
+ * Warn only when the remaining balance will not cover another call of the size
+ * just made.
+ */
+export function creditWarning(meta) {
+  const credits = meta?.credits;
+  if (!credits) return null;
+  const { used, remaining } = credits;
+  if (remaining === null) return null;
+  if (remaining === 0) {
+    return '⚠️  Out of API credits. Top up at https://app.nansen.ai/api';
+  }
+  if (used !== null && used > 0 && remaining < used) {
+    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${used}). Top up at https://app.nansen.ai/api`;
+  }
+  return null;
+}

package/src/schema.json

@@ -522,7 +522,11 @@
               "options": {
                 "market-cap": {
                   "description": "Filter by market cap group",
-                  "enum": ["lowcap", "midcap", "largecap"]
+                  "enum": [
+                    "lowcap",
+                    "midcap",
+                    "largecap"
+                  ]
                 },
                 "limit": {
                   "default": 25
@@ -555,6 +559,25 @@
               "options": {
                 "days": {
                   "default": 30
+                },
+                "trader-type": {
+                  "description": "Filter by trader type. One of: all, sm, whale, public_figure, high_winrate_hl_perps_trader. Defaults to all.",
+                  "enum": [
+                    "all",
+                    "sm",
+                    "whale",
+                    "public_figure",
+                    "high_winrate_hl_perps_trader"
+                  ]
+                },
+                "sectors-filter": {
+                  "description": "Comma-separated sector:subcategory pairs to filter by, e.g. \"Crypto:AI,TradFi:Stocks\"."
+                },
+                "sm-label-filter": {
+                  "description": "Comma-separated Nansen SM labels to filter by, e.g. \"30D Smart Trader\". Only applies when trader-type is all or sm."
+                },
+                "trader-label-filter": {
+                  "description": "Comma-separated HL perps trader labels to filter by, e.g. \"HL Perps Whale\". Only applies when trader-type is all or sm."
                 }
               }
             },
@@ -616,8 +639,12 @@
               "endpoint": "/api/v1/prediction-market/market-screener",
               "description": "Get Prediction Market Screener",
               "options": {
-                "query": { "default": "" },
-                "sort-by": { "description": "Deprecated: use --sort field:dir instead" },
+                "query": {
+                  "default": ""
+                },
+                "sort-by": {
+                  "description": "Deprecated: use --sort field:dir instead"
+                },
                 "tags": {},
                 "min-liquidity": {},
                 "max-liquidity": {},
@@ -638,8 +665,12 @@
               "endpoint": "/api/v1/prediction-market/event-screener",
               "description": "Get Prediction Market Event Screener",
               "options": {
-                "query": { "default": "" },
-                "sort-by": { "description": "Deprecated: use --sort field:dir instead" },
+                "query": {
+                  "default": ""
+                },
+                "sort-by": {
+                  "description": "Deprecated: use --sort field:dir instead"
+                },
                 "tags": {},
                 "min-liquidity": {},
                 "max-liquidity": {},
@@ -717,104 +748,218 @@
           "endpoint": "/api/v1beta1/tgm/historical-dex-trades",
           "description": "Historical DEX trades for a token at a point in time",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" },
-            "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "from-date": {
+              "required": true,
+              "description": "Start of date range (YYYY-MM-DD)"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End of date range (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-pnl-leaderboard": {
           "endpoint": "/api/v1beta1/tgm/historical-pnl-leaderboard",
           "description": "Historical PnL leaderboard for a token",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" },
-            "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "from-date": {
+              "required": true,
+              "description": "Start of date range (YYYY-MM-DD)"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End of date range (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-token-flow-summary": {
           "endpoint": "/api/v1beta1/tgm/historical-token-flow-summary",
           "description": "Historical token flow summary (no pagination)",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" },
-            "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "from-date": {
+              "required": true,
+              "description": "Start of date range (YYYY-MM-DD)"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End of date range (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-token-quant-scores": {
           "endpoint": "/api/v1beta1/tgm/historical-token-quant-scores",
           "description": "Historical token quantitative scores at a snapshot date",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-top-holders": {
           "endpoint": "/api/v1beta1/tgm/historical-top-holders",
           "description": "Historical top holders of a token at a snapshot date",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-who-bought-sold": {
           "endpoint": "/api/v1beta1/tgm/historical-who-bought-sold",
           "description": "Historical buyers/sellers of a token",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" },
-            "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" },
-            "buy-or-sell": { "default": "BUY", "description": "BUY or SELL" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "from-date": {
+              "required": true,
+              "description": "Start of date range (YYYY-MM-DD)"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End of date range (YYYY-MM-DD)"
+            },
+            "buy-or-sell": {
+              "default": "BUY",
+              "description": "BUY or SELL"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-smart-money-balances": {
           "endpoint": "/api/v1beta1/smart-money/historical-token-balances",
           "description": "Historical smart money token balances at a snapshot date (no order_by)",
           "options": {
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chains": { "default": "solana", "description": "Comma-separated chains" }
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chains": {
+              "default": "solana",
+              "description": "Comma-separated chains"
+            }
           }
         },
         "historical-token-screener": {
           "endpoint": "/api/v1beta1/token-screener/historical",
           "description": "Historical token screener over a trailing window",
           "options": {
-            "timeframe-days": { "required": true, "type": "number", "description": "Trailing window size in days" },
-            "to-date": { "required": true, "description": "End date for the window (YYYY-MM-DD)" },
-            "chains": { "default": "solana", "description": "Comma-separated chains" }
+            "timeframe-days": {
+              "required": true,
+              "type": "number",
+              "description": "Trailing window size in days"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End date for the window (YYYY-MM-DD)"
+            },
+            "chains": {
+              "default": "solana",
+              "description": "Comma-separated chains"
+            }
           }
         },
         "historical-wallet-balances": {
           "endpoint": "/api/v1beta1/profiler/address/historical-token-balances",
           "description": "Historical token balances for a wallet at a snapshot date",
           "options": {
-            "address": { "required": true, "description": "Wallet address" },
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chain": { "default": "ethereum", "description": "Chain" }
+            "address": {
+              "required": true,
+              "description": "Wallet address"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "ethereum",
+              "description": "Chain"
+            }
           }
         },
         "historical-tx-lookup": {
           "endpoint": "/api/v1beta1/profiler/historical-transaction-lookup",
           "description": "Lookup a historical transaction by hash",
           "options": {
-            "transaction-hash": { "required": true, "description": "Transaction hash (0x-prefixed, 66 chars)" },
-            "as-of-date": { "required": true, "description": "Reference date for label and pricing resolution (YYYY-MM-DD)" },
-            "block-timestamp": { "description": "Block timestamp (YYYY-MM-DD HH:MM:SS) — skips slow hash-resolution step if provided" },
-            "chain": { "default": "ethereum", "description": "Chain (ethereum, bnb, base)" }
+            "transaction-hash": {
+              "required": true,
+              "description": "Transaction hash (0x-prefixed, 66 chars)"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Reference date for label and pricing resolution (YYYY-MM-DD)"
+            },
+            "block-timestamp": {
+              "description": "Block timestamp (YYYY-MM-DD HH:MM:SS) \u2014 skips slow hash-resolution step if provided"
+            },
+            "chain": {
+              "default": "ethereum",
+              "description": "Chain (ethereum, bnb, base)"
+            }
           }
         },
         "historical-wallet-transactions": {
           "endpoint": "/api/v1beta1/profiler/address/historical-transactions",
           "description": "Historical transactions for a wallet at a snapshot date",
           "options": {
-            "address": { "required": true, "description": "Wallet address" },
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chain": { "default": "ethereum", "description": "Chain" }
+            "address": {
+              "required": true,
+              "description": "Wallet address"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "ethereum",
+              "description": "Chain"
+            }
           }
         }
       }
@@ -971,7 +1116,7 @@
             },
             "to-chain": {
               "type": "string",
-              "description": "Destination blockchain for cross-chain swap (solana or base). Omit for same-chain. At least one side must be USDC or a native token (ETH, SOL). Non-native to non-native is not supported — swap to USDC first, then bridge. Bridge providers (Li.Fi or Relay) are selected automatically based on best price. Sub-dollar swaps are supported via Relay."
+              "description": "Destination blockchain for cross-chain swap (solana or base). Omit for same-chain. At least one side must be USDC or a native token (ETH, SOL). Non-native to non-native is not supported \u2014 swap to USDC first, then bridge. Bridge providers (Li.Fi or Relay) are selected automatically based on best price. Sub-dollar swaps are supported via Relay."
             },
             "from": {
               "type": "string",
@@ -1047,7 +1192,7 @@
             },
             "aggregator": {
               "type": "string",
-              "description": "lifi or relay. Overrides auto-detection — use when polling from a different machine or after the 30-day local record TTL has expired."
+              "description": "lifi or relay. Overrides auto-detection \u2014 use when polling from a different machine or after the 30-day local record TTL has expired."
             }
           }
         },
@@ -1101,7 +1246,9 @@
                   "description": "Wallet name (or \"walletconnect\"/\"wc\")"
                 }
               },
-              "chains": ["solana"],
+              "chains": [
+                "solana"
+              ],
               "prerequisites": [
                 "A Solana wallet must be configured. Run: nansen wallet create"
               ]
@@ -1141,7 +1288,9 @@
                   "description": "Wallet name (or \"walletconnect\"/\"wc\")"
                 }
               },
-              "chains": ["solana"]
+              "chains": [
+                "solana"
+              ]
             },
             "cancel": {
               "description": "Cancel an open limit order",
@@ -1156,7 +1305,9 @@
                   "description": "Wallet name (or \"walletconnect\"/\"wc\")"
                 }
               },
-              "chains": ["solana"]
+              "chains": [
+                "solana"
+              ]
             },
             "update": {
               "description": "Update trigger price or slippage on an existing order",
@@ -1179,7 +1330,9 @@
                   "description": "Wallet name (or \"walletconnect\"/\"wc\")"
                 }
               },
-              "chains": ["solana"]
+              "chains": [
+                "solana"
+              ]
             }
           }
         }