nansen-cli 1.43.1 → 1.44.0

package/src/commands/research.js

@@ -1,29 +1,33 @@
 /**
  * Nansen CLI - Research command
  *
- * Historical/point-in-time analytics. Each subcommand resolves labels and
- * metrics at the requested date rather than current state — useful for
- * backtesting and historical research.
+ * Direct API analytics, including historical/point-in-time research.
  */
 
 import { NansenError, ErrorCode } from '../api.js';
+import { parseSort } from '../query-options.js';
 
-// Local copies of CLI helpers to avoid a circular import with src/cli.js.
+// Research subcommands validate --page strictly. The shared helper in
+// src/query-options.js clamps an invalid page to 1 for the category commands,
+// so keep a local variant here that rejects it instead.
 function buildPagination(options) {
-  if (!options.limit && !options.page) return undefined;
-  return {
-    page: Math.max(1, parseInt(options.page, 10) || 1),
-    per_page: options.limit,
-  };
-}
-
-function parseSort(sortOption, orderByOption) {
-  if (orderByOption) return orderByOption;
-  if (!sortOption) return undefined;
-  const parts = String(sortOption).split(':');
-  const field = parts[0];
-  const direction = (parts[1] || 'desc').toUpperCase();
-  return [{ field, direction }];
+  if (options.limit === undefined && options.page === undefined) return undefined;
+  const pagination = { page: 1 };
+  if (options.page !== undefined) {
+    const page = Number(options.page);
+    if (!Number.isInteger(page) || page < 1) {
+      throw new NansenError('--page must be a positive integer', ErrorCode.INVALID_PARAMS);
+    }
+    pagination.page = page;
+  }
+  if (options.limit !== undefined) {
+    const perPage = Number(options.limit);
+    if (!Number.isInteger(perPage) || perPage < 1) {
+      throw new NansenError('--limit must be a positive integer', ErrorCode.INVALID_PARAMS);
+    }
+    pagination.per_page = perPage;
+  }
+  return pagination;
 }
 
 const SUBCOMMANDS = [
@@ -38,9 +42,16 @@ const SUBCOMMANDS = [
   'historical-wallet-balances',
   'historical-tx-lookup',
   'historical-wallet-transactions',
+  'historical-token-ohlcv',
 ];
 
 export const RESEARCH_HISTORICAL_SUBCOMMANDS = new Set(SUBCOMMANDS);
+export const RESEARCH_SUBCOMMANDS = new Set(['chain-rank', 'token-sectors', 'address-premium-labels', 'smart-money-pnl-leaderboard', 'position-intelligence', 'perp-pnl-summary', 'transaction-with-token-transfer-lookup', ...SUBCOMMANDS]);
+
+const CHAIN_RANK_TIMEFRAMES = new Set([7, 30, 365]);
+const CHAIN_RANK_CHAIN_TYPES = new Set(['all', 'evm']);
+
+const SM_PNL_TIMEFRAME_DAYS = [1, 7, 30, 90, 180];
 
 function requireOptions(options, required) {
   const missing = required.filter(name => !options[name]);
@@ -58,11 +69,20 @@ function resolveDateRange(options) {
 
 function parseTimeframeDays(value) {
   if (value === undefined || value === null || value === '') return undefined;
-  const n = parseInt(value, 10);
-  if (Number.isNaN(n)) {
-    throw new NansenError('--timeframe-days must be an integer', ErrorCode.INVALID_PARAMS);
+  const trimmed = String(value).trim();
+  if (!/^[1-9]\d*$/.test(trimmed)) {
+    throw new NansenError('--timeframe-days must be a positive integer', ErrorCode.INVALID_PARAMS);
   }
-  return n;
+  return parseInt(trimmed, 10);
+}
+
+function parseBooleanOption(options, flags, key) {
+  const value = options[key] ?? flags[key];
+  if (value === undefined) return undefined;
+  if (typeof value === 'boolean') return value;
+  if (value === 'true' || value === '1') return true;
+  if (value === 'false' || value === '0') return false;
+  throw new NansenError(`--${key} must be true or false`, ErrorCode.INVALID_PARAMS);
 }
 
 function parseChains(options) {
@@ -75,9 +95,17 @@ function parseChains(options) {
   return undefined;
 }
 
-const HELP_TOP = `nansen research — Historical/point-in-time analytics
+const HELP_TOP = `nansen research — Direct API analytics
 
 SUBCOMMANDS:
+  chain-rank                       Rank chains by growth metrics
+  token-sectors                     List token sectors available for filtering
+  address-premium-labels            Get all labels for an address, including premium labels
+  smart-money-pnl-leaderboard       Rank smart money wallets by PnL
+  position-intelligence             Aggregate Hyperliquid positions by trader cohort
+  perp-pnl-summary                  Summarize realized Hyperliquid PnL for an address
+  transaction-with-token-transfer-lookup
+                                   Look up a transaction and its token/NFT transfers
   historical-dex-trades             Historical DEX trades for a token
   historical-pnl-leaderboard        Historical PnL leaderboard for a token
   historical-token-flow-summary     Historical token flow summary
@@ -89,6 +117,7 @@ SUBCOMMANDS:
   historical-wallet-balances        Historical token balances for a wallet
   historical-tx-lookup              Lookup a historical transaction by hash
   historical-wallet-transactions    Historical transactions for a wallet
+  historical-token-ohlcv            Historical token OHLCV candles
 
 COMMON OPTIONS:
   --from-date <YYYY-MM-DD>   Start of date range (for range-based subcommands)
@@ -102,6 +131,38 @@ COMMON OPTIONS:
 Run: nansen research <subcommand> --help`;
 
 const SUB_HELP = {
+  'chain-rank': `nansen research chain-rank — Rank chains by growth metrics
+
+USAGE:
+  nansen research chain-rank [--timeframe-days 7|30|365] [--chain-type all|evm]`,
+  'token-sectors': `nansen research token-sectors — List token sectors available for filtering
+
+USAGE:
+  nansen research token-sectors`,
+  'address-premium-labels': `nansen research address-premium-labels — Get all labels for an address, including premium labels
+
+USAGE:
+  nansen research address-premium-labels --address <addr> [--chain <chain>] [--page <n>] [--limit <n>]`,
+  'smart-money-pnl-leaderboard': `nansen research smart-money-pnl-leaderboard — Rank smart money wallets by PnL
+
+USAGE:
+  nansen research smart-money-pnl-leaderboard [--chains c1,c2] [--timeframe-days 1|7|30|90|180] [--filters '<json>'] [--sort <field[:asc|desc]>] [--page <n>] [--limit <n>]`,
+  'position-intelligence': `nansen research position-intelligence — Aggregate Hyperliquid positions by trader cohort
+
+USAGE:
+  nansen research position-intelligence --symbol <symbol>
+
+NOTE: --token-address is accepted as an alias for --symbol (the API request field is token_address).`,
+  'perp-pnl-summary': `nansen research perp-pnl-summary — Summarize realized Hyperliquid PnL for an address
+
+USAGE:
+  nansen research perp-pnl-summary --address <addr> --from-date <date> --to-date <date>`,
+  'transaction-with-token-transfer-lookup': `nansen research transaction-with-token-transfer-lookup — Look up a transaction and its token/NFT transfers
+
+USAGE:
+  nansen research transaction-with-token-transfer-lookup --transaction-hash <hash> [--chain <chain>] [--block-timestamp "YYYY-MM-DD HH:MM:SS"]
+
+NOTE: --block-timestamp is required for bitcoin, tron, ton, starknet, and sui.`,
   'historical-dex-trades': `nansen research historical-dex-trades — Historical DEX trades for a token
 
 USAGE:
@@ -152,6 +213,10 @@ NOTE: Providing --block-timestamp skips a slow hash-resolution step and returns
 
 USAGE:
   nansen research historical-wallet-transactions --address <addr> --as-of-date <YYYY-MM-DD> [--chain <chain>]`,
+  'historical-token-ohlcv': `nansen research historical-token-ohlcv — Historical token OHLCV candles
+
+USAGE:
+  nansen research historical-token-ohlcv --token-address <addr> --from-date <date> --timeframe <5m|15m|30m|1h|1d|1w> (--as-of-date <date> | --as-of-ts <timestamp>) [--chain <chain>] [--apply-blacklist-filter <true|false>]`,
 };
 
 export function buildResearchCommands(deps = {}) {
@@ -166,9 +231,9 @@ export function buildResearchCommands(deps = {}) {
         return;
       }
 
-      if (!RESEARCH_HISTORICAL_SUBCOMMANDS.has(sub)) {
+      if (!RESEARCH_SUBCOMMANDS.has(sub)) {
         throw new NansenError(
-          `Unknown research subcommand: ${sub}. Available: ${SUBCOMMANDS.join(', ')}`,
+          `Unknown research subcommand: ${sub}. Available: ${[...RESEARCH_SUBCOMMANDS].join(', ')}`,
           ErrorCode.UNKNOWN,
         );
       }
@@ -178,12 +243,121 @@ export function buildResearchCommands(deps = {}) {
         return;
       }
 
+      if (sub === 'token-sectors') return apiInstance.tokenSectors();
+
       const orderBy = parseSort(options.sort, options['order-by']);
       const pagination = buildPagination(options);
       const filters = options.filters || {};
       const { fromDate, toDate } = resolveDateRange(options);
       const asOfDate = options['as-of-date'];
 
+      if (sub === 'chain-rank') {
+        const timeFrame = parseTimeframeDays(options['timeframe-days']) ?? 7;
+        if (!CHAIN_RANK_TIMEFRAMES.has(timeFrame)) {
+          throw new NansenError(
+            `--timeframe-days must be one of: ${[...CHAIN_RANK_TIMEFRAMES].join(', ')}`,
+            ErrorCode.INVALID_PARAMS,
+          );
+        }
+        const chainType = options['chain-type'] || 'all';
+        if (!CHAIN_RANK_CHAIN_TYPES.has(chainType)) {
+          throw new NansenError(
+            `--chain-type must be one of: ${[...CHAIN_RANK_CHAIN_TYPES].join(', ')}`,
+            ErrorCode.INVALID_PARAMS,
+          );
+        }
+        return apiInstance.chainRank({ timeFrame, chainType });
+      }
+
+      if (sub === 'address-premium-labels') {
+        requireOptions({ address: options.address }, ['address']);
+        return apiInstance.addressPremiumLabels({
+          address: options.address,
+          chain: options.chain || 'all',
+          pagination,
+        });
+      }
+
+      if (sub === 'smart-money-pnl-leaderboard') {
+        const timeframe = parseTimeframeDays(options['timeframe-days']) ?? 7;
+        if (!SM_PNL_TIMEFRAME_DAYS.includes(timeframe)) {
+          throw new NansenError(
+            `--timeframe-days must be one of: ${SM_PNL_TIMEFRAME_DAYS.join(', ')}`,
+            ErrorCode.INVALID_PARAMS,
+          );
+        }
+        return apiInstance.smartMoneyPnlLeaderboard({
+          chains: parseChains(options) || ['solana'],
+          timeframe,
+          filters, orderBy, pagination,
+        });
+      }
+
+      if (sub === 'position-intelligence') {
+        const symbol = String(options.symbol || options['token-address'] || options.token || '').trim();
+        if (!symbol) {
+          throw new NansenError(
+            'Required: --symbol (or --token-address)',
+            ErrorCode.MISSING_PARAM,
+          );
+        }
+        return apiInstance.tokenPositionIntelligence({ tokenAddress: symbol });
+      }
+
+      if (sub === 'perp-pnl-summary') {
+        requireOptions(
+          { address: options.address, 'from-date': fromDate, 'to-date': toDate },
+          ['address', 'from-date', 'to-date'],
+        );
+        return apiInstance.addressPerpPnlSummary({ address: options.address, fromDate, toDate });
+      }
+
+      if (sub === 'historical-token-ohlcv') {
+        const tokenAddress = options['token-address'] || options.token;
+        const asOfTs = options['as-of-ts'];
+        requireOptions(
+          { 'token-address': tokenAddress, 'from-date': fromDate, timeframe: options.timeframe },
+          ['token-address', 'from-date', 'timeframe'],
+        );
+        if (!asOfDate && !asOfTs) {
+          throw new NansenError(
+            'Provide one of --as-of-date or --as-of-ts',
+            ErrorCode.MISSING_PARAM,
+          );
+        }
+        if (asOfDate && asOfTs) {
+          throw new NansenError(
+            '--as-of-date and --as-of-ts are mutually exclusive',
+            ErrorCode.INVALID_PARAMS,
+          );
+        }
+        return apiInstance.researchHistoricalTokenOhlcv({
+          tokenAddress,
+          chain: options.chain || 'solana',
+          fromDate,
+          asOfDate,
+          asOfTs,
+          timeframe: options.timeframe,
+          applyBlacklistFilter: parseBooleanOption(options, flags, 'apply-blacklist-filter'),
+        });
+      }
+
+      if (sub === 'transaction-with-token-transfer-lookup') {
+        const chain = options.chain || 'ethereum';
+        const blockTimestamp = options['block-timestamp'];
+        requireOptions({ 'transaction-hash': options['transaction-hash'] }, ['transaction-hash']);
+        // Chains the API rejects without block_timestamp. Every other enum value,
+        // including 'all', near, and injective, accepts a timestamp-less lookup.
+        if (['bitcoin', 'tron', 'ton', 'starknet', 'sui'].includes(chain)) {
+          requireOptions({ 'block-timestamp': blockTimestamp }, ['block-timestamp']);
+        }
+        return apiInstance.transactionWithTokenTransferLookup({
+          transactionHash: options['transaction-hash'],
+          chain,
+          blockTimestamp,
+        });
+      }
+
       // Range-based token endpoints (require --from-date + --to-date)
       const rangeTokenHandlers = {
         'historical-dex-trades': () => apiInstance.researchDexTrades({

package/src/hl-client.js

@@ -30,6 +30,15 @@ export {
 
 import { hlApiUrl } from "./hl-env.js";
 
+function exchangeError(message, code, exchangeResult) {
+  const error = new CommandError(message, code);
+  // Keep only a structured action response available to the caller so it can
+  // emit authoritative per-leg outcomes before rethrowing. Opaque HTTP bodies
+  // are not action results and must remain indeterminate.
+  if (exchangeResult !== undefined) error.exchangeResult = exchangeResult;
+  return error;
+}
+
 // Port of perp_execute.py::extract_action_errors. HL returns top-level
 // status "ok" even when individual actions are rejected:
 //   {"status":"ok","response":{"data":{"statuses":[{"error":"..."}]}}}
@@ -130,9 +139,9 @@ export async function submitExchange(
       typeof data === "string"
         ? data
         : data.response || data.error || JSON.stringify(data);
-    throw new CommandError(
+    throw exchangeError(
       `Hyperliquid error (HTTP ${response.status}): ${detail}`,
-      "HL_HTTP_ERROR"
+      "HL_HTTP_ERROR",
     );
   }
 
@@ -144,23 +153,26 @@ export async function submitExchange(
       typeof responseBody === "string"
         ? responseBody
         : "Hyperliquid rejected the action";
-    throw new CommandError(
+    throw exchangeError(
       `Hyperliquid rejected the action: ${reason}`,
-      "HL_ACTION_REJECTED"
+      "HL_ACTION_REJECTED",
+      data,
     );
   }
 
   const actionResults = extractActionErrors(responseBody, action);
   if (actionResults.failed.length > 0 && actionResults.succeeded.length > 0) {
-    throw new CommandError(
+    throw exchangeError(
       `Hyperliquid partially filled the action: succeeded ${actionResults.succeeded.join(", ")}; failed ${actionResults.failed.map(({ leg, error }) => `${leg}: ${error}`).join("; ")}`,
-      "PARTIAL_FILL"
+      "PARTIAL_FILL",
+      data,
     );
   }
   if (actionResults.failed.length > 0) {
-    throw new CommandError(
+    throw exchangeError(
       `Hyperliquid rejected the action: ${actionResults.failed.map(({ error }) => error).join("; ")}`,
-      "HL_ACTION_REJECTED"
+      "HL_ACTION_REJECTED",
+      data,
     );
   }
 

package/src/limit-order.js

@@ -396,23 +396,34 @@ export function parseExpiry(expiryStr) {
   const match = expiryStr.match(/^(\d+)(h|d)$/i);
   if (match) {
     const value = parseInt(match[1], 10);
+    if (!Number.isFinite(value)) {
+      throw new Error(`Invalid expiry "${expiryStr}". Duration must be finite.`);
+    }
     if (value <= 0) {
       throw new Error(`Invalid expiry "${expiryStr}". Duration must be greater than 0.`);
     }
     const unit = match[2].toLowerCase();
     const ms = unit === 'h' ? value * 3600 * 1000 : value * 24 * 3600 * 1000;
-    return Date.now() + ms;
+    const expiresAt = Date.now() + ms;
+    if (!Number.isFinite(expiresAt)) {
+      throw new Error(`Invalid expiry "${expiryStr}". Duration is too large.`);
+    }
+    return expiresAt;
   }
 
   // Try as raw epoch ms — must be in the future, or the order expires on arrival.
   const num = Number(expiryStr);
-  if (!isNaN(num)) {
+  if (Number.isFinite(num)) {
     if (num <= Date.now()) {
       throw new Error(`Expiry "${expiryStr}" is in the past. Provide a future time (e.g. "24h", "7d", or a future epoch in ms).`);
     }
     return num;
   }
 
+  if (!Number.isNaN(num)) {
+    throw new Error(`Invalid expiry "${expiryStr}". Provide a finite future epoch in milliseconds or a duration such as "24h" or "7d".`);
+  }
+
   throw new Error(`Invalid expiry format: "${expiryStr}". Use "24h", "7d", "30d", or epoch ms.`);
 }
 
@@ -569,6 +580,22 @@ EXAMPLES:
         return;
       }
 
+      const price = Number(triggerPrice);
+      if (!Number.isFinite(price) || price <= 0) {
+        log('Error: --trigger-price must be a finite positive number.');
+        exit(1);
+        return;
+      }
+
+      let expiresAt;
+      try {
+        expiresAt = parseExpiry(expiresStr);
+      } catch (err) {
+        log(`Error: ${err.message}`);
+        exit(1);
+        return;
+      }
+
       // Amount is always in human-readable token units (e.g. 1.5 = 1.5 SOL)
       // Converted to base units (lamports) internally
       let amountBaseUnits;
@@ -594,13 +621,6 @@ EXAMPLES:
         return;
       }
 
-      const price = Number(triggerPrice);
-      if (isNaN(price) || price <= 0) {
-        log('Error: --trigger-price must be a positive number (USD price).');
-        exit(1);
-        return;
-      }
-
       if (triggerCondition !== 'above' && triggerCondition !== 'below') {
         log('Error: --trigger-condition must be "above" or "below".');
         exit(1);
@@ -619,15 +639,6 @@ EXAMPLES:
         }
       }
 
-      let expiresAt;
-      try {
-        expiresAt = parseExpiry(expiresStr);
-      } catch (err) {
-        log(`Error: ${err.message}`);
-        exit(1);
-        return;
-      }
-
       const triggerMint = resolveTokenAddress(triggerMintRaw, 'solana');
 
       const tmValidation = validateTokenAddress(triggerMint, 'solana');
@@ -899,8 +910,8 @@ EXAMPLES:
       const updateBody = { orderType: 'single' };
       if (triggerPrice != null) {
         const price = Number(triggerPrice);
-        if (isNaN(price) || price <= 0) {
-          log('Error: --trigger-price must be a positive number.');
+        if (!Number.isFinite(price) || price <= 0) {
+          log('Error: --trigger-price must be a finite positive number.');
           exit(1);
           return;
         }

package/src/mcp-verify.js

@@ -12,6 +12,37 @@ class McpRequestError extends Error {
   }
 }
 
+const IPV4_OCTET = '(?:25[0-5]|2[0-4]\\d|1?\\d{1,2})';
+const LOOPBACK_IPV4 = new RegExp(`^127\\.${IPV4_OCTET}\\.${IPV4_OCTET}\\.${IPV4_OCTET}$`);
+
+// IPv4-mapped IPv6 loopback (127.0.0.0/8). Node's URL canonicalizes
+// ::ffff:127.x.x.x to ::ffff:7fNN:NNNN (the 127 becomes the 7f high byte), so
+// match that form; non-loopback mapped addresses fall outside the 7f prefix.
+const LOOPBACK_IPV4_MAPPED = /^::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}$/i;
+
+function isLoopbackHostname(hostname) {
+  if (!hostname) return false;
+  const host = hostname.toLowerCase().replace(/^\[/, '').replace(/\]$/, '');
+  if (host === 'localhost' || host === '::1') return true;
+  if (LOOPBACK_IPV4_MAPPED.test(host)) return true;
+  return LOOPBACK_IPV4.test(host);
+}
+
+/**
+ * Classify a destination URL for the credential-disclosure guard: its origin
+ * (for messaging), protocol, and whether the host is loopback.
+ */
+function classifyDestination(url) {
+  try {
+    const parsed = new URL(url);
+    return { origin: parsed.origin, protocol: parsed.protocol, loopback: isLoopbackHostname(parsed.hostname) };
+  } catch {
+    // An unparseable URL never reaches an authenticated fetch (tools/list fails
+    // first), so this is only for messaging; treat it as an unsafe destination.
+    return { origin: url, protocol: null, loopback: false };
+  }
+}
+
 function responseContentType(response) {
   return (
     response.headers?.get?.('content-type')
@@ -185,6 +216,7 @@ export async function runMcpVerifyChecks({
   fetchFn = fetch,
   timeoutMs = 30_000,
   devConfigPath,
+  sendApiKey = false,
 } = {}) {
   const checks = [];
   const auth = resolveAuthConfig(env, devConfigPath);
@@ -205,8 +237,39 @@ export async function runMcpVerifyChecks({
     ));
   }
 
+  // A saved key is trusted for the default Nansen endpoint only. Forwarding it
+  // to a caller-supplied URL requires explicit per-invocation consent, and no
+  // key may travel in cleartext to a public host.
+  let keyWithheld = null;
   if (key && url !== DEFAULT_MCP_URL) {
-    checks.push(check('mcp-url', 'warn', `Non-default MCP URL: ${url} — the API key will be sent to this host`));
+    const dest = classifyDestination(url);
+    if (dest.protocol === 'http:' && !dest.loopback) {
+      keyWithheld = check(
+        'mcp-url',
+        'error',
+        `Refusing to send the API key over plain HTTP to a non-loopback host (${dest.origin})`,
+        'Use an https:// URL. Plain HTTP is only permitted for localhost/loopback development.',
+      );
+    } else if (dest.protocol !== 'https:' && !(dest.protocol === 'http:' && dest.loopback)) {
+      // Anything not provably secure — an unparseable URL or a non-http(s)
+      // scheme — is refused rather than relied on to fail later in fetch.
+      keyWithheld = check(
+        'mcp-url',
+        'error',
+        `Refusing to send the API key to an unsupported MCP URL (${dest.origin})`,
+        'Use an https:// URL, or a loopback http:// URL for local development.',
+      );
+    } else if (!explicitKey && !sendApiKey) {
+      keyWithheld = check(
+        'mcp-url',
+        'error',
+        `Saved API key withheld from custom MCP URL (${dest.origin})`,
+        `Re-run with --send-api-key to authorize sending your saved key to ${dest.origin}, or pass --api-key <key> to supply one explicitly.`,
+      );
+    } else {
+      checks.push(check('mcp-url', 'warn', `Sending the API key to custom MCP host: ${dest.origin}`));
+    }
+    if (keyWithheld) checks.push(keyWithheld);
   }
 
   let serverReady = false;
@@ -239,6 +302,8 @@ export async function runMcpVerifyChecks({
 
   if (!key) {
     checks.push(skippedAuth('no API key was provided'));
+  } else if (keyWithheld) {
+    checks.push(skippedAuth('the API key was withheld from this custom URL (see above)'));
   } else if (!serverReady) {
     checks.push(skippedAuth('tools/list did not establish server reachability'));
   } else {