nansen-cli 1.45.0 → 2.0.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 (85) hide show
  1. package/CHANGELOG.md +172 -0
  2. package/README.md +158 -18
  3. package/docs/browser-login.md +117 -0
  4. package/package.json +11 -2
  5. package/scripts/postinstall.js +35 -30
  6. package/skills/nansen-agent-guide/SKILL.md +13 -2
  7. package/skills/nansen-alerts-webhook-listener/SKILL.md +5 -2
  8. package/skills/nansen-dca-tracker/SKILL.md +10 -2
  9. package/skills/nansen-defi-positions/SKILL.md +5 -2
  10. package/skills/nansen-exit-signals/SKILL.md +10 -2
  11. package/skills/nansen-fund-tracker/SKILL.md +10 -2
  12. package/skills/nansen-general-search/SKILL.md +10 -2
  13. package/skills/nansen-holder-analysis/SKILL.md +10 -2
  14. package/skills/nansen-limit-orders/SKILL.md +6 -3
  15. package/skills/nansen-perp-screener/SKILL.md +10 -2
  16. package/skills/nansen-perp-trader-profile/SKILL.md +10 -2
  17. package/skills/nansen-polymarket-deep-dive/SKILL.md +10 -2
  18. package/skills/nansen-polymarket-insider-scan/SKILL.md +10 -2
  19. package/skills/nansen-polymarket-trader-profile/SKILL.md +10 -2
  20. package/skills/nansen-portfolio-tracker/SKILL.md +10 -2
  21. package/skills/nansen-prediction-markets/SKILL.md +10 -2
  22. package/skills/nansen-sm-cross-chain-flows/SKILL.md +10 -2
  23. package/skills/nansen-smart-alerts/SKILL.md +9 -4
  24. package/skills/nansen-smart-money-alpha/SKILL.md +10 -2
  25. package/skills/nansen-smart-money-tracker/SKILL.md +10 -2
  26. package/skills/nansen-smart-money-trend/SKILL.md +10 -2
  27. package/skills/nansen-token-research/SKILL.md +10 -2
  28. package/skills/nansen-token-screener/SKILL.md +14 -4
  29. package/skills/nansen-token-transfer-analysis/SKILL.md +10 -2
  30. package/skills/nansen-trading/SKILL.md +27 -2
  31. package/skills/nansen-wallet-batch/SKILL.md +10 -2
  32. package/skills/nansen-wallet-clustering/SKILL.md +10 -2
  33. package/skills/nansen-wallet-deep-dive/SKILL.md +10 -2
  34. package/skills/nansen-wallet-keychain-migration/SKILL.md +23 -15
  35. package/skills/nansen-wallet-manager/SKILL.md +26 -10
  36. package/skills/nansen-wallet-profiler/SKILL.md +10 -2
  37. package/skills/nansen-web-fetcher/SKILL.md +5 -2
  38. package/skills/nansen-web-searcher/SKILL.md +5 -2
  39. package/src/api.js +319 -129
  40. package/src/auth-browser.js +16 -0
  41. package/src/auth-credentials.js +73 -0
  42. package/src/auth-device.js +242 -0
  43. package/src/auth-key-input.js +46 -0
  44. package/src/auth-login.js +90 -0
  45. package/src/auth-state.js +487 -0
  46. package/src/auth-store-native.js +20 -0
  47. package/src/auth-store-worker.js +64 -0
  48. package/src/auth-store.js +140 -0
  49. package/src/auto-paginate.js +272 -0
  50. package/src/bridge.js +309 -85
  51. package/src/cache-inspect.js +345 -0
  52. package/src/chain-ids.js +1 -2
  53. package/src/cli.js +779 -286
  54. package/src/commands/agent.js +20 -9
  55. package/src/commands/alerts.js +1 -1
  56. package/src/commands/completion.js +2 -15
  57. package/src/commands/mcp.js +22 -20
  58. package/src/commands/research.js +4 -2
  59. package/src/cost-cache.js +16 -2
  60. package/src/debug.js +348 -0
  61. package/src/doctor.js +22 -45
  62. package/src/ens.js +3 -1
  63. package/src/execute-guard.js +116 -0
  64. package/src/hl-action.js +41 -13
  65. package/src/limit-order.js +9 -1
  66. package/src/mcp-client-config.js +169 -0
  67. package/src/mcp-client-config.json +17 -0
  68. package/src/mcp-verify.js +6 -5
  69. package/src/perp.js +61 -9
  70. package/src/privy.js +12 -12
  71. package/src/query-options.js +38 -6
  72. package/src/response-meta.js +57 -2
  73. package/src/rpc-urls.js +9 -11
  74. package/src/schema.json +309 -30
  75. package/src/semver.js +23 -4
  76. package/src/swap-simulation.js +35 -30
  77. package/src/telemetry.js +20 -0
  78. package/src/trading.js +806 -40
  79. package/src/transfer.js +75 -9
  80. package/src/update-check.js +9 -1
  81. package/src/wallet.js +240 -20
  82. package/src/walletconnect-trading.js +29 -8
  83. package/src/walletconnect-x402.js +9 -5
  84. package/src/x402-svm.js +123 -64
  85. package/src/x402.js +46 -14
@@ -4,20 +4,20 @@
4
4
  */
5
5
 
6
6
  import crypto from 'crypto';
7
- import { NansenError, ErrorCode, statusToErrorCode, telemetryHeaders, packageVersion } from '../api.js';
7
+ import { NansenError, ErrorCode, statusToErrorCode, browserSessionError, browserSessionResponseMeta, telemetryHeaders, packageVersion } from '../api.js';
8
8
  import { getCostForEndpoint } from '../cost-cache.js';
9
9
  import { readResponseMeta } from '../response-meta.js';
10
10
 
11
11
  /**
12
12
  * Build standard request headers, matching apiInstance.request() conventions.
13
13
  */
14
- function buildHeaders(apiInstance) {
14
+ async function buildHeaders(apiInstance) {
15
15
  return {
16
16
  'Content-Type': 'application/json',
17
17
  'X-Client-Type': 'nansen-cli',
18
18
  'X-Client-Version': packageVersion,
19
19
  ...telemetryHeaders(),
20
- ...(apiInstance.apiKey ? { 'apikey': apiInstance.apiKey } : {}),
20
+ ...await apiInstance.requestCredentials(),
21
21
  ...(apiInstance.defaultHeaders || {}),
22
22
  };
23
23
  }
@@ -74,8 +74,11 @@ export async function consumeSSEStream(response, callbacks = {}) {
74
74
 
75
75
  const processFrame = (frame) => {
76
76
  for (const line of frame.split('\n')) {
77
- if (!line.startsWith('data: ')) continue;
78
- const payload = line.slice(6);
77
+ if (!line.startsWith('data:')) continue;
78
+ // SSE permits `data:value` and `data: value`; discard at most the one
79
+ // optional space after the colon before parsing the field value.
80
+ const fieldValue = line.slice(5);
81
+ const payload = fieldValue.startsWith(' ') ? fieldValue.slice(1) : fieldValue;
79
82
  if (payload === '[DONE]') { done = true; return; }
80
83
 
81
84
  let event;
@@ -239,7 +242,7 @@ EXAMPLES:
239
242
  }
240
243
 
241
244
  // ── Auth guard ──
242
- if (!apiInstance.apiKey) {
245
+ if (apiInstance.selection?.kind === 'anonymous') {
243
246
  throw new NansenError(
244
247
  'Not logged in. Run: nansen login',
245
248
  ErrorCode.UNAUTHORIZED,
@@ -249,12 +252,15 @@ EXAMPLES:
249
252
  }
250
253
 
251
254
  // ── Request (no retry — SSE streams are not idempotent) ──
255
+ const sessionAuth = apiInstance.selection?.kind === 'session';
252
256
  const url = `${apiInstance.baseUrl}${endpoint}`;
253
257
  const body = {
254
258
  text: question,
255
259
  conversation_id: conversationId,
256
260
  };
257
261
 
262
+ const requestHeaders = await buildHeaders(apiInstance);
263
+
258
264
  // ── Timeout ──
259
265
  const timeoutMs = expert ? 300_000 : 120_000; // 5min expert, 2min fast
260
266
  const controller = new AbortController();
@@ -268,7 +274,7 @@ EXAMPLES:
268
274
  // forwards custom credential headers (apikey) across a cross-origin
269
275
  // redirect, handing the key to whatever host the response points at.
270
276
  redirect: 'error',
271
- headers: buildHeaders(apiInstance),
277
+ headers: requestHeaders,
272
278
  body: JSON.stringify(body),
273
279
  signal: controller.signal,
274
280
  });
@@ -283,10 +289,10 @@ EXAMPLES:
283
289
  );
284
290
  }
285
291
  throw new NansenError(
286
- `Network error: ${err.message}`,
292
+ sessionAuth ? 'Agent network request failed. Retry after checking connectivity.' : `Network error: ${err.message}`,
287
293
  ErrorCode.NETWORK_ERROR,
288
294
  null,
289
- { originalError: err.message },
295
+ sessionAuth ? {} : { originalError: err.message },
290
296
  );
291
297
  }
292
298
 
@@ -300,6 +306,10 @@ EXAMPLES:
300
306
  serverDetail = errData.detail || errData.message;
301
307
  } catch { /* ignore parse failure */ }
302
308
  }
309
+ if (sessionAuth) {
310
+ const safe = browserSessionError(response.status, errData);
311
+ throw new NansenError(safe.message, safe.code, response.status, browserSessionResponseMeta(response));
312
+ }
303
313
  const meta = readResponseMeta(response);
304
314
  throwApiError(
305
315
  serverDetail || `Agent returned ${response.status}`,
@@ -321,6 +331,7 @@ EXAMPLES:
321
331
  { detail: `${modeName} mode timeout (${timeoutMs / 1000}s)` },
322
332
  );
323
333
  }
334
+ if (sessionAuth) throw new NansenError('Agent stream failed. The selected browser session was not replaced.', err.code || ErrorCode.NETWORK_ERROR, err.status || null);
324
335
  throw err;
