nansen-cli 1.46.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 (77) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +129 -14
  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 +8 -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 +5 -2
  35. package/skills/nansen-wallet-manager/SKILL.md +11 -9
  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 +202 -104
  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 +126 -21
  51. package/src/cache-inspect.js +345 -0
  52. package/src/cli.js +470 -197
  53. package/src/commands/agent.js +15 -7
  54. package/src/commands/completion.js +2 -15
  55. package/src/commands/mcp.js +20 -18
  56. package/src/cost-cache.js +16 -2
  57. package/src/debug.js +348 -0
  58. package/src/doctor.js +22 -45
  59. package/src/hl-action.js +41 -13
  60. package/src/mcp-client-config.js +169 -0
  61. package/src/mcp-client-config.json +17 -0
  62. package/src/mcp-verify.js +6 -5
  63. package/src/perp.js +41 -0
  64. package/src/privy.js +12 -12
  65. package/src/response-meta.js +56 -1
  66. package/src/rpc-urls.js +9 -11
  67. package/src/schema.json +185 -8
  68. package/src/semver.js +23 -4
  69. package/src/swap-simulation.js +35 -30
  70. package/src/telemetry.js +20 -0
  71. package/src/trading.js +266 -29
  72. package/src/transfer.js +53 -6
  73. package/src/update-check.js +9 -1
  74. package/src/wallet.js +107 -17
  75. package/src/walletconnect-trading.js +24 -5
  76. package/src/x402-svm.js +123 -64
  77. package/src/x402.js +46 -14
package/CHANGELOG.md CHANGED
@@ -1,5 +1,113 @@
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
+
3
111
  ## 1.46.0
4
112
 
5
113
  ### 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`
@@ -76,8 +89,22 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
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.
@@ -174,6 +203,8 @@ nansen trade execute --quote <quoteId> --yes # skip the confirmation promp
174
203
 
175
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.
176
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
+
177
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.
178
209
 
179
210
  | Exit code | Meaning |
@@ -322,8 +353,72 @@ after upgrading the CLI to pick up new commands.
322
353
  | `--pretty` | Human-readable JSON |
323
354
  | `--table` | Table format |
324
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) |
325
357
  | `--labels <label>` | Smart Money label filter |
326
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.
327
422
 
328
423
  ## Supported Chains
329
424
 
@@ -340,10 +435,30 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
340
435
 
341
436
  **Use `--stream` for large results** — outputs NDJSON instead of buffering a giant array.
342
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
+
343
452
  **ENS names** work anywhere `--address` is accepted: `--address vitalik.eth`
344
453
 
345
454
  ## Output Format
346
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
+
347
462
  ```json
348
463
  { "success": true, "data": <api_response> }
349
464
  { "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "requestId": "...", "details": { ... } }
@@ -380,7 +495,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
380
495
  |---------|-----|
381
496
  | `command not found` | `npm install -g nansen-cli` |
382
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 |
383
- | `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 |
384
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 |
385
500
  | Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
386
501
  | Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
