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
package/src/schema.json CHANGED
@@ -268,7 +268,7 @@
268
268
  },
269
269
  "bridge": {
270
270
  "description": "Move funds between Base and Hyperliquid",
271
- "notes": "Supported routes: base -> hyperliquid (deposit); hyperliquid -> base, hyperliquid -> ethereum, hyperliquid -> arbitrum (withdrawal). Any other combination is rejected. Deposits broadcast an EVM transaction from the local wallet, so they require a locally signable origin chain; withdrawals sign a Hyperliquid action and never transact on the destination chain.",
271
+ "notes": "Supported routes: base -> hyperliquid (deposit); hyperliquid -> base, hyperliquid -> ethereum, hyperliquid -> arbitrum (withdrawal). Any other combination is rejected. base -> hyperliquid deposits currently support USDC only — a non-USDC --from-token is rejected with INVALID_INPUT before the quote is created. Deposits broadcast an EVM transaction from the local wallet, so they require a locally signable origin chain; withdrawals sign a Hyperliquid action and never transact on the destination chain.",
272
272
  "routes": [
273
273
  {
274
274
  "origin": "base",
@@ -319,7 +319,7 @@
319
319
  "from-token": {
320
320
  "type": "string",
321
321
  "required": true,
322
- "description": "Source token symbol (USDC) or address (alias: --token)"
322
+ "description": "Source token symbol or address (alias: --token). Base -> Hyperliquid deposits require USDC; a non-USDC token is rejected before the quote is created."
323
323
  },
324
324
  "to-token": {
325
325
  "type": "string",
@@ -384,13 +384,30 @@
384
384
  "type": "string",
385
385
  "description": "Fee cap in gwei, overriding the computed one (EVM deposit legs only)"
386
386
  },
387
+ "max-tx-fee": {
388
+ "type": "string",
389
+ "description": "Most one EVM transaction may pay for gas (fee cap x gas limit), in ETH. Default 1; 0 disables the check."
390
+ },
387
391
  "nonce": {
388
392
  "type": "string",
389
393
  "description": "Sign at this nonce instead of the next one, to replace a stuck transaction (EVM deposit legs only)"
394
+ },
395
+ "dry-run": {
396
+ "type": "boolean",
397
+ "description": "Run every sign-free preflight available from the cached quote, its public signer address and read-only RPC calls; print the transfer that would be signed; then stop before wallet credentials and the first signature. Nothing is broadcast, no wallet password is needed, and the quote stays usable. Real execution still resolves and revalidates the live signer. Exits 0."
398
+ },
399
+ "yes": {
400
+ "type": "boolean",
401
+ "description": "Skip the confirmation prompt (alias: -y, or set NANSEN_YES=1). The prompt is only shown when stdin is an interactive terminal; when stdin is not a terminal (agents, CI, pipes) the command proceeds unprompted whether or not this is passed. Declining the prompt exits 1 with nothing signed."
390
402
  }
391
403
  },
404
+ "examples": [
405
+ "nansen bridge execute --quote bridge-1708900000000-abc123",
406
+ "nansen bridge execute --quote bridge-1708900000000-abc123 --dry-run",
407
+ "nansen bridge execute --quote bridge-1708900000000-abc123 --yes"
408
+ ],
392
409
  "prerequisites": [
393
- "A wallet must be configured. Run: nansen wallet create"
410
+ "A wallet must be configured for real execution. Dry-run can use the public signer saved in the cached quote."
394
411
  ]
395
412
  },
396
413
  "status": {
@@ -410,7 +427,7 @@
410
427
  }
411
428
  },