325
336
  };
326
337
 
@@ -132,7 +132,7 @@ function parseFiniteNumber(raw, name) {
132
132
  /**
133
133
  * Validate a single-value string filter option (e.g. --chain, --token-address).
134
134
  * Empty string/undefined mean "not provided"; any other non-string value
135
- * (e.g. `--chain true`, from parseArgs' JSON.parse of option values) is
135
+ * (e.g. `--chain '{}'`, from parseArgs' JSON.parse of option values) is
136
136
  * rejected instead of crashing on .toLowerCase() or being silently dropped
137
137
  * by a falsy check.
138
138
  */
@@ -19,28 +19,15 @@ const { version: VERSION } = require('../../package.json');
19
19
  export const COMPLETION_SHELLS = ['bash', 'zsh', 'fish'];
20
20
 
21
21
  /**
22
- * Commands the CLI dispatches that schema.json does not describe. Adding them
23
- * to schema.json instead would change `nansen logout --help` (the schema help
24
- * path runs before the hand-written text), so they are declared here.
22
+ * Commands the CLI dispatches that schema.json does not describe. They retain
23
+ * their hand-written help; the schema help path otherwise takes precedence.
25
24
  * completion.test.js fails if a new top-level command appears in neither place.
26
25
  */
27
26
  export const UNSCHEMA_COMMANDS = {
28
- login: {
29
- description: 'Save your Nansen API key',
30
- options: {
31
- 'api-key': { type: 'string', description: 'API key (recorded in shell history — prefer --human)' },
32
- human: { type: 'boolean', description: 'Prompt for the key interactively' },
33
- },
34
- },
35
- logout: { description: 'Remove the saved API key' },
36
27
  schema: {
37
28
  description: 'Print the JSON schema for every command',
38
29
  options: { full: { type: 'boolean', description: 'Verbose schema instead of the compact listing' } },
39
30
  },
40
- cache: {
41
- description: 'API response cache maintenance',
42
- subcommands: { clear: { description: 'Clear all cached responses' } },
43
- },
44
31
  changelog: {
45
32
  description: 'Show release history',
46
33
  options: { since: { type: 'string', description: 'Only show versions at or above this one' } },
@@ -8,22 +8,27 @@
8
8
 
9
9
  import { CommandError } from '../api.js';
10
10
  import { DEFAULT_MCP_URL, formatMcpVerifyReport, runMcpVerifyChecks } from '../mcp-verify.js';
11
+ import { MCP_CLIENT_CONFIG, buildHttpEntry, buildStdioEntry, mcpRemoteSpec } from '../mcp-client-config.js';
11
12
  import fs from 'fs';
12
13
  import os from 'os';
13
14
  import path from 'path';
14
15
 
16
+ // All values below come from src/mcp-client-config.json (API-322), the one
17
+ // maintained source that the README, the GitBook page and the .dxt manifest
18
+ // are generated from. Edit that file, not these constants.
19
+
15
20
  // Hosted Nansen MCP server (streamable HTTP, auth via NANSEN-API-KEY header).
16
- // Deliberately a constant: a user-supplied URL would let `install` write the
17
- // API key into a config that sends it to an arbitrary host. NANSEN_BASE_URL
18
- // (REST dev override) intentionally does not affect this.
19
- export const NANSEN_MCP_URL = 'https://mcp.nansen.ai/ra/mcp';
21
+ // Deliberately not user-configurable: a user-supplied URL would let `install`
22
+ // write the API key into a config that sends it to an arbitrary host.
23
+ // NANSEN_BASE_URL (REST dev override) intentionally does not affect this.
24
+ export const NANSEN_MCP_URL = MCP_CLIENT_CONFIG.endpoint;
20
25
 
21
26
  // Claude Desktop's config only supports stdio servers, so it bridges through
22
27
  // mcp-remote. Pinned exact so `npx -y` never auto-pulls a compromised future
23
- // release; bump deliberately.
24
- export const MCP_REMOTE_PIN = 'mcp-remote@0.2.1';
28
+ // release; bump deliberately (see AGENTS.md > MCP client config).
29
+ export const MCP_REMOTE_PIN = mcpRemoteSpec();
25
30
 
26
- const SERVER_KEY = 'nansen';
31
+ const SERVER_KEY = MCP_CLIENT_CONFIG.serverKey;
27
32
 
28
33
  // House idiom (see src/api.js CONFIG_DIR): env first so tests can point HOME
29
34
  // at a temp dir; os.homedir() as last resort.
@@ -49,8 +54,8 @@ OPTIONS:
49
54
  --send-api-key Authorize sending your saved API key to a custom --url
50
55
  (an https:// or loopback host). Not needed for --api-key.
51
56
 
52
- The API key is taken from \`nansen login\` / NANSEN_API_KEY. Re-run install after
53
- rotating your key to update the entry. Other clients: https://docs.nansen.ai/mcp/connecting`;
57
+ The API key is taken from \`nansen login --human\` / NANSEN_API_KEY. Re-run install after
58
+ rotating your key to update the entry. Other clients: ${MCP_CLIENT_CONFIG.docsUrl}`;
54
59
 
55
60
  /**
56
61
  * Resolve the client's config file path for this platform.
@@ -83,16 +88,17 @@ export function buildServerEntry(client, apiKey) {
83
88
  switch (client) {
84
89
  case 'claude-code':
85
90
  // "type" is required — a url without type is treated as broken stdio and skipped
86
- return { type: 'http', url: NANSEN_MCP_URL, headers: { 'NANSEN-API-KEY': apiKey } };
91
+ return buildHttpEntry(apiKey, { withType: true });
87
92
  case 'cursor':
88
- return { url: NANSEN_MCP_URL, headers: { 'NANSEN-API-KEY': apiKey } };
93
+ return buildHttpEntry(apiKey);
89
94
  case 'claude-desktop':
90
95
  // Header name and value must be one arg. mcp-remote parses with
91
96
  // /^([A-Za-z0-9_-]+):\s*(.*)$/, so whitespace after the colon is trimmed;
92
97
  // what breaks it is an empty value.
93
98
  // The ${NANSEN_API_KEY} placeholder is NOT shell syntax: mcp-remote itself
94
99
  // substitutes ${VAR} in header values from its process env — see
95
- // mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576
100
+ // mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576 (re-check this
101
+ // behavior before a pin bump; see AGENTS.md > MCP client config)
96
102
  // (`value.replace(/\$\{([^}]+)}/g, ...)`, logging "Replacing ${...} with
97
103
  // environment value in header"). Claude Desktop injects the `env` block
98
104
  // into the spawned npx process, mcp-remote expands the reference, and the
@@ -100,11 +106,7 @@ export function buildServerEntry(client, apiKey) {
100
106
  // the exact written config connects to prod with the substitution logged.
101
107
  // Do NOT "fix" this by inlining the key into args.
102
108
  // No --allow-http: the URL is HTTPS.
103
- return {
104
- command: 'npx',
105
- args: ['-y', MCP_REMOTE_PIN, NANSEN_MCP_URL, '--header', 'NANSEN-API-KEY:${NANSEN_API_KEY}'],
106
- env: { NANSEN_API_KEY: apiKey },
107
- };
109
+ return buildStdioEntry(apiKey);
108
110
  default:
109
111
  throw new CommandError(`Unknown client: ${client}. Supported: ${SUPPORTED_CLIENTS.join(', ')}`, 'INVALID_PARAMS');
110
112
  }
@@ -233,8 +235,8 @@ export function buildMcpCommands(deps = {}) {
233
235
  if (flags['api-key']) {
234
236
  throw new CommandError('--api-key requires a value. Usage: nansen mcp verify --api-key <key>', 'MISSING_PARAM');
235
237
  }
236
- // parseArgs JSON-parses option values, so `--api-key null` arrives as
237
- // null and a repeated flag as an array - both must fail, not fall back.
238
+ // parseArgs turns a repeated flag into an array and a JSON object/array
239
+ // value into an object - both must fail, not fall back.
238
240
  if ('api-key' in options && typeof options['api-key'] !== 'string') {
239
241
  throw new CommandError('--api-key must be a single key string. Usage: nansen mcp verify --api-key <key>', 'INVALID_PARAMS');
240
242
  }
@@ -356,7 +358,7 @@ export function buildMcpCommands(deps = {}) {
356
358
  // install
357
359
  const apiKey = apiInstance?.apiKey;
358
360
  if (!apiKey) {
359
- throw new CommandError('Not logged in. Run: nansen login', 'NOT_LOGGED_IN');
361
+ throw new CommandError('MCP installation requires an API key. Set NANSEN_API_KEY or run nansen login --human. Browser sessions are not exported to MCP clients.', 'API_KEY_REQUIRED');
360
362
  }
361
363
 
362
364
  // Deliberate asymmetry with uninstall --dry-run (which previews even an
@@ -5,7 +5,7 @@
5
5
  */
6
6
 
7
7
  import { NansenError, ErrorCode } from '../api.js';
8
- import { parseSort, rejectBlankOption } from '../query-options.js';
8
+ import { parseSort, rejectBlankOption, parseObjectOption } from '../query-options.js';
9
9
 
10
10
  // Research subcommands validate --page strictly. The shared helper in
11
11
  // src/query-options.js clamps an invalid page to 1 for the category commands,
@@ -79,6 +79,8 @@ function parseTimeframeDays(value) {
79
79
  function parseBooleanOption(options, flags, key) {
80
80
  const value = options[key] ?? flags[key];
81
81
  if (value === undefined) return undefined;
82
+ // Bare flags arrive through `flags` as true; explicit values arrive through
83
+ // `options` as strings (for example, `--apply-blacklist-filter false`).
82
84
  if (typeof value === 'boolean') return value;
83
85
  if (value === 'true' || value === '1') return true;
84
86
  if (value === 'false' || value === '0') return false;
@@ -254,7 +256,7 @@ export function buildResearchCommands(deps = {}) {
254
256
 
255
257
  const orderBy = parseSort(options.sort, options['order-by']);
256
258
  const pagination = buildPagination(options);
257
- const filters = options.filters || {};
259
+ const filters = parseObjectOption(options.filters, 'filters');
258
260
  const { fromDate, toDate } = resolveDateRange(options);
259
261
  const asOfDate = options['as-of-date'];
260
262
 
package/src/cost-cache.js CHANGED
@@ -14,6 +14,14 @@ const CACHE_FILE = path.join(CONFIG_DIR, 'cost-map.json');
14
14
  const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
15
15
  const OPENAPI_URL = 'https://api.nansen.ai/openapi.json';
16
16
 
17
+ /** How long a fetched cost map stays fresh. */
18
+ export const COST_MAP_TTL_MS = STALE_MS;
19
+
20
+ /** Absolute path of the cost map cache file, for `nansen cache stats` and `clear`. */
21
+ export function getCostMapFile() {
22
+ return CACHE_FILE;
23
+ }
24
+
17
25
  /**
18
26
  * Write `data` to `file` atomically: write to a unique temp file in the same
19
27
  * directory, then rename over the target. rename(2) is atomic on POSIX, so a
@@ -55,7 +63,13 @@ export function getCostForEndpoint(endpoint) {
55
63
  export function creditsCharged(meta, endpoint) {
56
64
  const charged = meta?.credits?.cost;
57
65
  if (charged != null) return { cost: charged, source: 'header' };
58
- const estimate = endpoint ? getCostForEndpoint(endpoint) : null;
66
+ let estimate = endpoint ? getCostForEndpoint(endpoint) : null;
67
+ const livePages = meta?.pagination?.livePages;
68
+ if (estimate != null && Number.isSafeInteger(livePages) && livePages > 1) {
69
+ estimate = Object.fromEntries(
70
+ Object.entries(estimate).map(([plan, cost]) => [plan, typeof cost === 'number' ? cost * livePages : cost])
71
+ );
72
+ }
59
73
  if (estimate != null) return { estimate, source: 'estimate' };
60
74
  return null;
61
75
  }
@@ -69,7 +83,7 @@ export async function refreshCostMapIfStale() {
69
83
  try {
70
84
  if (fs.existsSync(CACHE_FILE)) {
71
85
  const { fetchedAt } = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
72
- if (fetchedAt && Date.now() - fetchedAt < STALE_MS) return;
86
+ if (Number.isFinite(fetchedAt) && fetchedAt !== 0 && Date.now() - fetchedAt < STALE_MS) return;
73
87
  }
74
88
 
75
89
  const controller = new AbortController();
package/src/debug.js ADDED
@@ -0,0 +1,348 @@
1
+ /**
2
+ * Opt-in HTTP request tracing for the CLI.
3
+ *
4
+ * Turned on by the global `--debug` flag (which calls setDebugEnabled) or by
5
+ * `NANSEN_DEBUG=1` in the environment. The generic `DEBUG` variable is not
6
+ * consulted: other packages commonly use it, and enabling HTTP tracing must
7
+ * always be an explicit Nansen choice.
8
+ *
9
+ * Everything is written to **stderr**, never stdout. stdout carries the JSON
10
+ * or CSV that callers pipe into other programs, and a trace line in that
11
+ * stream would corrupt it.
12
+ *
13
+ * Nothing here ever prints a credential. Request and response bodies are never
14
+ * traced at all, header values are never traced, URLs go through redactUrl(),
15
+ * and every value handed to trace() goes through redact() first. Redaction is
16
+ * deliberately over-eager: an over-redacted value costs one support round
17
+ * trip, a leaked one costs a key rotation.
18
+ */
19
+
20
+ /** Placeholder written in place of anything that might be a credential. */
21
+ export const REDACTED = '[redacted]';
22
+
23
+ /** Longest traced value; anything longer is cut and marked. */
24
+ export const MAX_VALUE_LENGTH = 200;
25
+
26
+ /**
27
+ * Field/parameter/header names whose value is never safe to print.
28
+ * Matches substrings, so `apikey`, `X-Api-Key`, `authorization`,
29
+ * `payment-signature` and `token_address` are all covered — the last one is
30
+ * not a secret, but fail-closed is the right side to err on here.
31
+ */
32
+ const SECRET_NAME = /key|token|secret|signature|password|passphrase|mnemonic|seed|auth|credential|cookie|private/i;
33
+
34
+ /**
35
+ * A credential carried inline in a header-ish string, e.g. `Bearer eyJ...`.
36
+ * Two copies on purpose: a /g regex carries lastIndex between .test() calls,
37
+ * so the matcher and the replacer must not be the same object.
38
+ */
39
+ // Only `Bearer`/`Basic` introduce an inline credential in text we trace. `Payment`
40
+ // and `Signature` are ordinary English words here, and header-name matching plus the
41
+ // value-shape rules below already cover a real payment signature — keeping them in
42
+ // this pattern only garbled prose like "payment was transmitted".
43
+ // The value must look like a credential (8+ chars) so "Bearer token" stays readable.
44
+ // Keep this matcher stateless (no /g): looksLikeSecretValue calls .test() on
45
+ // it, while INLINE_SCHEME_ALL below is the separate global replacement copy.
46
+ const INLINE_SCHEME = /\b(Bearer|Basic)\s+[\w.~+/=-]{8,}/i;
47
+ const INLINE_SCHEME_ALL = new RegExp(INLINE_SCHEME.source, 'gi');
48
+
49
+ /** Request ids and other UUIDs are identifiers, not secrets — keep them readable. */
50
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
51
+
52
+ /** Private-key shaped: 32 bytes of hex, with or without the 0x prefix. */
53
+ const HEX_32_BYTES = /^(0x)?[0-9a-fA-F]{64}$/;
54
+
55
+ /**
56
+ * BIP-39 shaped: 12–24 lowercase words. Intentionally covers non-standard
57
+ * counts between the valid BIP-39 sizes too; over-redacting prose is safer
58
+ * than letting a malformed or partially copied recovery phrase through.
59
+ */
60
+ const MNEMONIC = /^([a-z]{3,10} ){11,23}[a-z]{3,10}$/;
61
+
62
+ /** JWT shaped: three dot-separated base64url segments starting with a JSON header. */
63
+ const JWT = /^ey[\w-]{8,}\.[\w-]{4,}\.[\w-]+$/;
64
+
65
+ /** Base58 secret-key shaped (Solana keypairs are ~88 chars; addresses are ≤44). */
66
+ const LONG_BASE58 = /^[1-9A-HJ-NP-Za-km-z]{80,}$/;
67
+
68
+ /**
69
+ * Long opaque blob — an encoded payment payload, an API key, a session token.
70
+ * The 64-character floor keeps public identifiers readable: EVM addresses are
71
+ * 42 characters and base58 mint addresses at most 44.
72
+ */
73
+ const LONG_OPAQUE = /^[A-Za-z0-9_\-+/=.]{64,}$/;
74
+
75
+ /**
76
+ * Credential-shaped substrings inside otherwise useful diagnostic prose.
77
+ *
78
+ * IMPORTANT: every module-level /g regex in this block, plus
79
+ * INLINE_SCHEME_ALL above, is replacement-only. Use these only with
80
+ * String.prototype.replace — never RegExp.test() or RegExp.exec(), whose
81
+ * stateful lastIndex would make results depend on earlier trace calls. Add a
82
+ * separate non-/g matcher (as INLINE_SCHEME does) if matching is ever needed.
83
+ */
84
+ const EMBEDDED_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi;
85
+ const EMBEDDED_NAMED_SECRET = /\b([\w-]*(?:key|token|secret|signature|password|passphrase|mnemonic|seed|auth|credential|cookie|private)[\w-]*)\s*([=:])\s*([^\s,;]+)/gi;
86
+ const EMBEDDED_HEX_32_BYTES = /(?<![0-9a-fA-F])(?:0x)?[0-9a-fA-F]{64}(?![0-9a-fA-F])/g;
87
+ const EMBEDDED_JWT = /\bey[\w-]{8,}\.[\w-]{4,}\.[\w-]+\b/g;
88
+ // NOTE: This intentionally also hides public long identifiers in error prose
89
+ // (for example Solana transaction signatures and block hashes). See README
90
+ // "Debugging"; do not loosen the threshold without auditing credential leaks.
91
+ const EMBEDDED_LONG_OPAQUE = /(?<![A-Za-z0-9_\-+/=.])[A-Za-z0-9_\-+/=.]{64,}(?![A-Za-z0-9_\-+/=.])/g;
92
+
93
+ let forcedEnabled = null;
94
+ let writer = null;
95
+
96
+ /**
97
+ * Force tracing on or off for the process, overriding the environment.
98
+ * Pass undefined to hand control back to NANSEN_DEBUG.
99
+ */
100
+ export function setDebugEnabled(enabled) {
101
+ forcedEnabled = enabled === undefined ? null : Boolean(enabled);
102
+ }
103
+
104
+ /** Replace the stderr sink. Pass undefined to restore it. Tests only. */
105
+ export function setDebugWriter(fn) {
106
+ writer = typeof fn === 'function' ? fn : null;
107
+ }
108
+
109
+ function envEnabled(value) {
110
+ if (value === undefined || value === null) return false;
111
+ const normalized = String(value).trim().toLowerCase();
112
+ if (normalized === '') return false;
113
+ return !['0', 'false', 'no', 'off'].includes(normalized);
114
+ }
115
+
116
+ export function isDebugEnabled() {
117
+ if (forcedEnabled !== null) return forcedEnabled;
118
+ return envEnabled(process.env.NANSEN_DEBUG);
119
+ }
120
+
121
+ /** Cut a value to MAX_VALUE_LENGTH, marking that it was cut. */
122
+ export function truncate(value, max = MAX_VALUE_LENGTH) {
123
+ const text = String(value);
124
+ if (text.length <= max) return text;
125
+ return `${text.slice(0, max)}…(+${text.length - max} more)`;
126
+ }
127
+
128
+ /** Whether a field, query parameter, or header name names a credential. */
129
+ export function isSecretName(name) {
130
+ return SECRET_NAME.test(String(name ?? ''));
131
+ }
132
+
133
+ /**
134
+ * Whether a value looks like a credential regardless of what it is called —
135
+ * a private key, a mnemonic, a JWT, an encoded payment payload.
136
+ */
137
+ export function looksLikeSecretValue(value) {
138
+ if (typeof value !== 'string') return false;
139
+ const text = value.trim();
140
+ if (text === '' || UUID.test(text)) return false;
141
+ return (
142
+ HEX_32_BYTES.test(text) ||
143
+ MNEMONIC.test(text) ||
144
+ JWT.test(text) ||
145
+ LONG_BASE58.test(text) ||
146
+ LONG_OPAQUE.test(text) ||
147
+ INLINE_SCHEME.test(text)
148
+ );
149
+ }
150
+
151
+ function redactString(value) {
152
+ // Delegate only when the whole value is a URL. URL-prefixed diagnostic
153
+ // prose must still pass through the embedded Bearer/JWT/secret scrubbers.
154
+ if (/^[a-z][a-z0-9+.-]*:\/\/\S+$/i.test(value)) return redactUrl(value);
155
+ // Drop inline credentials first, keeping the scheme label ("Bearer …") so
156
+ // the trace still says what kind of credential was in play. Doing this
157
+ // before the shape checks keeps the surrounding prose readable.
158
+ const neutralized = value
159
+ .replace(EMBEDDED_URL, match => redactUrl(match))
160
+ .replace(INLINE_SCHEME_ALL, (_match, kind) => `${kind} ${REDACTED}`)
161
+ .replace(EMBEDDED_NAMED_SECRET, (_match, name, separator) => `${name}${separator}${REDACTED}`)
162
+ .replace(EMBEDDED_HEX_32_BYTES, REDACTED)
163
+ .replace(EMBEDDED_JWT, REDACTED)
164
+ .replace(EMBEDDED_LONG_OPAQUE, REDACTED);
165
+ if (neutralized !== value) return truncate(neutralized);
166
+ return looksLikeSecretValue(neutralized) ? REDACTED : truncate(neutralized);
167
+ }
168
+
169
+ /**
170
+ * Redact a string, array, or (possibly nested) object for tracing.
171
+ * Values under a secret-looking key are replaced wholesale; every other value
172
+ * is still checked for credential-shaped content and truncated.
173
+ */
174
+ export function redact(value, seen = new WeakSet()) {
175
+ if (value === null || value === undefined) return value;
176
+ if (typeof value === 'string') return redactString(value);
177
+ if (typeof value === 'number' || typeof value === 'boolean') return value;
178
+ if (typeof value === 'bigint') return `${value}`;
179
+ if (ArrayBuffer.isView(value)) {
180
+ return `[${value.constructor?.name || 'TypedArray'} ${value.byteLength} bytes]`;
181
+ }
182
+ if (value instanceof ArrayBuffer) return `[ArrayBuffer ${value.byteLength} bytes]`;
183
+ if (Array.isArray(value)) return value.map((item) => redact(item, seen));
184
+ if (typeof value === 'object') {
185
+ if (seen.has(value)) return '[circular]';
186
+ seen.add(value);
187
+ const out = {};
188
+ for (const [key, item] of Object.entries(value)) {
189
+ out[key] = isSecretName(key) ? REDACTED : redact(item, seen);
190
+ }
191
+ return out;
192
+ }
193
+ return truncate(String(value));
194
+ }
195
+
196
+ /**
197
+ * Redact a URL: drop any userinfo and fragment, sanitize path segments, blank out query values
198
+ * whose parameter is credential-named, and blank out any remaining value that
199
+ * looks like a credential. Path segments that look credential-related are
200
+ * withheld because reset/session/payment credentials are often put there.
201
+ */
202
+ export function redactUrl(raw) {
203
+ const text = String(raw ?? '');
204
+ let url;
205
+ try {
206
+ url = new URL(text);
207
+ } catch {
208
+ // Not parseable (a relative path, or a malformed URL). Fall back to a
209
+ // textual pass over the query string so nothing leaks from the odd case.
210
+ const queryIndex = text.indexOf('?');
211
+ if (queryIndex === -1) return truncate(text);
212
+ const base = text.slice(0, queryIndex);
213
+ const query = text.slice(queryIndex + 1);
214
+ return truncate(`${base}?${redactQueryText(query)}`);
215
+ }
216
+
217
+ const parts = [];
218
+ for (const [key, value] of url.searchParams.entries()) {
219
+ const safe = isSecretName(key) || looksLikeSecretValue(value);
220
+ parts.push(`${encodeURIComponent(key)}=${safe ? REDACTED : encodeURIComponent(value)}`);
221
+ }
222
+
223
+ const credentials = url.username || url.password ? `${REDACTED}@` : '';
224
+ const query = parts.length ? `?${parts.join('&')}` : '';
225
+ const path = url.pathname.split('/').map((segment) => {
226
+ let decoded = segment;
227
+ try { decoded = decodeURIComponent(segment); } catch { /* keep raw text */ }
228
+ // Short path names describe API resources (`token-screener`, `auth`)
229
+ // rather than naming a value, so SECRET_NAME alone would hide the endpoint
230
+ // users need to diagnose. Long secret-named or credential-shaped dynamic
231
+ // segments still fail closed.
232
+ return looksLikeSecretValue(decoded) || (decoded.length >= 32 && isSecretName(decoded))
233
+ ? REDACTED
234
+ : segment;
235
+ }).join('/');
236
+ return truncate(`${url.protocol}//${credentials}${url.host}${path}${query}`);
237
+ }
238
+
239
+ function redactQueryText(query) {
240
+ return query
241
+ .split('&')
242
+ .map((pair) => {
243
+ const index = pair.indexOf('=');
244
+ if (index === -1) return pair;
245
+ const key = pair.slice(0, index);
246
+ const value = pair.slice(index + 1);
247
+ let decoded = value;
248
+ try { decoded = decodeURIComponent(value); } catch { /* keep malformed encoding readable */ }
249
+ if (isSecretName(key)) return `${key}=${REDACTED}`;
250
+ const safe = redactString(decoded);
251
+ return `${key}=${safe === decoded ? value : safe}`;
252
+ })
253
+ .join('&');
254
+ }
255
+
256
+ /**
257
+ * Redact a header bag (plain object, Map, or fetch Headers) down to names
258
+ * only. Header values are never traced: even the innocuous ones carry nothing
259
+ * worth the risk of a rule that misses one. Production traces currently omit
260
+ * headers entirely; this is exported as the mandatory boundary if a future
261
+ * trace event ever includes header names.
262
+ */
263
+ export function redactHeaders(headers) {
264
+ const entries = typeof headers?.entries === 'function' ? [...headers.entries()] : Object.entries(headers ?? {});
265
+ const out = {};
266
+ for (const [name] of entries) out[name] = REDACTED;
267
+ return out;
268
+ }
269
+
270
+ function formatValue(key, value) {
271
+ const safe = key === 'url' ? redactUrl(value) : redact(value);
272
+ const text = typeof safe === 'object' ? JSON.stringify(safe) : String(safe);
273
+ const bounded = truncate(text);
274
+ return /[\s"]/.test(bounded) ? JSON.stringify(bounded) : bounded;
275
+ }
276
+
277
+ function write(line) {
278
+ if (writer) writer(line);
279
+ else process.stderr.write(line);
280
+ }
281
+
282
+ /**
283
+ * Emit one trace line. No-op unless tracing is enabled.
284
+ * Fields are rendered as `key=value`, in the order given, with null and
285
+ * undefined fields dropped.
286
+ */
287
+ export function trace(event, fields = {}) {
288
+ if (!isDebugEnabled()) return;
289
+ const parts = [`[nansen:debug] ${event}`];
290
+ for (const [key, value] of Object.entries(fields)) {
291
+ if (value === undefined || value === null) continue;
292
+ parts.push(`${key}=${formatValue(key, value)}`);
293
+ }
294
+ write(`${parts.join(' ')}\n`);
295
+ }
296
+
297
+ /** An HTTP request is about to go out. */
298
+ export function traceRequest({ method, url, attempt, maxAttempts, payment }) {
299
+ trace('http.request', {
300
+ method,
301
+ url,
302
+ attempt: maxAttempts ? `${attempt}/${maxAttempts}` : attempt,
303
+ payment,
304
+ });
305
+ }
306
+
307
+ /**
308
+ * Response headers arrived. `duration_ms` is time from attempt start until
309
+ * fetch resolves with headers (time to first byte / TTFB); it deliberately
310
+ * excludes downloading and parsing the response body.
311
+ */
312
+ export function traceResponse({ method, url, status, durationMs, requestId, attempt, payment }) {
313
+ trace('http.response', {
314
+ method,
315
+ url,
316
+ status,
317
+ duration_ms: durationMs,
318
+ request_id: requestId,
319
+ attempt,
320
+ payment,
321
+ });
322
+ }
323
+
324
+ /**
325
+ * The request never produced response headers. `duration_ms` is elapsed time
326
+ * from attempt start until the transport failure.
327
+ */
328
+ export function traceError({ method, url, durationMs, attempt, error }) {
329
+ trace('http.error', { method, url, duration_ms: durationMs, attempt, error });
330
+ }
331
+
332
+ /** A retry was decided on: which attempt failed, why, and how long we wait. */
333
+ export function traceRetry({ method, url, status, attempt, reason, delayMs, retryAfterMs }) {
334
+ trace('http.retry', {
335
+ method,
336
+ url,
337
+ status,
338
+ attempt,
339
+ reason,
340
+ delay_ms: delayMs === undefined || delayMs === null ? null : Math.round(delayMs),
341
+ retry_after_ms: retryAfterMs,
342
+ });
343
+ }
344
+
345
+ /** The response came from the local cache, so no request was made at all. */
346
+ export function traceCacheHit({ method, url }) {
347
+ trace('http.cache_hit', { method, url });
348
+ }