nansen-cli 1.44.3 → 1.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/cli.js CHANGED
@@ -14,7 +14,7 @@ import { buildAgentCommands } from './commands/agent.js';
14
14
  import { buildMcpCommands } from './commands/mcp.js';
15
15
  import { buildCompletionCommands } from './commands/completion.js';
16
16
  import { buildResearchCommands, RESEARCH_HISTORICAL_SUBCOMMANDS, RESEARCH_SUBCOMMANDS } from './commands/research.js';
17
- import { buildPagination, parseSort } from './query-options.js';
17
+ import { buildPagination, parseSort, parseCsvOption, rejectBlankOption } from './query-options.js';
18
18
  export { buildPagination, parseSort };
19
19
  import { resolveAddress, isEnsName } from './ens.js';
20
20
  import { compareSemver } from './semver.js';
@@ -114,7 +114,10 @@ export function filterFields(data, fields) {
114
114
  * Parse comma-separated fields string
115
115
  */
116
116
  export function parseFields(fieldsOption) {
117
- if (!fieldsOption) return null;
117
+ if (fieldsOption === undefined || fieldsOption === '') return null;
118
+ if (typeof fieldsOption !== 'string') {
119
+ throw new NansenError('--fields must be a comma-separated string', ErrorCode.INVALID_PARAMS);
120
+ }
118
121
  return fieldsOption.split(',').map(f => f.trim()).filter(f => f.length > 0);
119
122
  }
120
123
 
@@ -171,7 +174,7 @@ export const VALUELESS_FLAGS = new Set([
171
174
  'pretty', 'help', 'version', 'table', 'no-retry', 'cache', 'no-cache', 'stream',
172
175
  'enrich', 'full', 'human', 'enabled', 'disabled', 'expert', 'json', 'offline',
173
176
  'no-simulate', 'no-verify-outcome', 'no-revoke-excessive-allowance', 'dry-run',
174
- 'send-api-key',
177
+ 'send-api-key', 'all', 'max', 'gasless', 'auto-slippage', 'unsafe-no-password',
175
178
  ]);
176
179
 
177
180
  export function parseArgs(args) {
@@ -186,7 +189,10 @@ export function parseArgs(args) {
186
189
 
187
190
  if (VALUELESS_FLAGS.has(key)) {
188
191
  result.flags[key] = true;
189
- } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
192
+ // `next !== undefined` rather than a truthiness check: an explicit empty
193
+ // string is a real value, and skipping it here left `""` dangling to be
194
+ // picked up as a positional arg on the next iteration.
195
+ } else if (next !== undefined && (!next.startsWith('-') || /^-\d/.test(next))) {
190
196
  // Try to parse as JSON first (for objects/arrays/booleans),
191
197
  // but keep numeric strings as strings to avoid precision loss
192
198
  // and scientific notation for large integers (e.g. 1e+21).
@@ -220,15 +226,65 @@ export function parseArgs(args) {
220
226
  return result;
221
227
  }
222
228
 
223
- function parseNonNegativeSafeIntegerOption(name, options, flags, defaultValue) {
229
+ function parseSafeIntegerOption(
230
+ name,
231
+ options,
232
+ flags,
233
+ defaultValue,
234
+ requirement = 'safe integer',
235
+ ) {
224
236
  if (flags[name]) {
225
237
  throw new NansenError(
226
- `--${name} requires a non-negative safe integer value`,
238
+ `--${name} requires a ${requirement} value`,
227
239
  ErrorCode.INVALID_PARAMS,
228
240
  );
229
241
  }
242
+
230
243
  if (options[name] === undefined) return defaultValue;
231
244
 
245
+ const rawValue = options[name];
246
+
247
+ if (Array.isArray(rawValue)) {
248
+ throw new NansenError(
249
+ `--${name} may only be specified once`,
250
+ ErrorCode.INVALID_PARAMS,
251
+ );
252
+ }
253
+
254
+ if (
255
+ typeof rawValue === 'boolean' ||
256
+ (typeof rawValue === 'string' && rawValue.trim() === '')
257
+ ) {
258
+ throw new NansenError(
259
+ `--${name} requires a ${requirement} value`,
260
+ ErrorCode.INVALID_PARAMS,
261
+ );
262
+ }
263
+
264
+ const value =
265
+ typeof rawValue === 'string' || typeof rawValue === 'number'
266
+ ? Number(rawValue)
267
+ : NaN;
268
+
269
+ if (!Number.isSafeInteger(value)) {
270
+ throw new NansenError(
271
+ `--${name} must be a ${requirement}; received: ${String(rawValue)}`,
272
+ ErrorCode.INVALID_PARAMS,
273
+ );
274
+ }
275
+
276
+ return value;
277
+ }
278
+
279
+ function parseFiniteNumberOption(name, options, flags) {
280
+ if (flags[name]) {
281
+ throw new NansenError(
282
+ `--${name} requires a finite number`,
283
+ ErrorCode.INVALID_PARAMS,
284
+ );
285
+ }
286
+ if (options[name] === undefined) return undefined;
287
+
232
288
  const rawValue = options[name];
233
289
  if (Array.isArray(rawValue)) {
234
290
  throw new NansenError(
@@ -238,22 +294,56 @@ function parseNonNegativeSafeIntegerOption(name, options, flags, defaultValue) {
238
294
  }
239
295
  if (typeof rawValue === 'string' && rawValue.trim() === '') {
240
296
  throw new NansenError(
241
- `--${name} requires a non-negative safe integer value`,
297
+ `--${name} requires a finite number`,
242
298
  ErrorCode.INVALID_PARAMS,
243
299
  );
244
300
  }
245
301
  const value = typeof rawValue === 'string' || typeof rawValue === 'number'
246
302
  ? Number(rawValue)
247
303
  : NaN;
248
- if (!Number.isSafeInteger(value) || value < 0) {
304
+ if (!Number.isFinite(value)) {
249
305
  throw new NansenError(
250
- `--${name} must be a non-negative safe integer; received: ${String(rawValue)}`,
306
+ `--${name} must be a finite number; received: ${String(rawValue)}`,
251
307
  ErrorCode.INVALID_PARAMS,
252
308
  );
253
309
  }
254
310
  return value;
255
311
  }
256
312
 
313
+ function parseNonNegativeSafeIntegerOption(name, options, flags, defaultValue) {
314
+ const value = parseSafeIntegerOption(
315
+ name,
316
+ options,
317
+ flags,
318
+ defaultValue,
319
+ 'non-negative safe integer',
320
+ );
321
+
322
+ if (value < 0) {
323
+ throw new NansenError(
324
+ `--${name} must be a non-negative safe integer; received: ${value}`,
325
+ ErrorCode.INVALID_PARAMS,
326
+ );
327
+ }
328
+
329
+ return value;
330
+ }
331
+
332
+
333
+ function parseDaysOption(options, flags) {
334
+ const days = parseNonNegativeSafeIntegerOption('days', options, flags, 30);
335
+ // Safe integers can still exceed JavaScript Date's representable range.
336
+ // Anchor the overflow check to the Unix epoch so the boundary is deterministic.
337
+ const fromMs = 0 - days * 24 * 60 * 60 * 1000;
338
+ if (Number.isNaN(new Date(fromMs).getTime())) {
339
+ throw new NansenError(
340
+ `--days is outside the supported date range; received: ${days}`,
341
+ ErrorCode.INVALID_PARAMS,
342
+ );
343
+ }
344
+ return days;
345
+ }
346
+
257
347
  // Format a single value for table display
258
348
  export function formatValue(val) {
259
349
  if (val === null || val === undefined) return '';
@@ -293,7 +383,7 @@ export function formatTable(data) {
293
383
  }
294
384
 
295
385
  // Get columns from first record, prioritize common useful fields
296
- const priorityFields = ['token_symbol', 'token_name', 'symbol', 'name', 'address', 'label', 'chain', 'value_usd', 'amount', 'pnl_usd', 'price_usd', 'volume_usd', 'net_flow_usd', 'timestamp', 'block_timestamp'];
386
+ const priorityFields = ['token_symbol', 'token_name', 'symbol', 'name', 'wallet_address', 'address', 'label', 'chain', 'value_usd', 'amount', 'pnl_usd', 'price_usd', 'volume_usd', 'net_flow_usd', 'timestamp', 'block_timestamp'];
297
387
  const allKeys = [...new Set(records.flatMap(r => Object.keys(r)))];
298
388
 
299
389
  // Sort: priority fields first, then alphabetically
@@ -468,23 +558,51 @@ export function formatStream(data) {
468
558
  * or already-parsed object {from, to}.
469
559
  * Falls back to days-based range if no date provided.
470
560
  */
471
- export function parseDateOption(dateOption, days = 30) {
472
- if (dateOption) {
473
- if (typeof dateOption === 'object' && dateOption.from) {
474
- return dateOption;
561
+ function isValidDateOnly(value) {
562
+ if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
563
+ const parsed = new Date(`${value}T00:00:00.000Z`);
564
+ return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
565
+ }
566
+
567
+ export function parseDateOption(dateOption, days = 30, valuelessDateFlag = false) {
568
+ if (valuelessDateFlag) {
569
+ throw new NansenError(
570
+ '--date requires a value in YYYY-MM-DD format or a JSON date range',
571
+ ErrorCode.INVALID_PARAMS,
572
+ );
573
+ }
574
+
575
+ if (dateOption === undefined) {
576
+ // Default: use days-based range only when --date was not supplied.
577
+ const to = new Date().toISOString().split('T')[0];
578
+ const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
579
+ return { from, to };
580
+ }
581
+
582
+ let parsedOption = dateOption;
583
+ if (typeof parsedOption === 'string' && !isValidDateOnly(parsedOption)) {
584
+ try {
585
+ parsedOption = JSON.parse(parsedOption);
586
+ } catch {
587
+ // Keep the original value so the actionable validation error below is used.
475
588
  }
476
- if (typeof dateOption === 'string') {
477
- // Simple date string: use as both from and to
478
- const dateMatch = dateOption.match(/^\d{4}-\d{2}-\d{2}$/);
479
- if (dateMatch) {
480
- return { from: dateOption, to: dateOption };
481
- }
589
+ }
590
+
591
+ if (typeof parsedOption === 'string' && isValidDateOnly(parsedOption)) {
592
+ return { from: parsedOption, to: parsedOption };
593
+ }
594
+
595
+ if (parsedOption && typeof parsedOption === 'object' && !Array.isArray(parsedOption)) {
596
+ const { from, to } = parsedOption;
597
+ if (isValidDateOnly(from) && (to === undefined || isValidDateOnly(to))) {
598
+ return { from, to: to ?? from };
482
599
  }
483
600
  }
484
- // Default: use days-based range
485
- const to = new Date().toISOString().split('T')[0];
486
- const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
487
- return { from, to };
601
+
602
+ throw new NansenError(
603
+ '--date must be YYYY-MM-DD or a JSON object with a valid "from" date and optional "to" date',
604
+ ErrorCode.INVALID_PARAMS,
605
+ );
488
606
  }
489
607
 
490
608
  // Enrich transfers with Nansen labels for from/to addresses
@@ -553,6 +671,35 @@ export function parseAddressList(raw) {
553
671
  }
554
672
  }
555
673
 
674
+ /**
675
+ * Read an address list from a file: either a JSON array of address strings or
676
+ * one address per line. Shared by the profiler commands that accept --file.
677
+ */
678
+ function readAddressFile(file) {
679
+ let content;
680
+ try {
681
+ content = fs.readFileSync(file, 'utf8');
682
+ } catch (err) {
683
+ throw new NansenError(
684
+ `Could not read --file ${file}: ${err.code === 'ENOENT' ? 'no such file' : err.message}`,
685
+ ErrorCode.INVALID_PARAMS
686
+ );
687
+ }
688
+ try {
689
+ const parsed = JSON.parse(content);
690
+ if (!Array.isArray(parsed) || !parsed.every(item => typeof item === 'string')) {
691
+ throw new NansenError(
692
+ 'File must contain a JSON array of address strings or one address per line',
693
+ ErrorCode.INVALID_PARAMS
694
+ );
695
+ }
696
+ return parsed.map(a => a.trim()).filter(Boolean);
697
+ } catch (e) {
698
+ if (e instanceof NansenError) throw e;
699
+ return content.split('\n').map(a => a.trim()).filter(Boolean);
700
+ }
701
+ }
702
+
556
703
  // ============= Composite Functions =============
557
704
 
558
705
  export async function batchProfile(api, params = {}) {
@@ -606,6 +753,17 @@ export async function batchProfile(api, params = {}) {
606
753
  return { results, total: addresses.length, completed: results.filter(r => !r.error).length };
607
754
  }
608
755
 
756
+ function normalizeTraceDepth(raw) {
757
+ const value = parseSafeIntegerOption(
758
+ 'depth',
759
+ { depth: raw },
760
+ {},
761
+ 2,
762
+ );
763
+
764
+ return Math.max(1, Math.min(value, 5));
765
+ }
766
+
609
767
  export async function traceCounterparties(api, params = {}) {
610
768
  let { address, chain = 'ethereum', depth = 2, width = 10, days = 30, delayMs = 1000 } = params;
611
769
  if (!address) {
@@ -626,7 +784,7 @@ export async function traceCounterparties(api, params = {}) {
626
784
  if (!validation.valid) {
627
785
  throw new NansenError(validation.error, ErrorCode.INVALID_ADDRESS);
628
786
  }
629
- const clampedDepth = Math.max(1, Math.min(depth, 5));
787
+ const clampedDepth = normalizeTraceDepth(depth);
630
788
  const visited = new Set();
631
789
  const nodes = [];
632
790
  const edges = [];
@@ -745,7 +903,7 @@ COMMANDS:
745
903
  trade DEX swaps/bridges: quote, execute, bridge-status, limit-order
746
904
  bridge Hyperliquid bridge: quote, execute, status (EVM <-> HL)
747
905
  perp Hyperliquid perps: order, cancel, close, leverage, positions
748
- research analytics: smart-money, profiler, token, search, perp, portfolio, points
906
+ research analytics: smart-money, profiler, token, search, perp, portfolio
749
907
  wallet create, list, show, export, default, delete, forget-password
750
908
  agent Ask the Nansen AI research agent (fast/expert modes)
751
909
  alerts list, create, update, toggle, delete
@@ -786,7 +944,7 @@ EXAMPLES:
786
944
  nansen research profiler balance --address 0x... --chain ethereum
787
945
 
788
946
  DEPRECATED ALIASES (still work, will be removed in a future version):
789
- smart-money, profiler, token, search, perp, portfolio, points → use "nansen research <command>"
947
+ smart-money, profiler, token, search, perp, portfolio → use "nansen research <command>"
790
948
  quote, execute → use "nansen trade <command>"
791
949
 
792
950
  Research chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
@@ -948,8 +1106,14 @@ export function buildCommands(deps = {}) {
948
1106
  'search': async () => {
949
1107
  // Accept queries as positional args or --query (repeated)
950
1108
  let queries = subArgs.length > 0 ? subArgs : [];
951
- if (options.query) {
1109
+ if (options.query !== undefined) {
952
1110
  const fromOption = Array.isArray(options.query) ? options.query : [options.query];
1111
+ if (!fromOption.every(q => typeof q === 'string')) {
1112
+ throw new NansenError(
1113
+ '--query values must be strings',
1114
+ ErrorCode.INVALID_PARAMS,
1115
+ );
1116
+ }
953
1117
  queries = queries.concat(fromOption);
954
1118
  }
955
1119
  queries = queries.filter(q => q.trim());
@@ -974,7 +1138,7 @@ export function buildCommands(deps = {}) {
974
1138
  'fetch': async () => {
975
1139
  // Accept URLs as positional args or --url (repeated)
976
1140
  let urls = subArgs.length > 0 ? subArgs : [];
977
- if (options.url) {
1141
+ if (options.url !== undefined) {
978
1142
  const fromOption = Array.isArray(options.url) ? options.url : [options.url];
979
1143
  urls = urls.concat(fromOption);
980
1144
  }
@@ -986,6 +1150,12 @@ export function buildCommands(deps = {}) {
986
1150
  throw new NansenError(`Invalid URL: "${u}". URLs must include a scheme, e.g. https://example.com`, ErrorCode.INVALID_PARAMS);
987
1151
  }
988
1152
  }
1153
+ if (Array.isArray(options.question)) {
1154
+ throw new NansenError('--question may only be specified once', ErrorCode.INVALID_PARAMS);
1155
+ }
1156
+ if (options.question !== undefined && typeof options.question !== 'string') {
1157
+ throw new NansenError('--question must be a string', ErrorCode.INVALID_PARAMS);
1158
+ }
989
1159
  if (!options.question || !options.question.trim()) {
990
1160
  throw new NansenError('--question is required and cannot be blank. Usage: nansen web fetch https://example.com --question "What is this about?"', ErrorCode.MISSING_PARAM);
991
1161
  }
@@ -1228,6 +1398,9 @@ export function buildCommands(deps = {}) {
1228
1398
  },
1229
1399
 
1230
1400
  'smart-money': async (args, apiInstance, flags, options) => {
1401
+ rejectBlankOption(options.days, 'days', '30');
1402
+ rejectBlankOption(options.chain, 'chain', 'solana');
1403
+ rejectBlankOption(options.chains, 'chains', 'solana');
1231
1404
  const subcommand = args[0] || 'help';
1232
1405
  const chain = options.chain || 'solana';
1233
1406
  const chains = options.chains || [chain];
@@ -1242,7 +1415,9 @@ export function buildCommands(deps = {}) {
1242
1415
  : [options.labels];
1243
1416
  }
1244
1417
 
1245
- const days = options.days ? parseInt(options.days) : 30;
1418
+ const days = subcommand === 'historical-holdings'
1419
+ ? parseDaysOption(options, flags)
1420
+ : 30;
1246
1421
 
1247
1422
  const handlers = {
1248
1423
  'netflow': () => apiInstance.smartMoneyNetflow({ chains, filters, orderBy, pagination }),
@@ -1266,6 +1441,8 @@ export function buildCommands(deps = {}) {
1266
1441
  },
1267
1442
 
1268
1443
  'profiler': async (args, apiInstance, flags, options) => {
1444
+ rejectBlankOption(options.days, 'days', '30');
1445
+ rejectBlankOption(options.chain, 'chain', 'ethereum');
1269
1446
  const subcommand = args[0] || 'help';
1270
1447
  let address = options.address;
1271
1448
  const entityName = options.entity || options['entity-name'];
@@ -1286,17 +1463,30 @@ export function buildCommands(deps = {}) {
1286
1463
  const filters = options.filters || {};
1287
1464
  const orderBy = parseSort(options.sort, options['order-by']);
1288
1465
  const pagination = buildPagination(options);
1289
- const days = options.days ? parseInt(options.days) : 30;
1466
+ const days = [
1467
+ 'transactions',
1468
+ 'pnl',
1469
+ 'historical-balances',
1470
+ 'counterparties',
1471
+ 'counterparties-batch',
1472
+ 'pnl-summary',
1473
+ 'perp-trades',
1474
+ 'dex-trades',
1475
+ 'trace',
1476
+ 'compare',
1477
+ ].includes(subcommand)
1478
+ ? parseDaysOption(options, flags)
1479
+ : 30;
1290
1480
 
1291
1481
  const handlers = {
1292
1482
  'balance': () => apiInstance.addressBalance({ address, entityName, chain, filters, orderBy }),
1293
1483
  'labels': () => apiInstance.addressLabels({ address, chain, pagination }),
1294
1484
  'transactions': () => {
1295
- const date = parseDateOption(options.date, days);
1485
+ const date = parseDateOption(options.date, days, flags.date);
1296
1486
  return apiInstance.addressTransactions({ address, chain, filters, orderBy, pagination, days, date });
1297
1487
  },
1298
1488
  'pnl': () => {
1299
- const date = parseDateOption(options.date, days);
1489
+ const date = parseDateOption(options.date, days, flags.date);
1300
1490
  return apiInstance.addressPnl({ address, chain, date, days, filters, orderBy, pagination });
1301
1491
  },
1302
1492
  'search': () => apiInstance.entitySearch({ query: options.query }),
@@ -1304,43 +1494,46 @@ export function buildCommands(deps = {}) {
1304
1494
  'related-wallets': () => apiInstance.addressRelatedWallets({ address, chain, orderBy, pagination }),
1305
1495
  'first-funder': () => apiInstance.addressFirstFunder({ address }),
1306
1496
  'counterparties': () => apiInstance.addressCounterparties({ address, chain, filters, orderBy, pagination, days }),
1497
+ 'counterparties-batch': () => {
1498
+ const addresses = options.addresses
1499
+ ? parseAddressList(options.addresses)
1500
+ : (options.file ? readAddressFile(options.file) : []);
1501
+ return apiInstance.addressCounterpartiesBatch({ addresses, chain, filters, orderBy, pagination, days });
1502
+ },
1307
1503
  'pnl-summary': () => apiInstance.addressPnlSummary({ address, chain, orderBy, pagination, days }),
1308
1504
  'perp-positions': () => apiInstance.addressPerpPositions({ address, filters, orderBy, pagination }),
1309
1505
  'perp-trades': () => apiInstance.addressPerpTrades({ address, filters, orderBy, pagination, days }),
1310
1506
  'dex-trades': () => {
1311
- const date = parseDateOption(options.date, days);
1507
+ const date = parseDateOption(options.date, days, flags.date);
1312
1508
  return apiInstance.addressDexTrades({ address, chain, filters, orderBy, pagination, days, date });
1313
1509
  },
1314
1510
  'batch': () => {
1511
+ rejectBlankOption(options.delay, 'delay', '1000');
1315
1512
  let addresses = [];
1316
1513
  if (options.addresses) {
1317
1514
  addresses = parseAddressList(options.addresses);
1318
1515
  } else if (options.file) {
1319
- const content = fs.readFileSync(options.file, 'utf8');
1320
- try {
1321
- const parsed = JSON.parse(content);
1322
- if (!Array.isArray(parsed)) {
1323
- throw new NansenError('File must contain a JSON array of address strings or one address per line', ErrorCode.INVALID_PARAMS);
1324
- }
1325
- if (!parsed.every(item => typeof item === 'string')) {
1326
- throw new NansenError('File must contain a JSON array of address strings or one address per line', ErrorCode.INVALID_PARAMS);
1327
- }
1328
- addresses = parsed.map(a => a.trim()).filter(Boolean);
1329
- } catch (e) {
1330
- if (e instanceof NansenError) throw e;
1331
- addresses = content.split('\n').map(a => a.trim()).filter(Boolean);
1332
- }
1516
+ addresses = readAddressFile(options.file);
1333
1517
  }
1334
1518
  if (addresses.length > 100) {
1335
1519
  throw new NansenError('Batch is limited to 100 addresses', ErrorCode.INVALID_PARAMS);
1336
1520
  }
1337
- const include = options.include ? options.include.split(',').map(s => s.trim()) : ['labels', 'balance'];
1521
+ const parsedInclude = parseCsvOption(options.include, 'include');
1522
+ const include = (parsedInclude && parsedInclude.length > 0) ? parsedInclude : ['labels', 'balance'];
1338
1523
  const delayMs = options.delay ? parseInt(options.delay) : 1000;
1339
1524
  return batchProfile(apiInstance, { addresses, chain, include, delayMs });
1340
1525
  },
1341
1526
  'trace': () => {
1342
- const depth = options.depth ? Math.max(1, Math.min(parseInt(options.depth), 5)) : 2;
1343
- const width = options.width ? parseInt(options.width) : 10;
1527
+ rejectBlankOption(options.delay, 'delay', '1000');
1528
+ rejectBlankOption(options.depth, 'depth', '2');
1529
+ if (flags.depth) {
1530
+ throw new NansenError(
1531
+ '--depth requires a safe integer value',
1532
+ ErrorCode.INVALID_PARAMS,
1533
+ );
1534
+ }
1535
+ const depth = options.depth ?? 2;
1536
+ const width = parseNonNegativeSafeIntegerOption('width', options, flags, 10);
1344
1537
  const delayMs = options.delay ? parseInt(options.delay) : 1000;
1345
1538
  return traceCounterparties(apiInstance, { address, chain, depth, width, days, delayMs });
1346
1539
  },
@@ -1349,7 +1542,7 @@ export function buildCommands(deps = {}) {
1349
1542
  return compareWallets(apiInstance, { addresses: addrs, chain, days });
1350
1543
  },
1351
1544
  'help': () => ({
1352
- commands: ['balance', 'labels', 'transactions', 'pnl', 'search', 'historical-balances', 'related-wallets', 'first-funder', 'counterparties', 'pnl-summary', 'perp-positions', 'perp-trades', 'dex-trades', 'batch', 'trace', 'compare'],
1545
+ commands: ['balance', 'labels', 'transactions', 'pnl', 'search', 'historical-balances', 'related-wallets', 'first-funder', 'counterparties', 'counterparties-batch', 'pnl-summary', 'perp-positions', 'perp-trades', 'dex-trades', 'batch', 'trace', 'compare'],
1353
1546
  description: 'Wallet profiling endpoints',
1354
1547
  example: 'nansen research profiler compare --addresses "0xABC...,0xDEF..." --chain ethereum'
1355
1548
  })
@@ -1368,6 +1561,11 @@ export function buildCommands(deps = {}) {
1368
1561
  },
1369
1562
 
1370
1563
  'token': async (args, apiInstance, flags, options) => {
1564
+ rejectBlankOption(options.days, 'days', '30');
1565
+ rejectBlankOption(options.chain, 'chain', 'solana');
1566
+ rejectBlankOption(options.chains, 'chains', 'solana');
1567
+ rejectBlankOption(options.timeframe, 'timeframe', '1d');
1568
+ rejectBlankOption(options['buy-or-sell'], 'buy-or-sell', 'SELL');
1371
1569
  const subcommand = args[0] || 'help';
1372
1570
  const chain = options.chain || 'solana';
1373
1571
  const tokenAddress = normalizeAddress(options.token || options['token-address'], chain);
@@ -1377,7 +1575,17 @@ export function buildCommands(deps = {}) {
1377
1575
  const filters = options.filters || {};
1378
1576
  const orderBy = parseSort(options.sort, options['order-by']);
1379
1577
  const pagination = buildPagination(options);
1380
- const days = options.days ? parseInt(options.days) : 30;
1578
+ const days = [
1579
+ 'flows',
1580
+ 'dex-trades',
1581
+ 'pnl',
1582
+ 'who-bought-sold',
1583
+ 'transfers',
1584
+ 'perp-trades',
1585
+ 'perp-pnl-leaderboard',
1586
+ ].includes(subcommand)
1587
+ ? parseDaysOption(options, flags)
1588
+ : 30;
1381
1589
 
1382
1590
  // Convenience filter for smart money only
1383
1591
  const onlySmartMoney = options['smart-money'] || flags['smart-money'] || false;
@@ -1421,7 +1629,7 @@ export function buildCommands(deps = {}) {
1421
1629
  },
1422
1630
  'holders': () => apiInstance.tokenHolders({ tokenAddress, chain, labelType: onlySmartMoney ? 'smart_money' : 'all_holders', filters, orderBy, pagination, withLabels: resolveBooleanOption(options, flags, 'premium-labels') }),
1423
1631
  'flows': () => {
1424
- const date = parseDateOption(options.date, days);
1632
+ const date = parseDateOption(options.date, days, flags.date);
1425
1633
  const label = options.label;
1426
1634
  return apiInstance.tokenFlows({ tokenAddress, chain, label, filters, orderBy, pagination, days, date });
1427
1635
  },
@@ -1431,7 +1639,7 @@ export function buildCommands(deps = {}) {
1431
1639
  return apiInstance.tokenPnlLeaderboard({ tokenAddress, chain, filters, orderBy, pagination, days, withLabels });
1432
1640
  },
1433
1641
  'who-bought-sold': () => {
1434
- const date = parseDateOption(options.date, days);
1642
+ const date = parseDateOption(options.date, days, flags.date);
1435
1643
  const buyOrSell = (options['buy-or-sell'] || 'BUY').toUpperCase();
1436
1644
  return apiInstance.tokenWhoBoughtSold({ tokenAddress, chain, buyOrSell, filters, orderBy, pagination, days, date });
1437
1645
  },
@@ -1519,24 +1727,21 @@ export function buildCommands(deps = {}) {
1519
1727
  },
1520
1728
 
1521
1729
  'perp': async (args, apiInstance, flags, options) => {
1730
+ rejectBlankOption(options.days, 'days', '30');
1522
1731
  const subcommand = args[0] || 'help';
1523
1732
  const filters = options.filters || {};
1524
1733
  const orderBy = parseSort(options.sort, options['order-by']);
1525
1734
  const pagination = buildPagination(options);
1526
- const days = options.days ? parseInt(options.days) : 30;
1735
+ const days = ['screener', 'leaderboard'].includes(subcommand)
1736
+ ? parseDaysOption(options, flags)
1737
+ : 30;
1527
1738
 
1528
1739
  const handlers = {
1529
1740
  'screener': () => {
1530
1741
  const traderType = options['trader-type'];
1531
- const sectorsFilter = options['sectors-filter']
1532
- ? options['sectors-filter'].split(',').map(s => s.trim()).filter(Boolean)
1533
- : undefined;
1534
- const smLabelFilter = options['sm-label-filter']
1535
- ? options['sm-label-filter'].split(',').map(s => s.trim()).filter(Boolean)
1536
- : undefined;
1537
- const traderLabelFilter = options['trader-label-filter']
1538
- ? options['trader-label-filter'].split(',').map(s => s.trim()).filter(Boolean)
1539
- : undefined;
1742
+ const sectorsFilter = parseCsvOption(options['sectors-filter'], 'sectors-filter');
1743
+ const smLabelFilter = parseCsvOption(options['sm-label-filter'], 'sm-label-filter');
1744
+ const traderLabelFilter = parseCsvOption(options['trader-label-filter'], 'trader-label-filter');
1540
1745
  return apiInstance.perpScreener({ filters, orderBy, pagination, days, traderType, sectorsFilter, smLabelFilter, traderLabelFilter });
1541
1746
  },
1542
1747
  'leaderboard': () => {
@@ -1558,6 +1763,7 @@ export function buildCommands(deps = {}) {
1558
1763
  },
1559
1764
 
1560
1765
  'search': async (args, apiInstance, flags, options) => {
1766
+ rejectBlankOption(options.chain, 'chain', 'solana');
1561
1767
  return apiInstance.generalSearch({
1562
1768
  query: args[0] || options.query,
1563
1769
  resultType: options.type,
@@ -1566,25 +1772,8 @@ export function buildCommands(deps = {}) {
1566
1772
  });
1567
1773
  },
1568
1774
 
1569
- 'points': async (args, apiInstance, flags, options) => {
1570
- const subcommand = args[0] || 'help';
1571
- const tier = options.tier;
1572
- const pagination = buildPagination(options);
1573
-
1574
- const handlers = {
1575
- 'leaderboard': () => apiInstance.pointsLeaderboard({ tier, pagination }),
1576
- 'help': () => ({
1577
- commands: ['leaderboard'],
1578
- description: 'Nansen Points analytics endpoints',
1579
- example: 'nansen points leaderboard --limit 100'
1580
- })
1581
- };
1582
-
1583
- if (!handlers[subcommand]) {
1584
- return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
1585
- }
1586
-
1587
- return handlers[subcommand]();
1775
+ 'points': async () => {
1776
+ throw new CommandError('The points leaderboard endpoint has been removed. Run "nansen research" to explore other analytics commands.', 'COMMAND_UNAVAILABLE');
1588
1777
  },
1589
1778
 
1590
1779
  'prediction-market': async (args, apiInstance, flags, options) => {
@@ -1601,20 +1790,21 @@ export function buildCommands(deps = {}) {
1601
1790
  const pagination = buildPagination(options);
1602
1791
 
1603
1792
  // Screener-specific filter options
1604
- const tags = options.tags ? options.tags.split(',').map(t => t.trim()) : undefined;
1605
- const minLiquidity = options['min-liquidity'] != null ? Number(options['min-liquidity']) : undefined;
1606
- const maxLiquidity = options['max-liquidity'] != null ? Number(options['max-liquidity']) : undefined;
1607
- const minUniqueTraders24h = options['min-unique-traders-24h'] != null ? Number(options['min-unique-traders-24h']) : undefined;
1608
- const maxUniqueTraders24h = options['max-unique-traders-24h'] != null ? Number(options['max-unique-traders-24h']) : undefined;
1609
- const minVolume24hr = options['min-volume-24hr'] != null ? Number(options['min-volume-24hr']) : undefined;
1610
- const maxVolume24hr = options['max-volume-24hr'] != null ? Number(options['max-volume-24hr']) : undefined;
1793
+ const isScreener = subcommand === 'market-screener' || subcommand === 'event-screener';
1794
+ const tags = parseCsvOption(options.tags, 'tags');
1795
+ const minLiquidity = isScreener ? parseFiniteNumberOption('min-liquidity', options, flags) : undefined;
1796
+ const maxLiquidity = isScreener ? parseFiniteNumberOption('max-liquidity', options, flags) : undefined;
1797
+ const minUniqueTraders24h = isScreener ? parseFiniteNumberOption('min-unique-traders-24h', options, flags) : undefined;
1798
+ const maxUniqueTraders24h = isScreener ? parseFiniteNumberOption('max-unique-traders-24h', options, flags) : undefined;
1799
+ const minVolume24hr = isScreener ? parseFiniteNumberOption('min-volume-24hr', options, flags) : undefined;
1800
+ const maxVolume24hr = isScreener ? parseFiniteNumberOption('max-volume-24hr', options, flags) : undefined;
1611
1801
  const negRisk = resolveBooleanOption(options, flags, 'neg-risk');
1612
- const minOpenInterest = options['min-open-interest'] != null ? Number(options['min-open-interest']) : undefined;
1613
- const maxOpenInterest = options['max-open-interest'] != null ? Number(options['max-open-interest']) : undefined;
1802
+ const minOpenInterest = isScreener ? parseFiniteNumberOption('min-open-interest', options, flags) : undefined;
1803
+ const maxOpenInterest = isScreener ? parseFiniteNumberOption('max-open-interest', options, flags) : undefined;
1614
1804
  const endDateBefore = options['end-date-before'];
1615
1805
  const endDateAfter = options['end-date-after'];
1616
- const minPrice = options['min-price'] != null ? Number(options['min-price']) : undefined;
1617
- const maxPrice = options['max-price'] != null ? Number(options['max-price']) : undefined;
1806
+ const minPrice = subcommand === 'market-screener' ? parseFiniteNumberOption('min-price', options, flags) : undefined;
1807
+ const maxPrice = subcommand === 'market-screener' ? parseFiniteNumberOption('max-price', options, flags) : undefined;
1618
1808
 
1619
1809
  const handlers = {
1620
1810
  'ohlcv': () => apiInstance.pmOhlcv({ marketId, orderBy, pagination }),
@@ -1797,7 +1987,7 @@ USAGE:
1797
1987
  }
1798
1988
 
1799
1989
  // Categories that moved under 'research'
1800
- export const DEPRECATED_TO_RESEARCH = new Set(['smart-money', 'profiler', 'token', 'search', 'portfolio', 'points']);
1990
+ export const DEPRECATED_TO_RESEARCH = new Set(['smart-money', 'profiler', 'token', 'search', 'portfolio']);
1801
1991
  // Subcommands that moved under 'trade'
1802
1992
  export const DEPRECATED_TO_TRADE = new Set(['quote', 'execute']);
1803
1993