412
429
  "research": {
413
- "description": "Research and analytics commands. Explicitly blank chain, timeframe, and days options are rejected instead of selecting defaults. Profiler batch rejects blank --delay; trace rejects blank --delay, --depth, and --width.",
430
+ "description": "Research and analytics commands. Explicitly blank chain, timeframe, and days options are rejected instead of selecting defaults. Profiler batch rejects blank --delay; trace rejects blank --delay, --depth, and --width. Browser nansen:api sessions use the same account API permissions and endpoint checks as API keys.",
414
431
  "subcommands": {
415
432
  "portfolio": {
416
433
  "subcommands": {
@@ -788,9 +805,8 @@
788
805
  },
789
806
  "width": {
790
807
  "type": "integer",
791
- "minimum": 0,
792
808
  "default": 10,
793
- "description": "Counterparties to follow at each hop"
809
+ "description": "Counterparties to follow at each hop (1-50); valid integers outside the range are clamped. Traversal stops expanding after 1000 nodes and reports stats.truncated"
794
810
  },
795
811
  "days": {
796
812
  "type": "integer",
@@ -1140,6 +1156,10 @@
1140
1156
  "include-stablecoins": {
1141
1157
  "description": "Whether to include stablecoins in screener results (default true on API side)",
1142
1158
  "default": true
1159
+ },
1160
+ "search": {
1161
+ "type": "string",
1162
+ "description": "Filter screener candidates client-side by token name, symbol, or exact address. Only the fetched candidate rows are searched (the first 500 by default, more with --limit/--page, every traversed page with --paginate/--all), so the response adds _meta.search: { query, searched, matched, complete }. complete: false means the API had more rows beyond that window and a missing token may simply rank below it; widen with --limit (max 1000) or --paginate, or narrow with --filters. A stderr note repeats this for --fields/--table/--csv/--stream output. With --paginate/--all, the fully traversed candidate pool is filtered after traversal; pagination metadata describes the upstream candidate-page traversal, not the number of matches after filtering."
1143
1163
  }
1144
1164
  }
1145
1165
  },
@@ -2026,6 +2046,9 @@
2026
2046
  "subcommands": {
2027
2047
  "quote": {
2028
2048
  "description": "Get a DEX swap quote (same-chain or cross-chain). Explicitly blank --swap-mode, --wallet, --to-chain, --aggregator, and --amount-unit values are rejected.",
2049
+ "apiEndpoints": [
2050
+ "/api/v1/sanctions/screen"
2051
+ ],
2029
2052
  "options": {
2030
2053
  "chain": {
2031
2054
  "type": "string",
@@ -2091,11 +2114,15 @@
2091
2114
  }
2092
2115
  },
2093
2116
  "prerequisites": [
2094
- "A local wallet must be configured. Run: nansen wallet create"
2117
+ "A local wallet must be configured. Run: nansen wallet create",
2118
+ "API access is required for pre-trade compliance screening. Run: nansen login (or set NANSEN_API_KEY)"
2095
2119
  ]
2096
2120
  },
2097
2121
  "execute": {
2098
2122
  "description": "Sign and broadcast a quoted trade. Explicitly blank --wallet values are rejected.",
2123
+ "apiEndpoints": [
2124
+ "/api/v1/sanctions/screen"
2125
+ ],
2099
2126
  "options": {
2100
2127
  "quote": {
2101
2128
  "type": "string",
@@ -2127,11 +2154,31 @@
2127
2154
  "type": "boolean",
2128
2155
  "description": "Skip swap-outcome verification. That check simulates the swap and confirms the wallet's balance changes match the quote (input spent within your max, expected output received, no other asset moved) before broadcasting; it needs a simulation-capable endpoint (NANSEN_BASE_SIM_RPC on EVM, NANSEN_SOLANA_SIM_RPC on Solana) and degrades with a warning when none is available."
2129
2156
  },
2157
+ "max-tx-fee": {
2158
+ "type": "string",
2159
+ "description": "Most one EVM transaction may pay for gas (fee cap x gas limit), in ETH. A quote above it is refused before anything is signed, approvals included. Default 1; 0 disables the check. Not applied to WalletConnect, where the wallet shows the fee."
2160
+ },
2130
2161
  "no-revoke-excessive-allowance": {
2131
2162
  "type": "boolean",
2132
2163
  "description": "Skip revoking an existing on-chain ERC-20 allowance before re-approving when it exceeds 10x this trade's scoped amount. By default, an oversized or legacy allowance is revoked to zero and a fresh trade-scoped allowance is granted. WalletConnect users will see separate wallet prompts for the revoke and re-approval."
2164
+ },
2165
+ "dry-run": {
2166
+ "type": "boolean",
2167
+ "description": "Run every sign-free preflight available from the cached quote, its public signer address and read-only RPC calls; plan the approval and print what would be sent; then stop before wallet credentials or signing. Nothing is signed or broadcast, no wallet password is needed, and the quote stays usable. Real execution still resolves and revalidates the live signer. On EVM preview also reads the current allowance and runs the pre-broadcast revert simulation when no approval is outstanding. Exits 0."
2168
+ },
2169
+ "yes": {
2170
+ "type": "boolean",
2171
+ "description": "Skip the confirmation prompt (alias: -y, or set NANSEN_YES=1). The prompt is only shown when stdin is an interactive terminal; when stdin is not a terminal (agents, CI, pipes) the command proceeds unprompted whether or not this is passed. Declining the prompt exits 1 with nothing signed."
2133
2172
  }
2134
- }
2173
+ },
2174
+ "examples": [
2175
+ "nansen trade execute --quote 1708900000000-abc123",
2176
+ "nansen trade execute --quote 1708900000000-abc123 --dry-run",
2177
+ "nansen trade execute --quote 1708900000000-abc123 --yes"
2178
+ ],
2179
+ "prerequisites": [
2180
+ "API access is required for pre-trade compliance screening. Run: nansen login (or set NANSEN_API_KEY)"
2181
+ ]
2135
2182
  },
2136
2183
  "bridge-status": {
2137
2184
  "description": "Check cross-chain bridge transaction status. Aggregator (Li.Fi or Relay) is auto-detected from a local tx record saved at execute time (kept 30 days); pass --aggregator to override when polling from a different machine.",
@@ -2309,10 +2356,18 @@
2309
2356
  "type": "boolean",
2310
2357
  "description": "Skip encryption; private keys are stored unencrypted on disk (local only)"
2311
2358
  }
2312
- }
2359
+ },
2360
+ "examples": [
2361
+ "nansen wallet create --name trading",
2362
+ "nansen wallet create --name agent-wallet --provider privy"
2363
+ ]
2313
2364
  },
