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/CHANGELOG.md +48 -0
- package/README.md +4 -1
- package/package.json +1 -1
- package/skills/nansen-wallet-clustering/REFERENCE.md +14 -2
- package/skills/nansen-wallet-clustering/SKILL.md +5 -0
- package/skills/nansen-wallet-profiler/SKILL.md +12 -0
- package/src/api.js +168 -11
- package/src/cli.js +286 -96
- package/src/commands/alerts.js +53 -43
- package/src/commands/mcp.js +6 -0
- package/src/commands/research.js +9 -2
- package/src/cost-cache.js +9 -1
- package/src/limit-order.js +10 -0
- package/src/query-options.js +30 -1
- package/src/schema.json +103 -35
- package/src/trading.js +19 -2
- package/src/update-check.js +9 -3
- package/src/wallet.js +4 -0
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 (
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
304
|
+
if (!Number.isFinite(value)) {
|
|
249
305
|
throw new NansenError(
|
|
250
|
-
`--${name} must be a
|
|
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
|
-
|
|
472
|
-
if (
|
|
473
|
-
|
|
474
|
-
|
|
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
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
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
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
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 =
|
|
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
|
|
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
|
|
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 =
|
|
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 =
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
1343
|
-
|
|
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 =
|
|
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 =
|
|
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
|
-
|
|
1533
|
-
|
|
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 (
|
|
1570
|
-
|
|
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
|
|
1605
|
-
const
|
|
1606
|
-
const
|
|
1607
|
-
const
|
|
1608
|
-
const
|
|
1609
|
-
const
|
|
1610
|
-
const
|
|
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 =
|
|
1613
|
-
const maxOpenInterest =
|
|
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 =
|
|
1617
|
-
const maxPrice =
|
|
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'
|
|
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
|
|