nansen-cli 2.3.0 → 2.4.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 (71) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/README.md +32 -32
  3. package/docs/auth.md +56 -0
  4. package/docs/browser-login.md +101 -7
  5. package/docs/error-codes.md +249 -0
  6. package/package.json +10 -4
  7. package/skills/nansen-agent-guide/SKILL.md +17 -1
  8. package/skills/nansen-alerts-webhook-listener/SKILL.md +1 -1
  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 +1 -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 +2 -1
  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 +1 -1
  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 +1 -1
  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 +202 -97
  43. package/src/auth-credentials.js +1 -0
  44. package/src/auth-state.js +2 -2
  45. package/src/auth-store-native.js +6 -1
  46. package/src/auth-store-worker.js +1 -1
  47. package/src/auth-store.js +9 -4
  48. package/src/bridge.js +19 -10
  49. package/src/cli.js +188 -89
  50. package/src/commands/agent.js +2 -3
  51. package/src/commands/alerts.js +277 -9
  52. package/src/commands/feedback.js +98 -37
  53. package/src/commands/mcp.js +1 -1
  54. package/src/commands/research.js +14 -37
  55. package/src/cost-cache.js +33 -7
  56. package/src/doctor.js +14 -5
  57. package/src/error-codes.js +226 -0
  58. package/src/input-validation.js +551 -0
  59. package/src/limit-order.js +12 -3
  60. package/src/perp.js +2 -1
  61. package/src/privy.js +89 -11
  62. package/src/query-options.js +30 -7
  63. package/src/rpc-urls.js +3 -1
  64. package/src/schema.json +1137 -145
  65. package/src/solana-tx.js +4 -0
  66. package/src/trade-validation.js +167 -8
  67. package/src/trading.js +172 -12
  68. package/src/transfer.js +7 -1
  69. package/src/update-check.js +32 -5
  70. package/src/wallet.js +211 -57
  71. package/src/walletconnect-x402.js +14 -8
@@ -4,6 +4,7 @@ import path from 'node:path';
4
4
  import { authDirectory } from '../auth-credentials.js';
5
5
  import { feedbackExpiry, withFeedbackJournal } from '../feedback-journal.js';
6
6
  import { NansenError, ErrorCode, packageVersion, telemetryHeaders, sleep, statusToErrorCode } from '../api.js';
7
+ import { traceError, traceRequest, traceResponse, traceRetry } from '../debug.js';
7
8
 
8
9
  const PATH = '/api/v1/feedback';
9
10
  const TEMPORARY = new Set([429, 500, 502, 503, 504]);
@@ -13,8 +14,20 @@ function requestId(response) {
13
14
  return response?.headers.get('x-request-id') ?? response?.headers.get('x-kong-request-id') ?? null;
14
15
  }
15
16
 
17
+ // Server messages do not always end with a full stop, and CLI guidance follows them.
18
+ function sentence(text) {
19
+ const value = String(text).trim();
20
+ return /[.!?]$/.test(value) ? value : `${value}.`;
21
+ }
22
+
23
+ function accountAuthOnly(api) {
24
+ if (Object.keys(api.defaultHeaders).length) {
25
+ throw new NansenError('Feedback uses account authentication only. Remove --x402-payment-signature.', ErrorCode.INVALID_PARAMS);
26
+ }
27
+ }
28
+
16
29
  function preserveUncertainSubmission(error, pending) {
17
- return new NansenError(`${error.message} ${pending.message}`, pending.code, error.status ?? pending.status,
30
+ return new NansenError(`${sentence(error.message)} ${pending.message}`, pending.code, error.status ?? pending.status,
18
31
  { ...error.details, ...pending.details, request_id: error.details?.request_id ?? pending.details.request_id, outcome: 'unknown' });
19
32
  }
20
33
 
@@ -27,14 +40,14 @@ function clearRejectedFeedback(journal, error, submissionId) {
27
40
  try { journal.clear(); }
28
41
  catch {
29
42
  const message = error.code === 'feedback_blocked' ? 'The report was blocked before reaching Nansen. No report was saved.' : error.message;
30
- throw new NansenError(`${message}${message.endsWith('.') ? '' : '.'} Local retry data could not be erased. Repair ~/.nansen/feedback, then run: nansen feedback forget before using --new with the corrected --file.`,
43
+ throw new NansenError(`${sentence(message)} Local retry data could not be erased. Repair ~/.nansen/feedback, then run: nansen feedback forget before using --new with the corrected --file.`,
31
44
  error.code, error.status, { ...error.details, submission_id: submissionId, outcome: 'rejected', retry_command: 'nansen feedback forget' });
32
45
  }
33
46
  }
34
47
 
35
- function required(value, name, usage = 'nansen feedback submit --file feedback.json --submission-id <new-id>') {
48
+ function required(value, name, usage, hint = '') {
36
49
  if (typeof value !== 'string' || !value.trim()) {
37
- throw new NansenError(`${name} is required. Use: ${usage}. Reuse the submission ID and unchanged file after an uncertain submission result.`, ErrorCode.MISSING_PARAM);
50
+ throw new NansenError(`${name} is required. Use: ${usage}.${hint}`, ErrorCode.MISSING_PARAM);
38
51
  }
39
52
  return value;
40
53
  }
@@ -48,18 +61,36 @@ function retryDelay(response, data, attempt, retry) {
48
61
  return Math.max(Math.min(retry.maxDelayMs, retry.baseDelayMs * 2 ** attempt), Number.isFinite(advertised) ? Math.max(0, advertised) : 0);
49
62
  }
50
63
 
64
+ function redactor(credentials) {
65
+ const secrets = Object.values(credentials).flatMap(value => [value, value.replace(/^Bearer /, '')]);
66
+ const redact = value => {
67
+ if (typeof value === 'string') return secrets.reduce((text, secret) => secret ? text.split(secret).join('[redacted]') : text, value);
68
+ if (Array.isArray(value)) return value.map(redact);
69
+ if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redact(item)]));
70
+ return value;
71
+ };
72
+ return redact;
73
+ }
74
+
75
+ // Undici quotes a rejected header value in its message, so a malformed key would reach the trace.
76
+ function transportFailure(error) {
77
+ const code = error?.cause?.code;
78
+ return typeof code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(code) ? code : error?.name ?? 'Error';
79
+ }
80
+
51
81
  // Feedback keeps the file bytes and uses selected account credentials. It never
52
82
  // enters the generic client's body cleaning, cache, pagination or payment paths.
53
- async function requestFeedback(api, endpoint, body, submissionId, responseType = 'receipt', previouslyUncertain = false) {
54
- const preference = responseType === 'preferences';
55
- if (Object.keys(api.defaultHeaders).length) {
56
- throw new NansenError('Feedback uses account authentication only. Remove --x402-payment-signature.', ErrorCode.INVALID_PARAMS);
57
- }
83
+ async function requestFeedback(api, endpoint, body, submissionId, { preference = false, previouslyUncertain = false, managed = false } = {}) {
84
+ accountAuthOnly(api);
58
85
  const retry = api.retryOptions;
59
86
  const maxRetries = Math.min(retry.maxRetries, 3);
87
+ const method = body === undefined ? 'GET' : 'POST', url = `${api.baseUrl}${endpoint}`;
88
+ // A generated ID is recovered with `nansen feedback resume`, which the caller adds.
89
+ const retryHint = managed ? '' : ' Retry the same --submission-id with the unchanged --file.';
90
+ const keepHint = managed ? '' : ' Keep the same --submission-id and unchanged --file for recovery.';
60
91
  let lastError;
61
92
  let uncertainSubmission = previouslyUncertain ? new NansenError(
62
- 'An earlier attempt may have been saved. Keep the same --submission-id and unchanged --file for recovery.',
93
+ `An earlier attempt may have been saved.${keepHint}`,
63
94
  'submission_outcome_unknown', null,
64
95
  { reason: 'submission_outcome_unknown', submission_id: submissionId, outcome: 'unknown' },
65
96
  ) : undefined;
@@ -72,18 +103,14 @@ async function requestFeedback(api, endpoint, body, submissionId, responseType =
72
103
  if (!Object.keys(credentials).length) {
73
104
  throw new NansenError('Not logged in. Run: nansen login, or set NANSEN_API_KEY.', ErrorCode.UNAUTHORIZED);
74
105
  }
75
- const secrets = Object.values(credentials).flatMap(value => [value, value.replace(/^Bearer /, '')]);
76
- const redact = value => {
77
- if (typeof value === 'string') return secrets.reduce((text, secret) => secret ? text.split(secret).join('[redacted]') : text, value);
78
- if (Array.isArray(value)) return value.map(redact);
79
- if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redact(item)]));
80
- return value;
81
- };
106
+ const redact = redactor(credentials);
82
107
  let response, data;
83
108
  api.beforeFeedbackRequest?.();
