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
package/src/privy.js CHANGED
@@ -11,7 +11,7 @@ import path from "path";
11
11
  import { parsePaymentRequirements } from "./x402.js";
12
12
  import { hasSufficientEvmPaymentBalance, hasSufficientSvmPaymentBalance } from "./x402-payment-balance.js";
13
13
  import { isEvmNetwork } from "./x402-evm.js";
14
- import { mkdirPrivateSync, readWalletJson, writeWalletJsonAtomic } from "./wallet.js";
14
+ import { mkdirPrivateSync, readWalletJson, withWalletLock, writeWalletJsonAtomic } from "./wallet.js";
15
15
  import { evaluatePaymentRequirement, resolvePaymentAmount, resolvePayTo, signWithSessionCharge } from "./x402-policy.js";
16
16
  import {
17
17
  isSvmNetwork,
@@ -152,6 +152,54 @@ export class PrivyClient {
152
152
 
153
153
  // ============= Helpers =============
154
154
 
155
+ function extractPrivyWalletAddress(response) {
156
+ return response?.address
157
+ ?? response?.data?.address
158
+ ?? response?.wallet?.address
159
+ ?? response?.data?.wallet?.address
160
+ ?? null;
161
+ }
162
+
163
+ /**
164
+ * Resolve a Privy wallet ID and bind it to the address stored locally before
165
+ * any preview, screening, or signing can rely on that address.
166
+ */
167
+ export async function assertPrivyWalletAddress(client, walletId, expectedAddress, chainType) {
168
+ if (chainType !== 'evm' && chainType !== 'solana') {
169
+ throw new Error(`Unsupported Privy wallet chain type: ${chainType}`);
170
+ }
171
+ const label = chainType === 'solana' ? 'Solana' : 'EVM';
172
+ if (!walletId) {
173
+ throw new Error(`No Privy ${label} wallet ID found. Re-create the wallet with: nansen wallet create --provider privy`);
174
+ }
175
+ if (!expectedAddress) {
176
+ throw new Error(`No ${label} address is stored for this Privy wallet. Re-create the wallet with: nansen wallet create --provider privy`);
177
+ }
178
+
179
+ const response = await client.getWallet(walletId);
180
+ const authoritativeAddress = extractPrivyWalletAddress(response);
181
+ const validAddress = chainType === 'evm'
182
+ ? /^0x[0-9a-f]{40}$/i
183
+ : /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
184
+ if (typeof authoritativeAddress !== 'string' || !validAddress.test(authoritativeAddress)) {
185
+ throw new Error(`Privy returned no valid ${label} address for the selected wallet ID. Re-create the wallet with: nansen wallet create --provider privy`);
186
+ }
187
+ if (typeof expectedAddress !== 'string' || !validAddress.test(expectedAddress)) {
188
+ throw new Error(`The locally stored Privy ${label} address is invalid. Re-create the wallet with: nansen wallet create --provider privy`);
189
+ }
190
+
191
+ const matches = chainType === 'evm'
192
+ ? authoritativeAddress.toLowerCase() === String(expectedAddress).toLowerCase()
193
+ : authoritativeAddress === expectedAddress;
194
+ if (!matches) {
195
+ throw new Error(
196
+ `The selected Privy wallet ID does not match the locally stored ${label} address. Re-create the wallet with: nansen wallet create --provider privy`,
197
+ );
198
+ }
199
+
200
+ return authoritativeAddress;
201
+ }
202
+
155
203
  function getClient() {
156
204
  return new PrivyClient(process.env.PRIVY_APP_ID, process.env.PRIVY_APP_SECRET);
157
205
  }
@@ -195,18 +243,48 @@ export async function createPrivyWalletPair(name) {
195
243
 
196
244
  mkdirPrivateSync(walletsDir);
197
245
 
198
- // Write config before wallet file so a crash doesn't leave an orphan without a default entry
199
- const configPath = path.join(walletsDir, "config.json");
200
- let config = { defaultWallet: null, passwordHash: null };
201
- if (fs.existsSync(configPath)) {
202
- config = readWalletJson(configPath);
203
- }
204
- if (!config.defaultWallet) {
205
- config.defaultWallet = name;
206
- writeWalletJsonAtomic(configPath, config);
246
+ // Only the local save is locked; the Privy calls above stay outside it. So
247
+ // re-check the name here: another command may have taken it meanwhile.
248
+ const deleteRemote = async () => {
249
+ try { await client.deleteWallet(evmResult.id); } catch { /* best effort */ }
250
+ try { await client.deleteWallet(solanaResult.id); } catch { /* best effort */ }
251
+ };
252
+ let saved;
253
+ try {
254
+ saved = withWalletLock(() => {
255
+ if (fs.existsSync(walletFile)) return false;
256
+
257
+ const configPath = path.join(walletsDir, "config.json");
258
+ let config = { defaultWallet: null, passwordHash: null };
259
+ if (fs.existsSync(configPath)) {
260
+ config = readWalletJson(configPath);
261
+ }
262
+
263
+ // Wallet file first, as createWallet does: if the config write then
264
+ // fails, the file is removed, so config never names a missing wallet.
265
+ writeWalletJsonAtomic(walletFile, walletData);
266
+ if (!config.defaultWallet) {
267
+ config.defaultWallet = name;
268
+ try {
269
+ writeWalletJsonAtomic(configPath, config);
270
+ } catch (err) {
271
+ fs.rmSync(walletFile, { force: true });
272
+ throw err;
273
+ }
274
+ }
275
+ return true;
276
+ });
277
+ } catch (err) {
278
+ // Busy lock or unreadable config: nothing local references the new
279
+ // Privy wallets, so remove them rather than orphan them.
280
+ await deleteRemote();
281
+ throw err;
207
282
  }
208
283
 
209
- writeWalletJsonAtomic(walletFile, walletData);
284
+ if (!saved) {
285
+ await deleteRemote();
286
+ throw new Error(`Wallet "${name}" already exists`);
287
+ }
210
288
 
211
289
  return walletData;
212
290
  }
@@ -7,17 +7,31 @@
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)
@@ -85,6 +99,15 @@ export function parseObjectOption(val, name) {
85
99
  return val;
86
100
  }
87
101
 
102
+ /**
103
+ * `--filters '<json>'` as a plain object with every EVM address lowercased.
104
+ * The API stores EVM addresses lowercase, so a checksummed address matched no
105
+ * rows and the command returned an empty success (API-1081).
106
+ */
107
+ export function parseFiltersOption(val) {
108
+ return normalizeFilterAddresses(parseObjectOption(val, 'filters'));
109
+ }
110
+
88
111
  /** Reject explicit blank strings before a handler selects an omitted-option default. */
89
112
  export function rejectBlankOption(value, name, example) {
90
113
  if (typeof value === 'string' && value.trim() === '') {
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';