nansen-cli 2.2.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 (78) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +109 -33
  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 +54 -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 +336 -121
  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 +258 -107
  50. package/src/commands/agent.js +2 -3
  51. package/src/commands/alerts.js +277 -9
  52. package/src/commands/completion.js +6 -1
  53. package/src/commands/feedback.js +413 -0
  54. package/src/commands/mcp.js +1 -1
  55. package/src/commands/research.js +14 -37
  56. package/src/cost-cache.js +33 -7
  57. package/src/doctor.js +14 -5
  58. package/src/error-codes.js +226 -0
  59. package/src/feedback-journal.js +86 -0
  60. package/src/input-validation.js +551 -0
  61. package/src/limit-order.js +12 -3
  62. package/src/perp.js +2 -1
  63. package/src/privy.js +144 -48
  64. package/src/query-options.js +30 -7
  65. package/src/rpc-urls.js +3 -1
  66. package/src/schema.json +1254 -150
  67. package/src/solana-tx.js +4 -0
  68. package/src/telemetry.js +5 -1
  69. package/src/trade-validation.js +190 -21
  70. package/src/trading.js +229 -129
  71. package/src/transfer.js +7 -1
  72. package/src/update-check.js +32 -5
  73. package/src/wallet.js +220 -57
  74. package/src/walletconnect-x402.js +152 -52
  75. package/src/x402-audit.js +191 -0
  76. package/src/x402-payment-balance.js +90 -0
  77. package/src/x402-policy.js +151 -4
  78. package/src/x402.js +51 -22
@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
5
5
  import { readLocalFile } from './local-file.js';
6
6
 
7
7
  export const DEFAULT_API_ORIGIN = 'https://api.nansen.ai';
8
+ export const ENV_API_KEY_GUIDANCE = "You can still use the CLI with an API key. Get your API key from https://app.nansen.ai/api. On macOS/Linux, run: export NANSEN_API_KEY='<your-api-key>'. On Windows PowerShell, run: $env:NANSEN_API_KEY = '<your-api-key>'. Then check access with: nansen account. This works without a credential store or native authentication locking. You don't need to run nansen login. The variable stays set for this terminal session. For CI or automation, supply NANSEN_API_KEY through your platform's secret manager.";
8
9
  const DEV_CONFIG = fileURLToPath(new URL('../config.json', import.meta.url));
9
10
  export class AuthError extends Error {
10
11
  constructor(code, message) { super(message); this.code = code; }
package/src/auth-state.js CHANGED
@@ -2,7 +2,7 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { randomUUID } from 'node:crypto';
4
4
  import { setTimeout as delay } from 'node:timers/promises';
5
- import { AuthError, authDirectory, validAuthPointer } from './auth-credentials.js';
5
+ import { AuthError, authDirectory, validAuthPointer, ENV_API_KEY_GUIDANCE } from './auth-credentials.js';
6
6
  import { createAuthStore } from './auth-store.js';
7
7
  import { refreshSession, retireSession, validateSession } from './auth-device.js';
8
8
  import { openLocalFile, readLocalFile } from './local-file.js';
@@ -78,7 +78,7 @@ async function waitTurn(previous, signal) {
78
78
  }
79
79
  async function loadLocks() {
80
80
  try { return (await import('fs-native-extensions')).default; }
81
- catch { throw new AuthError('AUTH_LOCK_UNAVAILABLE', 'Native authentication locking is unavailable. Reinstall nansen-cli with optional dependencies; if they are installed, this platform may lack a compatible fs-native-extensions prebuild. Legacy key setup and logout require this binding. Environment API keys still work. For offline saved-key removal, stop every CLI/auth process, then follow docs/browser-login.md#offline-recovery-without-native-locking. Do not delete auth journals or wallet files.'); }
81
+ catch { throw new AuthError('AUTH_LOCK_UNAVAILABLE', `Native authentication locking is unavailable. ${ENV_API_KEY_GUIDANCE} Saved login and logout require this binding. Reinstall nansen-cli with optional dependencies; if they are installed, this platform may lack a compatible fs-native-extensions prebuild. For offline saved-key removal, stop every CLI/auth process, then follow docs/browser-login.md#offline-recovery-without-native-locking. Do not delete auth journals or wallet files.`); }
82
82
  }
83
83
  export function createAuthState({ directory = authDirectory(), store = createAuthStore({ directory }), retire = retireSession, refresh = refreshSession, now = Date.now, barrier = async () => {}, locks = loadLocks, waitMs = 15000, operationMs = 60000 } = {}) {
84
84
  let operationSignal;
@@ -16,5 +16,10 @@ try {
16
16
  else if (operation === 'delete') value = entry.deleteCredential();
17
17
  else throw new Error();
18
18
  parentPort.postMessage({ value });
19
- } catch { parentPort.postMessage({ error: 'STORE_UNAVAILABLE' }); }
19
+ } catch (error) {
20
+ // The binding exposes GenericFailure for both cases. Recognize only the
21
+ // upstream Secret Service refusal; never forward native messages or secrets.
22
+ const locked = process.platform === 'linux' && /Secret Service: unlock prompt was dismissed/.test(error?.message || '');
23
+ parentPort.postMessage({ error: locked ? 'STORE_LOCKED' : 'STORE_UNAVAILABLE' });
24
+ }
20
25
  }
