nansen-cli 2.3.0 → 2.5.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.
- package/CHANGELOG.md +112 -0
- package/README.md +61 -38
- package/docs/auth.md +56 -0
- package/docs/browser-login.md +101 -7
- package/docs/error-codes.md +251 -0
- package/package.json +10 -4
- package/skills/nansen-agent-guide/SKILL.md +20 -4
- package/skills/nansen-alerts-webhook-listener/SKILL.md +17 -14
- package/skills/nansen-dca-tracker/SKILL.md +1 -1
- package/skills/nansen-defi-positions/SKILL.md +1 -1
- package/skills/nansen-exit-signals/SKILL.md +2 -2
- package/skills/nansen-fund-tracker/SKILL.md +1 -1
- package/skills/nansen-general-search/SKILL.md +1 -1
- package/skills/nansen-holder-analysis/SKILL.md +2 -2
- package/skills/nansen-limit-orders/SKILL.md +9 -1
- package/skills/nansen-mpp-payment/SKILL.md +2 -2
- package/skills/nansen-perp-screener/SKILL.md +1 -1
- package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
- package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
- package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
- package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
- package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
- package/skills/nansen-prediction-markets/SKILL.md +1 -1
- package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
- package/skills/nansen-smart-alerts/SKILL.md +5 -2
- package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
- package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
- package/skills/nansen-smart-money-trend/SKILL.md +1 -1
- package/skills/nansen-token-research/SKILL.md +1 -1
- package/skills/nansen-token-screener/SKILL.md +1 -1
- package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
- package/skills/nansen-trading/SKILL.md +23 -2
- package/skills/nansen-wallet-batch/SKILL.md +1 -1
- package/skills/nansen-wallet-clustering/SKILL.md +1 -1
- package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
- package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
- package/skills/nansen-wallet-manager/SKILL.md +11 -5
- package/skills/nansen-wallet-profiler/SKILL.md +1 -1
- package/skills/nansen-web-fetcher/SKILL.md +1 -1
- package/skills/nansen-web-searcher/SKILL.md +1 -1
- package/src/api-endpoints.json +1605 -0
- package/src/api.js +282 -124
- package/src/auth-credentials.js +1 -0
- package/src/auth-key-input.js +57 -9
- package/src/auth-state.js +2 -2
- package/src/auth-store-native.js +6 -1
- package/src/auth-store-worker.js +1 -1
- package/src/auth-store.js +9 -4
- package/src/auto-paginate.js +25 -7
- package/src/bridge.js +19 -10
- package/src/cache-inspect.js +16 -6
- package/src/cli.js +272 -114
- package/src/commands/agent.js +2 -3
- package/src/commands/alerts.js +365 -18
- package/src/commands/completion.js +4 -1
- package/src/commands/feedback.js +98 -37
- package/src/commands/mcp.js +1 -1
- package/src/commands/research.js +14 -37
- package/src/cost-cache.js +33 -7
- package/src/doctor.js +14 -5
- package/src/ens.js +14 -5
- package/src/error-codes.js +228 -0
- package/src/execute-guard.js +8 -3
- package/src/input-validation.js +555 -0
- package/src/limit-order.js +127 -54
- package/src/perp.js +358 -35
- package/src/privy.js +90 -15
- package/src/query-options.js +47 -8
- package/src/response-cache-files.js +65 -0
- package/src/response-meta.js +8 -2
- package/src/rpc-urls.js +3 -1
- package/src/schema.json +1254 -156
- package/src/solana-tx.js +4 -0
- package/src/telemetry-flags.js +75 -0
- package/src/trade-validation.js +167 -8
- package/src/trading.js +243 -20
- package/src/transfer.js +79 -12
- package/src/update-check.js +32 -5
- package/src/wallet.js +246 -69
- package/src/walletconnect-x402.js +27 -9
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,117 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2.5.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#801](https://github.com/nansen-ai/nansen-cli/pull/801) [`c7446fb`](https://github.com/nansen-ai/nansen-cli/commit/c7446fb17e076d2cd2731b40efe3d58ffef7e280) Thanks [@kome12](https://github.com/kome12)! - `nansen alerts create` and `nansen alerts update` accept the webhook signing secret from `--webhook-secret-stdin` (pipe or redirected file) or the `NANSEN_WEBHOOK_SECRET` environment variable, so it no longer has to appear on the command line, in shell history or in the process list. `--webhook-secret` still works; it cannot be combined with `--webhook-secret-stdin`, and either flag overrides the environment variable, which is read only when `--webhook` is given. `--webhook-secret` with no value or an empty value is now rejected instead of being silently ignored.
|
|
8
|
+
|
|
9
|
+
- [#767](https://github.com/nansen-ai/nansen-cli/pull/767) [`f5d9331`](https://github.com/nansen-ai/nansen-cli/commit/f5d93318ddf539531ac1ae237d049f9d4238c1bc) Thanks [@Kewe63](https://github.com/Kewe63)! - Add non-consuming `--dry-run` previews and interactive confirmation guards to limit-order create and cancel, with `--yes`/`-y` and `NANSEN_YES=1` prompt bypasses.
|
|
10
|
+
|
|
11
|
+
- [#809](https://github.com/nansen-ai/nansen-cli/pull/809) [`a69dc08`](https://github.com/nansen-ai/nansen-cli/commit/a69dc086dd070580318ff3b07634c42508c8208f) Thanks [@kome12](https://github.com/kome12)! - `perp order`, `perp close`, `perp cancel` and `perp leverage` now accept `--dry-run`, which runs the normal validation, prints the plan (coin, side, rounded size, price and type, estimated notional, leverage, builder fee) and exits 0 without signing or submitting anything. No wallet password is needed for a dry run, and the one-time builder-fee approval is not submitted.
|
|
12
|
+
|
|
13
|
+
These four commands now ask for confirmation before signing when stdin is an interactive terminal, the same way `trade execute` and `bridge execute` do. Answering anything but `y` exits 1 with nothing signed. `--yes`, `-y` or `NANSEN_YES=1` skips the question. **Scripts and agents whose stdin is not a terminal (pipes, CI, agent shells) see no change:** the commands submit without asking, as before, and `--yes` is a no-op there. A script that runs these commands from an interactive terminal, or an agent that runs them under a pseudo-terminal, will now be asked; add `--yes` or set `NANSEN_YES=1` to keep the old behaviour.
|
|
14
|
+
|
|
15
|
+
### Patch Changes
|
|
16
|
+
|
|
17
|
+
- [#811](https://github.com/nansen-ai/nansen-cli/pull/811) [`c1a9e39`](https://github.com/nansen-ai/nansen-cli/commit/c1a9e39892183227d1e9b66891fe6b4aee2a46c9) Thanks [@Ravan002](https://github.com/Ravan002)! - An API error response whose body is the JSON value `null` is now reported as a normal API error for its status (and retried when the status is retryable) instead of crashing with `Cannot read properties of null (reading 'message')`.
|
|
18
|
+
|
|
19
|
+
- [#817](https://github.com/nansen-ai/nansen-cli/pull/817) [`a732073`](https://github.com/nansen-ai/nansen-cli/commit/a7320733580b2fa860feb5e17db0c5ae19948b59) Thanks [@0xcfloki](https://github.com/0xcfloki)! - ENS names now still resolve when the ensideas API is unavailable. The on-chain fallback was pinned to `eth.llamarpc.com`, which answers HTTP 525, so any ensideas outage failed every `.eth` lookup. It now uses the same Ethereum RPC as the rest of the CLI (`NANSEN_EVM_RPC`, or the shared default), and keeps the port and query string of a custom RPC URL.
|
|
20
|
+
|
|
21
|
+
- [#807](https://github.com/nansen-ai/nansen-cli/pull/807) [`a38b217`](https://github.com/nansen-ai/nansen-cli/commit/a38b217e11c4c0adcfc1e3dc42440223a459d43f) Thanks [@Snan0M](https://github.com/Snan0M)! - A `--paginate` result that mixes cached and live pages is no longer reported as a cache hit. The merged result kept page 1's `_meta.fromCache`/`cacheAge`, and telemetry's `from_cache` followed page 1's marker or the last page's cache state; both now say cached only when every page came from the cache.
|
|
22
|
+
|
|
23
|
+
- [#814](https://github.com/nansen-ai/nansen-cli/pull/814) [`05fd62a`](https://github.com/nansen-ai/nansen-cli/commit/05fd62ad6e2e42527ee7e8d365286d58570f1470) Thanks [@kome12](https://github.com/kome12)! - `nansen perp close --dry-run` now exits 1 with `NO_OPEN_POSITION` when the wallet has no open position in that coin, instead of printing a plan and exiting 0 for a close Hyperliquid would reject. The error is retryable, because the positions data can lag a fill that just happened. A real close still goes to Hyperliquid; when it prompts, its plan shows a warning instead. If positions cannot be loaded, or the data for that coin is malformed, the dry run still prints the plan with "Open position: could not be loaded".
|
|
24
|
+
|
|
25
|
+
- [#797](https://github.com/nansen-ai/nansen-cli/pull/797) [`585ac67`](https://github.com/nansen-ai/nansen-cli/commit/585ac674b7cb46d1d5d851eb7afb499c0abdf47c) Thanks [@kome12](https://github.com/kome12)! - `perp positions` now shows each position's leverage and margin mode (`lev=1x cross`) next to the liquidation price, so a liquidation price on a low-leverage cross-margin position has context.
|
|
26
|
+
|
|
27
|
+
- [#789](https://github.com/nansen-ai/nansen-cli/pull/789) [`5edcb66`](https://github.com/nansen-ai/nansen-cli/commit/5edcb662e7e0496d5f752f0a831feb3d0dbfc646) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Show API warning headers on stderr and preserve them on cached responses.
|
|
28
|
+
|
|
29
|
+
- [#804](https://github.com/nansen-ai/nansen-cli/pull/804) [`ca8b77d`](https://github.com/nansen-ai/nansen-cli/commit/ca8b77dd10d437ac0b81cbb6583983d72500e86e) Thanks [@Ravan002](https://github.com/Ravan002)! - `wallet create` now rejects the names `config` (any case), `wc` and `walletconnect`. A wallet named `config` was saved as `wallets/config.json` and then overwritten by the wallet settings, losing its keys; `wc` and `walletconnect` are read as WalletConnect by `wallet send` and limit orders.
|
|
30
|
+
|
|
31
|
+
- [#803](https://github.com/nansen-ai/nansen-cli/pull/803) [`622b684`](https://github.com/nansen-ai/nansen-cli/commit/622b6846ac0a9a6cb47834a81af0d1ce0338ddb4) Thanks [@kome12](https://github.com/kome12)! - Response cache (`--cache`) no longer grows without bound. After a cached write, entries older than 24 hours (or the longest `--cache-ttl` that run reads with, if longer) and temp files left by an interrupted write are removed, at most once an hour per run. `nansen cache clear` also removes those leftover temp files, but never one younger than 10 minutes, which may be a write in progress.
|
|
32
|
+
|
|
33
|
+
- [#802](https://github.com/nansen-ai/nansen-cli/pull/802) [`28483ea`](https://github.com/nansen-ai/nansen-cli/commit/28483ea8f5bc0d98628ec552d6e5cf99a3023ae6) Thanks [@kome12](https://github.com/kome12)! - `nansen schema` no longer lists `research points leaderboard`, whose endpoint was removed, and now lists `--stream` (NDJSON output, alias `-s`) under global options. The points command is also left out of `nansen research` help and "did you mean" suggestions. Calling it, including with `--help`, still returns `COMMAND_UNAVAILABLE`.
|
|
34
|
+
|
|
35
|
+
- [#813](https://github.com/nansen-ai/nansen-cli/pull/813) [`58ee954`](https://github.com/nansen-ai/nansen-cli/commit/58ee954c59fdaaef61554e5feef489e3e72b83d0) Thanks [@0xcfloki](https://github.com/0xcfloki)! - `wallet send` on Solana no longer tells you to top up your wallet when a SOL send fails because the recipient would hold less than the rent-exempt minimum. Solana rejects a transfer that leaves a new address below about 0.00089 SOL, naming that account by its index; any account other than your wallet now gets an error that says so and gives the minimum, instead of the insufficient-balance advice meant for the wallet itself.
|
|
36
|
+
|
|
37
|
+
- [#812](https://github.com/nansen-ai/nansen-cli/pull/812) [`e2331f7`](https://github.com/nansen-ai/nansen-cli/commit/e2331f763f02c710fbd30ee41fbc585a44457ba5) Thanks [@Ravan002](https://github.com/Ravan002)! - `--sort` now rejects extra colon segments (`--sort value_usd:desc:asc`) instead of silently dropping them, and `--order-by` rejects anything that is not a JSON array of `{ "field", "direction" }` objects instead of sending it to the API unchecked.
|
|
38
|
+
|
|
39
|
+
- [#805](https://github.com/nansen-ai/nansen-cli/pull/805) [`11558d5`](https://github.com/nansen-ai/nansen-cli/commit/11558d57ff4a52da3ef6a1856d3119a0df5dafe1) Thanks [@Ravan002](https://github.com/Ravan002)! - Telemetry events no longer include positional values in the command path. `nansen search vitalik.eth` was reported as `/search/vitalik.eth` and `nansen 0x…` as `/0x…`; only command and subcommand names the CLI defines are sent now, and an unknown command is reported as `unknown`.
|
|
40
|
+
|
|
41
|
+
- [#808](https://github.com/nansen-ai/nansen-cli/pull/808) [`5bb3e75`](https://github.com/nansen-ai/nansen-cli/commit/5bb3e7546d974bd311825760dcd7270e1fb41895) Thanks [@kome12](https://github.com/kome12)! - Telemetry events now list only option names the CLI defines for the command being run (plus global options and built-in switches such as `--help`). Any other name is sent as `--<unknown>`. Previously a value that starts with `-` and is passed as a separate argument, as in `--webhook-secret -abc123`, was parsed as a flag and its text was sent as a flag name.
|
|
42
|
+
|
|
43
|
+
- [#810](https://github.com/nansen-ai/nansen-cli/pull/810) [`8703d39`](https://github.com/nansen-ai/nansen-cli/commit/8703d39aa489c0927b565b079a1cc9dfc0cce7de) Thanks [@kome12](https://github.com/kome12)! - `trade execute`: when the standard execution route rejects a swap before broadcasting it (quote expired, simulation failed, minimum return not reached, insufficient balance, input transfer failed), the CLI now releases the quote and tries the next candidate quote instead of aborting and marking the quote spent. Every other error response still stops the run.
|
|
44
|
+
|
|
45
|
+
- [#818](https://github.com/nansen-ai/nansen-cli/pull/818) [`3f5f059`](https://github.com/nansen-ai/nansen-cli/commit/3f5f059e4e6366ac6f9ea6a527ece3272bef9213) Thanks [@erkancamli](https://github.com/erkancamli)! - `wallet send` on EVM keeps the leading zero bytes of the recipient (or token contract) address in the signed transaction. They were stripped, so a send to an address such as `0x00000000219ab540356cBB839Cbe05303d7705Fa`, or of a token such as TrueUSD (`0x0000000000085d4780B73119b644AE5ecd22b376`), was rejected by the node, and a send to the zero address was signed as a contract creation.
|
|
46
|
+
|
|
47
|
+
- [#798](https://github.com/nansen-ai/nansen-cli/pull/798) [`9457798`](https://github.com/nansen-ai/nansen-cli/commit/9457798f1c69d7cc8e9753c07a8eed0bcd379e17) Thanks [@kome12](https://github.com/kome12)! - `wallet send --token` now accepts `USDC` and `USDT` on every chain it supports (`evm`/`ethereum`, `base`, `solana`) instead of failing with "Invalid params", and rejects any other non-address value with the accepted symbols. `wallet create --help`, `wallet send --help` and `nansen schema` now list every option (`--name`, `--provider`, `--human`, `--token`, `--wallet`, `--dry-run`) and explain that `wallet create` reads the password from `NANSEN_WALLET_PASSWORD` (it prompts only with `--human`) and saves it to the OS keychain or the `.credentials` fallback.
|
|
48
|
+
|
|
49
|
+
- [#806](https://github.com/nansen-ai/nansen-cli/pull/806) [`3f61a36`](https://github.com/nansen-ai/nansen-cli/commit/3f61a36e151f2f12dcdca7828819e63c260f2540) Thanks [@Ravan002](https://github.com/Ravan002)! - WalletConnect x402 payments now bound the authorization's `validBefore`. A `maxTimeoutSeconds` sent as a string (`"60"`) was concatenated onto the current time, giving a `validBefore` thousands of years out, and a large number was used as is; the timeout is now read as a whole number of seconds and capped at one hour, the window the local signer uses.
|
|
50
|
+
|
|
51
|
+
## 2.4.0
|
|
52
|
+
|
|
53
|
+
### Minor Changes
|
|
54
|
+
|
|
55
|
+
- [#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).
|
|
56
|
+
|
|
57
|
+
- Subcommand typos (also with `--fields`) and unknown commands return `UNKNOWN_COMMAND` with the closest match, instead of `success: true` with the error inside `data`.
|
|
58
|
+
- 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'?").
|
|
59
|
+
- Missing required options (for example `--address`) fail locally instead of returning "API request failed (422)".
|
|
60
|
+
- `--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`).
|
|
61
|
+
- `--fields` names that match nothing in the response are an error instead of `{}`.
|
|
62
|
+
- `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.
|
|
63
|
+
- 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.
|
|
64
|
+
- `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.
|
|
65
|
+
- 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`.
|
|
66
|
+
- A connection failure (`NETWORK_ERROR`) now says the API key was not checked; a rejected key (`UNAUTHORIZED`) says the connection works.
|
|
67
|
+
- All error codes are listed in `docs/error-codes.md`.
|
|
68
|
+
|
|
69
|
+
### Patch Changes
|
|
70
|
+
|
|
71
|
+
- [#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.
|
|
72
|
+
|
|
73
|
+
- [#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.
|
|
74
|
+
|
|
75
|
+
- [#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.
|
|
76
|
+
|
|
77
|
+
- [#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.
|
|
78
|
+
|
|
79
|
+
- [#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.
|
|
80
|
+
|
|
81
|
+
- [#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.
|
|
82
|
+
|
|
83
|
+
- [#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.
|
|
84
|
+
|
|
85
|
+
- [#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.
|
|
86
|
+
|
|
87
|
+
- [#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.
|
|
88
|
+
|
|
89
|
+
- [#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.
|
|
90
|
+
|
|
91
|
+
- [#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.
|
|
92
|
+
|
|
93
|
+
- [#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`.
|
|
94
|
+
|
|
95
|
+
- [#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.
|
|
96
|
+
|
|
97
|
+
- [#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.
|
|
98
|
+
|
|
99
|
+
- [#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.
|
|
100
|
+
|
|
101
|
+
- [#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.
|
|
102
|
+
|
|
103
|
+
- [#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.
|
|
104
|
+
|
|
105
|
+
- [#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.
|
|
106
|
+
|
|
107
|
+
- [#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.
|
|
108
|
+
|
|
109
|
+
- [#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.
|
|
110
|
+
|
|
111
|
+
- [#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.
|
|
112
|
+
|
|
113
|
+
- [#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`).
|
|
114
|
+
|
|
3
115
|
## 2.3.0
|
|
4
116
|
|
|
5
117
|
### 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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
119
|
+
NANSEN_WALLET_PASSWORD='<your-wallet-password>' nansen wallet create --name my-wallet
|
|
114
120
|
```
|
|
115
121
|
|
|
116
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
|
@@ -134,8 +141,8 @@ The check calls `tools/list` for reachability, then calls the paid `nansen_score
|
|
|
134
141
|
|
|
135
142
|
```
|
|
136
143
|
nansen research <category> <subcommand> [options]
|
|
137
|
-
nansen agent "<question>" # AI research agent (
|
|
138
|
-
nansen agent "<question>" --expert # deeper analysis (
|
|
144
|
+
nansen agent "<question>" # AI research agent (100 credits)
|
|
145
|
+
nansen agent "<question>" --expert # deeper analysis (400 credits)
|
|
139
146
|
nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
|
|
140
147
|
nansen trade execute --quote <quoteId>
|
|
141
148
|
nansen wallet <subcommand> [options]
|
|
@@ -147,7 +154,7 @@ nansen cache stats # what the local caches hold (no API key n
|
|
|
147
154
|
|
|
148
155
|
**Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`
|
|
149
156
|
|
|
150
|
-
The points leaderboard API has been removed. `nansen research points leaderboard` and the legacy command `nansen points leaderboard` return `success: false` with code `COMMAND_UNAVAILABLE` and exit status `1`, without making an API request.
|
|
157
|
+
The points leaderboard API has been removed. `nansen research points leaderboard` and the legacy command `nansen points leaderboard` return `success: false` with code `COMMAND_UNAVAILABLE` and exit status `1`, without making an API request (with `--help` too). The command is no longer listed in `nansen schema`, help or completions.
|
|
151
158
|
|
|
152
159
|
**Direct research subcommands:**
|
|
153
160
|
- `nansen research chain-rank [--timeframe-days 7|30|365] [--chain-type all|evm]` — rank chains by growth metrics
|
|
@@ -164,19 +171,17 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
|
|
|
164
171
|
|
|
165
172
|
**Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send`, `forget-password`, `secure` — local or Privy server-side wallets (EVM + Solana).
|
|
166
173
|
|
|
167
|
-
|
|
168
|
-
|
|
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
|
+
**Alerts:** `list`, `create`, `update`, `toggle`, `delete` — smart alerts delivered to Telegram, Slack, Discord or a webhook. Give a webhook's signing secret through stdin or the environment, not on the command line, so it stays out of shell history and the process list:
|
|
174
175
|
|
|
175
|
-
|
|
176
|
+
```bash
|
|
177
|
+
nansen alerts create --name 'ETH SM inflow' --type sm-token-flows --chains ethereum --inflow-1h-min 1000000 \
|
|
178
|
+
--webhook https://example.com/hook --webhook-secret-stdin < webhook-secret.txt
|
|
179
|
+
NANSEN_WEBHOOK_SECRET="$(cat webhook-secret.txt)" nansen alerts update <id> --webhook https://example.com/hook
|
|
180
|
+
```
|
|
176
181
|
|
|
177
|
-
|
|
182
|
+
`--webhook-secret <secret>` still works. It cannot be combined with `--webhook-secret-stdin`, and either flag overrides `NANSEN_WEBHOOK_SECRET`, which is read only when `--webhook` is given. Alerts output redacts channel credentials unless you pass `--reveal`.
|
|
178
183
|
|
|
179
|
-
|
|
184
|
+
Run `nansen schema --pretty` for the full subcommand and field reference.
|
|
180
185
|
|
|
181
186
|
## MCP
|
|
182
187
|
|
|
@@ -270,18 +275,22 @@ nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
|
|
|
270
275
|
|
|
271
276
|
### Before broadcasting
|
|
272
277
|
|
|
273
|
-
`trade execute` and `
|
|
278
|
+
`trade execute`, `bridge execute`, and the signing limit-order operations (`limit-order create` and `limit-order cancel`) accept:
|
|
274
279
|
|
|
275
280
|
```bash
|
|
276
281
|
nansen trade execute --quote <quoteId> --dry-run # validate + print the plan, broadcast nothing
|
|
277
282
|
nansen trade execute --quote <quoteId> --yes # skip the confirmation prompt (also: -y)
|
|
283
|
+
nansen trade limit-order create ... --dry-run # preview intent; no API request or signature
|
|
284
|
+
nansen trade limit-order cancel --order <id> --dry-run # does not request/consume a cancellation tx
|
|
278
285
|
```
|
|
279
286
|
|
|
280
287
|
`--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.
|
|
281
288
|
|
|
282
289
|
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.
|
|
283
290
|
|
|
284
|
-
|
|
291
|
+
For limit orders, `--dry-run` is a non-consuming intent preview built from locally validated arguments and the wallet's public address. It returns before limit-order authentication, custom-token metadata RPC lookups, transaction crafting, transaction signing, or final submission. Create preview does not submit an order; cancel preview does not request or consume the API's one-time cancellation transaction. Real execution performs the existing transaction and outcome validation after acknowledgement.
|
|
292
|
+
|
|
293
|
+
When stdin is an interactive terminal, each guarded command prints its plan and asks for confirmation first (`Broadcast this transaction?`, `Create this limit order?`, or `Cancel this limit order?`); anything but `y`/`yes` aborts with exit code 1 and nothing signed. `--yes`, `-y`, or `NANSEN_YES=1` skips only 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.
|
|
285
294
|
|
|
286
295
|
| Exit code | Meaning |
|
|
287
296
|
|-----------|---------|
|
|
@@ -310,6 +319,8 @@ nansen trade limit-order update --order <orderId> --trigger-price 85
|
|
|
310
319
|
|
|
311
320
|
`--amount` is in token units (`1.5` = 1.5 SOL). `--slippage-bps` is basis points (`300` = 3%, `100` = 1%); omit for auto. Minimum order value ~$10 (server-enforced). Local, Privy, and WalletConnect wallets all work.
|
|
312
321
|
|
|
322
|
+
Add `--dry-run` to `create` or `cancel` for a no-API, no-signature intent preview. In an interactive terminal these two commands otherwise ask for confirmation; pass `--yes`/`-y` (or set `NANSEN_YES=1`) to skip the prompt. Non-TTY automation remains unprompted.
|
|
323
|
+
|
|
313
324
|
For EVM chains, there's no native limit-order surface — pair an external venue's resting order with a `common-token-transfer` smart alert on the settlement wallet as a best-effort fill signal. See the `nansen-limit-orders` skill for details.
|
|
314
325
|
|
|
315
326
|
## Perpetuals
|
|
@@ -329,7 +340,7 @@ nansen perp positions
|
|
|
329
340
|
nansen perp account # value, unrealized PnL, margin, spot USDC
|
|
330
341
|
```
|
|
331
342
|
|
|
332
|
-
`--side` is `buy`/`long` or `sell`/`short` to open (`buy`/`sell` to close); `--tif` is `Gtc`/`Ioc`/`Alo`; `--slippage` is a decimal in `[0,1]`; `--leverage` is a whole integer capped at the asset max. Perp orders are irreversible once signed. USDC sent to a wallet via Hyperliquid's **Send** lands in the **Spot** balance (shown as `Spot USDC`); move it to Perps with `perp transfer` before trading. See the `nansen-trading` skill for details.
|
|
343
|
+
`--side` is `buy`/`long` or `sell`/`short` to open (`buy`/`sell` to close); `--tif` is `Gtc`/`Ioc`/`Alo`; `--slippage` is a decimal in `[0,1]`; `--leverage` is a whole integer capped at the asset max. Perp orders are irreversible once signed: add `--dry-run` to `order`, `close`, `cancel` or `leverage` to print the plan without signing anything. In an interactive terminal these four commands ask for confirmation first (`--yes`/`-y` or `NANSEN_YES=1` skips it); off a terminal they submit without asking, as before. USDC sent to a wallet via Hyperliquid's **Send** lands in the **Spot** balance (shown as `Spot USDC`); move it to Perps with `perp transfer` before trading. `perp positions` prints each position's leverage and margin mode next to Hyperliquid's liquidation price (`lev=1x cross liq=1.37`). On cross margin the liquidation price depends on the whole account's equity, so even a 1x position can have one close to the market price; `liq=n/a` means the exchange reports no liquidation price. See the `nansen-trading` skill for details.
|
|
333
344
|
|
|
334
345
|
## Bridge
|
|
335
346
|
|
|
@@ -353,11 +364,18 @@ nansen wallet create --name my-wallet --provider privy # server-side via Privy
|
|
|
353
364
|
nansen wallet list
|
|
354
365
|
nansen wallet default <name>
|
|
355
366
|
nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
|
|
356
|
-
nansen wallet
|
|
367
|
+
nansen wallet send --to <addr> --amount 25 --chain base --token USDC # USDC, USDT or a token address
|
|
368
|
+
nansen wallet secure # move a password from .credentials or the env var into the OS keychain
|
|
357
369
|
nansen wallet forget-password # drop the saved password from every store
|
|
358
370
|
```
|
|
359
371
|
|
|
360
|
-
**Local wallets** are password
|
|
372
|
+
**Local wallets** are encrypted with a password of at least 12 characters. `wallet create` reads it from `NANSEN_WALLET_PASSWORD`, or reuses the password an earlier `wallet create` saved, and does not prompt; without one the command fails with `PASSWORD_REQUIRED` (agents: ask the user for a password, never make one up). When no password is set or saved, pass `--human` to be prompted for one in an interactive terminal. On success the CLI saves the password to the OS keychain, or to `~/.nansen/wallets/.credentials` (plaintext) when no keychain is available, and later wallet commands read it from there. If neither can be written, the wallet is still created but the password is not saved: keep `NANSEN_WALLET_PASSWORD` set for every later wallet command. `nansen wallet secure` moves a password from that file or the env var into the keychain.
|
|
373
|
+
|
|
374
|
+
```bash
|
|
375
|
+
NANSEN_WALLET_PASSWORD='<password-from-user>' nansen wallet create --name my-wallet
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
`wallet send --token` takes `USDC`, `USDT` or a token contract (EVM) or mint (Solana) address; omit it to send the native currency. `--chain` is `evm` (Ethereum), `ethereum`, `base` or `solana`.
|
|
361
379
|
|
|
362
380
|
**Privy wallets** are server-side — no password, no local key storage. Requires `PRIVY_APP_ID` and `PRIVY_APP_SECRET` env vars. Get credentials at [dashboard.privy.io](https://dashboard.privy.io).
|
|
363
381
|
|
|
@@ -378,7 +396,7 @@ tempo wallet fund # follow the on-screen instructions to deposit USDC
|
|
|
378
396
|
**Calling the Nansen API via tempo:**
|
|
379
397
|
|
|
380
398
|
```bash
|
|
381
|
-
tempo request POST https://api.nansen.ai/api/v1/smart-money/netflow \
|
|
399
|
+
tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow \
|
|
382
400
|
--json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
|
|
383
401
|
```
|
|
384
402
|
|
|
@@ -573,7 +591,10 @@ Default JSON output still contains the complete response body.
|
|
|
573
591
|
| Code | Action |
|
|
574
592
|
|------|--------|
|
|
575
593
|
| `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` |
|
|
594
|
+
| `UNAUTHORIZED` | The API rejected the key (the connection works). Re-auth. |
|
|
595
|
+
| `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. |
|
|
596
|
+
| `INVALID_PARAMS` / `MISSING_PARAM` | Fix the option or field named in `details.param` and `details.errors[]` (each `{ field, message, code }`), then retry. |
|
|
597
|
+
| `UNKNOWN_COMMAND` | The command or subcommand does not exist; the message suggests the closest one. |
|
|
577
598
|
| `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
|
|
578
599
|
| `UNSUPPORTED_FILTER` | Remove the filter and retry. |
|
|
579
600
|
| `PLAN_UPGRADE_REQUIRED` | The endpoint or option needs a higher subscription plan. Do not retry. |
|
|
@@ -581,7 +602,9 @@ Default JSON output still contains the complete response body.
|
|
|
581
602
|
| `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
|
|
582
603
|
| `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
|
|
583
604
|
|
|
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.
|
|
605
|
+
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.
|
|
606
|
+
|
|
607
|
+
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
608
|
|
|
586
609
|
**Error metadata.** When the API reports them, `details` carries:
|
|
587
610
|
|
|
@@ -598,7 +621,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
|
|
|
598
621
|
| Symptom | Fix |
|
|
599
622
|
|---------|-----|
|
|
600
623
|
| `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
|
|
624
|
+
| 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
625
|
| `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
626
|
| 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
627
|
| 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).
|
package/docs/browser-login.md
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|