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/CHANGELOG.md CHANGED
@@ -1,5 +1,177 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - [#657](https://github.com/nansen-ai/nansen-cli/pull/657) [`55c5539`](https://github.com/nansen-ai/nansen-cli/commit/55c55397daabe48a8b4458fa4f1950025ede6295) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Plain `nansen login` now requests fresh browser approval and saves a revocable session in the OS credential store, even when NANSEN_API_KEY is set. Scripts that previously used plain login to save an environment key must use explicit `--human` or `--api-key` setup. Environment keys still override saved authentication for commands. Add `--no-browser`, safe machine login events, offline session diagnostics and wallet-preserving logout. Selected sessions renew automatically; rejected or uncertain renewal requires fresh login. Browser login is intended for a gated prerelease cohort before normal-release promotion.
8
+
9
+ API keys and browser sessions use the same automatic x402 wallet payment behavior for supported HTTP 402 challenges, under existing wallet controls and spending limits. The paid retry sends the payment credential without the account credential and leaves saved authentication unchanged. Authentication and authorization failures never trigger payment; login verification remains non-paying. Existing anonymous automatic payments and manual API-key payments remain supported.
10
+
11
+ Native credential operations acquire helper-owned execution exclusion before receiving secrets and retain it through executor termination, preventing a surviving helper from overtaking logout recovery after CLI process death. Native-daemon outstanding-write cancellation remains an OS acceptance gap; physical deletion is best effort.
12
+
13
+ Keep cancellation cleanup conservative after ambiguous issuance, preserve damaged recovery journals with actionable diagnostics, and restrict login/logout telemetry to fixed paths and allowed metadata.
14
+
15
+ First-party browser sessions request `nansen:api` for API-key-equivalent account permissions, including smart-alert CRUD and trading API operations under existing account/plan/endpoint checks. Read-scoped CLI sessions require fresh login; existing OAuth/MCP read grants are not broadened. Hosted swap simulation now uses the selected credential on the matching trusted API origin, without exposing it to third-party RPCs or granting wallet signing authority.
16
+
17
+ Hosted simulation rejects selected-account authentication/authorization failures instead of degrading past them; wallet signing checks remain unchanged.
18
+
19
+ Preserve anonymous hosted-simulation warn-and-proceed behavior on 401/403 while selected account credentials still fail closed. Resolve a missing home environment through the OS home directory, and refuse relative authentication storage paths.
20
+
21
+ Explicit API-key login now saves the same API URL used to verify the key, preserving staging or custom API configuration.
22
+
23
+ ### Minor Changes
24
+
25
+ - [#658](https://github.com/nansen-ai/nansen-cli/pull/658) [`70e56a7`](https://github.com/nansen-ai/nansen-cli/commit/70e56a729364546f32d2a60fdb3fcf0ad68b1050) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Automatically renew selected browser sessions under the shared credential owner. Coordinate concurrent commands, recover complete stored replacements, and require login after uncertain rotation without replaying consumed tokens or falling back to keys/payments. Renewal upgrades saved authentication metadata to v2; logout retains v2, so recovery requires a tested v2-compatible version; no in-place pre-v2 downgrade is supported.
26
+
27
+ Renewal preserves the first-party nansen:api grant for account API permissions, including smart alerts and matching-origin hosted trade simulation. Read-only or unscoped credentials are not upgraded. Wallet signing and MCP integration-key provisioning remain separate.
28
+
29
+ Stop automatic renewal after five consecutive proven non-consuming failures, with a durable counter and cooldown across commands. Malformed retry metadata fails closed without silently switching credentials.
30
+
31
+ Show the fresh-login recovery command during renewal cooldowns, including server-requested waits of up to 24 hours.
32
+
33
+ - [#670](https://github.com/nansen-ai/nansen-cli/pull/670) [`1faade8`](https://github.com/nansen-ai/nansen-cli/commit/1faade8450b8e5205e8f2d4d32722c742d089b23) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `nansen cache stats` and safe cache controls. `nansen cache stats` reports, for each cache the CLI keeps under `~/.nansen` (saved API responses, the credit cost map, the update check), how many entries it holds, how many bytes that is on disk, the age of its oldest and newest entry, the effective TTL, and how many entries are already expired — as a text report, or as an object with `--json`. Hits and misses are not recorded on disk, and the report says so rather than guessing.
34
+
35
+ `nansen cache clear` now takes an explicit target — `responses` (the default), `cost-map`, `update-check` or `all` — and prints exactly what it removed. It only ever deletes entries in the cache it was pointed at; credentials, wallets, saved quotes and config are never touched, and a symlink in the cache directory is skipped rather than followed.
36
+
37
+ Which commands cache is now documented rather than guessable: `nansen schema` carries a `caching` section, `nansen cache` explains it in its own help, and `--cache`/`--no-cache` are listed in the schema's global options alongside `--cache-ttl`. `NANSEN_NO_CACHE=1` is a new flagless equivalent of `--no-cache`, for wrappers that cannot change the command line.
38
+
39
+ Stats are aggregates only: only timestamp metadata is used, and no cached payload, request parameter, endpoint path or cache key is ever printed.
40
+
41
+ - [#668](https://github.com/nansen-ai/nansen-cli/pull/668) [`77b7020`](https://github.com/nansen-ai/nansen-cli/commit/77b7020af913f777dcf45fea82af19a47d3221f3) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `--debug` request tracing. `--debug` (or `NANSEN_DEBUG=1`) prints HTTP trace events to stderr — method, URL, response status, time-to-response-headers in milliseconds (TTFB; excluding body download/parsing), retry decisions (attempt, reason, delay) and the server request id — so auth, timing, retry and response-shape problems can be diagnosed without guesswork. stdout still carries only the JSON/CSV, so piping is unaffected. The trace never prints credentials or response bodies: header values are withheld entirely, and query-string values are blanked whenever the parameter names a key, token, secret, signature, password or auth, as is any remaining credential-shaped value.
42
+
43
+ Migration: `DEBUG=1` no longer enables Nansen diagnostics. Use `NANSEN_DEBUG=1` (or `--debug`) instead.
44
+
45
+ - [#656](https://github.com/nansen-ai/nansen-cli/pull/656) [`7faeb1c`](https://github.com/nansen-ai/nansen-cli/commit/7faeb1c40bf2524fa04f81cdfe80f895a60c93db) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `--paginate` (alias `--all`) to fetch every page of a list-returning command in one call (API-275). Starts at `--page`, uses `--limit` as the page size, and stops on a short or empty page, on server completion metadata, on a repeated page, or after `--max-pages` requests (default 10, maximum 1000). `--max-pages` is parsed only when pagination is active and is otherwise ignored. The merged response keeps the first page's shape with rows de-duplicated and adds `pagination: { page, pages_fetched, next_page, complete }`; `next_page` tells you where to resume when the cap was hit, and the stderr credit summary totals live page requests. Default single-page behaviour is unchanged.
46
+
47
+ Table, CSV, and stream output now intentionally use the same row extraction as pagination: they render rows inside nested `{ data: { data: [...] } }` and `{ data: { results: [...] } }` envelopes, and inside an unambiguous descriptive top-level array key such as `trades` or `holdings`, individually instead of treating the envelope as one row. Envelopes with multiple top-level arrays are not guessed.
48
+
49
+ This remains a minor release because the default JSON contract is unchanged; only the opt-in table, CSV, and NDJSON handling of a previously inconsistent, undocumented envelope shape is normalized.
50
+
51
+ With `token screener --search --paginate`, `--limit` remains the server page size and each candidate page is separately billed up to `--max-pages`; the merged candidate set is then filtered client-side without slicing it back to one page.
52
+
53
+ - [#706](https://github.com/nansen-ai/nansen-cli/pull/706) [`201290f`](https://github.com/nansen-ai/nansen-cli/commit/201290f8ffb849e63ae11396be30ac4edc39baf2) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `nansen login --api-key-stdin` to verify and save a key from a pipe or protected file without placing it in command arguments or printing it.
54
+
55
+ - [#703](https://github.com/nansen-ai/nansen-cli/pull/703) [`6b1e707`](https://github.com/nansen-ai/nansen-cli/commit/6b1e707f088379405df2ff724b0836cc39ff3ecc) Thanks [@gulshngill](https://github.com/gulshngill)! - `token screener --search` now says how far it looked. The client-side filter can only find a token among the candidate rows it fetched (the first 500 by default, more with `--limit`/`--page`, every traversed page with `--paginate`), so the response adds `_meta.search: { query, searched, matched, complete }`: `searched` is the number of candidate rows scanned, `matched` the number of matches before `--page`/`--limit` slicing, and `complete: false` means the API had more rows beyond that window, so an empty or short result no longer looks the same as "the token does not exist". `complete` follows the server's `is_last_page` (or the `--paginate` traversal summary) when present and falls back to "the window came back full". When the search was cut short a one-line note also goes to stderr with the ways to widen it (`--limit` up to 1000, `--paginate`, or a higher `--max-pages`) or narrow the candidates (`--filters`), so `--fields`, `--table`, `--format csv` and `--stream` callers that never see `_meta` still learn about it. Row data and `pagination` are unchanged.
56
+
57
+ ### Patch Changes
58
+
59
+ - [#713](https://github.com/nansen-ai/nansen-cli/pull/713) [`e1f9878`](https://github.com/nansen-ai/nansen-cli/commit/e1f987863122df6c16bf28ffee95a91b976430fe) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Check every EVM bridge transaction against the fee cap before broadcasting the first step, so an over-cap deposit cannot leave a paid approval behind.
60
+
61
+ - [#659](https://github.com/nansen-ai/nansen-cli/pull/659) [`a5f4529`](https://github.com/nansen-ai/nansen-cli/commit/a5f452935dafc91775ed7e0c4b81473c93ea7846) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Align browser onboarding, help and shipped skills with API-key-equivalent nansen:api account permissions. Preserve automatic renewal, configured-key precedence, separate wallet signing and persistent MCP integration keys. Verify the installed npm executable and shared browser/key command transports; retain native recovery and release gates.
62
+
63
+ Require an explicit yes before installing the optional AI coding skill. Pressing Enter skips installation.
64
+
65
+ - [#670](https://github.com/nansen-ai/nansen-cli/pull/670) [`1faade8`](https://github.com/nansen-ai/nansen-cli/commit/1faade8450b8e5205e8f2d4d32722c742d089b23) Thanks [@gulshngill](https://github.com/gulshngill)! - Use the default response TTL when cache stats receives an invalid TTL. Reject invalid clock values. Match the expiry boundary used by each cache reader, and reject invalid timestamp metadata in the readers.
66
+
67
+ - [#670](https://github.com/nansen-ai/nansen-cli/pull/670) [`1faade8`](https://github.com/nansen-ai/nansen-cli/commit/1faade8450b8e5205e8f2d4d32722c742d089b23) Thanks [@gulshngill](https://github.com/gulshngill)! - Reject invalid cache subcommands, empty clear targets, and extra positional arguments before deleting files. Fix cache stats for large response caches.
68
+
69
+ Show an informational message when a selected cache has no entries to clear.
70
+
71
+ - [#711](https://github.com/nansen-ai/nansen-cli/pull/711) [`5f0463b`](https://github.com/nansen-ai/nansen-cli/commit/5f0463b199f76fc09b92140d7a12d9b12d5c4b5f) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Explain pending session revocation in plain language, including that existing access tokens may briefly continue to work across API servers.
72
+
73
+ - [#694](https://github.com/nansen-ai/nansen-cli/pull/694) [`2eb2164`](https://github.com/nansen-ai/nansen-cli/commit/2eb21643fcbd1b528c89b16017ae7d21e93b414e) Thanks [@FlashWayne](https://github.com/FlashWayne)! - EVM swaps, approvals and bridge deposits refuse a transaction whose worst-case gas cost (fee cap × gas limit) exceeds 1 ETH, checked for the swap before any approval is sent. `--max-tx-fee <eth>` on `trade execute` and `bridge execute` changes the cap, and `0` disables it. A fee or gas limit that is zero, negative or malformed is refused too.
74
+
75
+ - [#678](https://github.com/nansen-ai/nansen-cli/pull/678) [`eff5ef3`](https://github.com/nansen-ai/nansen-cli/commit/eff5ef34167759cdb646a09043147bf9d8903df7) Thanks [@0xShadowX](https://github.com/0xShadowX)! - `wallet send` no longer tells an EVM user to top up SOL when the RPC rejects the transaction for insufficient native balance
76
+
77
+ - [#690](https://github.com/nansen-ai/nansen-cli/pull/690) [`da7aed8`](https://github.com/nansen-ai/nansen-cli/commit/da7aed8c085d943c01cc347bc233d62308b5a492) Thanks [@FlashWayne](https://github.com/FlashWayne)! - `perp order` and `perp close` refuse a price or size at or above 1e21 instead of encoding it as `"1e+21"` in the signed action, which Hyperliquid rejects after signing
78
+
79
+ - [#659](https://github.com/nansen-ai/nansen-cli/pull/659) [`a5f4529`](https://github.com/nansen-ai/nansen-cli/commit/a5f452935dafc91775ed7e0c4b81473c93ea7846) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Keep installation successful and show an authentication repair tip when onboarding cannot load or select credentials.
80
+
81
+ - [#627](https://github.com/nansen-ai/nansen-cli/pull/627) [`1be85a2`](https://github.com/nansen-ai/nansen-cli/commit/1be85a27945193d2ae4e513413c83f7a72827434) Thanks [@kome12](https://github.com/kome12)! - Harden EVM bridge deposit quote and execute validation.
82
+
83
+ - [#685](https://github.com/nansen-ai/nansen-cli/pull/685) [`ca758cc`](https://github.com/nansen-ai/nansen-cli/commit/ca758ccb53c865a33007e3643d98c7aa67de99ba) Thanks [@kriss39](https://github.com/kriss39)! - `perp order` take-profit/stop-loss side validation and `perp transfer` amount bounds now throw coded `INVALID_INPUT` errors like the rest of the perp input guards
84
+
85
+ - [#691](https://github.com/nansen-ai/nansen-cli/pull/691) [`8930137`](https://github.com/nansen-ai/nansen-cli/commit/8930137b6a0578d965aa72f5220acad63a7414be) Thanks [@FlashWayne](https://github.com/FlashWayne)! - WalletConnect results are parsed without counting braces inside string values, so a wallet message containing `}` no longer makes a successful transaction or x402 payment look like a failure
86
+
87
+ - [#698](https://github.com/nansen-ai/nansen-cli/pull/698) [`cd3db5a`](https://github.com/nansen-ai/nansen-cli/commit/cd3db5a825dd3ff7d57cae5e47cf3710863b8c80) Thanks [@FlashWayne](https://github.com/FlashWayne)! - `perp` commands refuse to run when `NANSEN_HL_API_URL` points at the Hyperliquid testnet, instead of signing mainnet asset ids into testnet actions and showing mainnet positions for a testnet account
88
+
89
+ - [#696](https://github.com/nansen-ai/nansen-cli/pull/696) [`e48fbfd`](https://github.com/nansen-ai/nansen-cli/commit/e48fbfd4ee153988b066ca0e18f14d3080fd8564) Thanks [@FlashWayne](https://github.com/FlashWayne)! - `trade execute` claims a quote by renaming it to `<id>.executing.json` before signing, so two concurrent runs of the same quote id cannot both broadcast a swap, and a run that waited at the confirmation prompt re-reads the quote before signing. A run that may have sent a swap without recording it leaves the quote claimed, so a retry is refused rather than broadcast twice
90
+
91
+ - [#687](https://github.com/nansen-ai/nansen-cli/pull/687) [`25408eb`](https://github.com/nansen-ai/nansen-cli/commit/25408eb1779dbf53491b8b9a5c8073643c0a3b19) Thanks [@Bruce039](https://github.com/Bruce039)! - Version comparison (update notifier, `doctor`) reads a prerelease-suffixed component numerically instead of as 0, so `1.2.10-beta` no longer compares below `1.2.9`. Build metadata is now ignored when ranking, so `1.2.3+build.7` and `1.2.3` compare equal, and a prerelease ranks below the release it precedes.
92
+
93
+ - [#684](https://github.com/nansen-ai/nansen-cli/pull/684) [`5485795`](https://github.com/nansen-ai/nansen-cli/commit/5485795c39105d17afb19ec4f9d682aff88c8ce0) Thanks [@kriss39](https://github.com/kriss39)! - `research profiler trace` clamps `--width` to 1-50 (as `--depth` is clamped to 1-5) and stops expanding the counterparty graph after 1000 nodes, reporting `stats.truncated`, so a hub address can no longer turn one command into hundreds of API calls
94
+
95
+ - [#692](https://github.com/nansen-ai/nansen-cli/pull/692) [`250d51f`](https://github.com/nansen-ai/nansen-cli/commit/250d51f81ee92ca7fde8e765b2b3e1bb3d692ec3) Thanks [@FlashWayne](https://github.com/FlashWayne)! - `trade quote` refuses an amount that resolves to zero base units (for example a fraction of a cent with `--amount-unit usd`) instead of requesting a quote for nothing
96
+
97
+ - [#702](https://github.com/nansen-ai/nansen-cli/pull/702) [`04c444c`](https://github.com/nansen-ai/nansen-cli/commit/04c444c53d9a2047a3564dbcbb2c208232435e6a) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - `perp order` now rejects a take-profit or stop-loss on the wrong side of entry before resolving the signing context, so a wallet's first order no longer submits the one-time builder-fee approval on chain for an order that was never valid
98
+
99
+ - [#680](https://github.com/nansen-ai/nansen-cli/pull/680) [`009cf9d`](https://github.com/nansen-ai/nansen-cli/commit/009cf9df3b6fbd9f9487d1b0bdd7b541ff875265) Thanks [@kriss39](https://github.com/kriss39)! - Write wallet config and key files atomically with owner-only permissions regardless of umask, and report a corrupt wallet file by name instead of hiding every other wallet behind a JSON parse error
100
+
101
+ - [#700](https://github.com/nansen-ai/nansen-cli/pull/700) [`20c43ba`](https://github.com/nansen-ai/nansen-cli/commit/20c43ba01cc133c2bc118a63f6b363b0b18b1ecf) Thanks [@FlashWayne](https://github.com/FlashWayne)! - x402 auto-payment tries the cheapest viable option a server offers first, instead of whichever it listed first
102
+
103
+ - [#712](https://github.com/nansen-ai/nansen-cli/pull/712) [`d0da5ad`](https://github.com/nansen-ai/nansen-cli/commit/d0da5ad1a716d5519cdec2c2115a81ffe58dea43) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Preserve automatic x402 payment for API-key requests and give browser sessions the same behavior on supported HTTP 402 challenges. Existing wallet authorization, payment policy and spending limits remain in force. Authentication, authorization and session-renewal failures never trigger payment; login verification and account checks never pay automatically. Paid retries send the payment credential without the API key or browser token and leave saved authentication unchanged. If a paid retry is denied for authentication, authorization, rate limits or geography, stop without signing another payment option because the transmitted payment's outcome is unconfirmed.
104
+
105
+ - [#708](https://github.com/nansen-ai/nansen-cli/pull/708) [`59ebd64`](https://github.com/nansen-ai/nansen-cli/commit/59ebd646599874d58e68293b3138e63089d303c6) Thanks [@gulshngill](https://github.com/gulshngill)! - x402 payments skip an option whose chain has no key in the wallet with a clear reason (for example `wallet "main" has no Solana key`) instead of a raw JavaScript error, and the self-sponsored Solana `feePayer` error no longer points only at Base as the alternative.
106
+
107
+ - [#683](https://github.com/nansen-ai/nansen-cli/pull/683) [`2743fea`](https://github.com/nansen-ai/nansen-cli/commit/2743feaf858998f87af8b4e864a8ef0791e51341) Thanks [@Bruce039](https://github.com/Bruce039)! - x402 Solana payments honour `NANSEN_SOLANA_RPC` for blockhash and balance calls instead of always using the public mainnet endpoint. The blockhash fetch also rejects a malformed RPC URL up front without echoing it (private RPC URLs often embed an API key), times out after 15s so a hanging endpoint no longer stalls payment fallback, and defaults to the shared RPC registry rather than a hardcoded public endpoint.
108
+
109
+ - [#686](https://github.com/nansen-ai/nansen-cli/pull/686) [`2b3541a`](https://github.com/nansen-ai/nansen-cli/commit/2b3541a3f040d022b0963d3305c5f014579137bd) Thanks [@Bruce039](https://github.com/Bruce039)! - x402 Solana payments refuse an option whose `feePayer` is the paying wallet, instead of building a transaction that fails at broadcast. The payment loop now logs why it skipped an option and moves on to the next one.
110
+
111
+ ## 1.46.0
112
+
113
+ ### Minor Changes
114
+
115
+ - [#667](https://github.com/nansen-ai/nansen-cli/pull/667) [`8dad3b9`](https://github.com/nansen-ai/nansen-cli/commit/8dad3b9a2938bbf83d4d7cbce5986e728df7b975) Thanks [@gulshngill](https://github.com/gulshngill)! - `trade execute` and `bridge execute` now take `--dry-run` and `--yes`. `--dry-run` runs the sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints the trade or transfer that would be sent (chain, tokens, amounts, recipient, approvals, fees — plus the current allowance and revert simulation on EVM); and stops before wallet credentials or signing: no wallet password needed, the quote is not consumed, exit code 0. Real execution still resolves and revalidates the live signer. When stdin is an interactive terminal, both commands now print that plan and ask `Broadcast this transaction? [y/N]` before broadcasting; declining exits 1 with nothing signed. `--yes` (`-y`) or `NANSEN_YES=1` skips the prompt. Non-interactive callers — agents, CI, pipes — are unchanged: they proceed without prompting, and `--yes` is accepted there as a no-op.
116
+
117
+ - [#501](https://github.com/nansen-ai/nansen-cli/pull/501) [`5a79f9d`](https://github.com/nansen-ai/nansen-cli/commit/5a79f9db91aa3dab3d0e8b043172e5a3af418924) Thanks [@gulshngill](https://github.com/gulshngill)! - Guard `wallet export` against accidental plaintext key disclosure. The default output is now redacted (addresses only — no decryption, no password needed). Printing private keys to stdout requires explicit acknowledgement via `--reveal` (which also warns on stderr when stdout is an interactive terminal), and the new `--file <path>` writes keys to a file created with 0600 permissions (refusing to overwrite) while keeping stdout clean. Scripts that parsed `wallet export` output must add `--reveal` or switch to `--file`. `--file` failures carry machine-readable codes: `FILE_EXISTS` when the path already exists, `FILE_WRITE_FAILED` for any other create/write error.
118
+
119
+ This safety hardening is intentionally classified as a minor change rather than a major release: it changes an unsafe default to prevent accidental private-key disclosure while preserving explicit export through `--reveal` and `--file`.
120
+
121
+ - [#669](https://github.com/nansen-ai/nansen-cli/pull/669) [`b821104`](https://github.com/nansen-ai/nansen-cli/commit/b821104abb2860b9c0bf13b79a0bb3043b65cb5f) Thanks [@gulshngill](https://github.com/gulshngill)! - Show the real subcommand help for `nansen research perp screener --help` and `nansen research perp leaderboard --help`. Because `perp` is also a top-level trading command, the help lookup stopped at the trading command's subcommand list and fell back to printing the category listing — "Use: nansen research perp <subcommand> --help", the command that had just been run — so the parameters, credit cost and example were unreachable. `nansen perp screener --help` now resolves to the same help, with an example pointing at the `research` path. Boolean options now accept `--flag=false` and reject invalid or repeated values instead of silently falling back to the server default; value-taking options also accept the conventional `--key=value` spelling, while valueless switches reject inline values instead of creating unusable stale flags. Invalid `changelog --since` values now return a structured error and a non-zero exit status.
122
+
123
+ The stricter validation intentionally rejects invalid, previously undocumented inputs that only appeared to succeed while being ignored; relying on that quiet fallback was relying on a bug, so this is classified as a minor change rather than a major breaking release.
124
+
125
+ ### Patch Changes
126
+
127
+ - [#682](https://github.com/nansen-ai/nansen-cli/pull/682) [`3e172f2`](https://github.com/nansen-ai/nansen-cli/commit/3e172f26cca04e52187b95dfbed0b43d35dc9f93) Thanks [@Bruce039](https://github.com/Bruce039)! - `alerts update` no longer resends a PATCH through the retry loop after a transient failure, matching `alerts create`
128
+
129
+ - [#649](https://github.com/nansen-ai/nansen-cli/pull/649) [`66152af`](https://github.com/nansen-ai/nansen-cli/commit/66152af23024cad484393d37849e05d749409b7e) Thanks [@kriss39](https://github.com/kriss39)! - `research profiler compare` no longer turns failed API requests into an empty comparison. When every request fails the command errors with the underlying code (for example `UNAUTHORIZED` or `RATE_LIMITED`); when some fail the result carries `incomplete: true`, an `errors` list, and `null` for the fields that could not be computed. Shared tokens are now matched on the token address when both wallets report one, falling back to the symbol when either side omits it, so two different contracts with the same symbol are no longer reported as shared.
130
+
131
+ - [#674](https://github.com/nansen-ai/nansen-cli/pull/674) [`ad178db`](https://github.com/nansen-ai/nansen-cli/commit/ad178db7cbcd21628df3c68c90a8defaef85db57) Thanks [@0xShadowX](https://github.com/0xShadowX)! - A repeated list option whose values are themselves comma-separated (`--tags defi,nft --tags sports`) is now flattened to `defi, nft, sports`. Previously the first value was kept as the literal `defi,nft`, so the same list was read differently depending on whether it was passed once or as repeated flags.
132
+
133
+ - [#652](https://github.com/nansen-ai/nansen-cli/pull/652) [`d0433d4`](https://github.com/nansen-ai/nansen-cli/commit/d0433d4e0da5092c47f63c9a74d71f167c9a347e) Thanks [@Bruce039](https://github.com/Bruce039)! - Resolve ENS names when the profiler chain is `all`. The profiler commands default `--chain` to `all`, but the resolver only accepted explicit EVM chains, so `research profiler labels --address vitalik.eth` (and every other profiler subcommand except `first-funder`) failed with `ENS names can only be resolved on EVM chains, not all` unless `--chain ethereum` was passed.
134
+
135
+ - [#654](https://github.com/nansen-ai/nansen-cli/pull/654) [`0aad196`](https://github.com/nansen-ai/nansen-cli/commit/0aad1963027ad90761e860501db4db9d438c1143) Thanks [@Bruce039](https://github.com/Bruce039)! - `--fields` now supports dotted paths. `--fields data.results.address` selects that field at that position only (array elements do not add a segment), while a bare name such as `--fields address` keeps matching at any depth. Dotted paths were mentioned in the code but matched nothing, so `--fields data.results` returned an empty object.
136
+
137
+ - [#672](https://github.com/nansen-ai/nansen-cli/pull/672) [`b10dc31`](https://github.com/nansen-ai/nansen-cli/commit/b10dc31fc0509a7941f6fac02dda76088ece71eb) Thanks [@0xShadowX](https://github.com/0xShadowX)! - `--filters` is validated as a JSON object before the request is sent. A value such as `--filters '[]'`, `--filters abc` or a repeated `--filters` flag used to be forwarded to the API as-is and only failed there with a 422; it now fails with an `INVALID_PARAMS` error that shows the expected form.
138
+
139
+ - [#660](https://github.com/nansen-ai/nansen-cli/pull/660) [`42db750`](https://github.com/nansen-ai/nansen-cli/commit/42db750fbc261572f53f02dab1716125ec3b2079) Thanks [@Ahmett101](https://github.com/Ahmett101)! - Parse SSE `data:` fields with or without the optional space after the colon so standards-compliant agent streams do not produce an empty response.
140
+
141
+ - [#651](https://github.com/nansen-ai/nansen-cli/pull/651) [`ab784a3`](https://github.com/nansen-ai/nansen-cli/commit/ab784a331aba66c7899845d22961a52c4f50b93a) Thanks [@kriss39](https://github.com/kriss39)! - Respect the server's `Retry-After` header when retrying rate-limited (429) requests. The wait was capped at the local backoff ceiling (30s), so a `Retry-After: 60` led to a retry after 30s that could only hit the limiter again. The client now waits at least as long as the header asks, and if the server asks for more than `maxRetryAfterMs` (default 120s) it fails immediately with the `retryAfterMs` in the error details instead of retrying too early. A `Retry-After` on a 5xx response is still treated as advisory and capped at the backoff ceiling as before.
142
+
143
+ - [#663](https://github.com/nansen-ai/nansen-cli/pull/663) [`bc4ecc8`](https://github.com/nansen-ai/nansen-cli/commit/bc4ecc82c4bfedfc66dbe621f96a581437bb415d) Thanks [@gulshngill](https://github.com/gulshngill)! - Option values that spell a JSON keyword (`--sort true`, `--search false`, `--label null`) are now kept as the literal strings `true`/`false`/`null` instead of being converted to a boolean or null, so string options no longer crash or silently drop the value; `--filters '{}'` and `--order-by '[...]'` still parse as JSON, and `--sort` now rejects a repeated or non-text value with `--sort must be "field" or "field:direction"`.
144
+
145
+ - [#671](https://github.com/nansen-ai/nansen-cli/pull/671) [`8a4e98f`](https://github.com/nansen-ai/nansen-cli/commit/8a4e98f8275701f328ab8d4cef850afbd5183177) Thanks [@0xShadowX](https://github.com/0xShadowX)! - Keep the body of a non-JSON error response (gateway HTML, plain text) in the error details instead of reporting `body: null`, and apply the same retry policy to it as to a JSON error: a plain-text `429` is now retried, with its `Retry-After` respected, instead of failing on the first attempt.
146
+
147
+ - [#676](https://github.com/nansen-ai/nansen-cli/pull/676) [`0112fa1`](https://github.com/nansen-ai/nansen-cli/commit/0112fa1aba981e961a2795ae4c92534eb3a8694f) Thanks [@0xShadowX](https://github.com/0xShadowX)! - Refuse to sign EVM approval, revoke, and Privy swap transactions when the quote carries no gas price, instead of defaulting to an unmineable 0.001 gwei fee that left the wallet's nonce stuck
148
+
149
+ - [#681](https://github.com/nansen-ai/nansen-cli/pull/681) [`c82492d`](https://github.com/nansen-ai/nansen-cli/commit/c82492df4d7f260f5d234aa8cbe362e4d27b08aa) Thanks [@kriss39](https://github.com/kriss39)! - `wallet send` and `trade limit-order create` reject an amount of zero, or one that truncates to zero base units at the token's precision, instead of broadcasting a transfer of nothing or creating a limit order with `inputAmount: "0"`
150
+
151
+ - [#650](https://github.com/nansen-ai/nansen-cli/pull/650) [`d4b4925`](https://github.com/nansen-ai/nansen-cli/commit/d4b4925d0de9035df6cd01a5a9165691646e9a9f) Thanks [@kriss39](https://github.com/kriss39)! - `research token screener --search` now honours `--page`. The search filter runs client-side, and previously every page returned the same first slice of matches; the candidate fetch is now widened to cover the requested page and the filtered list is sliced at the page offset.
152
+
153
+ - [#661](https://github.com/nansen-ai/nansen-cli/pull/661) [`fe5b294`](https://github.com/nansen-ai/nansen-cli/commit/fe5b294d30a8dc3e93270aead4a27a4b6513ce60) Thanks [@gulshngill](https://github.com/gulshngill)! - Recognise the API's full set of structured error codes. A 401 `unauthenticated` response once again shows `Not logged in. Run: nansen login`, `insufficient_credits` gets its do-not-retry hint, and codes that previously leaked through as raw server strings now surface as CLI codes, including the new `PLAN_UPGRADE_REQUIRED`, `GEO_BLOCKED`, `QUERY_TOO_LARGE`, `PAYLOAD_TOO_LARGE`, `METHOD_NOT_ALLOWED`, and `CONFLICT`. Retry behaviour is unchanged: it stays keyed on the HTTP status.
154
+
155
+ - [#679](https://github.com/nansen-ai/nansen-cli/pull/679) [`5c8d22b`](https://github.com/nansen-ai/nansen-cli/commit/5c8d22bc52a23574de6138a396ea878ccfb5efca) Thanks [@0xShadowX](https://github.com/0xShadowX)! - Fail with an actionable error when a Solana RPC cannot return an SPL mint's decimals, instead of silently assuming 9 and building a transfer or limit order with a mis-scaled amount
156
+
157
+ - [#675](https://github.com/nansen-ai/nansen-cli/pull/675) [`938a011`](https://github.com/nansen-ai/nansen-cli/commit/938a0112cba40f9f80ced1569fd9d2e2f32db608) Thanks [@kome12](https://github.com/kome12)! - Reject malformed or negative profiler `--delay` and token `top-tokens --limit` values instead of partially parsing them.
158
+
159
+ - [#646](https://github.com/nansen-ai/nansen-cli/pull/646) [`3290e3c`](https://github.com/nansen-ai/nansen-cli/commit/3290e3cefa2c7c5e1405d09e4d5d860ca05d404f) Thanks [@gulshngill](https://github.com/gulshngill)! - `--table` and `--format csv` error output now includes the error `code`, HTTP `status`, and `details` instead of only the message. CSV errors are emitted as a header row plus one record; table errors keep the leading `Error:` line and add one `key: value` line per field.
160
+
161
+ - [#662](https://github.com/nansen-ai/nansen-cli/pull/662) [`7fd923f`](https://github.com/nansen-ai/nansen-cli/commit/7fd923ff4d58128c19e6995e015af6093dee7586) Thanks [@gulshngill](https://github.com/gulshngill)! - Sync the `chains` list reported by `nansen schema` (and mirrored in `--help` and the README) with the chains the Nansen API actually accepts. Drops `scroll` and `ronin`, which no endpoint serves any more, and adds the chains that were missing: `algorand`, `aptos`, `arc`, `bitcoin`, `bitlayer`, `chiliz`, `citrea`, `gravity`, `hyperliquid`, `injective`, `mantra`, `near`, `robinhood`, `stacks`, `starknet`, `stellar`, `sui`, `ton`, `tron`, `viction`. Not every chain is served by every endpoint; the API still validates `--chain` per endpoint.
162
+
163
+ - [#664](https://github.com/nansen-ai/nansen-cli/pull/664) [`d034ae1`](https://github.com/nansen-ai/nansen-cli/commit/d034ae1d01582f721e8572dcd40234d21b31708a) Thanks [@gulshngill](https://github.com/gulshngill)! - `trade quote` and `trade execute` now screen the signing wallet (and any distinct `--to-wallet` destination) against the compliance blocklist before requesting a quote or signing — the same fail-closed check `bridge` and `perp` already run — so a flagged address, or a screening call that fails, aborts the command before anything is signed or broadcast. Both commands now require API access for this check; authenticate with `nansen login` or `NANSEN_API_KEY` before trading.
164
+
165
+ - [#653](https://github.com/nansen-ai/nansen-cli/pull/653) [`337271d`](https://github.com/nansen-ai/nansen-cli/commit/337271d10d226cf61b24c18d656e955cd588d91d) Thanks [@Bruce039](https://github.com/Bruce039)! - `--sort` now rejects a direction other than `asc`/`desc` and an empty field name with an `INVALID_PARAMS` error. Previously `--sort pnl_usd:sideways` was uppercased and sent to the API as `direction: SIDEWAYS`, which only failed later with an upstream 422.
166
+
167
+ - [#648](https://github.com/nansen-ai/nansen-cli/pull/648) [`0514c76`](https://github.com/nansen-ai/nansen-cli/commit/0514c76029a6c0609743d8c4af87cbdf80d9bbff) Thanks [@kriss39](https://github.com/kriss39)! - Validate `token screener --search` and `token who-bought-sold --buy-or-sell` before the request is sent, so a JSON array/object or a repeated flag (`--search '[]'`, `--buy-or-sell '{}'`) and values outside the `BUY`/`SELL` enum produce an actionable `INVALID_PARAMS` error instead of a raw `.toLowerCase()`/`.toUpperCase()` TypeError.
168
+
169
+ - [#666](https://github.com/nansen-ai/nansen-cli/pull/666) [`6539558`](https://github.com/nansen-ai/nansen-cli/commit/65395584ab9844ec3f0117ef951b2eb26ff6342c) Thanks [@gulshngill](https://github.com/gulshngill)! - Make every wallet subcommand discoverable from the places agents look first. `nansen --help` now lists `send`, `forget-password` and `secure` on the wallet line (previously only seven of the nine were shown) and the full perp subcommand set (`transfer`, `approve-builder-fee`, `orders`, `account`, `meta`, `screener` and `leaderboard` were missing). It also stops describing the combined top-level `perp` command as a deprecated analytics alias. README lists the same wallet set, and `nansen schema wallet` now documents `forget-password` and `secure` with descriptions plus an example for every wallet subcommand. Help text, README, runtime command help and schema are pinned together by a new drift-guard test.
170
+
171
+ - [#677](https://github.com/nansen-ai/nansen-cli/pull/677) [`b91e108`](https://github.com/nansen-ai/nansen-cli/commit/b91e10878d8606aa419b71a12493fbd8d273e731) Thanks [@0xShadowX](https://github.com/0xShadowX)! - Read a pretty-printed WalletConnect `sign-typed-data` result on the x402 payment path instead of failing after the user has already approved the payment in their wallet
172
+
173
+ - [#673](https://github.com/nansen-ai/nansen-cli/pull/673) [`05a2056`](https://github.com/nansen-ai/nansen-cli/commit/05a20562edb6875541998db57ec47375e2dbb2ab) Thanks [@0xShadowX](https://github.com/0xShadowX)! - `web search --num-results` now rejects a malformed value (`5abc`, `2.5`, `abc`, a repeated or valueless flag) with `INVALID_PARAMS`. Previously `5abc` was silently truncated to 5, `2.5` to 2, and a non-numeric value fell back to the API default instead of reporting the mistake.
174
+
3
175
  ## 1.45.0
4
176
 
5
177
  ### Minor Changes
package/README.md CHANGED
@@ -16,20 +16,32 @@ npx skills add nansen-ai/nansen-cli # load agent skill files
16
16
 
17
17
  ## Auth
18
18
 
19
- Three options — pick whichever fits your setup:
19
+ Plain `nansen login` requests fresh browser approval and saves a session automatically. No API-key copying or PEM setup is needed. Selected sessions renew automatically; rejected or uncertain renewal requires fresh login.
20
20
 
21
- 1. **API key** (subscription):
22
- ```bash
23
- nansen login --human # interactive prompt; saves to ~/.nansen/config.json
24
- nansen login # uses NANSEN_API_KEY when already set
25
- nansen logout # remove saved key
26
- ```
27
- For automation, inject `NANSEN_API_KEY` through your environment or secret manager.
28
- Get your API key at [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup).
21
+ ```bash
22
+ nansen login # approve the displayed code, account and CLI
23
+ nansen login --no-browser # same approval from a remote terminal
24
+ nansen auth status # offline, cached/unverified credential selection
25
+ nansen account # free live check, including with zero research credits
26
+ nansen logout # clear saved API auth; preserve wallets and environment keys
27
+ ```
28
+
29
+ Browser login requires working native credential storage and enabled server admission. Normal-release acceptance is pending; no published browser cohort is established by this branch. See [storage, supported scope and recovery](docs/browser-login.md). Email/password and Google sign-in are supported by the device-flow contract. Apple device sign-in remains deferred.
30
+
31
+ Existing API-key users can run commands directly with `NANSEN_API_KEY`. It overrides the saved session, even after successful browser login. To deliberately save an injected key, use explicit `nansen login --human`; without an environment key this prompts in a human terminal. `nansen login --api-key <key>` remains available but puts the key in shell history. Saved-auth mutations require the native lock binding. Get a conventional key at [agent setup](https://app.nansen.ai/auth/agent-setup); MCP installation exports a separate persistent API key; it does not export browser sessions.
32
+
33
+ For automation, pipe a key from your secret manager into `nansen login --api-key-stdin`, or redirect a protected key file:
34
+
35
+ ```bash
36
+ nansen login --api-key-stdin --json < /path/to/protected-api-key
37
+ ```
38
+
39
+ This reads one key (up to 4096 bytes, with an optional trailing newline), verifies it, and saves it without printing it. Input must close within 30 seconds. `--json` prints one `saved` event with the effective credential source; errors exit nonzero. As with existing API-key login, the key is stored in `~/.nansen/config.json` using an atomic write with owner-only file permissions (`0600` on POSIX), not in the OS keychain. The native lock binding is required for saving credentials. It does not create an account or issue a key. Avoid commands containing literal secrets, which may enter shell history. Do not combine it with `--api-key`, `--human`, or `--no-browser`. An existing `NANSEN_API_KEY` still overrides the saved credential until you unset it.
29
40
 
30
- 2. **x402 micropayment** (no key needed): `nansen wallet create`, fund with USDC on Base or Solana, or USDT0 on X Layer, then call any endpoint — the CLI signs `Payment-Signature` headers automatically on 402 responses. See [Wallet](#wallet).
41
+ Wallet and micropayment options:
31
42
 
32
- 3. **MPP via tempo** (no key needed): install the [tempo CLI](https://docs.tempo.xyz) separately, run `tempo wallet login` to set up, then call the Nansen API through `tempo request`. The Nansen API selects the MPP rail when it sees `Authorization: Payment ...`. See [MPP / Tempo](#mpp--tempo) below.
43
+ - **x402:** create and fund a wallet with USDC on Base/Solana or USDT0 on X Layer. API keys, browser sessions and anonymous requests can all pay a supported HTTP 402 challenge under the same wallet policy and spending limits. The paid retry sends `Payment-Signature` without the account credential. Authentication or authorization failures never trigger payment. Explicit manual API-key payment signatures remain supported.
44
+ - **MPP:** install the separate tempo CLI and use `tempo request`. Browser login does not configure a wallet, sign MPP credentials or purchase credits. See [MPP / Tempo](#mpp--tempo).
33
45
 
34
46
  ## Verify your MCP setup
35
47
 
@@ -53,6 +65,7 @@ nansen wallet <subcommand> [options]
53
65
  nansen mcp install <client> # add the Nansen MCP server to Claude Code/Desktop or Cursor
54
66
  nansen completion <bash|zsh|fish> # shell completions (no API key needed)
55
67
  nansen schema [command] [--pretty] # full command reference (no API key needed)
68
+ nansen cache stats # what the local caches hold (no API key needed)
56
69
  ```
57
70
 
58
71
  **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`
@@ -72,12 +85,26 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
72
85
 
73
86
  **Trade:** `quote`, `execute`, `bridge-status`, `limit-order` — DEX swaps on Solana and Base, cross-chain bridges, and Solana limit orders.
74
87
 
75
- **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local or Privy server-side wallets (EVM + Solana).
88
+ **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send`, `forget-password`, `secure` — local or Privy server-side wallets (EVM + Solana).
76
89
 
77
90
  Run `nansen schema --pretty` for the full subcommand and field reference.
78
91
 
92
+ ## Browser login compatibility and scope
93
+
94
+ Browser login requests `nansen:api` for the same account/API permissions as a pasted API key, including smart-alert CRUD, public agent, portfolio, web, beta and existing trading API operations. The same endpoint ownership, plan, credit, quota, sanctions and geographic checks apply. Existing OAuth/MCP `nansen:read` grants keep their existing semantics. Wallet signing remains separate.
95
+
96
+ Plain `nansen login` always starts fresh browser approval, whether no credential, an environment key, a saved key or a saved session exists. It preflights secure storage, shows a link/code, verifies the approved account through the free account endpoint, then replaces the single saved API credential. `nansen login --no-browser` runs the same flow in a remote terminal. Non-TTY login and `--json` emit NDJSON pending and terminal events; the private device code and tokens are never printed.
97
+
98
+ `NANSEN_API_KEY` still overrides the saved session. Login verifies the new account independently and explains this override. Failed approval or installation preserves the previous selection. `nansen auth status` is offline and labels saved metadata as cached/unverified; `nansen account` checks the effective credential live. `nansen logout` removes saved API authentication and attempts family retirement, preserving wallets and environment keys. Remote revocation and physical deletion failures are reported separately.
99
+
100
+ This is a breaking change for scripts that used plain login to persist an environment key. Use explicit `nansen login --human` with that environment key, or `--api-key <key>` with its existing shell-history risk. Direct key-authenticated commands need no migration. Existing API-key x402 payment behavior is preserved and also applies to browser sessions: a supported HTTP 402 challenge can trigger wallet payment under the existing policy and spending limits. A paid retry does not change the saved credential or top up account credits. Invalid credentials never cause an account switch or payment; login verification remains free and never pays.
101
+
102
+ No published cohort or normal-release acceptance is claimed. The proposed initial preview is local macOS arm64 with an unlocked Keychain. Linux remote-terminal qualification is pending; Windows is excluded from that first preview. See the [platform scope](docs/browser-login.md#preview-platform-scope). Selected browser sessions renew automatically near expiry. A lost refresh response without a complete stored replacement requires fresh login; the consumed credential is never retried. There is no browser-only research route allowlist. Public API permission parity does not grant internal service identity or wallet signing authority. Account admission and non-account API admission remain separately gated and default off. Public local/remote walkthroughs, ledger evidence and OS verification remain gates. Read [browser login custody, compatibility and release gates](docs/browser-login.md) before cohort use. Browser sessions do not add wallet-signing authority and cannot be exported as MCP API keys.
103
+
79
104
  ## MCP
80
105
 
106
+ <!-- BEGIN GENERATED: mcp. Do not edit by hand. Edit src/mcp-client-config.json (values) or scripts/templates/readme-mcp.md (prose), not README.md, then run: npm run mcp:generate. -->
107
+
81
108
  Connect any MCP client to Nansen's streamable HTTP server:
82
109
 
83
110
  - **Endpoint:** `https://mcp.nansen.ai/ra/mcp`
@@ -94,7 +121,7 @@ nansen mcp install cursor --dry-run # print what would be written (key redacted
94
121
  nansen mcp uninstall <client> # remove the entry (add --dry-run to preview)
95
122
  ```
96
123
 
97
- Uses the API key from `nansen login` / `NANSEN_API_KEY`; re-run `install` after rotating your key. Writes are merge-only and atomic: existing servers and settings are preserved, a `.bak` copy is written before every install or uninstall, and the CLI refuses to touch a config it can't parse. Note the client config stores the API key in plaintext — new files are created with `0600` permissions. Restart the client after installing.
124
+ Uses the API key from `nansen login --human` / `NANSEN_API_KEY`; re-run `install` after rotating your key. Writes are merge-only and atomic: existing servers and settings are preserved, a `.bak` copy is written before every install or uninstall, and the CLI refuses to touch a config it can't parse. Note the client config stores the API key in plaintext — new files are created with `0600` permissions. Restart the client after installing.
98
125
 
99
126
  **Manual setup**, for other clients or if you would rather not use the CLI — the paths below, and the connection docs at [docs.nansen.ai/mcp/connecting](https://docs.nansen.ai/mcp/connecting).
100
127
 
@@ -141,10 +168,12 @@ claude mcp add --transport http nansen https://mcp.nansen.ai/ra/mcp --header "NA
141
168
  }
142
169
  ```
143
170
 
144
- `mcp-remote` is pinned to an exact version rather than `@latest` because the bridge handles your API key on every request, and `npx` would otherwise pull a new release automatically. `0.2.1` is the current release and the version this config is tested against; bumping it is safe — review the release and update the pin.
171
+ `mcp-remote` is pinned to an exact version rather than `@latest` because the bridge handles your API key on every request, and `npx` would otherwise pull a new release automatically. `0.2.1` is the version this config is tested against. A weekly check reports when a newer release exists; to bump the pin, review the release and follow [MCP client config](AGENTS.md#mcp-client-config).
145
172
 
146
173
  **Claude Tag (Claude in Slack):** an admin must attach a plugin whose `.mcp.json` points at `https://mcp.nansen.ai/ra/mcp` and add a custom credential allowing the host `mcp.nansen.ai`. See the [Claude Tag custom-connections documentation](https://claude.com/docs/claude-tag/admins/connections/custom). Per-user fallback: use Claude Code or Claude Desktop.
147
174
 
175
+ <!-- END GENERATED: mcp -->
176
+
148
177
  ## Trading
149
178
 
150
179
  DEX swaps on `solana` and `base`. Two-step: quote then execute.
@@ -163,6 +192,26 @@ nansen trade execute --quote <quoteId> --gasless # Relay-only: solver pays
163
192
  nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
164
193
  ```
165
194
 
195
+ ### Before broadcasting
196
+
197
+ `trade execute` and `bridge execute` move funds irreversibly, so both accept:
198
+
199
+ ```bash
200
+ nansen trade execute --quote <quoteId> --dry-run # validate + print the plan, broadcast nothing
201
+ nansen trade execute --quote <quoteId> --yes # skip the confirmation prompt (also: -y)
202
+ ```
203
+
204
+ `--dry-run` runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints what *would* be sent (chain, tokens, amounts, recipient, approvals, fees); and stops before wallet credentials, signing, or broadcast — no wallet password needed, the quote stays usable, exit code 0. Real execution still resolves and revalidates the live signer before signing.
205
+
206
+ On EVM, both commands refuse a transaction whose worst-case gas cost (fee cap × gas limit) is above 1 ETH, before anything is signed, approvals included. That is a backstop against an anomalous quote, the same kind of cap geth and reth apply to `eth_sendTransaction`. `--max-tx-fee <eth>` changes it, and `--max-tx-fee 0` turns it off. WalletConnect transactions are not checked, since the wallet shows the fee before signing.
207
+
208
+ When stdin is an interactive terminal, execute prints that plan and asks `Broadcast this transaction? [y/N]` first; anything but `y`/`yes` aborts with exit code 1 and nothing signed. `--yes`, or `NANSEN_YES=1`, skips the question. **When stdin is not a terminal — agents, CI, pipes — nothing changes: the command proceeds without prompting**, and `--yes` is accepted as a no-op so it is always safe to pass.
209
+
210
+ | Exit code | Meaning |
211
+ |-----------|---------|
212
+ | `0` | Broadcast succeeded, or the dry run completed |
213
+ | `1` | Declined at the confirmation prompt, or the execution failed |
214
+
166
215
  Amounts are in base units (lamports, wei) by default — use `--amount-unit token|usd|percent` for friendlier inputs. Common symbols (`SOL`, `ETH`, `USDC`, `USDT`) resolve automatically. A wallet is required — set one with `nansen wallet default <name>`.
167
216
 
168
217
  ## Limit Orders
@@ -213,11 +262,12 @@ Move USDC between EVM chains and Hyperliquid via `nansen bridge`. Uses the same
213
262
  ```bash
214
263
  nansen bridge quote --from-chain base --to-chain hyperliquid --from-token USDC --amount 1000000
215
264
  nansen bridge execute --quote <quoteId>
265
+ nansen bridge execute --quote <quoteId> --dry-run # preview, nothing is broadcast
216
266
  nansen bridge execute --quote <quoteId> --nonce 20 --priority-fee 5 # replace a stuck EVM deposit
217
267
  nansen bridge status --request-id <id>
218
268
  ```
219
269
 
220
- Supported routes: `base → hyperliquid` (deposit), and `hyperliquid → base`/`ethereum`/`arbitrum` (withdraw). Deposits broadcast an EVM transaction locally, so only Base is offered on the deposit side; run `nansen bridge help` for the current list. `--amount` is a base-unit integer by default; pass `--amount-unit token` for a human amount. `--recipient` defaults to the wallet's own EVM address. `--priority-fee`/`--max-fee` (gwei) and `--nonce` apply only to EVM deposit legs and let a stuck transaction be replaced. Bridge transfers are irreversible once signed.
270
+ Supported routes: `base → hyperliquid` (deposit), and `hyperliquid → base`/`ethereum`/`arbitrum` (withdraw). Deposits broadcast an EVM transaction locally, so only Base is offered on the deposit side; run `nansen bridge help` for the current list. `--amount` is a base-unit integer by default; pass `--amount-unit token` for a human amount. `--recipient` defaults to the wallet's own EVM address. `--priority-fee`/`--max-fee` (gwei) and `--nonce` apply only to EVM deposit legs and let a stuck transaction be replaced. Bridge transfers are irreversible once signed, so `bridge execute` takes the same `--dry-run` and `--yes`/`NANSEN_YES` gate as `trade execute` (see [Before broadcasting](#before-broadcasting)); on a multi-step transfer, a dry run stops before the first step.
221
271
 
222
272
  ## Wallet
223
273
 
@@ -227,6 +277,8 @@ nansen wallet create --name my-wallet --provider privy # server-side via Privy
227
277
  nansen wallet list
228
278
  nansen wallet default <name>
229
279
  nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
280
+ nansen wallet secure # move a saved password into the OS keychain
281
+ nansen wallet forget-password # drop the saved password from every store
230
282
  ```
231
283
 
232
284
  **Local wallets** are password-encrypted. Set `NANSEN_WALLET_PASSWORD` to skip the prompt.
@@ -296,17 +348,81 @@ after upgrading the CLI to pick up new commands.
296
348
  | `--chain <chain>` | Blockchain to query |
297
349
  | `--limit <n>` | Result count |
298
350
  | `--timeframe <tf>` | Time window: `5m` `1h` `6h` `24h` `7d` `30d` |
299
- | `--fields <list>` | Comma-separated fields (reduces response size) |
351
+ | `--fields <list>` | Comma-separated fields (reduces response size); a bare name matches at any depth, a dotted path such as `data.results.address` only at that position |
300
352
  | `--sort <field:dir>` | Sort results, e.g. `--sort value_usd:desc` |
301
353
  | `--pretty` | Human-readable JSON |
302
354
  | `--table` | Table format |
303
355
  | `--stream` | NDJSON output for large results |
356
+ | `--paginate` | Fetch every page of a list command (alias `--all`); bound with `--max-pages <n>` (default 10; ignored without pagination) |
304
357
  | `--labels <label>` | Smart Money label filter |
305
358
  | `--smart-money` | Filter for Smart Money addresses only |
359
+ | `--cache` | Serve this invocation from the local cache (see [Caching](#caching)) |
360
+ | `--no-cache` | Bypass the cache for this invocation |
361
+ | `--debug` | Trace every HTTP request on stderr (see [Debugging](#debugging)) |
362
+
363
+ ## Caching
364
+
365
+ Response caching is **off by default** and opt-in per invocation:
366
+
367
+ ```bash
368
+ nansen research token screener --chain solana --cache # cache this result
369
+ nansen research token screener --chain solana --cache --cache-ttl 60
370
+ nansen research token screener --chain solana --cache --no-cache # veto: always live
371
+ ```
372
+
373
+ `NANSEN_NO_CACHE=1` does the same as `--no-cache` without a flag, for wrappers
374
+ that cannot change the command line.
375
+
376
+ With `--cache` on, every read the CLI makes through the Nansen API client is
377
+ cached — all of `nansen research ...`, plus `alerts list` and `alerts get`.
378
+ Never cached: `account`, `web search`, `web fetch`, the `alerts`
379
+ create/update/toggle/delete commands, `agent`, every `trade`, `bridge`, `wallet`
380
+ and `mcp` command, and `perp` trading. The analytics commands `perp screener`
381
+ and `perp leaderboard` are cached.
382
+
383
+ Inspect and clear what is on disk:
384
+
385
+ ```bash
386
+ nansen cache stats # entries, size, age, effective TTL per cache
387
+ nansen cache stats --json # the same numbers as an object
388
+ nansen cache clear # delete cached API responses
389
+ nansen cache clear cost-map # or update-check, or all
390
+ ```
391
+
392
+ `nansen cache stats` reports totals and ages. It reads timestamp metadata but does not print cached payloads, request parameters, or cache keys. `nansen cache clear` deletes only files in the selected cache. Credentials, wallets, saved quotes, and config are never changed. CLI startup loads the saved config as usual.
393
+
394
+ | Cache | Location | TTL |
395
+ |-------|----------|-----|
396
+ | `responses` | `~/.nansen/cache` | `--cache-ttl`, default 300s |
397
+ | `cost-map` | `~/.nansen/cost-map.json` | 24h |
398
+ | `update-check` | `~/.nansen/update-check.json` | 24h |
399
+
400
+ ## Debugging
401
+
402
+ `--debug` (or `NANSEN_DEBUG=1`) prints HTTP trace events to **stderr**, so stdout stays pure JSON/CSV and stays pipeable:
403
+
404
+ ```bash
405
+ nansen research token screener --chain solana --debug
406
+ nansen research token screener --chain solana 2>trace.log | jq . # trace to a file, JSON to jq
407
+ ```
408
+
409
+ ```
410
+ [nansen:debug] http.request method=POST url=https://api.nansen.ai/api/v1/token-screener attempt=1/4
411
+ [nansen:debug] http.response method=POST url=https://api.nansen.ai/api/v1/token-screener status=429 duration_ms=182 request_id=6f1c0f2a-0000-4000-8000-0000000000aa attempt=1
412
+ [nansen:debug] http.retry method=POST url=https://api.nansen.ai/api/v1/token-screener status=429 attempt=1 reason=retry-after delay_ms=1100 retry_after_ms=1000
413
+ [nansen:debug] http.request method=POST url=https://api.nansen.ai/api/v1/token-screener attempt=2/4
414
+ [nansen:debug] http.response method=POST url=https://api.nansen.ai/api/v1/token-screener status=200 duration_ms=143 request_id=6f1c0f2a-0000-4000-8000-0000000000ab attempt=2
415
+ ```
416
+
417
+ Events: `http.request`, `http.response`, `http.retry`, `http.error`, `http.cache_hit` (answered from the local cache, no request made).
418
+
419
+ For `http.response`, `duration_ms` is the elapsed time from starting the attempt until response headers arrive (time to first byte / TTFB). It deliberately excludes downloading and parsing the response body. For `http.error`, `duration_ms` is the elapsed time until the transport failed before any response headers arrived.
420
+
421
+ **What the trace never contains.** No API keys, wallet keys, mnemonics or payment signatures; no `Authorization`, `apikey` or `Payment-Signature` header values (header values are not traced at all); no request or response bodies. Query-string values are blanked whenever the parameter name mentions a key, token, secret, signature, password or auth, and any remaining credential-shaped value is blanked too. This intentionally includes public identifiers under names such as `token` and `token_address`, so use the original command—not the trace alone—to confirm which token was queried. Redaction deliberately fails closed: bare 64-character hex URL segments and long opaque/base58 identifiers are hidden even when they are public transaction, block, or Solana signature identifiers, because they are indistinguishable from key material without endpoint-specific assumptions. Long values are truncated. Paste a trace into a bug report as-is — but a quick read before you share is always wise.
306
422
 
307
423
  ## Supported Chains
308
424
 
309
- `ethereum` `solana` `base` `bnb` `arbitrum` `polygon` `optimism` `avalanche` `linea` `scroll` `mantle` `ronin` `sei` `plasma` `sonic` `monad` `hyperevm` `iotaevm`
425
+ `algorand` `aptos` `arbitrum` `arc` `avalanche` `base` `bitcoin` `bitlayer` `bnb` `chiliz` `citrea` `ethereum` `gravity` `hyperevm` `hyperliquid` `injective` `iotaevm` `linea` `mantle` `mantra` `monad` `near` `optimism` `plasma` `polygon` `robinhood` `sei` `solana` `sonic` `stacks` `starknet` `stellar` `sui` `ton` `tron` `viction`
310
426
 
311
427
  > Run `nansen schema` to get the current chain list (source of truth).
312
428
 
@@ -319,10 +435,30 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
319
435
 
320
436
  **Use `--stream` for large results** — outputs NDJSON instead of buffering a giant array.
321
437
 
438
+ **Use `--paginate` to fetch every page** of a list command in one call instead of looping over `--page`:
439
+ ```bash
440
+ nansen smart-money netflow --chain solana --limit 100 --paginate --max-pages 5
441
+ ```
442
+ `--limit` is the page size and `--max-pages` (default 10; ignored without pagination) caps the number of requests — every page is a
443
+ separate, separately billed API call. Server completion metadata (`total_pages`, `total`, or
444
+ `is_last_page`) is honoured so a known final page is not fetched again. Rows are de-duplicated and
445
+ the response gains
446
+ `pagination: { page, pages_fetched, next_page, complete }`; when `complete` is `false`, resume with
447
+ `--page <next_page>`. The stderr credit summary totals the live page requests; cached pages are not
448
+ counted as charges. Traversal trusts the server's `total`; if a live dataset changes or reports
449
+ inconsistent totals while pages are being fetched, later rows can be omitted. Combine with
450
+ `--stream` for NDJSON.
451
+
322
452
  **ENS names** work anywhere `--address` is accepted: `--address vitalik.eth`
323
453
 
324
454
  ## Output Format
325
455
 
456
+ > **Compatibility note:** `--table`, `--format csv`, and `--stream` now render an
457
+ > unambiguous descriptive top-level array (for example, `trades` or `holdings`)
458
+ > as one row per item, even without `--paginate`. Older versions rendered the
459
+ > enclosing response object as a single row. Envelopes with multiple candidate
460
+ > data arrays remain unexpanded.
461
+
326
462
  ```json
327
463
  { "success": true, "data": <api_response> }
328
464
  { "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "requestId": "...", "details": { ... } }
@@ -336,9 +472,13 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
336
472
  | `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
337
473
  | `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
338
474
  | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
475
+ | `PLAN_UPGRADE_REQUIRED` | The endpoint or option needs a higher subscription plan. Do not retry. |
476
+ | `GEO_BLOCKED` | Not available in your region. Do not retry. |
339
477
  | `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
340
478
  | `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
341
479
 
480
+ Every code documented on the API's [error-handling page](https://docs.nansen.ai/getting-started/error-handling) maps onto a stable CLI error code; a code the CLI does not recognise is passed through unchanged.
481
+
342
482
  **Error metadata.** When the API reports them, `details` carries:
343
483
 
344
484
  | Field | Meaning |
@@ -355,7 +495,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
355
495
  |---------|-----|
356
496
  | `command not found` | `npm install -g nansen-cli` |
357
497
  | Global install reports an older version | `npm i -g nansen-cli@latest --registry=https://registry.npmjs.org/ --prefer-online`, then check `which -a nansen` for stale binaries |
358
- | `UNAUTHORIZED` after login | `nansen auth status` shows which key is active and where it comes from; re-run `nansen login` or set `NANSEN_API_KEY` |
498
+ | `UNAUTHORIZED` after login | `nansen auth status` shows the effective credential and cached/unverified session metadata. Correct an invalid environment key first; browser login does not override it. Use fresh `nansen login` for a rejected session, or explicit legacy key setup for integration credentials |
359
499
  | MCP client lists tools but paid calls fail | Run `npx -y nansen-cli mcp verify` with the saved key or `NANSEN_API_KEY`, and ensure that same key is in the client's `NANSEN-API-KEY` header |
360
500
  | Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
361
501
  | Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |