nansen-cli 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/README.md +32 -32
  3. package/docs/auth.md +56 -0
  4. package/docs/browser-login.md +101 -7
  5. package/docs/error-codes.md +249 -0
  6. package/package.json +10 -4
  7. package/skills/nansen-agent-guide/SKILL.md +17 -1
  8. package/skills/nansen-alerts-webhook-listener/SKILL.md +1 -1
  9. package/skills/nansen-dca-tracker/SKILL.md +1 -1
  10. package/skills/nansen-defi-positions/SKILL.md +1 -1
  11. package/skills/nansen-exit-signals/SKILL.md +2 -2
  12. package/skills/nansen-fund-tracker/SKILL.md +1 -1
  13. package/skills/nansen-general-search/SKILL.md +1 -1
  14. package/skills/nansen-holder-analysis/SKILL.md +2 -2
  15. package/skills/nansen-limit-orders/SKILL.md +1 -1
  16. package/skills/nansen-mpp-payment/SKILL.md +2 -2
  17. package/skills/nansen-perp-screener/SKILL.md +1 -1
  18. package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
  19. package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
  20. package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
  21. package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
  22. package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
  23. package/skills/nansen-prediction-markets/SKILL.md +1 -1
  24. package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
  25. package/skills/nansen-smart-alerts/SKILL.md +2 -1
  26. package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
  27. package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
  28. package/skills/nansen-smart-money-trend/SKILL.md +1 -1
  29. package/skills/nansen-token-research/SKILL.md +1 -1
  30. package/skills/nansen-token-screener/SKILL.md +1 -1
  31. package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
  32. package/skills/nansen-trading/SKILL.md +1 -1
  33. package/skills/nansen-wallet-batch/SKILL.md +1 -1
  34. package/skills/nansen-wallet-clustering/SKILL.md +1 -1
  35. package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
  36. package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
  37. package/skills/nansen-wallet-manager/SKILL.md +1 -1
  38. package/skills/nansen-wallet-profiler/SKILL.md +1 -1
  39. package/skills/nansen-web-fetcher/SKILL.md +1 -1
  40. package/skills/nansen-web-searcher/SKILL.md +1 -1
  41. package/src/api-endpoints.json +1605 -0
  42. package/src/api.js +202 -97
  43. package/src/auth-credentials.js +1 -0
  44. package/src/auth-state.js +2 -2
  45. package/src/auth-store-native.js +6 -1
  46. package/src/auth-store-worker.js +1 -1
  47. package/src/auth-store.js +9 -4
  48. package/src/bridge.js +19 -10
  49. package/src/cli.js +188 -89
  50. package/src/commands/agent.js +2 -3
  51. package/src/commands/alerts.js +277 -9
  52. package/src/commands/feedback.js +98 -37
  53. package/src/commands/mcp.js +1 -1
  54. package/src/commands/research.js +14 -37
  55. package/src/cost-cache.js +33 -7
  56. package/src/doctor.js +14 -5
  57. package/src/error-codes.js +226 -0
  58. package/src/input-validation.js +551 -0
  59. package/src/limit-order.js +12 -3
  60. package/src/perp.js +2 -1
  61. package/src/privy.js +89 -11
  62. package/src/query-options.js +30 -7
  63. package/src/rpc-urls.js +3 -1
  64. package/src/schema.json +1137 -145
  65. package/src/solana-tx.js +4 -0
  66. package/src/trade-validation.js +167 -8
  67. package/src/trading.js +172 -12
  68. package/src/transfer.js +7 -1
  69. package/src/update-check.js +32 -5
  70. package/src/wallet.js +211 -57
  71. package/src/walletconnect-x402.js +14 -8