@@ -0,0 +1,117 @@
1
+ # Browser login
2
+
3
+ Browser login saves a session after you approve the CLI in your browser. This source includes browser login, but normal-release acceptance is still pending. No published browser-login cohort is established by these docs. Existing direct API-key commands remain available.
4
+
5
+ ## Preview platform scope
6
+
7
+ The proposed initial preview is limited to macOS arm64, a local Terminal in a GUI login session, an unlocked login Keychain and a local home directory. It remains subject to release approval. Background agents, SSH sessions and network or synchronized home directories are not qualified by a successful local Terminal login.
8
+
9
+ Linux live remote-login qualification is pending. Windows is excluded from the initial preview. The presence of an OS adapter or native prebuilt package does not establish support. Desktop prompt cancellation and OS login/reboot persistence remain unverified.
10
+
11
+ Browser login requires enabled server access and working native credential storage. If the store is locked, unlock it and retry from the supported Terminal context. Repeating browser approval does not repair Keychain access. Missing native dependencies require reinstalling with optional dependencies enabled. There is no plaintext session-storage fallback.
12
+
13
+ ## Commands and selection
14
+
15
+ ```bash
16
+ nansen login
17
+ nansen login --no-browser
18
+ nansen auth status
19
+ nansen account
20
+ nansen logout
21
+ ```
22
+
23
+ Plain `nansen login` always requests fresh browser approval, even when you already have a saved session or API key. Check the displayed code, account, client and requested access before approving. Visiting the link alone grants nothing. Email/password and Google are the documented sign-in methods; Apple device sign-in is not supported by this flow.
24
+
25
+ `--no-browser` runs the same flow without opening a browser automatically. You can approve on another device; the terminal needs no inbound callback and still needs usable native storage.
26
+
27
+ Ordinary commands prefer an existing supported explicit credential override, then `NANSEN_API_KEY`, then the active saved credential. Plain login does not copy an environment key into config. The candidate browser session is checked independently before it replaces a saved credential. An environment key still takes precedence afterward; unset it to use the saved session.
28
+
29
+ Explicit legacy key setup remains available through `nansen login --human` and `nansen login --api-key <key>`. Prefer the hidden prompt over placing secrets in shell arguments. Legacy setup retains option, environment, then hidden-prompt precedence. No new global key option or named profile is introduced.
30
+
31
+ | Starting state | Plain login | Ordinary commands after success |
32
+ | --- | --- | --- |
33
+ | No credentials | Fresh approval installs B | B |
34
+ | Environment key A only | Verify B independently, save B, report override | A until the key is unset, then B |
35
+ | Saved key A | Fresh approval replaces A after durable install | B; failed approval/install preserves A |
36
+ | Saved session A | Fresh approval installs B and retires A | B; failed approval/install preserves A |
37
+ | Environment A and saved B | Fresh approval is independent of A | A still wins; status distinguishes saved and effective |
38
+ | Missing/locked store | Fail before approval with recovery guidance | Existing direct API-key access remains usable |
39
+
40
+ Login verifies the approved account without charging for research. Research uses the effective account's credits, plan and endpoint permissions. Login does not purchase credits or create a subscription. Existing server-side account billing settings remain separate.
41
+
42
+ An invalid selected credential fails with an error. The CLI does not silently switch accounts, restore an older saved key or pay after authentication or authorization fails. A supported HTTP 402 payment challenge uses the same automatic x402 flow for API keys, browser sessions and anonymous requests, subject to existing wallet authorization, token/recipient policy and spending limits. The paid retry sends only the payment credential; it does not change saved authentication or top up account credits. Login verification never pays. Browser Bearer requests cannot be combined with an API key or a manually supplied payment signature. Explicit manual API-key payment remains supported.
43
+
44
+ ## Permissions and credential safety
45
+
46
+ Browser login requests `nansen:api` for the account's API permissions. Ownership, plan, credit, quota and endpoint restrictions still apply. Wallet signing and trade confirmation remain separately authorized. Existing OAuth/MCP read-only grants are unchanged; older read-only sessions require fresh approval for API access.
47
+
48
+ API resource requests use Bearer authentication. Anyone holding a copied access token can use it until the server rejects it or it expires. Device-key proof applies to pairing, refresh and revocation; it is not required on each API resource request. Treat access tokens, refresh tokens and device keys as secrets.
49
+
50
+ Only matching trusted Nansen API origins receive session credentials. Arbitrary RPCs and separate wallet/trading authorization flows do not receive the browser token. MCP installation provisions a separate integration key and cannot export a browser session as an API key.
51
+
52
+ ## Machine output
53
+
54
+ `login --json` and non-TTY login emit NDJSON. There is one pending event and one terminal event on a normal approval attempt. Preflight failure emits only the terminal error. Human progress goes to stderr in machine mode.
55
+
56
+ ```json
57
+ {"version":1,"event":"pending","verification_uri":"https://idp.nansen.ai/device?user_code=ABCD-EFGH","user_code":"ABCD-EFGH","expires_at":"2026-09-19T00:10:00.000Z"}
58
+ {"version":1,"event":"saved","account_id":"example-account","effective_source":"session","cleanup":[]}
59
+ ```
60
+
61
+ Failure/cancellation events contain a fixed code, message and cleanup outcomes. Events never contain device_code, access/refresh token, private JWK, proof or nonce. Public user codes are displayed only for approval, never telemetry. Local diagnostics are cached/unverified; the native store is not opened by status because it could prompt. `storage_access:not_checked_no_prompt` is deliberate, not a success claim.
62
+
63
+ ## Secure storage and compatibility
64
+
65
+ Browser access tokens, refresh tokens and the private device key are stored in the OS credential store. Config and recovery journals retain bounded metadata and credential references. Legacy saved API keys retain their existing config-file storage policy. Do not share config, journals or store contents in public bug reports.
66
+
67
+ The CLI coordinates reads and writes across processes with native locking. Only local filesystems are intended. A login approved earlier cannot overwrite a later completed login or logout. Failed approval or storage leaves the previous selected credential intact.
68
+
69
+ Native lock and keyring bindings are optional package dependencies, but are required for saved-auth writes and browser-session storage. Help, offline diagnostics and direct environment/API-key requests do not open the browser-session store. macOS uses Keychain, Linux uses persistent Secret Service, and the Windows adapter uses Credential Manager. These implementations do not widen the preview platform scope above. Windows persistence may roam according to OS policy; device-local-only storage is not promised.
70
+
71
+ The session format uses chunked secure entries and a manifest. Incomplete, mixed or corrupt entries are rejected. Larger-than-supported sessions fail without replacing the previous credential. Do not manually modify these entries.
72
+
73
+ Renewal upgrades authentication metadata to v2. Logout retains v2 metadata, so installing an older pre-v2 CLI after logout is not a supported in-place downgrade. Use a tested compatible recovery version. Never force a metadata version, delete journals or restore a superseded key to make an older binary run. Do not run older and newer auth writers concurrently.
74
+
75
+ ## Automatic session renewal
76
+
77
+ Ordinary commands renew the selected session near access-token expiry or after expiry. They do not open the browser. Explicit/environment keys bypass inactive saved sessions. Concurrent commands coordinate renewal through the same authentication owner.
78
+
79
+ A known non-consuming refusal can be retried with backoff. Repeated refusals eventually require fresh login. During a long cooldown, `nansen login` requests new approval. Unexpired access may still be used during a cooldown; expired access is never used.
80
+
81
+ A lost or malformed refresh response can mean the server consumed the refresh token. The CLI does not replay an uncertain token. If a complete replacement was saved, retrying the command can recover it; otherwise follow the error's fresh-login guidance. Storage-access errors require repairing storage first. Correct system time when the error indicates clock skew. API authentication failure never triggers account switching or payment fallback.
82
+
83
+ `nansen auth status` reports cached, unverified metadata without opening the store or renewing a session. Its renewal state does not prove that the server currently accepts the token. `nansen account` is the live check for the effective credential.
84
+
85
+ If an approval expires or was consumed before token issuance completed, run `nansen login` again and approve the new code. The CLI cannot assume that a failed or lost response issued no credentials.
86
+
87
+ ## Logout and uncertainty
88
+
89
+ `nansen logout` clears saved API authentication and attempts to retire its browser session. It preserves wallets, wallet passwords, environment variables and independently managed API keys. It does not sign out unrelated sessions.
90
+
91
+ Local removal, a server retirement receipt and observed API rejection are separate outcomes. Revocation can take time to reach API caches. A receipt marked recorded/pending is not an immediate-rejection guarantee. Legacy refresh-only retirement can leave access tokens usable until expiry; the CLI reports that limitation. No fixed propagation time is promised here.
92
+
93
+ A locked store can allow deselection while preventing physical deletion. Unlock it and rerun logout. If remote retirement is unconfirmed, treat the remote session as potentially usable and contact support through a private channel. A missing local credential is not proof of remote revocation.
94
+
95
+ ## Offline recovery without native locking
96
+
97
+ Restore the native optional dependencies before modifying saved authentication. Environment/API-key requests, help and offline diagnostics remain usable without opening the browser-session store. Do not use an incompatible older CLI as a recovery shortcut. Platforms without a verified working native binding are outside the browser-login preview.
98
+
99
+ For emergency removal of a **legacy saved API key only**, first stop every CLI/auth process, including older CLI versions. If any pending, corrupt or unrecognized auth-operations journal exists, stop and use a compatible recovery binary or support-assisted reconciliation instead. Back up config.json securely without displaying its contents. In `~/.nansen/config.json`, remove only `apiKey` and replace `auth` with `{"version":1,"selectionEpoch":"<fresh UUID>","active":{"kind":"none"}}`. If the existing auth version is 2, retain version 2 in this legacy-key-only tombstone; do not downgrade it. Generate the UUID with `node -e 'console.log(require("node:crypto").randomUUID())'`; it is not a secret. Preserve every other config field, file permissions and all wallet files. Do not modify a config whose `auth.active.kind` is `session`: restore native locking instead so its generation remains available for retirement. Do not delete `auth-operations`, lock files or OS credential entries. This offline edit removes saved-key selection only; it does not revoke an API key or remove an environment override. Once native support is restored, rerun `nansen logout` to drain pending cleanup. The packaged copy of this document is available under `docs/browser-login.md` in the installed package.
100
+
101
+ ## Damaged or unrecognized journals
102
+
103
+ `AUTH_JOURNAL_INVALID` means recovery metadata could not be read safely. `AUTH_STATE_INVALID` can indicate disagreement between the selected credential and its journal. Logout may already have cleared selection while leaving cleanup incomplete. These errors do not prove the secure entries were removed or the remote session was revoked.
104
+
105
+ Do not delete, rename or quarantine journals to make login succeed. Stop all CLI/auth processes and preserve the config, journals and secure-store entries. Restore a known-valid backup only for the same operation and current state, preserving ownership and permissions. Otherwise contact support privately to reconcile the metadata. Never post credential-bearing files or store contents publicly.
106
+
107
+ After validated recovery, rerun logout and inspect its cleanup result. Cleanup is bounded per invocation; locked storage may require another attempt after unlocking. Damaged metadata requires reconciliation, not repeated unlocks or fresh approvals.
108
+
109
+ ## Telemetry preferences
110
+
111
+ Set `DO_NOT_TRACK=1` or `NANSEN_NO_TELEMETRY=1` to disable telemetry. Login/logout telemetry uses fixed command paths and bounded outcome/error categories. It excludes tokens, device/user codes, private keys, flag values and raw hostnames. Local status and offline doctor remain offline; cached metadata is not proof of validity or unlocked storage.
112
+
113
+ ## Release status
114
+
115
+ Browser-login publication and production access require separate release approval. The proposed platform scope above is not a normal-release support claim. Current source code or a passing test does not establish that browser login is enabled for your account. Use the documented API-key setup if browser access is unavailable.
116
+
117
+ Maintainers should use the [release checklist](https://github.com/nansen-ai/nansen-cli/blob/main/docs/releases/browser-login-checklist.md) in the repository. Internal validation captures, deployment inventories and incident records belong in access-controlled project records, not the public package.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nansen-cli",
3
- "version": "1.46.0",
3
+ "version": "2.0.0",
4
4
  "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
@@ -13,7 +13,8 @@
13
13
  "!src/__tests__/**",
14
14
  "skills/**",
15
15
  "scripts/postinstall.js",
16
- "CHANGELOG.md"
16
+ "CHANGELOG.md",
17
+ "docs/browser-login.md"
17
18
  ],