2314
2365
  "list": {
2315
- "description": "List all wallets"
2366
+ "description": "List all wallets",
2367
+ "examples": [
2368
+ "nansen wallet list",
2369
+ "nansen wallet list --pretty"
2370
+ ]
2316
2371
  },
2317
2372
  "show": {
2318
2373
  "description": "Show wallet details",
@@ -2320,7 +2375,10 @@
2320
2375
  "name": {
2321
2376
  "description": "Wallet name"
2322
2377
  }
2323
- }
2378
+ },
2379
+ "examples": [
2380
+ "nansen wallet show <name>"
2381
+ ]
2324
2382
  },
2325
2383
  "send": {
2326
2384
  "description": "Send tokens or native currency. Explicitly blank --token and --wallet values are rejected; omit them for native currency and the default wallet.",
@@ -2344,30 +2402,76 @@
2344
2402
  "type": "boolean",
2345
2403
  "description": "Send the entire spendable balance instead of --amount"
2346
2404
  }
2347
- }
2405
+ },
2406
+ "examples": [
2407
+ "nansen wallet send --to <address> --amount 1.5 --chain evm",
2408
+ "nansen wallet send --to <address> --max --chain solana"
2409
+ ]
2348
2410
  },
2349
2411
  "export": {
2350
- "description": "Export private keys"
2412
+ "description": "Export private keys (redacted by default; pass --reveal or --file <path> for the actual keys)",
2413
+ "options": {
2414
+ "reveal": {
2415
+ "type": "boolean",
2416
+ "description": "Print private keys in plaintext to stdout (explicit acknowledgement; warns on interactive terminals)"
2417
+ },
2418
+ "file": {
2419
+ "type": "string",
2420
+ "description": "Write private keys to this path instead of stdout (created with 0600 permissions, refuses to overwrite)"
2421
+ }
2422
+ },
2423
+ "examples": [
2424
+ "nansen wallet export <name>",
2425
+ "nansen wallet export <name> --file backup.json"
2426
+ ]
2351
2427
  },
2352
2428
  "delete": {
2353
- "description": "Delete a wallet"
2429
+ "description": "Delete a wallet",
2430
+ "examples": [
2431
+ "nansen wallet delete <name>"
2432
+ ]
2354
2433
  },