package/CHANGELOG.md CHANGED
@@ -1,5 +1,69 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#773](https://github.com/nansen-ai/nansen-cli/pull/773) [`47eb68d`](https://github.com/nansen-ai/nansen-cli/commit/47eb68db976b140be32fc776c7b44dcc630ea7bf) Thanks [@gulshngill](https://github.com/gulshngill)! - Every failure now exits 1 with `success: false`, and research commands check their input before calling the API (API-1080, API-1081).
8
+
9
+ - Subcommand typos (also with `--fields`) and unknown commands return `UNKNOWN_COMMAND` with the closest match, instead of `success: true` with the error inside `data`.
10
+ - Unknown options (`--turbo`), options a command used to ignore (`--limit` on `token ohlcv`, `--address` on `prediction-market position-detail`), options without a value (`--chain` with nothing after it), `--page 0`, `--format xml`, bad enum values and invalid dates (`--from-date 2024-13-45`) are rejected with the option named, in the REST API's wording ("Option '--timefrme' is not recognized by ... Did you mean '--timeframe'?").
11
+ - Missing required options (for example `--address`) fail locally instead of returning "API request failed (422)".
12
+ - `--chain`/`--chains` are checked against the chains each endpoint accepts; `nansen schema` lists them as `supportedChains`. Case and the API's chain aliases (`bsc`, `eth`, ...) are normalised first, as the API does. An invalid bitcoin token address now names native BTC (`1111111111111111111114oLvT2`).
13
+ - `--fields` names that match nothing in the response are an error instead of `{}`.
14
+ - `profiler balance` now sends `--limit`/`--page`, and `smart-money holdings --token` filters by token. Mixed-case EVM addresses in `--filters` are lowercased, so they match.
15
+ - List options are sent as lists, whether given comma-separated, repeated or as a JSON array: `token screener --chains ethereum,solana` no longer sends one `"ethereum,solana"` string, `smart-money --labels` accepts a comma-separated list, and a repeated `--addresses` or `research ... --chains` value that itself holds a comma-separated list is split. An empty list (`--chains ,`) is rejected.
16
+ - `prediction-market market-screener` and `event-screener` no longer accept `--min-unique-traders-24h` or `--max-volume-24hr`. The REST API has no such filters and rejected every request that used them; the CLI now says so before the request. `--max-unique-traders-24h` and `--min-volume-24hr` are unchanged.
17
+ - API validation errors keep the field name (`details.param`, `details.errors[]`), also for browser-session logins, and the message is no longer repeated inside `details`.
18
+ - A connection failure (`NETWORK_ERROR`) now says the API key was not checked; a rejected key (`UNAUTHORIZED`) says the connection works.
19
+ - All error codes are listed in `docs/error-codes.md`.
20
+
21
+ ### Patch Changes
22
+
23
+ - [#768](https://github.com/nansen-ai/nansen-cli/pull/768) [`3600f66`](https://github.com/nansen-ai/nansen-cli/commit/3600f66c95977cf048555c077c3f586dbef20c0a) Thanks [@kome12](https://github.com/kome12)! - `nansen alerts` now redacts channel credentials (Slack, Discord and webhook URLs, webhook signing secrets) in its output and error messages by default. Pass `--reveal` to show the full values; scripts that read `channels[].data` values from `nansen alerts` output need it.
24
+
25
+ - [#760](https://github.com/nansen-ai/nansen-cli/pull/760) [`c776ae0`](https://github.com/nansen-ai/nansen-cli/commit/c776ae0310bc5c7dd2143a8509c9338b57a200ae) Thanks [@Kewe63](https://github.com/Kewe63)! - Bind Privy wallet IDs to their authoritative addresses before previews, screening, or signing wallet sends, limit orders, perp actions, and Hyperliquid bridge withdrawals.
26
+
27
+ - [#794](https://github.com/nansen-ai/nansen-cli/pull/794) [`3cca1af`](https://github.com/nansen-ai/nansen-cli/commit/3cca1affb349c83b10f864f8c72feea6d0047c5e) Thanks [@Snan0M](https://github.com/Snan0M)! - A call answered from the response cache (`--cache`) now prints `Credits: 0 (cached)` on stderr instead of a spec estimate for a request that was never made.
28
+
29
+ - [#787](https://github.com/nansen-ai/nansen-cli/pull/787) [`3830386`](https://github.com/nansen-ai/nansen-cli/commit/383038637c52385934c16b13fc60615ab3aa646e) Thanks [@Ravan002](https://github.com/Ravan002)! - Reject a comma-separated `--chain` (for example `--chain eth,sol`) with a message pointing to `--chains`, instead of sending it to the API as one unresolvable chain name.
30
+
31
+ - [#781](https://github.com/nansen-ai/nansen-cli/pull/781) [`5002e66`](https://github.com/nansen-ai/nansen-cli/commit/5002e664d603706a5ccb553bc393edbe30567ac8) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Use chain-valid research examples, consistent bridge routes, command-specific trade help with option descriptions, and explicit wallet naming in doctor guidance.
32
+
33
+ - [#775](https://github.com/nansen-ai/nansen-cli/pull/775) [`3185171`](https://github.com/nansen-ai/nansen-cli/commit/3185171d1e5de1820853b234de22ef0d38ca8eab) Thanks [@kome12](https://github.com/kome12)! - `trade execute` on Solana now waits for the transaction signature to be confirmed on chain before it reports success, as EVM swaps already do. A transaction that lands with an error fails with `TX_REVERTED`, and one that is not confirmed within 90 seconds fails with `RECEIPT_TIMEOUT` (it may still land, so check the explorer before retrying). Previously both cases printed "Transaction successful" and exited 0.
34
+
35
+ - [#799](https://github.com/nansen-ai/nansen-cli/pull/799) [`98b2dd7`](https://github.com/nansen-ai/nansen-cli/commit/98b2dd70580dc61bc53dee2e36f91525babd802c) Thanks [@kome12](https://github.com/kome12)! - Fix `wallet send --chain ethereum` (and `--chain evm`) failing with "Unauthorized: You must authenticate your request with an API key": the default Ethereum RPC now requires a key, so the CLI uses `https://ethereum-rpc.publicnode.com` instead. `NANSEN_EVM_RPC` still overrides it.
36
+
37
+ - [#770](https://github.com/nansen-ai/nansen-cli/pull/770) [`cdc4094`](https://github.com/nansen-ai/nansen-cli/commit/cdc4094e7163d72afa0e219fa16dc14ce4518005) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - List the feedback report categories and fields in `feedback submit --help`, the schema, the README and the agent skill. Show the feedback ID in `feedback get --help`, name a rejected API key when feedback cannot verify the account or read the preference, trace feedback requests with `--debug`, and drop explicit-ID advice from generated-ID recovery messages.
38
+
39
+ - [#793](https://github.com/nansen-ai/nansen-cli/pull/793) [`c1d1422`](https://github.com/nansen-ai/nansen-cli/commit/c1d14225768280f5d20249640d63502b0d5ac8c6) Thanks [@Snan0M](https://github.com/Snan0M)! - A blank (`--fields ' , '`, bare `--fields`) or repeated `--fields` is now rejected before the request is made, instead of after a billed call or by silently returning every field.
40
+
41
+ - [#766](https://github.com/nansen-ai/nansen-cli/pull/766) [`19c80ef`](https://github.com/nansen-ai/nansen-cli/commit/19c80efa3e1b73e8e5a392628acf87106de15db9) Thanks [@Kewe63](https://github.com/Kewe63)! - Harden response-cache reads against linked or non-regular entries, and atomically publish private cache writes without following linked destinations.
42
+
43
+ - [#777](https://github.com/nansen-ai/nansen-cli/pull/777) [`ff846d5`](https://github.com/nansen-ai/nansen-cli/commit/ff846d50af6de61645753011cb66d1902c16dea4) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Explain how to use NANSEN_API_KEY directly when browser login lacks an interactive terminal, secure credential storage, or native authentication locking.
44
+
45
+ - [#784](https://github.com/nansen-ai/nansen-cli/pull/784) [`c6fcb27`](https://github.com/nansen-ai/nansen-cli/commit/c6fcb27b680733fdca950f604f09521e16f25eec) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Help and `nansen schema` now show when label history starts: 2025-03-11 for the whale, public figure, top PnL and exchange segments of `research historical-token-flow-summary`, and for entity labels in `research historical-tx-lookup`.
46
+
47
+ - [#792](https://github.com/nansen-ai/nansen-cli/pull/792) [`82e1199`](https://github.com/nansen-ai/nansen-cli/commit/82e119914943b13a7528432cb0eae75e785842e0) Thanks [@Snan0M](https://github.com/Snan0M)! - `trade limit-order list --offset N` now prints the correct "Showing …" range and next-page offset, and rejects an offset that is not a non-negative integer.
48
+
49
+ - [#778](https://github.com/nansen-ai/nansen-cli/pull/778) [`f5209cb`](https://github.com/nansen-ai/nansen-cli/commit/f5209cb7add6fbf5e736ea0506bd8bab551b8e9a) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Qualify saved browser login on Debian 12 x64 over SSH with GNOME Keyring, document setup and reboot recovery, and distinguish dismissed unlock prompts from missing native bindings.
50
+
51
+ - [#785](https://github.com/nansen-ai/nansen-cli/pull/785) [`3543112`](https://github.com/nansen-ai/nansen-cli/commit/354311207d06c6f45351eac8a0ee7c8e3110ec94) Thanks [@gulshngill](https://github.com/gulshngill)! - List valid options and response fields for unknown input names instead of suggesting a similar name that can mean something else. Clarify that common options also apply, list all supported pagination controls, and label truncated response-field lists with their total count.
52
+
53
+ - [#795](https://github.com/nansen-ai/nansen-cli/pull/795) [`3d15212`](https://github.com/nansen-ai/nansen-cli/commit/3d15212f4c71095c886bbf346cc9f61396674578) Thanks [@Snan0M](https://github.com/Snan0M)! - `trade execute --quote-index` now rejects values that are not whole numbers (`1.9`, `1abc`, `1e0`) instead of pinning the quote at their leading digits.
54
+
55
+ - [#780](https://github.com/nansen-ai/nansen-cli/pull/780) [`6f83f98`](https://github.com/nansen-ai/nansen-cli/commit/6f83f989513340b8b215911f54c2d9a74db5fd4d) Thanks [@kome12](https://github.com/kome12)! - Wallet create, default and delete now wait for each other instead of racing. Two overlapping first `wallet create` runs with different passwords could both report success while leaving one wallet impossible to unlock.
56
+
57
+ - [#786](https://github.com/nansen-ai/nansen-cli/pull/786) [`eb30fc8`](https://github.com/nansen-ai/nansen-cli/commit/eb30fc8612f3e0f4af9c2d8423a63232423b8698) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Show one credit cost in help and post-call estimates when Free and Pro pay the same, and show the 150-credit `--premium-labels` price on commands that have it.
58
+
59
+ - [#779](https://github.com/nansen-ai/nansen-cli/pull/779) [`bdbab83`](https://github.com/nansen-ai/nansen-cli/commit/bdbab834a3a38899a7ebda0473ed02cca34c127c) Thanks [@kome12](https://github.com/kome12)! - Drop `Fund` from the Smart Money label list in `nansen schema`, the examples and the default labels for `--smart-money`. The help text now says `Fund` is no longer a Smart Money label. Fund wallets left the Smart Money cohort on 2026-09-09, so `Fund` matched no wallets there.
60
+
61
+ - [#752](https://github.com/nansen-ai/nansen-cli/pull/752) [`d074c1d`](https://github.com/nansen-ai/nansen-cli/commit/d074c1d9d1033a6772a7634335446b947b5b0a8b) Thanks [@kome12](https://github.com/kome12)! - `trade execute` on Solana now checks, before signing, that the wallet holds enough SOL for the transaction's actual network fee (base plus priority fee, priced by the cluster). A quote the wallet cannot pay the fee for is skipped with an actionable error instead of being broadcast to fail on-chain. The check runs even with `--no-verify-outcome`, and if the balance lookup fails it warns and proceeds.
62
+
63
+ - [#771](https://github.com/nansen-ai/nansen-cli/pull/771) [`6a24e25`](https://github.com/nansen-ai/nansen-cli/commit/6a24e259893ad659e8af1960e7667acd09fbb542) Thanks [@kome12](https://github.com/kome12)! - The update notice and `nansen doctor` now say when the latest release needs a newer Node.js than the one running, instead of suggesting `npm i -g nansen-cli`, which npm resolves back to the installed version on an older Node.
64
+
65
+ - [#796](https://github.com/nansen-ai/nansen-cli/pull/796) [`6ed3486`](https://github.com/nansen-ai/nansen-cli/commit/6ed348627f57ddf7f5217d3fa3a0bdcda5b5d64a) Thanks [@Snan0M](https://github.com/Snan0M)! - The WalletConnect x402 approval line on stderr now shows the amount the payment policy priced (e.g. `0.01 USD1`) instead of reading 18-decimal BNB Chain tokens as 6-decimal (`10000000000 Token`).
66
+
3
67
  ## 2.3.0
4
68
 
5
69
  ### Minor Changes
package/README.md CHANGED
@@ -26,6 +26,18 @@ Send product feedback to Nansen with your configured API key or login session:
26
26
  }
27
27
  ```
28
28
 
29
+ `category` and `description` are required. `category` is one of `bug`,
30
+ `data_quality`, `documentation`, `missing_capability`, `usability` or `other`.
31
+ A feature request or product gap is `missing_capability`. `description` says
32
+ what happened and what was needed, in up to 2,000 characters. Optional fields
33
+ are `endpoint` and `tool` (up to 256 characters each), `goal`,
34
+ `expected_behavior`, `observed_behavior` and `workaround` (up to 2,000
35
+ characters each), `request_ids` (up to 10 of your own request IDs) and
36
+ `client` (`{"name": ..., "version": ...}`, attribution only). The API rejects
37
+ any other field or category with a 422, so leave out fields such as `title`,
38
+ `summary` or `severity`. Write plain sentences without Markdown or code
39
+ formatting. `nansen feedback submit --help` prints the same list.
40
+
29
41
  Save the report as `feedback.json`. Omit the ID to save private recovery data before sending:
30
42
 
31
43
  ```bash
@@ -93,32 +105,27 @@ uncertain attempt remains uncertain. Never switch accounts or pay to bypass deni
93
105
 
94
106
  ## Auth
95
107
 
96
- 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.
108
+ Pick one of three ways to authenticate and pay for API calls.
109
+
110
+ **Nansen account.** Calls use your account's plan and credits. `nansen login` approves the CLI in your browser and saves a session. On a server, in a container or in CI, set `NANSEN_API_KEY` to a key from [the API page](https://app.nansen.ai/api) instead.
97
111
 
98
112
  ```bash
99
- nansen login # approve the displayed code, account and CLI
100
- nansen login --no-browser # approve on another device; same storage requirements
101
- nansen auth status # offline, cached/unverified credential selection
102
- nansen account # free live check, including with zero research credits
103
- nansen logout # clear saved API auth; preserve wallets and environment keys
113
+ nansen login
104
114
  ```
105
115
 
106
- Browser login is available in Nansen CLI 2.0.0 and enabled in production. Saved browser sessions are currently qualified on macOS arm64 in a local GUI Terminal with an unlocked login Keychain and local home directory. Other platforms and terminal environments still need qualification. 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.
107
-
108
- 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.
109
-
110
- For automation, pipe a key from your secret manager into `nansen login --api-key-stdin`, or redirect a protected key file:
116
+ **x402.** Pay per call from a CLI wallet funded with USDC on Base or Solana, or USDT0 on X Layer. When the API answers with HTTP 402, the CLI pays from your default wallet and retries. Each payment is capped at $1.00 by default; set `NANSEN_X402_MAX_AMOUNT` to change it. Your first wallet becomes the default. The wallet needs a password of at least 12 characters. The CLI saves it for later payments, in the OS keychain when one is available.
111
117
 
112
118
  ```bash
113
- nansen login --api-key-stdin --json < /path/to/protected-api-key
119
+ NANSEN_WALLET_PASSWORD='<your-wallet-password>' nansen wallet create --name my-wallet
114
120
  ```
115
121
 
116
- 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.
122
+ **MPP via tempo.** Pay per call through the separate [tempo CLI](https://docs.tempo.xyz). The Nansen CLI does not sign MPP payments. After the [one-time tempo setup](#mpp--tempo):
117
123
 
118
- Wallet and micropayment options:
124
+ ```bash
125
+ tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
126
+ ```
119
127
 
120
- - **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.
121
- - **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).
128
+ [docs/auth.md](docs/auth.md) covers headless setup, saving an API key, browser-session storage and how x402 payment works with each credential.
122
129
 
123
130
  ## Verify your MCP setup
124
131
 
@@ -166,18 +173,6 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
166
173
 
167
174
  Run `nansen schema --pretty` for the full subcommand and field reference.
168
175
 
169
- ## Browser login compatibility and scope
170
-
171
- 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.
172
-
173
- 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` lets you approve on another device without opening a browser on the CLI machine. It does not remove the native-storage or supported-platform requirements. Browser login requires both stdin and stdout to be terminals; without either, it exits immediately with `NOT_A_TTY` and points to `nansen login --human` with `NANSEN_API_KEY` or `nansen login --api-key-stdin`. In a terminal, `--json` emits NDJSON pending and terminal events; the private device code and tokens are never printed.
174
-
175
- `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.
176
-
177
- 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.
178
-
179
- Browser login is enabled in production. Saved browser-session storage is [qualified on macOS arm64](docs/browser-login.md#preview-platform-scope); Linux qualification is pending, and Windows and SSH/background sessions are not qualified. Selected sessions renew automatically near expiry. If a refresh response is lost before a complete replacement is stored, follow the fresh-login guidance; the CLI never retries a consumed refresh credential. Browser sessions have the same account API permissions as API keys, subject to existing endpoint checks. They add no wallet-signing or internal-service authority and cannot be exported as MCP API keys. See [storage and recovery](docs/browser-login.md).
180
-
181
176
  ## MCP
182
177
 
183
178
  <!-- 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. -->
@@ -378,7 +373,7 @@ tempo wallet fund # follow the on-screen instructions to deposit USDC
378
373
  **Calling the Nansen API via tempo:**
379
374
 
380
375
  ```bash
381
- tempo request POST https://api.nansen.ai/api/v1/smart-money/netflow \
376
+ tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow \
382
377
  --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
383
378
  ```
384
379
 
@@ -573,7 +568,10 @@ Default JSON output still contains the complete response body.
573
568
  | Code | Action |
574
569
  |------|--------|
575
570
  | `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api?tab=api](https://app.nansen.ai/api?tab=api). |
576
- | `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
571
+ | `UNAUTHORIZED` | The API rejected the key (the connection works). Re-auth. |
572
+ | `NETWORK_ERROR` | The CLI could not reach the API, so the key was not checked. Fix the connection (`nansen doctor`); do not replace the key. |
573
+ | `INVALID_PARAMS` / `MISSING_PARAM` | Fix the option or field named in `details.param` and `details.errors[]` (each `{ field, message, code }`), then retry. |
574
+ | `UNKNOWN_COMMAND` | The command or subcommand does not exist; the message suggests the closest one. |
577
575
  | `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
578
576
  | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
579
577
  | `PLAN_UPGRADE_REQUIRED` | The endpoint or option needs a higher subscription plan. Do not retry. |
@@ -581,7 +579,9 @@ Default JSON output still contains the complete response body.
581
579
  | `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
582
580
  | `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
583
581
 
584
- 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.
582
+ Every failure exits 1. The full list of codes is in [docs/error-codes.md](docs/error-codes.md). 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.
583
+
584
+ Research commands check their options before calling the API: an unknown or ignored option, a missing required option, a bad value or a chain the endpoint does not accept fails locally with the option named. `nansen schema <command>` lists each command's options and `supportedChains`.
585
585
 
586
586
  **Error metadata.** When the API reports them, `details` carries:
587
587
 
@@ -598,7 +598,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
598
598
  | Symptom | Fix |
599
599
  |---------|-----|
600
600
  | `command not found` | `npm install -g nansen-cli` |
601
- | 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 |
601
+ | Global install reports an older version | Check `node -v` first: current releases need Node.js >= 22. On an older Node, `npm i -g nansen-cli` installs the newest release that still supports it without an error, and `npm i -g nansen-cli@latest` installs the current release with an `EBADENGINE` warning (or fails under `engine-strict`). Upgrade Node, then run `npm i -g nansen-cli@latest --registry=https://registry.npmjs.org/ --prefer-online` and check `which -a nansen` for stale binaries |
602
602
  | `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 |
603
603
  | 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 |
604
604
  | Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
package/docs/auth.md ADDED
@@ -0,0 +1,56 @@
1
+ # Authentication
2
+
3
+ The Nansen API accepts three ways to authenticate and pay for calls: a Nansen account, x402 and MPP via tempo. The [README](../README.md#auth) shows one command for each. This page has the details.
4
+
5
+ ## Nansen account: browser login or API key
6
+
7
+ 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.
8
+
9
+ ```bash
10
+ nansen login # approve the displayed code, account and CLI
11
+ nansen login --no-browser # approve on another device; same storage requirements
12
+ nansen auth status # offline, cached/unverified credential selection
13
+ nansen account # free live check, including with zero research credits
14
+ nansen logout # clear saved API auth; preserve wallets and environment keys
15
+ ```
16
+
17
+ Browser login is available in Nansen CLI 2.0.0 and enabled in production. Saved browser sessions are qualified on macOS arm64 in a local GUI Terminal with an unlocked login Keychain, and on Debian 12 x64 over SSH with Node 22.23.4, user D-Bus and an unlocked GNOME Keyring 42.1. Both require a local home directory. Other configurations still need qualification. See [storage, supported scope and recovery](browser-login.md). Email/password and Google sign-in are supported by the device-flow contract. Apple device sign-in remains deferred.
18
+
19
+ 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.
20
+
21
+ On a server, in a container, or in CI without a credential store, get your key from [the API page](https://app.nansen.ai/api) and use it directly:
22
+
23
+ ```bash
24
+ export NANSEN_API_KEY='<your-api-key>'
25
+ nansen account
26
+ ```
27
+
28
+ No `nansen login` is needed. Core API commands using the environment key require neither secure storage nor native authentication locking. The variable stays set for this terminal session; for automation, inject it through your platform's secret manager. See [headless setup, including PowerShell](browser-login.md#servers-containers-and-ci-without-secure-storage).
29
+
30
+ To save a key for later commands on a machine with native authentication locking, pipe it from your secret manager into `nansen login --api-key-stdin`, or redirect a protected key file:
31
+
32
+ ```bash
33
+ nansen login --api-key-stdin --json < /path/to/protected-api-key
34
+ ```
35
+
36
+ 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.
37
+
38
+ ### Browser login compatibility and scope
39
+
40
+ 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.
41
+
42
+ 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` lets you approve on another device without opening a browser on the CLI machine. It does not remove the native-storage or supported-platform requirements. Browser login requires both stdin and stdout to be terminals; without either, it exits immediately with `NOT_A_TTY` and explains how to use `NANSEN_API_KEY` directly without login. Deliberately saving a key with `--human` or `--api-key-stdin` still requires native locking. In a terminal, `--json` emits NDJSON pending and terminal events; the private device code and tokens are never printed.
43
+
44
+ `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.
45
+
46
+ 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.
47
+
48
+ Browser login is enabled in production. Saved browser-session storage is [qualified on macOS arm64 and the documented Debian 12 x64 SSH configuration](browser-login.md#preview-platform-scope). Windows, Alpine/musl and unattended background sessions are not qualified. Selected sessions renew automatically near expiry. If a refresh response is lost before a complete replacement is stored, follow the fresh-login guidance; the CLI never retries a consumed refresh credential. Browser sessions have the same account API permissions as API keys, subject to existing endpoint checks. They add no wallet-signing or internal-service authority and cannot be exported as MCP API keys. See [storage and recovery](browser-login.md).
49
+
50
+ ## x402
51
+
52
+ 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.
53
+
54
+ ## MPP via tempo
55
+
56
+ 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](../README.md#mpp--tempo).
@@ -4,11 +4,18 @@ Browser login saves a session after you approve the CLI in your browser. It is a
4
4
 
5
5
  ## Preview platform scope
6
6
 
7
- The initial preview is limited to macOS arm64, a local Terminal in a GUI login session, an unlocked login Keychain and a local home directory. Background agents, SSH sessions and network or synchronized home directories are not qualified by a successful local Terminal login.
7
+ Saved browser login is qualified on the configurations below. Both require a local home directory and an unlocked persistent OS credential store. Network or synchronized home directories and unattended background agents are not qualified.
8
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.
9
+ | OS / architecture | Terminal and storage | Qualification |
10
+ | --- | --- | --- |
11
+ | macOS arm64 | Local GUI Terminal, unlocked login Keychain, local home | Initial preview |
12
+ | Debian 12 x64, glibc 2.36, Node 22.23.4 | SSH with a TTY, user D-Bus, GNOME Keyring 42.1, password-protected login collection, local home | Live approval, durable save, fresh-process account access, renewal, locked/unavailable recovery, reboot/unlock persistence and logout verified |
13
+ | Linux desktop prompts, arm64 or other providers/distributions | Secret Service adapter exists | Not qualified |
14
+ | Alpine/musl, Windows | See native compatibility below | Excluded |
15
+
16
+ Linux qualification used the packaged CLI on Debian 12.15 x64 in a disposable VM, kernel 6.1, a user systemd bus and a local ext4 home. The user manager was kept available between SSH connections with `loginctl enable-linger`; this does not unlock the keyring. A fresh SSH login after a real guest reboot recovered the same renewed session after manual unlock. Renewal was triggered by a near-expiry clock injected into the test state owner; proof signing, the issuer and account verification used real time. Concurrent renewal and interrupted-operation recovery are additionally covered by the real-store synthetic-issuer check and process tests. Desktop unlock prompts remain unqualified.
10
17
 
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. If optional dependencies were omitted, reinstall with them enabled. A platform without a compatible prebuild still cannot use saved authentication. There is no plaintext session-storage fallback.
18
+ 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 credential-store access. If optional dependencies were omitted, reinstall with them enabled. A platform without a compatible prebuild still cannot use saved authentication. There is no plaintext session-storage fallback.
12
19
 
13
20
  ## Commands and selection
14
21
 
@@ -22,7 +29,7 @@ nansen logout
22
29
 
23
30
  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
31
 
25
- Browser login needs both stdin and stdout connected to a terminal. In CI or another headless environment, set `NANSEN_API_KEY` and run `nansen login --human`, or pipe a key to `nansen login --api-key-stdin`. Plain login and `--no-browser` fail immediately without a terminal rather than waiting for device approval.
32
+ Browser login needs both stdin and stdout connected to a terminal. Plain login and `--no-browser` fail immediately without a terminal rather than waiting for device approval.
26
33
 
27
34
  `--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.
28
35
 
@@ -43,6 +50,93 @@ Login verifies the approved account without charging for research. Research uses
43
50
 
44
51
  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.
45
52
 
53
+ ## Linux Secret Service setup
54
+
55
+ Linux browser sessions require the native binding, a user D-Bus, a running Secret Service provider and an unlocked default collection. These are separate requirements. The adapter explicitly selects `secret-service`; it never falls back to the kernel's memory-only keyring. The setup below targets Debian 12 x64 with GNOME Keyring and a local home directory. Qualification limits are listed above.
56
+
57
+ 1. Install the service and diagnostic tools, then install the CLI with optional dependencies:
58
+
59
+ ```bash
60
+ sudo apt-get update
61
+ sudo apt-get install --no-install-recommends dbus dbus-user-session gnome-keyring libsecret-tools libglib2.0-bin
62
+ npm install -g nansen-cli --include=optional
63
+ ```
64
+
65
+ 2. Run the remaining commands as your normal user. Check the user bus with `busctl --user list`. If your terminal has no user bus, start a private session and stay inside its shell:
66
+
67
+ ```bash
68
+ dbus-run-session -- bash
69
+ ```
70
+
71
+ For SSH, allocate a TTY and run the commands on the Linux host. An unlocked store on your laptop does not unlock the server's store. A private bus ends when its shell exits; a later shell needs its own service connection and unlock.
72
+
73
+ 3. Start or unlock GNOME Keyring from Bash. On first use, choose a non-empty keyring password; later, use the same password. This password protects the OS keyring, and is separate from your Nansen account password.
74
+
75
+ ```bash
76
+ (
77
+ set +x
78
+ IFS= read -r -s -p 'Keyring password: ' keyring_password </dev/tty || exit 1
79
+ printf '\n' >/dev/tty
80
+ [ -n "$keyring_password" ] || exit 1
81
+ printf '%s' "$keyring_password" |
82
+ gnome-keyring-daemon --daemonize --unlock --components=secrets
83
+ )
84
+ ```
85
+
86
+ The password goes through stdin, without being saved in a file or placed in process arguments. Keep the provider's encrypted keyring files in your persistent home directory. Do not use an empty password. On a desktop, use the provider's unlock UI instead. If another daemon owns the bus and the unlocked collection remains inaccessible, GNOME Keyring's `--replace` option can reconcile the daemon. It can interrupt other applications using that daemon; see its [manual](https://manpages.debian.org/bookworm/gnome-keyring/gnome-keyring-daemon.1.en.html).
87
+
88
+ 4. Check which collection the provider uses, then check its lock state:
89
+
90
+ ```bash
91
+ busctl --user call org.freedesktop.secrets \
92
+ /org/freedesktop/secrets org.freedesktop.Secret.Service ReadAlias s default
93
+ busctl --user get-property org.freedesktop.secrets \
94
+ /org/freedesktop/secrets/collection/login org.freedesktop.Secret.Collection Locked
95
+ ```
96
+
97
+ The second command assumes the first returned `/org/freedesktop/secrets/collection/login`; otherwise use the returned path. `b false` means unlocked. A default alias of `/` means no default collection exists. Create/select one using the provider's tools before login. See the [Secret Service specification](https://specifications.freedesktop.org/secret-service/latest-single/).
98
+
99
+ 5. In the same terminal, run `nansen login --no-browser`. Approve the displayed code in a trusted browser, then run `nansen account` in a fresh process. For a fresh shell, reconnect to the same user bus or repeat the private-bus setup and unlock the persisted keyring first. After OS login, reboot or provider restart, unlock again unless your distribution's login integration already does so. SSH public-key authentication does not itself provide the keyring password. The tested SSH setup keeps the user manager available with `sudo loginctl enable-linger "$USER"`; use this only when you want user services to continue after logout. It starts the user bus again after reboot, but the persisted keyring still needs unlocking. If no user bus is available, use the private-session setup above.
100
+
101
+ ### Linux storage recovery
102
+
103
+ | Failure | Recovery |
104
+ | --- | --- |
105
+ | Native credential-store binding could not load | Reinstall with `--include=optional` on a listed architecture. Service installation cannot repair a missing native prebuild. `nansen doctor --offline` does not test the native bindings or open the credential store. |
106
+ | User bus or Secret Service unavailable | Check `busctl --user list`, connect to your user bus, install/start GNOME Keyring and check the default alias. Run as the same user, without `sudo`. Installing the npm binding alone does not supply a service. |
107
+ | Locked collection or dismissed unlock prompt | Unlock with the provider's UI or the stdin command above, on the same bus. A headless terminal cannot display GNOME's graphical unlock prompt. Starting the daemon alone does not unlock existing entries. |
108
+ | Default collection missing or inconsistent | Check the alias and provider state. Reconcile competing daemons using provider tools. Preserve existing keyring files and auth journals. |
109
+
110
+ The CLI recognizes GNOME Keyring's dismissed-unlock response. Other provider failures and timeouts retain the broader unavailable-or-locked message; it does not guess that credentials are absent. Fix storage before repeating approval. Login preflight fails before requesting a browser code and preserves the selected credential. A later failure still uses the existing journal and cleanup rules. `NANSEN_API_KEY` remains usable without either native dependency.
111
+
112
+ Maintainers can run the isolated real-storage check from a checkout:
113
+
114
+ ```bash
115
+ node src/__tests__/fixtures/linux-store-qualification.js
116
+ ```
117
+
118
+ It creates a disposable password-protected GNOME keyring and private D-Bus, with no access to the invoking user's credentials. It tests save, fresh-process read, locked/unavailable preflight preservation, service restart/unlock, concurrent renewal and logout using a synthetic issuer. It does not establish live browser, SSH, graphical prompt or OS login/reboot support. The setup uses the same provider requirements described in [Git Credential Manager's headless guide](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/secretservice-headless.md).
119
+
120
+ ## Servers, containers and CI without secure storage
121
+
122
+ Core API commands work without a credential store or native authentication locking when you supply `NANSEN_API_KEY`. Get your key from [the API page](https://app.nansen.ai/api), set it in your terminal, and check access:
123
+
124
+ ```bash
125
+ export NANSEN_API_KEY='<your-api-key>'
126
+ nansen account
127
+ ```
128
+
129
+ On Windows PowerShell:
130
+
131
+ ```powershell
132
+ $env:NANSEN_API_KEY = '<your-api-key>'
133
+ nansen account
134
+ ```
135
+
136
+ You don't need to run `nansen login`. The variable stays set for this terminal session. In CI or automation, inject `NANSEN_API_KEY` through your platform's secret manager. The CLI uses it directly without saving the key to config or opening the browser-session store. The key overrides any saved session until you unset it.
137
+
138
+ To deliberately save an API key, use `nansen login --human` or `nansen login --api-key-stdin`. Both require native authentication locking, so they are not a workaround when that binding is unavailable. Saved browser login also requires a working OS credential store and a supported terminal environment. See [preview platform scope](#preview-platform-scope) for recovery guidance. Wallet passwords have a separate, older plaintext-file fallback; browser-session secrets never use that fallback.
139
+
46
140
  ## Permissions and credential safety
47
141
 
48
142
  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.
@@ -68,11 +162,11 @@ Browser access tokens, refresh tokens and the private device key are stored in t
68
162
 
69
163
  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.
70
164
 
71
- 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.
165
+ 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. Only the combinations qualified above are supported. Windows persistence may roam according to OS policy; device-local-only storage is not promised.
72
166
 
73
- For `nansen-cli@2.0.0`, stock Alpine Linux on x64 cannot load native locking. Its musl install includes `fs-native-extensions@1.5.1`, but that package has no `linux-x64-musl` prebuild. `nansen login --human` and `nansen logout` return `AUTH_LOCK_UNAVAILABLE` even with optional dependencies enabled. The musl keyring binding loads, but this does not establish that a persistent Secret Service is available.
167
+ Stock Alpine Linux on x64 remains excluded from saved authentication because it cannot load native locking. Its musl install includes `fs-native-extensions@1.5.1`, but that package has no `linux-x64-musl` prebuild. `nansen login --human` and `nansen logout` return `AUTH_LOCK_UNAVAILABLE` even with optional dependencies enabled. The musl keyring binding loads, but this does not establish that a persistent Secret Service is available. The published `fs-native-extensions@1.5.2` archive and upstream prebuild matrix also lack a musl target; upgrading to it does not close this gap. This change retains `1.5.1` and the existing lock protocol.
74
168
 
75
- On Alpine, pass `NANSEN_API_KEY` in the environment for ordinary commands and do not rely on saved-auth writes or logout. Follow the offline recovery guidance below if you already have saved authentication to remove. Linux browser-login qualification remains pending regardless of binding availability.
169
+ On Alpine, pass `NANSEN_API_KEY` in the environment for ordinary commands and do not rely on saved-auth writes or logout. Follow the offline recovery guidance below if you already have saved authentication to remove. Other Linux configurations require the lifecycle qualification listed above, even when both native bindings load.
76
170
 
77
171
  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.
78
172