18
19
  "scripts": {
19
20
  "postinstall": "node scripts/postinstall.js",
@@ -27,6 +28,10 @@
27
28
  "test:send": "vitest run --config vitest.e2e.config.js src/__tests__/send.e2e.test.js",
28
29
  "test:privy": "vitest run --config vitest.e2e.config.js src/__tests__/privy.e2e.test.js",
29
30
  "lint": "eslint .",
31
+ "mcp:generate": "node scripts/generate-mcp-docs.js",
32
+ "mcp:check": "node scripts/generate-mcp-docs.js --check",
33
+ "mcp:check-pin": "node scripts/check-mcp-remote-pin.js",
34
+ "mcp:check-consumers": "node scripts/check-mcp-consumers.js",
30
35
  "lint:fix": "eslint . --fix",
31
36
  "changeset": "changeset",
32
37
  "changeset:version": "changeset version && npm install --package-lock-only",
@@ -76,5 +81,9 @@
76
81
  "@noble/curves": "^2.4.0",
77
82
  "@noble/hashes": "^2.4.0",
78
83
  "@scure/base": "^2.0.0"
84
+ },
85
+ "optionalDependencies": {
86
+ "@napi-rs/keyring": "2.1.0",
87
+ "fs-native-extensions": "1.5.1"
79
88
  }
80
89
  }