2355
2434
  "default": {
2356
- "description": "Set default wallet"
2435
+ "description": "Set default wallet",
2436
+ "examples": [
2437
+ "nansen wallet default <name>"
2438
+ ]
2439
+ },
2440
+ "forget-password": {
2441
+ "description": "Forget the saved wallet password, removing it from the OS keychain and from the local credentials file. Later commands fall back to NANSEN_WALLET_PASSWORD or an interactive prompt (--human).",
2442
+ "examples": [
2443
+ "nansen wallet forget-password"
2444
+ ]
2445
+ },
2446
+ "secure": {
2447
+ "description": "Move a wallet password that is held in the local credentials file or in NANSEN_WALLET_PASSWORD into the OS keychain, then delete the plaintext copy. Verifies the password against the stored hash first, reports success when it is already in the keychain, and fails with KEYCHAIN_UNAVAILABLE when no OS keychain is reachable.",
2448
+ "examples": [
2449
+ "nansen wallet secure",
2450
+ "NANSEN_WALLET_PASSWORD=<password> nansen wallet secure"
2451
+ ]
2357
2452
  }
2358
2453
  }
2359
2454
  },
2360
2455
  "account": {
2361
2456
  "endpoint": "/api/v1/account",
2362
- "description": "Show API key status, plan, and remaining credits. Does not consume credits."
2457
+ "description": "Check the effective credential, plan, and remaining credits live. Free, including for a valid zero-credit account. NANSEN_API_KEY overrides saved authentication."
2363
2458
  },