109
+ const startedAt = Date.now();
110
+ traceRequest({ method, url, attempt: attempt + 1, maxAttempts: maxRetries + 1 });
84
111
  try {
85
- response = await fetch(`${api.baseUrl}${endpoint}`, {
86
- method: body === undefined ? 'GET' : 'POST', redirect: 'error', cache: 'no-store',
112
+ response = await fetch(url, {
113
+ method, redirect: 'error', cache: 'no-store',
87
114
  signal: AbortSignal.timeout(30000),
88
115
  headers: {
89
116
  'X-Client-Type': 'nansen-cli', 'X-Client-Version': packageVersion,
@@ -91,7 +118,11 @@ async function requestFeedback(api, endpoint, body, submissionId, responseType =
91
118
  ...(body !== undefined && { 'Content-Type': 'application/json', 'Idempotency-Key': submissionId }),
92
119
  },
93
120
  ...(body !== undefined && { body }),
121
+ }).catch(error => {
122
+ traceError({ method, url, durationMs: Date.now() - startedAt, attempt: attempt + 1, error: transportFailure(error) });
123
+ throw error;
94
124
  });
125
+ traceResponse({ method, url, status: response.status, durationMs: Date.now() - startedAt, requestId: requestId(response), attempt: attempt + 1 });
95
126
  data = await response.json();
96
127
  if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('Invalid response');
97
128
  if (response.ok) {
@@ -111,7 +142,7 @@ async function requestFeedback(api, endpoint, body, submissionId, responseType =
111
142
  if (body !== undefined && response?.status === 403 && response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() === 'text/html') {
112
143
  const blocked = new NansenError(uncertainSubmission
113
144
  ? 'This attempt was blocked before reaching Nansen.'
114
- : 'The report was blocked before reaching Nansen. No report was saved. Change the report and use a new submission ID.',
145
+ : `The report was blocked before reaching Nansen. No report was saved.${managed ? '' : ' Change the report and use a new submission ID.'}`,
115
146
  'feedback_blocked', 403,
116
147
  { reason: 'feedback_blocked', outcome: 'rejected', submission_id: submissionId, request_id: redact(requestId(response)) });
117
148
  if (uncertainSubmission) throw preserveUncertainSubmission(blocked, uncertainSubmission);
@@ -125,14 +156,17 @@ async function requestFeedback(api, endpoint, body, submissionId, responseType =
125
156
  }
126
157
  const unknown = body !== undefined;
127
158
  lastError = new NansenError(
128
- unknown ? 'The submission may have been saved. Retry the same --submission-id with the unchanged --file.' : preference ? 'Feedback preference unavailable. Show the report and ask before sending.' : 'Receipt lookup failed. Retry nansen feedback get with the same feedback ID.',
159
+ unknown ? `The submission may have been saved.${retryHint}` : preference ? 'Feedback preference unavailable. Show the report and ask before sending.' : 'Receipt lookup failed. Retry nansen feedback get with the same feedback ID.',
129
160
  unknown ? 'submission_outcome_unknown' : ErrorCode.NETWORK_ERROR, response?.status ?? null,
130
161
  { reason: unknown ? 'submission_outcome_unknown' : preference ? 'preference_unavailable' : 'receipt_unavailable', submission_id: submissionId ?? null, request_id: redact(requestId(response)), ...(unknown && { outcome: 'unknown' }) },
131
162
  );
132
163
  if (unknown) uncertainSubmission = lastError;
133
164
  if (attempt < maxRetries && (!response || response.ok || TEMPORARY.has(response.status))) {
134
165
  const delay = retryDelay(response, null, attempt, retry);
135
- if (delay <= retry.maxRetryAfterMs) { await sleep(delay); continue; }
166
+ if (delay <= retry.maxRetryAfterMs) {
167
+ traceRetry({ method, url, status: response?.status, attempt: attempt + 1, reason: response ? 'unparseable-response' : 'network-error', delayMs: delay });
168
+ await sleep(delay); continue;
169
+ }
136
170
  }
137
171
  throw lastError;
138
172
  }
@@ -141,7 +175,7 @@ async function requestFeedback(api, endpoint, body, submissionId, responseType =
141
175
  if (submissionId) details.submission_id = submissionId;
142
176
  if (uncertainSubmission && data.reason !== 'feedback_erased') details.outcome = 'unknown';
143
177
  if (response.status === 403 && data.reason === 'feedback_not_enabled') {
144
- const uncertainty = uncertainSubmission ? ' An earlier attempt may have been saved. Keep the same --submission-id and unchanged --file for recovery.' : '';
178
+ const uncertainty = uncertainSubmission ? ` An earlier attempt may have been saved.${keepHint}` : '';
145
179
  throw new NansenError(`Feedback is not enabled for this account. Stop automatic retries. User approval or an enabled preference does not override rollout.${uncertainty}`,
146
180
  uncertainSubmission ? uncertainSubmission.code : details.code || 'forbidden', response.status,
147
181
  { ...details, outcome: uncertainSubmission ? 'unknown' : 'rejected' });
@@ -159,7 +193,7 @@ async function requestFeedback(api, endpoint, body, submissionId, responseType =
159
193
  }
160
194
  lastError = new NansenError(details.message || 'Feedback request failed.', details.code || statusToErrorCode(response.status, data), response.status, details);
161
195
  if (body !== undefined && response.status >= 500 && data.reason !== 'feedback_admissions_paused') {
162
- uncertainSubmission ??= new NansenError('The submission may have been saved. Retry the same --submission-id with the unchanged --file.',
196
+ uncertainSubmission ??= new NansenError(`The submission may have been saved.${retryHint}`,
163
197
  'submission_outcome_unknown', response.status,
164
198
  { reason: 'submission_outcome_unknown', submission_id: submissionId, request_id: details.request_id });
165
199
  }
@@ -167,11 +201,12 @@ async function requestFeedback(api, endpoint, body, submissionId, responseType =
167
201
  const weekly = data.reason === 'feedback_weekly_quota_exhausted';
168
202
  const delay = retryDelay(response, data, attempt, retry);
169
203
  if (!weekly && TEMPORARY.has(response.status) && attempt < maxRetries && delay <= retry.maxRetryAfterMs) {
204
+ traceRetry({ method, url, status: response.status, attempt: attempt + 1, reason: 'retryable-status', delayMs: delay });
170
205
  await sleep(delay);
171
206
  continue;
172
207
  }
173
208
  if (uncertainSubmission && response.status >= 500) {
174
- throw new NansenError(`${lastError.message} ${uncertainSubmission.message}`, uncertainSubmission.code,
209
+ throw new NansenError(`${sentence(lastError.message)} ${uncertainSubmission.message}`, uncertainSubmission.code,
175
210
  response.status, { ...details, outcome: 'unknown' });
176
211
  }
177
212
  throw lastError;
@@ -182,16 +217,34 @@ async function requestFeedback(api, endpoint, body, submissionId, responseType =
182
217
  // Resolve the account from the server, then freeze those exact credentials for
183
218
  // the entire operation. Re-login in another process cannot redirect a replay.
184
219
  async function feedbackIdentity(api) {
185
- if (Object.keys(api.defaultHeaders).length) throw new NansenError('Feedback uses account authentication only. Remove --x402-payment-signature.', ErrorCode.INVALID_PARAMS);
220
+ accountAuthOnly(api);
186
221
  const credentials = await api.requestCredentials({});
187
222
  if (!Object.keys(credentials).length) throw new NansenError('Not logged in. Run: nansen login, or set NANSEN_API_KEY.', ErrorCode.UNAUTHORIZED);
223
+ let response, data;
188
224
  try {
189
225
  const environment = new URL(api.baseUrl).href.replace(/\/$/, '');
190
- const response = await fetch(`${environment}/api/v1/account`, { headers: credentials, redirect: 'error', cache: 'no-store', signal: AbortSignal.timeout(15000) });
191
- const data = await response.json();
226
+ const url = `${environment}/api/v1/account`, startedAt = Date.now();
227
+ traceRequest({ method: 'GET', url, attempt: 1 });
228
+ response = await fetch(url, { headers: credentials, redirect: 'error', cache: 'no-store', signal: AbortSignal.timeout(15000) }).catch(error => {
229
+ traceError({ method: 'GET', url, durationMs: Date.now() - startedAt, attempt: 1, error: transportFailure(error) });
230
+ throw error;
231
+ });
232
+ traceResponse({ method: 'GET', url, status: response.status, durationMs: Date.now() - startedAt, requestId: requestId(response), attempt: 1 });
233
+ data = await response.json();
192
234
  if (!response.ok || typeof data.user_id !== 'string' || !data.user_id || data.user_id.length > 255 || [...data.user_id].some(c => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127)) throw new Error();
193
235
  return { account: data.user_id, environment, api: { ...api, baseUrl: environment, requestCredentials: async () => credentials } };
194
- } catch { throw new NansenError('Could not verify the feedback account. No report was sent. Retry with the original account and NANSEN_BASE_URL.', 'feedback_identity_unverified'); }
236
+ } catch {
237
+ // A rejected credential is not an account or environment change. An HTML 403 is an edge block, not a key problem.
238
+ if (response?.status === 401 || (response?.status === 403 && typeof data?.message === 'string')) {
239
+ const redact = redactor(credentials);
240
+ const reason = typeof data?.message === 'string' && data.message.trim() ? redact(data.message) : `HTTP ${response.status}`;
241
+ // Any key may read the account, so a JSON 403 refuses the account itself and another key would not help.
242
+ const next = response.status === 401 ? 'Use a valid API key or login for the original account, then retry.' : "Check this account's access, then retry.";
243
+ throw new NansenError(`${sentence(reason)} Could not verify the feedback account. No report was sent. ${next}`,
244
+ 'feedback_identity_unverified', response.status, { request_id: redact(requestId(response)) });
245
+ }
246
+ throw new NansenError('Could not verify the feedback account. No report was sent. Retry with the original account and NANSEN_BASE_URL.', 'feedback_identity_unverified');
247
+ }
195
248
  }
196
249
 
197
250
  async function managedFeedback(api, { body, newSubmission = false, forget = false } = {}) {
@@ -231,9 +284,9 @@ async function managedFeedback(api, { body, newSubmission = false, forget = fals
231
284
  try {
232
285
  const receipt = entry.state === 'confirmed'
233
286
  ? await requestFeedback(identity.api, `${PATH}/${encodeURIComponent(entry.feedback_id)}`, undefined, entry.submission_id)
234
- : await requestFeedback(identity.api, PATH, entry.body, entry.submission_id, 'receipt', previouslyUncertain);
287
+ : await requestFeedback(identity.api, PATH, entry.body, entry.submission_id, { previouslyUncertain, managed: true });
235
288
  const expiry = Date.parse(receipt.expires_at);
236
- if (!Number.isFinite(expiry)) throw new NansenError('The receipt expiry could not be confirmed.', 'submission_outcome_unknown');
289
+ if (!Number.isFinite(expiry)) throw new NansenError('The receipt expiry could not be confirmed. The submission may have been saved.', 'submission_outcome_unknown');
237
290
  // Never retain the body, its digest, or any free-text receipt fields.
238
291
  journal.save({ version: 1, state: 'confirmed', submission_id: entry.submission_id, account: entry.account, environment: entry.environment,
239
292
  expires_at: new Date(Math.min(expiry, Date.parse(entry.expires_at))).toISOString(), feedback_id: receipt.feedback_id });
@@ -250,7 +303,7 @@ async function managedFeedback(api, { body, newSubmission = false, forget = fals
250
303
  if (!unknown && ([400, 413, 422].includes(error.status) || (error.status === 409 && error.details?.reason === 'idempotency_key_reused') ||
251
304
  error.code === 'feedback_blocked')) {
252
305
  clearRejectedFeedback(journal, error, entry.submission_id);
253
- throw new NansenError(`${error.message} This attempt was rejected. Local retry data was erased. Correct the report and use --new with the corrected --file.`,
306
+ throw new NansenError(`${sentence(error.message)} This attempt was rejected. Local retry data was erased. Correct the report and use --new with the corrected --file.`,
254
307
  error.code, error.status, { ...error.details, submission_id: entry.submission_id, outcome: 'rejected' });
255
308
  }
256
309
  try { journal.save({ ...entry, uncertain: unknown }); }
@@ -261,11 +314,15 @@ async function managedFeedback(api, { body, newSubmission = false, forget = fals
261
314
  error.code, error.status, { ...error.details, submission_id: entry.submission_id, outcome: unknown ? 'unknown' : 'rejected' });
262
315
  }
263
316
  if (error.status === 429 && error.details?.reason === 'feedback_weekly_quota_exhausted') {
264
- throw new NansenError(`${error.message} ${unknown ? 'An earlier attempt may have been accepted.' : 'This submission was not accepted.'} Wait for the weekly reset before running: nansen feedback resume.`,
317
+ throw new NansenError(`${sentence(error.message)} ${unknown ? 'An earlier attempt may have been accepted.' : 'This submission was not accepted.'} Wait for the weekly reset before running: nansen feedback resume.`,
265
318
  error.code, error.status, { ...error.details, submission_id: entry.submission_id, outcome: unknown ? 'unknown' : 'rejected',
266
319
  retry_command: 'nansen feedback resume', retry_not_before: error.details.quota?.resets_at ?? null });
267
320
  }
268
- throw new NansenError(`${error.message} ${unknown ? 'The saved submission may have been accepted. Retry safely with: nansen feedback resume' : 'This report was not accepted. Retry the saved report with: nansen feedback resume.'}`,
321
+ // submission_outcome_unknown messages already say the submission may have been saved.
322
+ const recovery = unknown
323
+ ? `${error.code === 'submission_outcome_unknown' ? '' : 'The saved submission may have been accepted. '}Retry safely with: nansen feedback resume.`
324
+ : 'This report was not accepted. Retry the saved report with: nansen feedback resume.';
325
+ throw new NansenError(`${sentence(error.message)} ${recovery}`,
269
326
  error.code, error.status, { ...error.details, submission_id: entry.submission_id, retry_command: 'nansen feedback resume', outcome: unknown ? 'unknown' : 'rejected' });
270
327
  }
271
328
  }, { erase: forget });
@@ -299,10 +356,13 @@ export function buildFeedbackCommands({ log = console.log } = {}) {
299
356
  if (flags['submission-id']) throw new NansenError('--submission-id requires a value.', ErrorCode.INVALID_PARAMS);
300
357
  if (args[0] === 'preferences') {
301
358
  if (args.length !== 1 || options.file || options['submission-id'] || flags.new) throw new NansenError('Use: nansen feedback preferences [--json]', ErrorCode.INVALID_PARAMS);
302
- try { receipt = await requestFeedback(api, `${PATH}/preferences`, undefined, undefined, 'preferences'); }
359
+ accountAuthOnly(api);
360
+ try { receipt = await requestFeedback(api, `${PATH}/preferences`, undefined, undefined, { preference: true }); }
303
361
  catch (error) {
304
362
  const guidance = 'Feedback preference unavailable. Show the report and ask before sending.';
305
- throw new NansenError(`${guidance}${error.status == null && error.message !== guidance ? ` ${error.message}` : ''}`, error.code, error.status,
363
+ // Local failures and rejected credentials tell the user what to fix; other HTTP failures only need the guidance.
364
+ const cause = (error.status == null || [401, 403].includes(error.status)) && error.message !== guidance ? ` ${error.message}` : '';
365
+ throw new NansenError(`${guidance}${cause}`, error.code, error.status,
306
366
  { ...error.details, reason: 'preference_unavailable' });
307
367
  }
308
368
  if (flags.json || flags.pretty || flags.p) return receipt;
@@ -313,7 +373,8 @@ export function buildFeedbackCommands({ log = console.log } = {}) {
313
373
  const id = options['submission-id'];
314
374
  if (id !== undefined && flags.new) throw new NansenError('Use either --new or --submission-id.', ErrorCode.INVALID_PARAMS);
315
375
  if (id !== undefined && (typeof id !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(id))) throw new NansenError('--submission-id must contain 1 to 128 ASCII letters, digits, underscores or hyphens.', ErrorCode.INVALID_PARAMS);
316
- const file = required(options.file, '--file');
376
+ const file = required(options.file, '--file', 'nansen feedback submit --file feedback.json --submission-id <new-id>',
377
+ ' Reuse the submission ID and unchanged file after an uncertain submission result.');
317
378
  let body;
318
379
  try { body = fs.readFileSync(file, 'utf8'); } catch { throw new NansenError('Cannot read --file. Supply a readable JSON report file.', ErrorCode.INVALID_PARAMS); }
319
380
  let report;
@@ -307,7 +307,7 @@ export function buildMcpCommands(deps = {}) {
307
307
  }
308
308
 
309
309
  if (sub !== 'install' && sub !== 'uninstall') {
310
- throw new CommandError(`Unknown subcommand: ${sub}\n\n${MCP_USAGE}`, 'INVALID_PARAMS');
310
+ throw new CommandError(`Unknown subcommand: ${sub}\n\n${MCP_USAGE}`, 'UNKNOWN_COMMAND');
311
311
  }
312
312
 
313
313
  requireClient(sub, client);
@@ -5,30 +5,8 @@
5
5
  */
6
6
 
7
7
  import { NansenError, ErrorCode } from '../api.js';
8
- import { parseSort, rejectBlankOption, parseObjectOption } from '../query-options.js';
9
-
10
- // Research subcommands validate --page strictly. The shared helper in
11
- // src/query-options.js clamps an invalid page to 1 for the category commands,
12
- // so keep a local variant here that rejects it instead.
13
- function buildPagination(options) {
14
- if (options.limit === undefined && options.page === undefined) return undefined;
15
- const pagination = { page: 1 };
16
- if (options.page !== undefined) {
17
- const page = Number(options.page);
18
- if (!Number.isInteger(page) || page < 1) {
19
- throw new NansenError('--page must be a positive integer', ErrorCode.INVALID_PARAMS);
20
- }
21
- pagination.page = page;
22
- }
23
- if (options.limit !== undefined) {
24
- const perPage = Number(options.limit);
25
- if (!Number.isInteger(perPage) || perPage < 1) {
26
- throw new NansenError('--limit must be a positive integer', ErrorCode.INVALID_PARAMS);
27
- }
28
- pagination.per_page = perPage;
29
- }
30
- return pagination;
31
- }
8
+ import { buildPagination, parseSort, rejectBlankOption, parseFiltersOption } from '../query-options.js';
9
+ import { unknownCommandError } from '../input-validation.js';
32
10
 
33
11
  const SUBCOMMANDS = [
34
12
  'historical-dex-trades',
@@ -89,9 +67,9 @@ function parseBooleanOption(options, flags, key) {
89
67
 
90
68
  function parseChains(options) {
91
69
  if (options.chains) {
92
- return Array.isArray(options.chains)
93
- ? options.chains
94
- : String(options.chains).split(',').map(s => s.trim()).filter(Boolean);
70
+ // "a,b", a repeated flag (each value may itself be "a,b") or a JSON array.
71
+ const values = Array.isArray(options.chains) ? options.chains : [options.chains];
72
+ return values.flatMap(value => String(value).split(',')).map(s => s.trim()).filter(Boolean);
95
73
  }
96
74
  if (options.chain) return [options.chain];
97
75
  return undefined;
@@ -178,7 +156,8 @@ USAGE:
178
156
  USAGE:
179
157
  nansen research historical-token-flow-summary --token-address <addr> --from-date <YYYY-MM-DD> --to-date <YYYY-MM-DD> [--chain <chain>]
180
158
 
181
- NOTE: This endpoint does not support pagination.`,
159
+ NOTE: This endpoint does not support pagination.
160
+ Whale, public figure, top PnL and exchange label history starts 2025-03-11, so those fields are null for an earlier --to-date.`,
182
161
  'historical-token-quant-scores': `nansen research historical-token-quant-scores — Historical token quantitative scores
183
162
 
184
163
  USAGE:
@@ -210,7 +189,8 @@ USAGE:
210
189
  USAGE:
211
190
  nansen research historical-tx-lookup --transaction-hash <hash> --as-of-date <YYYY-MM-DD> [--chain <chain>] [--block-timestamp "YYYY-MM-DD HH:MM:SS"]
212
191
 
213
- NOTE: Providing --block-timestamp skips a slow hash-resolution step and returns results much faster.`,
192
+ NOTE: Providing --block-timestamp skips a slow hash-resolution step and returns results much faster.
193
+ Entity labels are available from 2025-03-11 onward.`,
214
194
  'historical-wallet-transactions': `nansen research historical-wallet-transactions — Historical transactions for a wallet
215
195
 
216
196
  USAGE:
@@ -218,7 +198,7 @@ USAGE:
218
198
  'historical-token-ohlcv': `nansen research historical-token-ohlcv — Historical token OHLCV candles
219
199
 
220
200
  USAGE:
221
- nansen research historical-token-ohlcv --token-address <addr> --from-date <date> --timeframe <5m|15m|30m|1h|1d|1w> (--as-of-date <date> | --as-of-ts <timestamp>) [--chain <chain>] [--apply-blacklist-filter <true|false>]`,
201
+ nansen research historical-token-ohlcv --token-address <addr> --from-date <date> --timeframe <5m|15m|30m|1h|4h|1d|1w> (--as-of-date <date> | --as-of-ts <timestamp>) [--chain <chain>] [--apply-blacklist-filter <true|false>]`,
222
202
  };
223
203
 
224
204
  export function buildResearchCommands(deps = {}) {
@@ -234,10 +214,7 @@ export function buildResearchCommands(deps = {}) {
234
214
  }
235
215
 
236
216
  if (!RESEARCH_SUBCOMMANDS.has(sub)) {
237
- throw new NansenError(
238
- `Unknown research subcommand: ${sub}. Available: ${[...RESEARCH_SUBCOMMANDS].join(', ')}`,
239
- ErrorCode.UNKNOWN,
240
- );
217
+ throw unknownCommandError('research subcommand', sub, [...RESEARCH_SUBCOMMANDS]);
241
218
  }
242
219
 
243
220
  if (flags.help || flags.h || args[1] === 'help') {
@@ -256,7 +233,7 @@ export function buildResearchCommands(deps = {}) {
256
233
 
257
234
  const orderBy = parseSort(options.sort, options['order-by']);
258
235
  const pagination = buildPagination(options);
259
- const filters = parseObjectOption(options.filters, 'filters');
236
+ const filters = parseFiltersOption(options.filters);
260
237
  const { fromDate, toDate } = resolveDateRange(options);
261
238
  const asOfDate = options['as-of-date'];
262
239
 
@@ -382,7 +359,7 @@ export function buildResearchCommands(deps = {}) {
382
359
  'historical-token-flow-summary': () => apiInstance.researchTokenFlowSummary({
383
360
  tokenAddress: options['token-address'] || options.token,
384
361
  chain: options.chain,
385
- fromDate, toDate, filters, orderBy,
362
+ fromDate, toDate,
386
363
  }),
387
364
  'historical-who-bought-sold': () => apiInstance.researchWhoBoughtSold({
388
365
  tokenAddress: options['token-address'] || options.token,
@@ -491,7 +468,7 @@ export function buildResearchCommands(deps = {}) {
491
468
  }
492
469
 
493
470
  // Should be unreachable because SUBCOMMANDS guarded above.
494
- throw new NansenError(`Unknown research subcommand: ${sub}`, ErrorCode.UNKNOWN);
471
+ throw unknownCommandError('research subcommand', sub, [...RESEARCH_SUBCOMMANDS]);
495
472
  },
496
473
  };
497
474
  }
package/src/cost-cache.js CHANGED
@@ -3,6 +3,7 @@
3
3
  * by an inline fetch of the Nansen OpenAPI spec (at most once per 24h).
4
4
  *
5
5
  * getCostForEndpoint(endpoint) — sync, reads cache, returns { free, pro } or null
6
+ * getCostVariants(endpoint) — sync, reads cache, returns parameter-dependent costs or null
6
7
  * refreshCostMapIfStale() — async, fetches inline if cache is missing or stale
7
8
  */
8
9
 
@@ -40,19 +41,42 @@ function writeAtomic(file, data) {
40
41
  }
41
42
  }
42
43
 
43
- /**
44
- * Returns { free, pro } credit cost for the given API path, or null if unavailable.
45
- */
46
- export function getCostForEndpoint(endpoint) {
44
+ function readCache() {
47
45
  try {
48
46
  if (!fs.existsSync(CACHE_FILE)) return null;
49
- const { costs } = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
50
- return costs?.[endpoint] ?? null;
47
+ return JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
51
48
  } catch {
52
49
  return null;
53
50
  }
54
51
  }
55
52
 
53
+ /**
54
+ * Returns { free, pro } credit cost for the given API path, or null if unavailable.
55
+ */
56
+ export function getCostForEndpoint(endpoint) {
57
+ return readCache()?.costs?.[endpoint] ?? null;
58
+ }
59
+
60
+ /**
61
+ * Returns the spec's x-credit-cost-variants for the given API path, e.g.
62
+ * { 'premium_labels=true': { pro: 150 }, ... }, or null if it has none.
63
+ */
64
+ export function getCostVariants(endpoint) {
65
+ return readCache()?.variants?.[endpoint] ?? null;
66
+ }
67
+
68
+ const credits = n => `${n} credit${n === 1 ? '' : 's'}`;
69
+
70
+ /**
71
+ * "5 credits" when both tiers pay the same, otherwise both prices. A cost
72
+ * with no free price (premium labels) is Pro-only.
73
+ */
74
+ export function formatCost({ free, pro }) {
75
+ if (free === pro) return credits(free);
76
+ if (free == null) return `${credits(pro)} (Pro tier only)`;
77
+ return `${credits(free)} (Free tier) / ${credits(pro)} (Pro tier)`;
78
+ }
79
+
56
80
  /**
57
81
  * What did (or would) this call cost?
58
82
  *
@@ -105,17 +129,19 @@ export async function refreshCostMapIfStale() {
105
129
  if (!spec?.paths || typeof spec.paths !== 'object') return;
106
130
 
107
131
  const costs = {};
132
+ const variants = {};
108
133
  for (const [p, methods] of Object.entries(spec.paths)) {
109
134
  for (const op of Object.values(methods)) {
110
135
  if (op['x-credit-cost']) {
111
136
  costs[p] = op['x-credit-cost'];
137
+ if (op['x-credit-cost-variants']) variants[p] = op['x-credit-cost-variants'];
112
138
  break;
113
139
  }
114
140
  }
115
141
  }
116
142
 
117
143
  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { mode: 0o700, recursive: true });
118
- writeAtomic(CACHE_FILE, JSON.stringify({ costs, fetchedAt: Date.now() }));
144
+ writeAtomic(CACHE_FILE, JSON.stringify({ costs, variants, fetchedAt: Date.now() }));
119
145
  } catch {
120
146
  // silent — network failure, parse error, write error
121
147
  }
package/src/doctor.js CHANGED
@@ -15,7 +15,7 @@ import fs from 'fs';
15
15
  import path from 'path';
16
16
  import { fileURLToPath } from 'url';
17
17
  import { passwordSource } from './keychain.js';
18
- import { isNewer } from './update-check.js';
18
+ import { isNewer, nodeTooOldFor } from './update-check.js';
19
19
  import { isTelemetryDisabled } from './telemetry.js';
20
20
 
21
21
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -316,7 +316,7 @@ export function runDoctorChecks(deps = {}) {
316
316
  if (walletInfo.dirError) {
317
317
  checks.push(check('wallets', 'error', `${walletInfo.dir} exists but cannot be read — permission problem?`, `Check ownership and mode: ls -ld "${walletInfo.dir}"`));
318
318
  } else if (!walletInfo.dirExists || walletInfo.wallets.length === 0) {
319
- checks.push(check('wallets', 'info', 'No local wallets (only needed for trading and x402 micropayments)', 'Run: nansen wallet create <name>'));
319
+ checks.push(check('wallets', 'info', 'No local wallets (only needed for trading and x402 micropayments)', 'Run: nansen wallet create --name <name>'));
320
320
  } else {
321
321
  const defaultNote = walletInfo.defaultWallet ? `default: ${walletInfo.defaultWallet}` : 'no default set';
322
322
  checks.push(check('wallets', 'ok', `${walletInfo.wallets.length} wallet${walletInfo.wallets.length === 1 ? '' : 's'} in ${walletInfo.dir} (${defaultNote})`));
@@ -374,9 +374,18 @@ export function runDoctorChecks(deps = {}) {
374
374
  if (cliVersion) {
375
375
  const updateCache = readJson(path.join(getConfigDir(env), 'update-check.json'));
376
376
  if (updateCache?.latest) {
377
- checks.push(isNewer(updateCache.latest, cliVersion)
378
- ? check('cli-version', 'warn', `Update available: ${cliVersion} → ${updateCache.latest}`, 'Run: npm i -g nansen-cli')
379
- : check('cli-version', 'ok', `nansen-cli ${cliVersion} is up to date`));
377
+ const neededNode = nodeTooOldFor(updateCache.engines, nodeVersion);
378
+ if (!isNewer(updateCache.latest, cliVersion)) {
379
+ checks.push(check('cli-version', 'ok', `nansen-cli ${cliVersion} is up to date`));
380
+ } else if (neededNode) {
381
+ // npm only installs releases whose engines match the running Node, so
382
+ // a plain reinstall would land back on this version.
383
+ checks.push(check('cli-version', 'warn',
384
+ `Update available: ${cliVersion} → ${updateCache.latest}, but it requires Node >= ${neededNode} (you have ${nodeVersion})`,
385
+ `Install Node >= ${neededNode} (https://nodejs.org), then run: npm i -g nansen-cli`));
386
+ } else {
387
+ checks.push(check('cli-version', 'warn', `Update available: ${cliVersion} → ${updateCache.latest}`, 'Run: npm i -g nansen-cli'));
388
+ }
380
389
  } else {
381
390
  checks.push(check('cli-version', 'info', `nansen-cli ${cliVersion} (no update-check cache yet)`));
382
391
  }