nansen-cli 1.30.1 → 1.31.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.31.0
+
+### Minor Changes
+
+- [#437](https://github.com/nansen-ai/nansen-cli/pull/437) [`5ec7bd3`](https://github.com/nansen-ai/nansen-cli/commit/5ec7bd33f173cd712f9f592599e32b2a0d28fe0f) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `nansen research` command with 11 subcommands for historical/point-in-time analytics: dex-trades, pnl-leaderboard, token-flow-summary, token-quant-scores, top-holders, who-bought-sold, smart-money-balances, token-screener, wallet-balances, tx-lookup, wallet-transactions. Labels and metrics resolve at the requested date rather than current state — useful for backtesting and historical research.
+
+### Patch Changes
+
+- [#440](https://github.com/nansen-ai/nansen-cli/pull/440) [`701dad4`](https://github.com/nansen-ai/nansen-cli/commit/701dad49f54323cf2b455376b1af3b012e2e0b71) Thanks [@kome12](https://github.com/kome12)! - Fix `research historical-token-screener` schema to mark `--to-date` as required (matching CLI and API behavior)
+
+- [#442](https://github.com/nansen-ai/nansen-cli/pull/442) [`6edbb68`](https://github.com/nansen-ai/nansen-cli/commit/6edbb686b52e00b8725470a3f4409ff15f2ccb95) Thanks [@kome12](https://github.com/kome12)! - `research historical-token-flow-summary` now errors immediately when `--page` or `--limit` are passed (the endpoint returns a single aggregated row and does not support pagination). `research historical-smart-money-balances` now errors when `--sort` or `--order-by` are passed (the endpoint does not support ordering). Previously both flags were silently dropped.
+
+## 1.30.2
+
+### Patch Changes
+
+- [#431](https://github.com/nansen-ai/nansen-cli/pull/431) [`c2c033b`](https://github.com/nansen-ai/nansen-cli/commit/c2c033b86f9dab59df9497ce971ef6f267ee3669) Thanks [@MarcLlopart](https://github.com/MarcLlopart)! - Pass backend quoteId in execute requests for BI correlation
+
 ## 1.30.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.30.1",
+  "version": "1.31.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",
@@ -66,6 +66,7 @@
     "@changesets/cli": "^2.29.4",
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.0.18",
+    "clawhub": "^0.9.0",
     "eslint": "^10.0.2",
     "globals": "^17.4.0",
     "vitest": "^4.0.18"

package/src/api.js

@@ -336,6 +336,22 @@ export function validateTokenAddress(tokenAddress, chain = 'solana') {
   return validateAddress(tokenAddress, chain);
 }
 
+/**
+ * Throw if address is present but invalid.
+ */
+function requireValidAddress(address, chain) {
+  const v = validateAddress(address, chain);
+  if (!v.valid) throw new NansenError(v.error, v.code);
+}
+
+/**
+ * Throw if token address is present but invalid.
+ */
+function requireValidToken(tokenAddress, chain) {
+  const v = validateTokenAddress(tokenAddress, chain);
+  if (!v.valid) throw new NansenError(v.error, v.code);
+}
+
 function loadConfig() {
   // Base config from files, then env vars override individual fields
   let config = null;
@@ -791,10 +807,7 @@ export class NansenAPI {
 
   async addressBalance(params = {}) {
     const { address, entityName, chain = 'all', hideSpamToken = true, filters = {}, orderBy } = params;
-    if (address) {
-      const validation = validateAddress(address, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (address) requireValidAddress(address, chain);
     return this.request('/api/v1/profiler/address/current-balance', {
       address,
       entity_name: entityName,
@@ -807,10 +820,7 @@ export class NansenAPI {
 
   async addressLabels(params = {}) {
     const { address, chain = 'ethereum', pagination = { page: 1, per_page: 100 } } = params;
-    if (address) {
-      const validation = validateAddress(address, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (address) requireValidAddress(address, chain);
     return this.request('/api/beta/profiler/address/labels', {
       parameters: { address, chain },
       pagination
@@ -819,10 +829,7 @@ export class NansenAPI {
 
   async addressTransactions(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30, date } = params;
-    if (address) {
-      const validation = validateAddress(address, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (address) requireValidAddress(address, chain);
     const dateRange = date || buildDateRange(days);
     return this.request('/api/v1/profiler/address/transactions', {
       address,
@@ -836,10 +843,7 @@ export class NansenAPI {
 
   async addressPnl(params = {}) {
     const { address, chain = 'ethereum', date, days = 30, filters = {}, orderBy, pagination } = params;
-    if (address) {
-      const validation = validateAddress(address, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (address) requireValidAddress(address, chain);
     const dateRange = date || buildDateRange(days);
     return this.request('/api/v1/profiler/address/pnl', {
       address,
@@ -899,10 +903,7 @@ export class NansenAPI {
 
   async addressHistoricalBalances(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
-    if (address) {
-      const validation = validateAddress(address, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (address) requireValidAddress(address, chain);
     return this.request('/api/v1/profiler/address/historical-balances', {
       address,
       chain,
@@ -915,10 +916,7 @@ export class NansenAPI {
 
   async addressRelatedWallets(params = {}) {
     const { address, chain = 'ethereum', orderBy, pagination } = params;
-    if (address) {
-      const validation = validateAddress(address, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (address) requireValidAddress(address, chain);
     return this.request('/api/v1/profiler/address/related-wallets', {
       address,
       chain,
@@ -929,10 +927,7 @@ export class NansenAPI {
 
   async addressCounterparties(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
-    if (address) {
-      const validation = validateAddress(address, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (address) requireValidAddress(address, chain);
     return this.request('/api/v1/profiler/address/counterparties', {
       address,
       chain,
@@ -947,10 +942,7 @@ export class NansenAPI {
     // Note: pnl-summary endpoint is non-paginated (returns aggregate stats, not a list).
     // Pagination param intentionally omitted from this request.
     const { address, chain = 'ethereum', orderBy, days = 30 } = params;
-    if (address) {
-      const validation = validateAddress(address, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (address) requireValidAddress(address, chain);
     return this.request('/api/v1/profiler/address/pnl-summary', {
       address,
       chain,
@@ -996,10 +988,7 @@ export class NansenAPI {
 
   async tokenHolders(params = {}) {
     const { tokenAddress, chain = 'solana', labelType = 'all_holders', filters = {}, orderBy, pagination, withLabels } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     const body = {
       token_address: tokenAddress,
       chain,
@@ -1014,10 +1003,7 @@ export class NansenAPI {
 
   async tokenFlows(params = {}) {
     const { tokenAddress, chain = 'solana', label, filters = {}, orderBy, pagination, days = 30, date } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     const dateRange = date || buildDateRange(days);
     return this.request('/api/v1/tgm/flows', {
       token_address: tokenAddress,
@@ -1032,10 +1018,7 @@ export class NansenAPI {
 
   async tokenDexTrades(params = {}) {
     const { tokenAddress, chain = 'solana', onlySmartMoney = false, filters = {}, orderBy, pagination, days = 7 } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     // Apply smart money filter via filters object
     if (onlySmartMoney) {
       filters.include_smart_money_labels = filters.include_smart_money_labels || 
@@ -1054,10 +1037,7 @@ export class NansenAPI {
 
   async tokenPnlLeaderboard(params = {}) {
     const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30, withLabels } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     const body = {
       token_address: tokenAddress,
       chain,
@@ -1072,10 +1052,7 @@ export class NansenAPI {
 
   async tokenWhoBoughtSold(params = {}) {
     const { tokenAddress, chain = 'solana', buyOrSell = 'BUY', filters = {}, orderBy, pagination, days = 30, date } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     const dateRange = date || buildDateRange(days);
     return this.request('/api/v1/tgm/who-bought-sold', {
       token_address: tokenAddress,
@@ -1090,10 +1067,7 @@ export class NansenAPI {
 
   async tokenFlowIntelligence(params = {}) {
     const { tokenAddress, chain = 'solana', timeframe = '1d' } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     return this.request('/api/v1/tgm/flow-intelligence', {
       token_address: tokenAddress,
       chain,
@@ -1103,10 +1077,7 @@ export class NansenAPI {
 
   async tokenTransfers(params = {}) {
     const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 7 } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     return this.request('/api/v1/tgm/transfers', {
       token_address: tokenAddress,
       chain,
@@ -1120,10 +1091,7 @@ export class NansenAPI {
   async tokenJupDca(params = {}) {
     const { tokenAddress, filters = {}, orderBy, pagination } = params;
     // JUP DCA is Solana-only
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, 'solana');
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, 'solana');
     return this.request('/api/v1/tgm/jup-dca', {
       token_address: tokenAddress,
       filters,
@@ -1168,10 +1136,7 @@ export class NansenAPI {
 
   async tokenIndicators(params = {}) {
     const { tokenAddress, chain = 'ethereum' } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     return this.request('/api/v1/tgm/indicators', {
       token_address: tokenAddress,
       chain
@@ -1180,10 +1145,7 @@ export class NansenAPI {
 
   async tokenOhlcv(params = {}) {
     const { tokenAddress, chain = 'solana', timeframe } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     return this.request('/api/v1/tgm/token-ohlcv', {
       token_address: tokenAddress,
       chain,
@@ -1193,10 +1155,7 @@ export class NansenAPI {
 
   async tokenInformation(params = {}) {
     const { tokenAddress, chain = 'solana', timeframe = '1d' } = params;
-    if (tokenAddress) {
-      const validation = validateTokenAddress(tokenAddress, chain);
-      if (!validation.valid) throw new NansenError(validation.error, validation.code);
-    }
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
     return this.request('/api/v1/tgm/token-information', {
       token_address: tokenAddress,
       chain,
@@ -1279,8 +1238,7 @@ export class NansenAPI {
   async pmTradesByAddress(params = {}) {
     const { address, orderBy, pagination } = params;
     // Polymarket runs exclusively on Polygon
-    const validation = validateAddress(address, 'polygon');
-    if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    requireValidAddress(address, 'polygon');
     return this.request('/api/v1/prediction-market/trades-by-address', {
       address,
       order_by: orderBy,
@@ -1351,8 +1309,7 @@ export class NansenAPI {
   async pmPnlByAddress(params = {}) {
     const { address, orderBy, pagination } = params;
     // Polymarket runs exclusively on Polygon
-    const validation = validateAddress(address, 'polygon');
-    if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    requireValidAddress(address, 'polygon');
     return this.request('/api/v1/prediction-market/pnl-by-address', {
       address,
       order_by: orderBy,
@@ -1406,6 +1363,151 @@ export class NansenAPI {
     });
   }
 
+  // ============= Research (Historical) Endpoints =============
+  // Historical/point-in-time analytics: labels and metrics are resolved at the
+  // requested date rather than current state. Useful for backtesting and historical
+  // research. Some endpoints use a { from, to } date range; others use a single
+  // as_of_date snapshot; the token-screener uses timeframe_days + optional to_date.
+
+  async researchDexTrades(params = {}) {
+    const { tokenAddress, chain = 'solana', fromDate, toDate, filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
+    return this.request('/api/v1beta1/tgm/historical-dex-trades', {
+      token_address: tokenAddress,
+      chain,
+      date_range: { from: fromDate, to: toDate },
+      filters,
+      order_by: orderBy,
+      pagination,
+    });
+  }
+
+  async researchPnlLeaderboard(params = {}) {
+    const { tokenAddress, chain = 'solana', fromDate, toDate, filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
+    return this.request('/api/v1beta1/tgm/historical-pnl-leaderboard', {
+      token_address: tokenAddress,
+      chain,
+      date_range: { from: fromDate, to: toDate },
+      filters,
+      order_by: orderBy,
+      pagination,
+    });
+  }
+
+  async researchTokenFlowSummary(params = {}) {
+    // API does not support pagination on this endpoint.
+    const { tokenAddress, chain = 'solana', fromDate, toDate, filters = {}, orderBy } = params;
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
+    return this.request('/api/v1beta1/tgm/historical-token-flow-summary', {
+      token_address: tokenAddress,
+      chain,
+      date_range: { from: fromDate, to: toDate },
+      filters,
+      order_by: orderBy,
+    });
+  }
+
+  async researchTokenQuantScores(params = {}) {
+    const { tokenAddress, chain = 'solana', asOfDate, filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
+    return this.request('/api/v1beta1/tgm/historical-token-quant-scores', {
+      token_address: tokenAddress,
+      chain,
+      as_of_date: asOfDate,
+      filters,
+      order_by: orderBy,
+      pagination,
+    });
+  }
+
+  async researchTopHolders(params = {}) {
+    const { tokenAddress, chain = 'solana', asOfDate, filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
+    return this.request('/api/v1beta1/tgm/historical-top-holders', {
+      token_address: tokenAddress,
+      chain,
+      as_of_date: asOfDate,
+      filters,
+      order_by: orderBy,
+      pagination,
+    });
+  }
+
+  async researchWhoBoughtSold(params = {}) {
+    const { tokenAddress, chain = 'solana', fromDate, toDate, buyOrSell = 'BUY', filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) requireValidToken(tokenAddress, chain);
+    return this.request('/api/v1beta1/tgm/historical-who-bought-sold', {
+      token_address: tokenAddress,
+      chain,
+      buy_or_sell: buyOrSell,
+      date_range: { from: fromDate, to: toDate },
+      filters,
+      order_by: orderBy,
+      pagination,
+    });
+  }
+
+  async researchSmartMoneyBalances(params = {}) {
+    // API does not support order_by on this endpoint.
+    const { chains = ['solana'], asOfDate, filters = {}, pagination } = params;
+    return this.request('/api/v1beta1/smart-money/historical-token-balances', {
+      chains,
+      as_of_date: asOfDate,
+      filters,
+      pagination,
+    });
+  }
+
+  async researchTokenScreener(params = {}) {
+    const { chains = ['solana'], timeframeDays, toDate, filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1beta1/token-screener/historical', {
+      chains,
+      timeframe_days: timeframeDays,
+      to_date: toDate,
+      filters,
+      order_by: orderBy,
+      pagination,
+    });
+  }
+
+  async researchWalletBalances(params = {}) {
+    const { address, chain = 'ethereum', asOfDate, filters = {}, orderBy, pagination } = params;
+    if (address) requireValidAddress(address, chain);
+    return this.request('/api/v1beta1/profiler/address/historical-token-balances', {
+      address,
+      chain,
+      as_of_date: asOfDate,
+      filters,
+      order_by: orderBy,
+      pagination,
+    });
+  }
+
+  async researchTxLookup(params = {}) {
+    const { txHash, chain = 'ethereum', asOfDate, blockTimestamp } = params;
+    const body = {
+      transaction_hash: txHash,
+      chain,
+      as_of_date: asOfDate,
+    };
+    if (blockTimestamp) body.block_timestamp = blockTimestamp;
+    return this.request('/api/v1beta1/profiler/historical-transaction-lookup', body);
+  }
+
+  async researchWalletTransactions(params = {}) {
+    const { address, chain = 'ethereum', asOfDate, filters = {}, orderBy, pagination } = params;
+    if (address) requireValidAddress(address, chain);
+    return this.request('/api/v1beta1/profiler/address/historical-transactions', {
+      address,
+      chain,
+      as_of_date: asOfDate,
+      filters,
+      order_by: orderBy,
+      pagination,
+    });
+  }
+
   // ============= Smart Alert Endpoints =============
 
   async alertsList(params = {}) {

package/src/cli.js

@@ -9,6 +9,7 @@ import { buildTradingCommands } from './trading.js';
 import { buildLimitOrderCommands } from './limit-order.js';
 import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
 import { buildAgentCommands } from './commands/agent.js';
+import { buildResearchCommands, RESEARCH_HISTORICAL_SUBCOMMANDS } from './commands/research.js';
 import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
@@ -1471,19 +1472,25 @@ export function buildCommands(deps = {}) {
   // 'research' delegates to the category handlers defined above
   const RESEARCH_CATEGORIES = new Set(['smart-money', 'profiler', 'token', 'search', 'perp', 'portfolio', 'points', 'prediction-market']);
 
+  const researchHistorical = buildResearchCommands(deps).research;
+
   cmds['research'] = async (args, apiInstance, flags, options) => {
     const rawCategory = args[0];
     if (!rawCategory || rawCategory === 'help') {
       return {
         categories: [...RESEARCH_CATEGORIES],
+        historical: [...RESEARCH_HISTORICAL_SUBCOMMANDS],
         aliases: RESEARCH_CATEGORY_ALIASES,
         description: 'Research and analytics commands',
         example: 'nansen research smart-money netflow --chain solana'
       };
     }
+    if (RESEARCH_HISTORICAL_SUBCOMMANDS.has(rawCategory)) {
+      return researchHistorical(args, apiInstance, flags, options);
+    }
     const category = RESEARCH_CATEGORY_ALIASES[rawCategory] || rawCategory;
     if (!RESEARCH_CATEGORIES.has(category)) {
-      throw new NansenError(`Unknown research category: ${rawCategory}. Available: ${[...RESEARCH_CATEGORIES].join(', ')}`, ErrorCode.UNKNOWN);
+      throw new NansenError(`Unknown research category: ${rawCategory}. Available: ${[...RESEARCH_CATEGORIES, ...RESEARCH_HISTORICAL_SUBCOMMANDS].join(', ')}`, ErrorCode.UNKNOWN);
     }
     return cmds[category](args.slice(1), apiInstance, flags, options);
   };
@@ -1712,6 +1719,19 @@ export async function runCLI(rawArgs, deps = {}) {
           if (catSchema.subcommands) {
             lines.push('Subcommands: ' + Object.keys(catSchema.subcommands).join(', '));
             lines.push(`Use: nansen research ${category} <subcommand> --help`);
+          } else if (catSchema.options) {
+            // Leaf historical subcommand: render options + example
+            const params = Object.entries(catSchema.options).map(([name, opt]) => {
+              const parts = [`--${name}`];
+              if (opt.required) parts[0] += '*';
+              if (opt.default !== undefined) parts.push(`(${opt.default})`);
+              return parts.join(' ');
+            });
+            lines.push(`Params (* required): ${params.join(', ')}`);
+            if (catSchema.endpoint) {
+              const cost = getCostForEndpoint(catSchema.endpoint);
+              if (cost) lines.push(`Cost: ${cost.free} credit${cost.free === 1 ? '' : 's'} (Free tier) / ${cost.pro} credit${cost.pro === 1 ? '' : 's'} (Pro tier)`);
+            }
           }
           output(lines.join('\n'));
           notify();

package/src/commands/research.js

@@ -0,0 +1,314 @@
+/**
+ * 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.
+ */
+
+import { NansenError, ErrorCode } from '../api.js';
+
+// Local copies of CLI helpers to avoid a circular import with src/cli.js.
+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 }];
+}
+
+const SUBCOMMANDS = [
+  'historical-dex-trades',
+  'historical-pnl-leaderboard',
+  'historical-token-flow-summary',
+  'historical-token-quant-scores',
+  'historical-top-holders',
+  'historical-who-bought-sold',
+  'historical-smart-money-balances',
+  'historical-token-screener',
+  'historical-wallet-balances',
+  'historical-tx-lookup',
+  'historical-wallet-transactions',
+];
+
+export const RESEARCH_HISTORICAL_SUBCOMMANDS = new Set(SUBCOMMANDS);
+
+function requireOptions(options, required) {
+  const missing = required.filter(name => !options[name]);
+  if (missing.length > 0) {
+    throw new NansenError(
+      `Required: ${missing.map(n => '--' + n).join(', ')}`,
+      ErrorCode.MISSING_PARAM,
+    );
+  }
+}
+
+function resolveDateRange(options) {
+  return { fromDate: options['from-date'], toDate: options['to-date'] };
+}
+
+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);
+  }
+  return n;
+}
+
+function parseChains(options) {
+  if (options.chains) {
+    return Array.isArray(options.chains)
+      ? options.chains
+      : String(options.chains).split(',').map(s => s.trim()).filter(Boolean);
+  }
+  if (options.chain) return [options.chain];
+  return undefined;
+}
+
+const HELP_TOP = `nansen research — Historical/point-in-time analytics
+
+SUBCOMMANDS:
+  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
+  historical-token-quant-scores     Historical token quantitative scores
+  historical-top-holders            Historical top holders of a token
+  historical-who-bought-sold        Historical buyers/sellers of a token
+  historical-smart-money-balances   Historical smart money token balances
+  historical-token-screener         Historical token screener
+  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
+
+COMMON OPTIONS:
+  --from-date <YYYY-MM-DD>   Start of date range (for range-based subcommands)
+  --to-date <YYYY-MM-DD>     End of date range (for range-based subcommands)
+  --as-of-date <YYYY-MM-DD>  Snapshot date (for as-of-date subcommands)
+  --chain <chain>            Chain (default: solana for tokens, ethereum for wallets)
+  --page <n> --limit <n>     Pagination (not supported by historical-token-flow-summary)
+  --sort <field[:asc|desc]>  Sort order (not supported by historical-smart-money-balances)
+  --filters '<json>'         Filters as JSON object
+
+Run: nansen research <subcommand> --help`;
+
+const SUB_HELP = {
+  'historical-dex-trades': `nansen research historical-dex-trades — Historical DEX trades for a token
+
+USAGE:
+  nansen research historical-dex-trades --token-address <addr> --from-date <YYYY-MM-DD> --to-date <YYYY-MM-DD> [--chain <chain>]`,
+  'historical-pnl-leaderboard': `nansen research historical-pnl-leaderboard — Historical PnL leaderboard for a token
+
+USAGE:
+  nansen research historical-pnl-leaderboard --token-address <addr> --from-date <YYYY-MM-DD> --to-date <YYYY-MM-DD> [--chain <chain>]`,
+  'historical-token-flow-summary': `nansen research historical-token-flow-summary — Historical token flow summary
+
+USAGE:
+  nansen research historical-token-flow-summary --token-address <addr> --from-date <YYYY-MM-DD> --to-date <YYYY-MM-DD> [--chain <chain>]
+
+NOTE: This endpoint does not support pagination.`,
+  'historical-token-quant-scores': `nansen research historical-token-quant-scores — Historical token quantitative scores
+
+USAGE:
+  nansen research historical-token-quant-scores --token-address <addr> --as-of-date <YYYY-MM-DD> [--chain <chain>]`,
+  'historical-top-holders': `nansen research historical-top-holders — Historical top holders of a token
+
+USAGE:
+  nansen research historical-top-holders --token-address <addr> --as-of-date <YYYY-MM-DD> [--chain <chain>]`,
+  'historical-who-bought-sold': `nansen research historical-who-bought-sold — Historical buyers/sellers of a token
+
+USAGE:
+  nansen research historical-who-bought-sold --token-address <addr> --from-date <YYYY-MM-DD> --to-date <YYYY-MM-DD> [--buy-or-sell BUY|SELL] [--chain <chain>]`,
+  'historical-smart-money-balances': `nansen research historical-smart-money-balances — Historical smart money token balances
+
+USAGE:
+  nansen research historical-smart-money-balances --as-of-date <YYYY-MM-DD> [--chains c1,c2]
+
+NOTE: This endpoint does not support order_by.`,
+  'historical-token-screener': `nansen research historical-token-screener — Historical token screener
+
+USAGE:
+  nansen research historical-token-screener --timeframe-days <n> --to-date <YYYY-MM-DD> [--chains c1,c2]`,
+  'historical-wallet-balances': `nansen research historical-wallet-balances — Historical token balances for a wallet
+
+USAGE:
+  nansen research historical-wallet-balances --address <addr> --as-of-date <YYYY-MM-DD> [--chain <chain>]`,
+  'historical-tx-lookup': `nansen research historical-tx-lookup — Lookup a historical transaction by hash
+
+USAGE:
+  nansen research historical-tx-lookup --transaction-hash <hash> --as-of-date <YYYY-MM-DD> [--chain <chain>] [--block-timestamp "YYYY-MM-DD HH:MM:SS"]
+
+NOTE: Providing --block-timestamp skips a slow hash-resolution step and returns results much faster.`,
+  'historical-wallet-transactions': `nansen research historical-wallet-transactions — Historical transactions for a wallet
+
+USAGE:
+  nansen research historical-wallet-transactions --address <addr> --as-of-date <YYYY-MM-DD> [--chain <chain>]`,
+};
+
+export function buildResearchCommands(deps = {}) {
+  const { log = console.log } = deps;
+
+  return {
+    'research': async (args, apiInstance, flags, options) => {
+      const sub = args[0];
+
+      if (!sub || sub === 'help') {
+        log(HELP_TOP);
+        return;
+      }
+
+      if (!RESEARCH_HISTORICAL_SUBCOMMANDS.has(sub)) {
+        throw new NansenError(
+          `Unknown research subcommand: ${sub}. Available: ${SUBCOMMANDS.join(', ')}`,
+          ErrorCode.UNKNOWN,
+        );
+      }
+
+      if (flags.help || flags.h || args[1] === 'help') {
+        log(SUB_HELP[sub] || HELP_TOP);
+        return;
+      }
+
+      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'];
+
+      // Range-based token endpoints (require --from-date + --to-date)
+      const rangeTokenHandlers = {
+        'historical-dex-trades': () => apiInstance.researchDexTrades({
+          tokenAddress: options['token-address'] || options.token,
+          chain: options.chain,
+          fromDate, toDate, filters, orderBy, pagination,
+        }),
+        'historical-pnl-leaderboard': () => apiInstance.researchPnlLeaderboard({
+          tokenAddress: options['token-address'] || options.token,
+          chain: options.chain,
+          fromDate, toDate, filters, orderBy, pagination,
+        }),
+        'historical-token-flow-summary': () => apiInstance.researchTokenFlowSummary({
+          tokenAddress: options['token-address'] || options.token,
+          chain: options.chain,
+          fromDate, toDate, filters, orderBy,
+        }),
+        'historical-who-bought-sold': () => apiInstance.researchWhoBoughtSold({
+          tokenAddress: options['token-address'] || options.token,
+          chain: options.chain,
+          buyOrSell: options['buy-or-sell'],
+          fromDate, toDate, filters, orderBy, pagination,
+        }),
+      };
+
+      if (rangeTokenHandlers[sub]) {
+        requireOptions(
+          { 'token-address': options['token-address'] || options.token, 'from-date': fromDate, 'to-date': toDate },
+          ['token-address', 'from-date', 'to-date'],
+        );
+        if (sub === 'historical-token-flow-summary' && (options.page || options.limit)) {
+          throw new NansenError(
+            'historical-token-flow-summary does not support --page or --limit (endpoint returns a single aggregated row)',
+            ErrorCode.INVALID_PARAMS,
+          );
+        }
+        return rangeTokenHandlers[sub]();
+      }
+
+      // As-of-date token endpoints (require --as-of-date)
+      const asOfTokenHandlers = {
+        'historical-token-quant-scores': () => apiInstance.researchTokenQuantScores({
+          tokenAddress: options['token-address'] || options.token,
+          chain: options.chain,
+          asOfDate, filters, orderBy, pagination,
+        }),
+        'historical-top-holders': () => apiInstance.researchTopHolders({
+          tokenAddress: options['token-address'] || options.token,
+          chain: options.chain,
+          asOfDate, filters, orderBy, pagination,
+        }),
+      };
+
+      if (asOfTokenHandlers[sub]) {
+        requireOptions(
+          { 'token-address': options['token-address'] || options.token, 'as-of-date': asOfDate },
+          ['token-address', 'as-of-date'],
+        );
+        return asOfTokenHandlers[sub]();
+      }
+
+      if (sub === 'historical-smart-money-balances') {
+        if (options.sort || options['order-by']) {
+          throw new NansenError(
+            'historical-smart-money-balances does not support --sort or --order-by (endpoint does not support ordering)',
+            ErrorCode.INVALID_PARAMS,
+          );
+        }
+        requireOptions({ 'as-of-date': asOfDate }, ['as-of-date']);
+        return apiInstance.researchSmartMoneyBalances({
+          chains: parseChains(options),
+          asOfDate, filters, pagination,
+        });
+      }
+
+      if (sub === 'historical-token-screener') {
+        const timeframeDays = parseTimeframeDays(options['timeframe-days']);
+        requireOptions({ 'timeframe-days': timeframeDays, 'to-date': options['to-date'] }, ['timeframe-days', 'to-date']);
+        return apiInstance.researchTokenScreener({
+          chains: parseChains(options),
+          timeframeDays,
+          toDate: options['to-date'],
+          filters, orderBy, pagination,
+        });
+      }
+
+      if (sub === 'historical-wallet-balances') {
+        requireOptions(
+          { address: options.address, 'as-of-date': asOfDate },
+          ['address', 'as-of-date'],
+        );
+        return apiInstance.researchWalletBalances({
+          address: options.address,
+          chain: options.chain,
+          asOfDate, filters, orderBy, pagination,
+        });
+      }
+
+      if (sub === 'historical-tx-lookup') {
+        requireOptions(
+          { 'transaction-hash': options['transaction-hash'], 'as-of-date': asOfDate },
+          ['transaction-hash', 'as-of-date'],
+        );
+        return apiInstance.researchTxLookup({
+          txHash: options['transaction-hash'],
+          chain: options.chain,
+          asOfDate,
+          blockTimestamp: options['block-timestamp'],
+        });
+      }
+
+      if (sub === 'historical-wallet-transactions') {
+        requireOptions(
+          { address: options.address, 'as-of-date': asOfDate },
+          ['address', 'as-of-date'],
+        );
+        return apiInstance.researchWalletTransactions({
+          address: options.address,
+          chain: options.chain,
+          asOfDate, filters, orderBy, pagination,
+        });
+      }
+
+      // Should be unreachable because SUBCOMMANDS guarded above.
+      throw new NansenError(`Unknown research subcommand: ${sub}`, ErrorCode.UNKNOWN);
+    },
+  };
+}

package/src/schema.json

@@ -697,6 +697,110 @@
               "description": "Points leaderboard"
             }
           }
+        },
+        "historical-dex-trades": {
+          "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" }
+          }
+        },
+        "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" }
+          }
+        },
+        "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" }
+          }
+        },
+        "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" }
+          }
+        },
+        "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" }
+          }
+        },
+        "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" }
+          }
+        },
+        "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" }
+          }
+        },
+        "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" }
+          }
+        },
+        "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" }
+          }
+        },
+        "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)" }
+          }
+        },
+        "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" }
+          }
         }
       }
     },

package/src/trading.js

@@ -104,6 +104,14 @@ function getQuotesDir() {
   return path.join(configDir, 'quotes');
 }
 
+// Resolve a filename inside the quotes dir, rejecting path traversal.
+function safeQuotesPath(filename) {
+  const base = path.resolve(getQuotesDir());
+  const target = path.resolve(base, filename);
+  if (path.relative(base, target).startsWith('..')) return null;
+  return target;
+}
+
 // ============= Trading API Client =============
 
 /**
@@ -151,6 +159,7 @@ export async function getQuote(params) {
  * @param {object} params
  * @param {string} params.signedTransaction - Base64 (Solana) or 0x hex (EVM)
  * @param {string} [params.chain] - Target chain name
+ * @param {string} [params.quoteId] - Backend quote ID for BI correlation
  * @param {string} [params.requestId] - Optional Jupiter request ID (Solana only)
  * @param {boolean} [params.simulate] - Run pre-broadcast simulation
  * @returns {Promise<object>} Execution result
@@ -337,10 +346,12 @@ const TX_RECORD_TTL_MS = 30 * 24 * 3600 * 1000; // 30 days
  */
 export function saveTxRecord(txHash, { aggregator, requestId, fromChain, toChain }) {
   if (!txHash) return;
-  const dir = getQuotesDir();
+  const filePath = safeQuotesPath(`tx-${txHash}.json`);
+  if (!filePath) return;
+  const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   const data = { txHash, aggregator, requestId, fromChain, toChain, timestamp: Date.now() };
-  fs.writeFileSync(path.join(dir, `tx-${txHash}.json`), JSON.stringify(data, null, 2), { mode: 0o600 });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
 }
 
 /**
@@ -348,7 +359,8 @@ export function saveTxRecord(txHash, { aggregator, requestId, fromChain, toChain
  */
 export function loadTxRecord(txHash) {
   if (!txHash) return null;
-  const filePath = path.join(getQuotesDir(), `tx-${txHash}.json`);
+  const filePath = safeQuotesPath(`tx-${txHash}.json`);
+  if (!filePath) return null;
   if (!fs.existsSync(filePath)) return null;
   try {
     const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -391,8 +403,8 @@ export function saveQuote(quoteResponse, chain, signerType = 'local', privyWalle
  * Load a saved quote by ID.
  */
 export function loadQuote(quoteId) {
-  const filePath = path.join(getQuotesDir(), `${quoteId}.json`);
-  if (!fs.existsSync(filePath)) {
+  const filePath = safeQuotesPath(`${quoteId}.json`);
+  if (!filePath || !fs.existsSync(filePath)) {
     throw new Error(`Quote "${quoteId}" not found. Quotes expire after 1 hour.`);
   }
   const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -2006,12 +2018,20 @@ EXAMPLES:
               chain,
               simulate: !noSimulate && !gasless,
             };
+
+            // Prefer the backend quote id saved from /quote; per-aggregator ids can
+            // appear on individual quote metadata and are only a fallback.
+            const backendQuoteId =
+              quoteData.response?.metadata?.quoteId ?? currentQuote.metadata?.quoteId;
+            if (backendQuoteId) {
+              execParams.quoteId = backendQuoteId;
+            }
             // The backend's /execute schema is strict; sending fields it doesn't expect
             // for the (chain × aggregator × gasless) combination causes 502s or
             // "Unrecognized keys" rejections. The matrix we've validated against the
             // live backend:
-            //   - EVM signed (any aggregator): no extra fields. requestId/aggregator
-            //     trigger schema errors.
+            //   - EVM signed (any aggregator): no aggregator/requestId fields.
+            //     Those trigger schema errors.
             //   - Solana signed (Jupiter/OKX): include requestId for Jupiter Ultra
             //     intent resolution.
             //   - Solana signed (Relay): omit requestId — backend tries to look it up