2364
2459
  "auth": {
2365
- "description": "Offline authentication status. Reports API key presence and source (env var vs config file), base URL, and x402 wallet readiness without any network call. Consumes no credits.",
2460
+ "description": "Offline authentication status. Reports effective credential source, cached/unverified browser session metadata, API key presence, base URL, and x402 wallet readiness without any network call. Consumes no credits.",
2366
2461
  "subcommands": {
2367
2462
  "status": {
2368
2463
  "description": "Show where credentials come from, entirely offline",
2369
2464
  "returns": [
2370
2465
  "logged_in",
2466
+ "effective_credential.kind",
2467
+ "effective_credential.source",
2468
+ "effective_credential.validity",
2469
+ "saved_session.account_id",
2470
+ "saved_session.expires_at",
2471
+ "saved_session.expired",
2472
+ "saved_session.validity",
2473
+ "saved_session.storage_access",
2474
+ "saved_session.renewal_state",
2371
2475
  "api_key.present",
2372
2476
  "api_key.source",
2373
2477
  "api_key.masked",
@@ -2518,7 +2622,7 @@
2518
2622
  ]
2519
2623
  },
2520
2624
  "install": {
2521
- "description": "Add the Nansen MCP server to a client's config. Client (positional): claude-code, claude-desktop, or cursor. Uses the API key from `nansen login` / NANSEN_API_KEY; re-run after key rotation to update the entry.",
2625
+ "description": "Add the Nansen MCP server to a client's config. Client (positional): claude-code, claude-desktop, or cursor. Uses the API key from `nansen login --human` / NANSEN_API_KEY; re-run after key rotation to update the entry.",
2522
2626
  "args": [
2523
2627
  {
2524
2628
  "name": "client",
@@ -2584,6 +2688,95 @@
2584
2688
  ]
2585
2689
  }
2586
2690
  }
2691
+ },
2692
+ "login": {
2693
+ "description": "Fresh browser approval in every starting state for API-key-equivalent account API permissions (nansen:api). Wallet signing and MCP key export remain separate. Plain login never persists NANSEN_API_KEY; it still overrides commands. Selected sessions renew automatically; uncertain renewal requires fresh login. Native custody and enabled server admission required; release acceptance pending.",
2694
+ "options": {
2695
+ "no-browser": {
2696
+ "type": "boolean",
2697
+ "description": "Print the approval URL/code without opening a browser"
2698
+ },
2699
+ "json": {
2700
+ "type": "boolean",
2701
+ "description": "Browser login: NDJSON pending and one terminal event; automatic in non-TTY. With --api-key-stdin: one saved event with effective_source, environment_key_blank and cleanup."
2702
+ },
2703
+ "human": {
2704
+ "type": "boolean",
2705
+ "description": "Legacy API-key setup: option, environment, then hidden interactive prompt"
2706
+ },
2707
+ "api-key": {
2708
+ "type": "string",
2709
+ "description": "Legacy API key to verify and save; recorded in shell history"
2710
+ },
2711
+ "api-key-stdin": {
2712
+ "type": "boolean",
2713
+ "description": "Read a single API key from a pipe or redirected file (maximum 4096 bytes; input must close within 30 seconds), verify and save it without echoing it. Requires the native lock binding. Cannot combine with --api-key, --human or --no-browser. NANSEN_API_KEY still overrides saved credentials for subsequent commands."
2714
+ }
2715
+ },
2716
+ "returns": {
2717
+ "description": "Operational command. Machine events: pending {verification_uri,user_code,expires_at}; saved {account_id,effective_source,cleanup}; error/cancelled {code,message,cleanup}. Never includes device_code or tokens. Cleanup preserves malformed journals and reports AUTH_JOURNAL_INVALID; unrecognized JSON files remain untouched."
2718
+ }
2719
+ },
2720
+ "logout": {
2721
+ "description": "Clear saved API authentication and attempt browser-family retirement. Preserve wallets and environment keys. Report incomplete local deletion or remote revocation separately. Preserve damaged recovery journals and report auth-operations repair guidance."
2722
+ },
2723
+ "cache": {
2724
+ "description": "Inspect and clear the caches the CLI keeps under ~/.nansen. Reads and deletes local files only: no network call, no credits, and credentials, wallets, saved quotes and config are never changed. CLI startup loads the saved config as usual.",
2725
+ "subcommands": {
2726
+ "stats": {
2727
+ "description": "Report what each cache holds: entry count, bytes on disk, age of the oldest and newest entry, the effective TTL, and how many entries are already expired. Aggregates only — no cached payload, request parameter or cache key is printed.",
2728
+ "options": {
2729
+ "json": {
2730
+ "type": "boolean",
2731
+ "description": "Return the stats as a JSON object instead of a text report"
2732
+ },
2733
+ "cache-ttl": {
2734
+ "type": "integer",
2735
+ "minimum": 0,
2736
+ "maximum": 9007199254740991,
2737
+ "default": 300,
2738
+ "description": "TTL to evaluate the response cache against, matching the TTL a request would use"
2739
+ }
2740
+ },
2741
+ "returns": [
2742
+ "config_dir",
2743
+ "caches[].name",
2744
+ "caches[].description",
2745
+ "caches[].path",
2746
+ "caches[].entries",
2747
+ "caches[].bytes",
2748
+ "caches[].ttl_seconds",
2749
+ "caches[].oldest_age_seconds",
2750
+ "caches[].newest_age_seconds",
2751
+ "caches[].expired_entries",
2752
+ "total_entries",
2753
+ "total_bytes",
2754
+ "hit_miss_recorded"
2755
+ ],
2756
+ "examples": [
2757
+ "nansen cache stats",
2758
+ "nansen cache stats --json --pretty",
2759
+ "nansen cache stats --cache-ttl 60"
2760
+ ]
2761
+ },
2762
+ "clear": {
2763
+ "description": "Delete cached entries and print exactly what was removed. Takes an explicit target: responses (the default), cost-map, update-check, or all. An unrecognised target removes nothing.",
2764
+ "args": [
2765
+ {
2766
+ "name": "target",
2767
+ "type": "string",
2768
+ "default": "responses",
2769
+ "enum": ["responses", "cost-map", "update-check", "all"],
2770
+ "description": "Which cache to delete"
2771
+ }
2772
+ ],
2773
+ "examples": [
2774
+ "nansen cache clear",
2775
+ "nansen cache clear cost-map",
2776
+ "nansen cache clear all"
2777
+ ]
2778
+ }
2779
+ }
2587
2780
  }
2588
2781
  },
2589
2782
  "globalOptions": {
@@ -2608,6 +2801,17 @@
2608
2801
  "default": 1,
2609
2802
  "description": "1-based page number for list-returning research commands; maps to pagination.page. Supported by smart-money, profiler, token, perp, points, prediction-market, and supported research historical-* commands. Trade, wallet, and operational commands ignore it; token ohlcv, profiler perp-positions, and historical-token-flow-summary do not support pagination. profiler labels defaults to page 1 when omitted."
2610
2803
  },
