nansen-cli 2.3.0 → 2.5.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.
Files changed (80) hide show
  1. package/CHANGELOG.md +112 -0
  2. package/README.md +61 -38
  3. package/docs/auth.md +56 -0
  4. package/docs/browser-login.md +101 -7
  5. package/docs/error-codes.md +251 -0
  6. package/package.json +10 -4
  7. package/skills/nansen-agent-guide/SKILL.md +20 -4
  8. package/skills/nansen-alerts-webhook-listener/SKILL.md +17 -14
  9. package/skills/nansen-dca-tracker/SKILL.md +1 -1
  10. package/skills/nansen-defi-positions/SKILL.md +1 -1
  11. package/skills/nansen-exit-signals/SKILL.md +2 -2
  12. package/skills/nansen-fund-tracker/SKILL.md +1 -1
  13. package/skills/nansen-general-search/SKILL.md +1 -1
  14. package/skills/nansen-holder-analysis/SKILL.md +2 -2
  15. package/skills/nansen-limit-orders/SKILL.md +9 -1
  16. package/skills/nansen-mpp-payment/SKILL.md +2 -2
  17. package/skills/nansen-perp-screener/SKILL.md +1 -1
  18. package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
  19. package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
  20. package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
  21. package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
  22. package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
  23. package/skills/nansen-prediction-markets/SKILL.md +1 -1
  24. package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
  25. package/skills/nansen-smart-alerts/SKILL.md +5 -2
  26. package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
  27. package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
  28. package/skills/nansen-smart-money-trend/SKILL.md +1 -1
  29. package/skills/nansen-token-research/SKILL.md +1 -1
  30. package/skills/nansen-token-screener/SKILL.md +1 -1
  31. package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
  32. package/skills/nansen-trading/SKILL.md +23 -2
  33. package/skills/nansen-wallet-batch/SKILL.md +1 -1
  34. package/skills/nansen-wallet-clustering/SKILL.md +1 -1
  35. package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
  36. package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
  37. package/skills/nansen-wallet-manager/SKILL.md +11 -5
  38. package/skills/nansen-wallet-profiler/SKILL.md +1 -1
  39. package/skills/nansen-web-fetcher/SKILL.md +1 -1
  40. package/skills/nansen-web-searcher/SKILL.md +1 -1
  41. package/src/api-endpoints.json +1605 -0
  42. package/src/api.js +282 -124
  43. package/src/auth-credentials.js +1 -0
  44. package/src/auth-key-input.js +57 -9
  45. package/src/auth-state.js +2 -2
  46. package/src/auth-store-native.js +6 -1
  47. package/src/auth-store-worker.js +1 -1
  48. package/src/auth-store.js +9 -4
  49. package/src/auto-paginate.js +25 -7
  50. package/src/bridge.js +19 -10
  51. package/src/cache-inspect.js +16 -6
  52. package/src/cli.js +272 -114
  53. package/src/commands/agent.js +2 -3
  54. package/src/commands/alerts.js +365 -18
  55. package/src/commands/completion.js +4 -1
  56. package/src/commands/feedback.js +98 -37
  57. package/src/commands/mcp.js +1 -1
  58. package/src/commands/research.js +14 -37
  59. package/src/cost-cache.js +33 -7
  60. package/src/doctor.js +14 -5
  61. package/src/ens.js +14 -5
  62. package/src/error-codes.js +228 -0
  63. package/src/execute-guard.js +8 -3
  64. package/src/input-validation.js +555 -0
  65. package/src/limit-order.js +127 -54
  66. package/src/perp.js +358 -35
  67. package/src/privy.js +90 -15
  68. package/src/query-options.js +47 -8
  69. package/src/response-cache-files.js +65 -0
  70. package/src/response-meta.js +8 -2
  71. package/src/rpc-urls.js +3 -1
  72. package/src/schema.json +1254 -156
  73. package/src/solana-tx.js +4 -0
  74. package/src/telemetry-flags.js +75 -0
  75. package/src/trade-validation.js +167 -8
  76. package/src/trading.js +243 -20
  77. package/src/transfer.js +79 -12
  78. package/src/update-check.js +32 -5
  79. package/src/wallet.js +246 -69
  80. package/src/walletconnect-x402.js +27 -9