@@ -45,7 +45,7 @@ function receive(line) {
45
45
  worker.on('error', stop);
46
46
  worker.on('exit', code => {
47
47
  // No response or lock release until the executor can no longer write.
48
- if (code !== 0 || !result || (result.error && result.error !== 'BINDING_MISSING')) return stop();
48
+ if (code !== 0 || !result || (result.error && !['BINDING_MISSING', 'STORE_LOCKED', 'STORE_UNAVAILABLE'].includes(result.error))) return stop();
49
49
  process.stdout.write(JSON.stringify(result) + '\n', () => {
50
50
  clearTimeout(timer);
51
51
  fs.closeSync(fd);
package/src/auth-store.js CHANGED
@@ -2,12 +2,12 @@ import { spawn } from 'node:child_process';
2
2
  import { randomBytes, createHash } from 'node:crypto';
3
3
  import { fileURLToPath } from 'node:url';
4
4
  import path from 'node:path';
5
- import { AuthError, authDirectory } from './auth-credentials.js';
5
+ import { AuthError, authDirectory, ENV_API_KEY_GUIDANCE } from './auth-credentials.js';
6
6
 
7
7
  export const CHUNK_BYTES = 2048;
8
8
  export const MAX_BUNDLE_BYTES = 16384;
9
9
  const digest = bytes => createHash('sha256').update(bytes).digest('hex');
10
- const unavailable = () => new AuthError('AUTH_STORE_UNAVAILABLE', 'Secure credential storage is unavailable or locked. Unlock your OS credential store and retry nansen login. No file fallback is used.');
10
+ const unavailable = () => new AuthError('AUTH_STORE_UNAVAILABLE', `Secure credential storage is unavailable or locked. ${ENV_API_KEY_GUIDANCE} To use browser login, enable and unlock your OS credential store, then retry nansen login from a supported terminal. On Linux, check the user D-Bus session, Secret Service provider and default collection; installing the native binding alone does not start or unlock a service. See docs/browser-login.md#linux-secret-service-setup. No file fallback is used.`);
11
11
  export function nativeStoreOperation(operation, account, bytes, { directory = authDirectory(), signal } = {}) {
12
12
  signal?.throwIfAborted();
13
13
  return new Promise((resolve, reject) => {
@@ -47,7 +47,7 @@ export function nativeStoreOperation(operation, account, bytes, { directory = au
47
47
  // The child already holds execution/cleanup exclusion. Keep the
48
48
  // pipe open as a parent-lifetime signal; never send secrets early.
49
49
  child.stdin.write(JSON.stringify({ operation, account, ...(bytes && { data: Buffer.from(bytes).toString('base64') }) }) + '\n');
50
- } else if (ready && !result && (Object.hasOwn(message, 'value') || message.error === 'BINDING_MISSING')) result = message;
50
+ } else if (ready && !result && (Object.hasOwn(message, 'value') || ['BINDING_MISSING', 'STORE_LOCKED', 'STORE_UNAVAILABLE'].includes(message.error))) result = message;
51
51
  else throw new Error();
52
52
  } catch { stop(); }
53
53
  }
@@ -62,9 +62,14 @@ export function nativeStoreOperation(operation, account, bytes, { directory = au
62
62
  try {
63
63
  if (failed || code !== 0 || !ready || !result || output) throw new Error();
64
64
  if (result.error === 'BINDING_MISSING') {
65
- reject(new AuthError('AUTH_STORE_UNAVAILABLE', 'The native credential-store binding could not load. Reinstall nansen-cli with optional dependencies enabled on a supported OS and architecture. See nansen doctor --offline and the browser-login platform guide.'));
65
+ reject(new AuthError('AUTH_STORE_UNAVAILABLE', `The native credential-store binding could not load. ${ENV_API_KEY_GUIDANCE} For saved browser login, reinstall nansen-cli with optional dependencies enabled on a supported OS and architecture. See docs/browser-login.md#preview-platform-scope.`));
66
66
  return;
67
67
  }
68
+ if (result.error === 'STORE_LOCKED') {
69
+ reject(new AuthError('AUTH_STORE_UNAVAILABLE', `The Linux Secret Service unlock prompt was dismissed or could not run in this terminal. Unlock the default collection using your provider's tools in the same user D-Bus session, then retry. Starting the service alone does not unlock it. See docs/browser-login.md#linux-secret-service-setup. ${ENV_API_KEY_GUIDANCE}`));
70
+ return;
71
+ }
72
+ if (result.error) { reject(unavailable()); return; }
68
73
  resolve(operation === 'get' && result.value !== null ? Buffer.from(result.value, 'base64') : result.value);
69
74
  } catch { reject(unavailable()); }
70
75
  });
package/src/bridge.js CHANGED
@@ -1918,13 +1918,15 @@ from a quote are the same ones that got stuck. Check the stuck nonce with
1918
1918
  log(` Type: ${execution_type}`);
1919
1919
  log(` Steps: ${steps.length}`);
1920
1920
 
1921
- // Dry-run preflight needs only the public address persisted alongside the
1922
- // quote. Prefer it before touching local wallet configuration; legacy
1923
- // quotes without the field retain the previous wallet-resolution path.
1924
- // A real execution always resolves the live signer independently and
1925
- // binds it to the quote before any credentials are loaded.
1921
+ // Dry-run preflight normally needs only the public address persisted with
1922
+ // the quote. Privy Hyperliquid quotes are the exception: resolve the live
1923
+ // signer so its wallet ID can be bound before even showing a preview.
1924
+ // Real execution always resolves the live signer independently and binds
1925
+ // it to the quote before any credentials are loaded.
1926
1926
  const quotedWalletAddress = validateQuotedWalletAddress(quoteId, quoteData.walletAddress);
1927
- const signer = guard.dryRun && quotedWalletAddress
1927
+ const requiresPrivyBinding = execution_type === 'hyperliquid_signature'
1928
+ && quoteData.walletProvider === 'privy';
1929
+ const signer = guard.dryRun && quotedWalletAddress && !requiresPrivyBinding
1928
1930
  ? null
1929
1931
  : resolveWalletAddress(walletName);
1930
1932
  const signerAddress = signer?.address || quotedWalletAddress;
@@ -1947,6 +1949,15 @@ from a quote are the same ones that got stuck. Check the stuck nonce with
1947
1949
  );
1948
1950
  }
1949
1951
 
1952
+ let privyBinding = null;
1953
+ if (execution_type === 'hyperliquid_signature' && signer?.provider === 'privy') {
1954
+ const { PrivyClient, assertPrivyWalletAddress } = await import('./privy.js');
1955
+ const client = new PrivyClient(process.env.PRIVY_APP_ID, process.env.PRIVY_APP_SECRET);
1956
+ const walletId = signer.privyWalletIds?.evm;
1957
+ await assertPrivyWalletAddress(client, walletId, signer.address, 'evm');
1958
+ privyBinding = { client, walletId };
1959
+ }
1960
+
1950
1961
  // Re-screen the signer and any distinct recipient immediately before
1951
1962
  // signing. Quotes live up to an hour, and the EVM leg broadcasts directly.
1952
1963
  const screenAddresses = recipient
@@ -2106,14 +2117,12 @@ from a quote are the same ones that got stuck. Check the stuck nonce with
2106
2117
  }
2107
2118
  } else if (execution_type === 'hyperliquid_signature') {
2108
2119
  if (creds.provider === 'privy') {
2109
- const { PrivyClient } = await import('./privy.js');
2110
- const privyClient = new PrivyClient(process.env.PRIVY_APP_ID, process.env.PRIVY_APP_SECRET);
2111
2120
  for (const [index, step] of steps.entries()) {
2112
2121
  await processSignatureStepPrivy(step, {
2113
- privyClient,
2122
+ privyClient: privyBinding.client,
2114
2123
  // `signer` above — the same resolution that was screened and
2115
2124
  // matched against the quote, rather than resolving a second time.
2116
- walletId: signer.privyWalletIds?.evm,
2125
+ walletId: privyBinding.walletId,
2117
2126
  log,
2118
2127
  apiInstance,
2119
2128
  onBroadcast,