2804
+ "paginate": {
2805
+ "type": "boolean",
2806
+ "description": "Fetch every page of a list-returning command and return one merged response (alias: --all). Starts at --page (default 1) and uses --limit as the page size; stops on a short or empty page, when server pagination metadata (total_pages, total, is_last_page, has_more, or next_page) says the traversal is complete, when a page repeats rows already seen, or after --max-pages requests. Server total metadata is trusted, so a live dataset that changes or reports inconsistent totals during traversal can omit later rows. The merged response keeps the first page's shape (a bare array is wrapped as { data: [...] }) with rows de-duplicated, plus pagination: { page, pages_fetched, next_page, complete } — next_page is null when complete, otherwise the page to resume from. Each page is a separate, separately billed API call. Works with --stream (NDJSON), --table, --format csv and --fields. Commands without pagination are unaffected."
2807
+ },
2808
+ "max-pages": {
2809
+ "type": "integer",
2810
+ "minimum": 1,
2811
+ "maximum": 1000,
2812
+ "default": 10,
2813
+ "description": "Positive safe-integer page-request cap for --paginate/--all. It is parsed and validated only when pagination is active, and is otherwise ignored. Hitting the cap sets pagination.complete to false and pagination.next_page to the page to resume from."
2814
+ },
2611
2815
  "no-retry": {
2612
2816
  "type": "boolean",
2613
2817
  "description": "Disable automatic retry on rate limits/errors"
@@ -2619,6 +2823,14 @@
2619
2823
  "default": 3,
2620
2824
  "description": "Max retry attempts (non-negative safe integer)"
2621
2825
  },
2826
+ "cache": {
2827
+ "type": "boolean",
2828
+ "description": "Serve this invocation from the local response cache and save its result there. Off by default; see the caching section for which commands it applies to"
2829
+ },
2830
+ "no-cache": {
2831
+ "type": "boolean",
2832
+ "description": "Bypass the local response cache for this invocation even when --cache is passed. NANSEN_NO_CACHE=1 does the same without a flag"
2833
+ },
2622
2834
  "cache-ttl": {
2623
2835
  "type": "integer",
2624
2836
  "minimum": 0,
@@ -2626,6 +2838,10 @@
2626
2838
  "default": 300,
2627
2839
  "description": "Cache TTL in seconds (non-negative safe integer; 0 disables cache reads)"
2628
2840
  },
2841
+ "debug": {
2842
+ "type": "boolean",
2843
+ "description": "Trace HTTP request events on stderr: method, redacted URL, response status, time-to-response-headers (TTFB), retry decisions and request id. Also enabled by NANSEN_DEBUG=1. Response timing excludes body download/parsing. Never prints credentials or response bodies."
2844
+ },
2629
2845
  "format": {
2630
2846
  "type": "string",
2631
2847
  "enum": [
@@ -2639,25 +2855,88 @@
2639
2855
  "description": "Pre-signed x402 payment signature header"
2640
2856
  }
2641
2857
  },