@@ -7,28 +7,58 @@
7
7
  */
8
8
 
9
9
  import { NansenError, CommandError, ErrorCode } from './api.js';
10
+ import { normalizeFilterAddresses } from './input-validation.js';
10
11
 
12
+ /**
13
+ * The request `pagination` object for --page/--limit, or undefined when
14
+ * neither is given. Both must be positive whole numbers: --page 0 used to be
15
+ * clamped to 1 silently (API-1081).
16
+ */
11
17
  export function buildPagination(options) {
12
18
  if (options.limit === undefined && options.page === undefined) return undefined;
13
- const perPage = options.limit === undefined ? undefined : Number(options.limit);
14
- if (perPage !== undefined && (!Number.isInteger(perPage) || perPage < 1)) {
15
- throw new NansenError('--limit must be a positive integer', ErrorCode.INVALID_PARAMS);
19
+ const pagination = { page: 1 };
20
+ if (options.page !== undefined) {
21
+ const page = Number(options.page);
22
+ if (typeof options.page === 'boolean' || String(options.page).trim() === '' || !Number.isSafeInteger(page) || page < 1) {
23
+ throw new NansenError('--page must be a positive integer', ErrorCode.INVALID_PARAMS);
24
+ }
25
+ pagination.page = page;
26
+ }
27
+ if (options.limit !== undefined) {
28
+ const perPage = Number(options.limit);
29
+ if (typeof options.limit === 'boolean' || String(options.limit).trim() === '' || !Number.isSafeInteger(perPage) || perPage < 1) {
30
+ throw new NansenError('--limit must be a positive integer', ErrorCode.INVALID_PARAMS);
31
+ }
32
+ pagination.per_page = perPage;
16
33
  }
17
- return {
18
- page: Math.max(1, parseInt(options.page, 10) || 1),
19
- per_page: perPage,
20
- };
34
+ return pagination;
21
35
  }
22
36
 
23
37
  // Parse simple sort syntax: "field:direction" or "field" (defaults to DESC)
24
38
  export function parseSort(sortOption, orderByOption) {
25
39
  // If --order-by is provided, use it (full JSON control)
26
- if (orderByOption) return orderByOption;
40
+ if (orderByOption) {
41
+ const isEntry = e => e !== null && typeof e === 'object' && !Array.isArray(e)
42
+ && typeof e.field === 'string' && e.field.trim() !== '';
43
+ if (!Array.isArray(orderByOption) || !orderByOption.every(isEntry)) {
44
+ throw new NansenError(
45
+ `--order-by must be a JSON array of {"field", "direction"} objects, e.g. --order-by '[{"field":"value_usd","direction":"DESC"}]'`,
46
+ ErrorCode.INVALID_PARAMS,
47
+ );
48
+ }
49
+ return orderByOption;
50
+ }
27
51
  if (!sortOption) return undefined;
28
52
  if (typeof sortOption !== 'string') {
29
53
  throw new NansenError('--sort must be "field" or "field:direction"', ErrorCode.INVALID_PARAMS);
30
54
  }
31
55
  const parts = sortOption.split(':');
56
+ if (parts.length > 2) {
57
+ throw new NansenError(
58
+ `--sort must be "field" or "field:direction", got "${sortOption}" (e.g. --sort ${parts[0].trim()}:desc)`,
59
+ ErrorCode.INVALID_PARAMS,
60
+ );
61
+ }
32
62
  const field = parts[0].trim();
33
63
  const rawDirection = (parts[1] || '').trim();
34
64
  const direction = (rawDirection || 'desc').toUpperCase();
@@ -85,6 +115,15 @@ export function parseObjectOption(val, name) {
85
115
  return val;
86
116
  }
87
117
 
118
+ /**
119
+ * `--filters '<json>'` as a plain object with every EVM address lowercased.
120
+ * The API stores EVM addresses lowercase, so a checksummed address matched no
121
+ * rows and the command returned an empty success (API-1081).
122
+ */
123
+ export function parseFiltersOption(val) {
124
+ return normalizeFilterAddresses(parseObjectOption(val, 'filters'));
125
+ }
126
+
88
127
  /** Reject explicit blank strings before a handler selects an omitted-option default. */
89
128
  export function rejectBlankOption(value, name, example) {
90
129
  if (typeof value === 'string' && value.trim() === '') {
@@ -0,0 +1,65 @@
1
+ /**
2
+ * File-level housekeeping for the response cache directory (~/.nansen/cache),
3
+ * shared by api.js (which writes entries) and cache-inspect.js (which clears
4
+ * them). Imports nothing from either so both can use it without a cycle.
5
+ *
6
+ * Names in the directory:
7
+ * <sha256>.json a cache entry
8
+ * <sha256>.json.<pid>.<uuid>.tmp a write in progress; renamed onto the
9
+ * entry when it completes, so a leftover one
10
+ * means the writing process was killed
11
+ */
12
+
13
+ import fs from 'fs';
14
+ import path from 'path';
15
+
16
+ export const RESPONSE_ENTRY = /^[0-9a-f]{64}\.json$/;
17
+ export const RESPONSE_TEMP = /^[0-9a-f]{64}\.json\.\d+\.[0-9a-f-]{36}\.tmp$/;
18
+
19
+ // A write holds its temp file for milliseconds. Anything this old was left by
20
+ // a process that died before the rename.
21
+ export const STALE_TEMP_MS = 10 * 60 * 1000;
22
+
23
+ // Entries are never read back after their TTL (default 300s, set per call with
24
+ // --cache-ttl) and a read does not delete them, so without a sweep, requests
25
+ // that are never repeated leave files behind forever. The sweep after a cache
26
+ // write removes entries older than this, or older than the longest TTL the
27
+ // writing process has read with, whichever is longer.
28
+ export const ENTRY_MAX_AGE_MS = 24 * 60 * 60 * 1000;
29
+
30
+ /** A temp file left behind by a write that never completed. */
31
+ export function isStaleTemp(name, stat, now = Date.now()) {
32
+ return RESPONSE_TEMP.test(name) && now - stat.mtimeMs > STALE_TEMP_MS;
33
+ }
34
+
35
+ /**
36
+ * Remove stale temp files and entries older than `retentionMs` (default
37
+ * ENTRY_MAX_AGE_MS) from `dir`.
38
+ * Only regular files whose names match the two shapes above are touched; a
39
+ * symlinked or missing directory and symlinked entries are left alone.
40
+ * Returns how many files were removed.
41
+ *
42
+ * Another process may rename a fresh entry onto a path between the lstat and
43
+ * the unlink. That costs it one cache miss, never wrong data.
44
+ */
45
+ export function pruneResponseCacheDir(dir, now = Date.now(), retentionMs = ENTRY_MAX_AGE_MS) {
46
+ const dirStat = fs.lstatSync(dir, { throwIfNoEntry: false });
47
+ if (!dirStat || !dirStat.isDirectory()) return 0;
48
+ let removed = 0;
49
+ for (const name of fs.readdirSync(dir)) {
50
+ const isEntry = RESPONSE_ENTRY.test(name);
51
+ if (!isEntry && !RESPONSE_TEMP.test(name)) continue;
52
+ const file = path.join(dir, name);
53
+ const stat = fs.lstatSync(file, { throwIfNoEntry: false });
54
+ if (!stat || !stat.isFile()) continue;
55
+ const stale = isEntry ? now - stat.mtimeMs > retentionMs : isStaleTemp(name, stat, now);
56
+ if (!stale) continue;
57
+ try {
58
+ fs.unlinkSync(file);
59
+ removed += 1;
60
+ } catch (error) {
61
+ if (error?.code !== 'ENOENT') throw error;
62
+ }
63
+ }
64
+ return removed;
65
+ }
@@ -66,6 +66,7 @@ export function readResponseMeta(response) {
66
66
  const planNotice = stringHeader(response, PLAN_NOTICE);
67
67
  const apiKeyNotice = stringHeader(response, API_KEY_NOTICE);
68
68
  const requestId = stringHeader(response, REQUEST_ID);
69
+ const warning = stringHeader(response, 'warning');
69
70
 
70
71
  const meta = {};
71
72
  if (requestId !== null) {
@@ -83,8 +84,9 @@ export function readResponseMeta(response) {
83
84
  // drain — not a wall-clock timestamp.
84
85
  meta.rateLimit = { limit, remaining: rateRemaining, resetSeconds };
85
86
  }
86
- if (upgradeHint !== null || planNotice !== null || apiKeyNotice !== null) {
87
+ if (upgradeHint !== null || planNotice !== null || apiKeyNotice !== null || warning !== null) {
87
88
  meta.notices = {
89
+ ...(warning !== null && { warning }),
88
90
  ...(upgradeHint !== null && { upgradeHint }),
89
91
  ...(planNotice !== null && { planNotice }),
90
92
  ...(apiKeyNotice !== null && { apiKeyNotice }),
@@ -102,11 +104,13 @@ export function readResponseMeta(response) {
102
104
  export function aggregatePaginatedResponseMeta(pages) {
103
105
  if (!Array.isArray(pages) || pages.length === 0) return null;
104
106
 
107
+ const warning = [...new Set(pages.map(page => page.meta?.notices?.warning).filter(Boolean))].join(', ');
105
108
  const livePages = pages.filter(page => !page.cached);
106
109
  const metas = livePages.map(page => page.meta);
107
110
  const present = metas.filter(Boolean);
108
111
  if (livePages.length === 0) {
109
112
  return {
113
+ ...(warning && { notices: { warning } }),
110
114
  credits: { used: 0, remaining: null, cost: 0 },
111
115
  pagination: { pagesFetched: pages.length, livePages: 0, cachedPages: pages.length },
112
116
  };
@@ -134,6 +138,7 @@ export function aggregatePaginatedResponseMeta(pages) {
134
138
 
135
139
  const notices = {};
136
140
  for (const meta of present) Object.assign(notices, meta.notices || {});
141
+ if (warning) notices.warning = warning;
137
142
  if (Object.keys(notices).length > 0) result.notices = notices;
138
143
 
139
144
  result.pagination = {
@@ -147,12 +152,13 @@ export function aggregatePaginatedResponseMeta(pages) {
147
152
  /**
148
153
  * Yield notice strings for any server-set advisory headers.
149
154
  * Each yields a `⚠️ <message>` line for stderr.
150
- * Order: apiKeyNotice (most urgent) → upgradeHint → planNotice.
155
+ * Order: API warning → apiKeyNotice → upgradeHint → planNotice.
151
156
  */
152
157
  export function noticeWarnings(meta) {
153
158
  const notices = meta?.notices;
154
159
  if (!notices) return [];
155
160
  const out = [];
161
+ if (notices.warning) out.push(`⚠️ ${notices.warning}`);
156
162
  if (notices.apiKeyNotice) out.push(`⚠️ ${notices.apiKeyNotice}`);
157
163
  if (notices.upgradeHint) out.push(`ℹ️ ${notices.upgradeHint}`);
158
164
  if (notices.planNotice) out.push(`ℹ️ ${notices.planNotice}`);
package/src/rpc-urls.js CHANGED
@@ -37,7 +37,9 @@
37
37
  * working while new code uses the standardised NANSEN_BASE_RPC name.
38
38
  */
39
39
 
40
- const DEFAULT_EVM_RPC = 'https://eth.public-rpc.com';
40
+ // eth.public-rpc.com started requiring an API key (HTTP 403), which broke every
41
+ // `wallet send --chain ethereum|evm` that had no NANSEN_EVM_RPC override.
42
+ const DEFAULT_EVM_RPC = 'https://ethereum-rpc.publicnode.com';
41
43
  const DEFAULT_BASE_RPC = 'https://mainnet.base.org';
42
44
  const DEFAULT_BSC_RPC = 'https://bsc-dataseed.binance.org';
43
45
  const DEFAULT_XLAYER_RPC = 'https://rpc.xlayer.tech';