2858
+ "caching": {
2859
+ "summary": "Response caching is off by default and opt-in per invocation with --cache. It is a property of the request path, not of individual commands: with --cache on, every read the CLI makes through the Nansen API client is served from and written to the local response cache.",
2860
+ "enableWith": "--cache",
2861
+ "disableWith": ["--no-cache", "NANSEN_NO_CACHE=1"],
2862
+ "ttlOption": "--cache-ttl <seconds>",
2863
+ "defaultTtlSeconds": 300,
2864
+ "cachedCommands": "All research commands (including top-level perp screener and perp leaderboard), plus alerts list and alerts get.",
2865
+ "neverCached": [
2866
+ "account",
2867
+ "web search",
2868
+ "web fetch",
2869
+ "alerts create",
2870
+ "alerts update",
2871
+ "alerts toggle",
2872
+ "alerts delete",
2873
+ "agent",
2874
+ "trade (all subcommands)",
2875
+ "bridge (all subcommands)",
2876
+ "wallet (all subcommands)",
2877
+ "perp trading (order, cancel, close, leverage, transfer, approve-builder-fee, positions, orders, account, meta)",
2878
+ "mcp (all subcommands)"
2879
+ ],
2880
+ "inspect": "nansen cache stats",
2881
+ "clear": "nansen cache clear [responses|cost-map|update-check|all]",
2882
+ "caches": [
2883
+ {
2884
+ "name": "responses",
2885
+ "path": "~/.nansen/cache",
2886
+ "ttlSeconds": 300,
2887
+ "description": "API responses saved when --cache is passed; TTL is the effective --cache-ttl"
2888
+ },
2889
+ {
2890
+ "name": "cost-map",
2891
+ "path": "~/.nansen/cost-map.json",
2892
+ "ttlSeconds": 86400,
2893
+ "description": "Per-endpoint credit costs used to report what a call cost"
2894
+ },
2895
+ {
2896
+ "name": "update-check",
2897
+ "path": "~/.nansen/update-check.json",
2898
+ "ttlSeconds": 86400,
2899
+ "description": "Latest published CLI version, for the upgrade notice"
2900
+ }
2901
+ ]
2902
+ },
2642
2903
  "chains": [
2643
- "ethereum",
2644
- "solana",
2645
- "base",
2646
- "bnb",
2904
+ "algorand",
2905
+ "aptos",
2647
2906
  "arbitrum",
2648
- "polygon",
2649
- "optimism",
2907
+ "arc",
2650
2908
  "avalanche",
2909
+ "base",
2910
+ "bitcoin",
2911
+ "bitlayer",
2912
+ "bnb",
2913
+ "chiliz",
2914
+ "citrea",
2915
+ "ethereum",
2916
+ "gravity",
2917
+ "hyperevm",
2918
+ "hyperliquid",
2919
+ "injective",
2920
+ "iotaevm",
2651
2921
  "linea",
2652
- "scroll",
2653
2922
  "mantle",
2654
- "ronin",
2655
- "sei",
2923
+ "mantra",
2924
+ "monad",
2925
+ "near",
2926
+ "optimism",
2656
2927
  "plasma",
2928
+ "polygon",
2929
+ "robinhood",
2930
+ "sei",
2931
+ "solana",
2657
2932
  "sonic",
2658
- "monad",
2659
- "hyperevm",
2660
- "iotaevm"
2933
+ "stacks",
2934
+ "starknet",
2935
+ "stellar",
2936
+ "sui",
2937
+ "ton",
2938
+ "tron",
2939
+ "viction"
2661
2940
  ],
2662
2941
  "smartMoneyLabels": [
2663
2942
  "Fund",
package/src/semver.js CHANGED
@@ -13,14 +13,33 @@
13
13
  * correct way instead of each hand-rolling its own parser.
14
14
  */
15
15
  export function compareSemver(a, b) {
16
+ // A prerelease or build suffix ("1.2.10-beta.1", "1.2.10+sha") used to be
17
+ // parsed with Number(), which turned the suffixed component into NaN and
18
+ // then into 0 — so "1.2.10-beta" compared below "1.2.9". Split the suffix
19
+ // off first and read each component as a plain integer. A prerelease ranks
20
+ // below the release it precedes, and build metadata is ignored entirely.
21
+ //
22
+ // Known limitation: prerelease *identity* is not compared, so two
23
+ // prereleases of the same core read as equal ("1.3.0-beta.1" vs
24
+ // "1.3.0-beta.2" is 0). No caller hits that today because every published
25
+ // `latest` has been a plain release — but that's a fact about what we've
26
+ // shipped, not a guarantee the callers make. If the `latest` dist-tag ever
27
+ // points at a prerelease, the update notifier and `doctor` will silently
28
+ // under-report. Full prerelease precedence (SemVer §11) is deliberately
29
+ // out of scope here.
16
30
  const parse = v => {
17
- const parts = String(v).replace(/^v/, '').split('.').map(Number);
18
- return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
31
+ const str = String(v).replace(/^v/, '');
32
+ const suffixAt = str.search(/[-+]/);
33
+ const core = suffixAt === -1 ? str : str.slice(0, suffixAt);
34
+ const prerelease = suffixAt !== -1 && str[suffixAt] === '-';
35
+ const parts = core.split('.').map(p => parseInt(p, 10));
36
+ return [parts[0] || 0, parts[1] || 0, parts[2] || 0, prerelease];
19
37
  };
20
- const [aM, am, ap] = parse(a);
21
- const [bM, bm, bp] = parse(b);
38
+ const [aM, am, ap, aPre] = parse(a);
39
+ const [bM, bm, bp, bPre] = parse(b);
22
40
  if (aM !== bM) return aM > bM ? 1 : -1;
23
41
  if (am !== bm) return am > bm ? 1 : -1;
24
42
  if (ap !== bp) return ap > bp ? 1 : -1;
43
+ if (aPre !== bPre) return aPre ? -1 : 1;
25
44
  return 0;
26
45
  }