nansen-cli 1.44.3 → 1.46.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 CHANGED
@@ -1,5 +1,117 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.46.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#667](https://github.com/nansen-ai/nansen-cli/pull/667) [`8dad3b9`](https://github.com/nansen-ai/nansen-cli/commit/8dad3b9a2938bbf83d4d7cbce5986e728df7b975) Thanks [@gulshngill](https://github.com/gulshngill)! - `trade execute` and `bridge execute` now take `--dry-run` and `--yes`. `--dry-run` runs the sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints the trade or transfer that would be sent (chain, tokens, amounts, recipient, approvals, fees — plus the current allowance and revert simulation on EVM); and stops before wallet credentials or signing: no wallet password needed, the quote is not consumed, exit code 0. Real execution still resolves and revalidates the live signer. When stdin is an interactive terminal, both commands now print that plan and ask `Broadcast this transaction? [y/N]` before broadcasting; declining exits 1 with nothing signed. `--yes` (`-y`) or `NANSEN_YES=1` skips the prompt. Non-interactive callers — agents, CI, pipes — are unchanged: they proceed without prompting, and `--yes` is accepted there as a no-op.
8
+
9
+ - [#501](https://github.com/nansen-ai/nansen-cli/pull/501) [`5a79f9d`](https://github.com/nansen-ai/nansen-cli/commit/5a79f9db91aa3dab3d0e8b043172e5a3af418924) Thanks [@gulshngill](https://github.com/gulshngill)! - Guard `wallet export` against accidental plaintext key disclosure. The default output is now redacted (addresses only — no decryption, no password needed). Printing private keys to stdout requires explicit acknowledgement via `--reveal` (which also warns on stderr when stdout is an interactive terminal), and the new `--file <path>` writes keys to a file created with 0600 permissions (refusing to overwrite) while keeping stdout clean. Scripts that parsed `wallet export` output must add `--reveal` or switch to `--file`. `--file` failures carry machine-readable codes: `FILE_EXISTS` when the path already exists, `FILE_WRITE_FAILED` for any other create/write error.
10
+
11
+ This safety hardening is intentionally classified as a minor change rather than a major release: it changes an unsafe default to prevent accidental private-key disclosure while preserving explicit export through `--reveal` and `--file`.
12
+
13
+ - [#669](https://github.com/nansen-ai/nansen-cli/pull/669) [`b821104`](https://github.com/nansen-ai/nansen-cli/commit/b821104abb2860b9c0bf13b79a0bb3043b65cb5f) Thanks [@gulshngill](https://github.com/gulshngill)! - Show the real subcommand help for `nansen research perp screener --help` and `nansen research perp leaderboard --help`. Because `perp` is also a top-level trading command, the help lookup stopped at the trading command's subcommand list and fell back to printing the category listing — "Use: nansen research perp <subcommand> --help", the command that had just been run — so the parameters, credit cost and example were unreachable. `nansen perp screener --help` now resolves to the same help, with an example pointing at the `research` path. Boolean options now accept `--flag=false` and reject invalid or repeated values instead of silently falling back to the server default; value-taking options also accept the conventional `--key=value` spelling, while valueless switches reject inline values instead of creating unusable stale flags. Invalid `changelog --since` values now return a structured error and a non-zero exit status.
14
+
15
+ The stricter validation intentionally rejects invalid, previously undocumented inputs that only appeared to succeed while being ignored; relying on that quiet fallback was relying on a bug, so this is classified as a minor change rather than a major breaking release.
16
+
17
+ ### Patch Changes
18
+
19
+ - [#682](https://github.com/nansen-ai/nansen-cli/pull/682) [`3e172f2`](https://github.com/nansen-ai/nansen-cli/commit/3e172f26cca04e52187b95dfbed0b43d35dc9f93) Thanks [@Bruce039](https://github.com/Bruce039)! - `alerts update` no longer resends a PATCH through the retry loop after a transient failure, matching `alerts create`
20
+
21
+ - [#649](https://github.com/nansen-ai/nansen-cli/pull/649) [`66152af`](https://github.com/nansen-ai/nansen-cli/commit/66152af23024cad484393d37849e05d749409b7e) Thanks [@kriss39](https://github.com/kriss39)! - `research profiler compare` no longer turns failed API requests into an empty comparison. When every request fails the command errors with the underlying code (for example `UNAUTHORIZED` or `RATE_LIMITED`); when some fail the result carries `incomplete: true`, an `errors` list, and `null` for the fields that could not be computed. Shared tokens are now matched on the token address when both wallets report one, falling back to the symbol when either side omits it, so two different contracts with the same symbol are no longer reported as shared.
22
+
23
+ - [#674](https://github.com/nansen-ai/nansen-cli/pull/674) [`ad178db`](https://github.com/nansen-ai/nansen-cli/commit/ad178db7cbcd21628df3c68c90a8defaef85db57) Thanks [@0xShadowX](https://github.com/0xShadowX)! - A repeated list option whose values are themselves comma-separated (`--tags defi,nft --tags sports`) is now flattened to `defi, nft, sports`. Previously the first value was kept as the literal `defi,nft`, so the same list was read differently depending on whether it was passed once or as repeated flags.
24
+
25
+ - [#652](https://github.com/nansen-ai/nansen-cli/pull/652) [`d0433d4`](https://github.com/nansen-ai/nansen-cli/commit/d0433d4e0da5092c47f63c9a74d71f167c9a347e) Thanks [@Bruce039](https://github.com/Bruce039)! - Resolve ENS names when the profiler chain is `all`. The profiler commands default `--chain` to `all`, but the resolver only accepted explicit EVM chains, so `research profiler labels --address vitalik.eth` (and every other profiler subcommand except `first-funder`) failed with `ENS names can only be resolved on EVM chains, not all` unless `--chain ethereum` was passed.
26
+
27
+ - [#654](https://github.com/nansen-ai/nansen-cli/pull/654) [`0aad196`](https://github.com/nansen-ai/nansen-cli/commit/0aad1963027ad90761e860501db4db9d438c1143) Thanks [@Bruce039](https://github.com/Bruce039)! - `--fields` now supports dotted paths. `--fields data.results.address` selects that field at that position only (array elements do not add a segment), while a bare name such as `--fields address` keeps matching at any depth. Dotted paths were mentioned in the code but matched nothing, so `--fields data.results` returned an empty object.
28
+
29
+ - [#672](https://github.com/nansen-ai/nansen-cli/pull/672) [`b10dc31`](https://github.com/nansen-ai/nansen-cli/commit/b10dc31fc0509a7941f6fac02dda76088ece71eb) Thanks [@0xShadowX](https://github.com/0xShadowX)! - `--filters` is validated as a JSON object before the request is sent. A value such as `--filters '[]'`, `--filters abc` or a repeated `--filters` flag used to be forwarded to the API as-is and only failed there with a 422; it now fails with an `INVALID_PARAMS` error that shows the expected form.
30
+
31
+ - [#660](https://github.com/nansen-ai/nansen-cli/pull/660) [`42db750`](https://github.com/nansen-ai/nansen-cli/commit/42db750fbc261572f53f02dab1716125ec3b2079) Thanks [@Ahmett101](https://github.com/Ahmett101)! - Parse SSE `data:` fields with or without the optional space after the colon so standards-compliant agent streams do not produce an empty response.
32
+
33
+ - [#651](https://github.com/nansen-ai/nansen-cli/pull/651) [`ab784a3`](https://github.com/nansen-ai/nansen-cli/commit/ab784a331aba66c7899845d22961a52c4f50b93a) Thanks [@kriss39](https://github.com/kriss39)! - Respect the server's `Retry-After` header when retrying rate-limited (429) requests. The wait was capped at the local backoff ceiling (30s), so a `Retry-After: 60` led to a retry after 30s that could only hit the limiter again. The client now waits at least as long as the header asks, and if the server asks for more than `maxRetryAfterMs` (default 120s) it fails immediately with the `retryAfterMs` in the error details instead of retrying too early. A `Retry-After` on a 5xx response is still treated as advisory and capped at the backoff ceiling as before.
34
+
35
+ - [#663](https://github.com/nansen-ai/nansen-cli/pull/663) [`bc4ecc8`](https://github.com/nansen-ai/nansen-cli/commit/bc4ecc82c4bfedfc66dbe621f96a581437bb415d) Thanks [@gulshngill](https://github.com/gulshngill)! - Option values that spell a JSON keyword (`--sort true`, `--search false`, `--label null`) are now kept as the literal strings `true`/`false`/`null` instead of being converted to a boolean or null, so string options no longer crash or silently drop the value; `--filters '{}'` and `--order-by '[...]'` still parse as JSON, and `--sort` now rejects a repeated or non-text value with `--sort must be "field" or "field:direction"`.
36
+
37
+ - [#671](https://github.com/nansen-ai/nansen-cli/pull/671) [`8a4e98f`](https://github.com/nansen-ai/nansen-cli/commit/8a4e98f8275701f328ab8d4cef850afbd5183177) Thanks [@0xShadowX](https://github.com/0xShadowX)! - Keep the body of a non-JSON error response (gateway HTML, plain text) in the error details instead of reporting `body: null`, and apply the same retry policy to it as to a JSON error: a plain-text `429` is now retried, with its `Retry-After` respected, instead of failing on the first attempt.
38
+
39
+ - [#676](https://github.com/nansen-ai/nansen-cli/pull/676) [`0112fa1`](https://github.com/nansen-ai/nansen-cli/commit/0112fa1aba981e961a2795ae4c92534eb3a8694f) Thanks [@0xShadowX](https://github.com/0xShadowX)! - Refuse to sign EVM approval, revoke, and Privy swap transactions when the quote carries no gas price, instead of defaulting to an unmineable 0.001 gwei fee that left the wallet's nonce stuck
40
+
41
+ - [#681](https://github.com/nansen-ai/nansen-cli/pull/681) [`c82492d`](https://github.com/nansen-ai/nansen-cli/commit/c82492df4d7f260f5d234aa8cbe362e4d27b08aa) Thanks [@kriss39](https://github.com/kriss39)! - `wallet send` and `trade limit-order create` reject an amount of zero, or one that truncates to zero base units at the token's precision, instead of broadcasting a transfer of nothing or creating a limit order with `inputAmount: "0"`
42
+
43
+ - [#650](https://github.com/nansen-ai/nansen-cli/pull/650) [`d4b4925`](https://github.com/nansen-ai/nansen-cli/commit/d4b4925d0de9035df6cd01a5a9165691646e9a9f) Thanks [@kriss39](https://github.com/kriss39)! - `research token screener --search` now honours `--page`. The search filter runs client-side, and previously every page returned the same first slice of matches; the candidate fetch is now widened to cover the requested page and the filtered list is sliced at the page offset.
44
+
45
+ - [#661](https://github.com/nansen-ai/nansen-cli/pull/661) [`fe5b294`](https://github.com/nansen-ai/nansen-cli/commit/fe5b294d30a8dc3e93270aead4a27a4b6513ce60) Thanks [@gulshngill](https://github.com/gulshngill)! - Recognise the API's full set of structured error codes. A 401 `unauthenticated` response once again shows `Not logged in. Run: nansen login`, `insufficient_credits` gets its do-not-retry hint, and codes that previously leaked through as raw server strings now surface as CLI codes, including the new `PLAN_UPGRADE_REQUIRED`, `GEO_BLOCKED`, `QUERY_TOO_LARGE`, `PAYLOAD_TOO_LARGE`, `METHOD_NOT_ALLOWED`, and `CONFLICT`. Retry behaviour is unchanged: it stays keyed on the HTTP status.
46
+
47
+ - [#679](https://github.com/nansen-ai/nansen-cli/pull/679) [`5c8d22b`](https://github.com/nansen-ai/nansen-cli/commit/5c8d22bc52a23574de6138a396ea878ccfb5efca) Thanks [@0xShadowX](https://github.com/0xShadowX)! - Fail with an actionable error when a Solana RPC cannot return an SPL mint's decimals, instead of silently assuming 9 and building a transfer or limit order with a mis-scaled amount
48
+
49
+ - [#675](https://github.com/nansen-ai/nansen-cli/pull/675) [`938a011`](https://github.com/nansen-ai/nansen-cli/commit/938a0112cba40f9f80ced1569fd9d2e2f32db608) Thanks [@kome12](https://github.com/kome12)! - Reject malformed or negative profiler `--delay` and token `top-tokens --limit` values instead of partially parsing them.
50
+
51
+ - [#646](https://github.com/nansen-ai/nansen-cli/pull/646) [`3290e3c`](https://github.com/nansen-ai/nansen-cli/commit/3290e3cefa2c7c5e1405d09e4d5d860ca05d404f) Thanks [@gulshngill](https://github.com/gulshngill)! - `--table` and `--format csv` error output now includes the error `code`, HTTP `status`, and `details` instead of only the message. CSV errors are emitted as a header row plus one record; table errors keep the leading `Error:` line and add one `key: value` line per field.
52
+
53
+ - [#662](https://github.com/nansen-ai/nansen-cli/pull/662) [`7fd923f`](https://github.com/nansen-ai/nansen-cli/commit/7fd923ff4d58128c19e6995e015af6093dee7586) Thanks [@gulshngill](https://github.com/gulshngill)! - Sync the `chains` list reported by `nansen schema` (and mirrored in `--help` and the README) with the chains the Nansen API actually accepts. Drops `scroll` and `ronin`, which no endpoint serves any more, and adds the chains that were missing: `algorand`, `aptos`, `arc`, `bitcoin`, `bitlayer`, `chiliz`, `citrea`, `gravity`, `hyperliquid`, `injective`, `mantra`, `near`, `robinhood`, `stacks`, `starknet`, `stellar`, `sui`, `ton`, `tron`, `viction`. Not every chain is served by every endpoint; the API still validates `--chain` per endpoint.
54
+
55
+ - [#664](https://github.com/nansen-ai/nansen-cli/pull/664) [`d034ae1`](https://github.com/nansen-ai/nansen-cli/commit/d034ae1d01582f721e8572dcd40234d21b31708a) Thanks [@gulshngill](https://github.com/gulshngill)! - `trade quote` and `trade execute` now screen the signing wallet (and any distinct `--to-wallet` destination) against the compliance blocklist before requesting a quote or signing — the same fail-closed check `bridge` and `perp` already run — so a flagged address, or a screening call that fails, aborts the command before anything is signed or broadcast. Both commands now require API access for this check; authenticate with `nansen login` or `NANSEN_API_KEY` before trading.
56
+
57
+ - [#653](https://github.com/nansen-ai/nansen-cli/pull/653) [`337271d`](https://github.com/nansen-ai/nansen-cli/commit/337271d10d226cf61b24c18d656e955cd588d91d) Thanks [@Bruce039](https://github.com/Bruce039)! - `--sort` now rejects a direction other than `asc`/`desc` and an empty field name with an `INVALID_PARAMS` error. Previously `--sort pnl_usd:sideways` was uppercased and sent to the API as `direction: SIDEWAYS`, which only failed later with an upstream 422.
58
+
59
+ - [#648](https://github.com/nansen-ai/nansen-cli/pull/648) [`0514c76`](https://github.com/nansen-ai/nansen-cli/commit/0514c76029a6c0609743d8c4af87cbdf80d9bbff) Thanks [@kriss39](https://github.com/kriss39)! - Validate `token screener --search` and `token who-bought-sold --buy-or-sell` before the request is sent, so a JSON array/object or a repeated flag (`--search '[]'`, `--buy-or-sell '{}'`) and values outside the `BUY`/`SELL` enum produce an actionable `INVALID_PARAMS` error instead of a raw `.toLowerCase()`/`.toUpperCase()` TypeError.
60
+
61
+ - [#666](https://github.com/nansen-ai/nansen-cli/pull/666) [`6539558`](https://github.com/nansen-ai/nansen-cli/commit/65395584ab9844ec3f0117ef951b2eb26ff6342c) Thanks [@gulshngill](https://github.com/gulshngill)! - Make every wallet subcommand discoverable from the places agents look first. `nansen --help` now lists `send`, `forget-password` and `secure` on the wallet line (previously only seven of the nine were shown) and the full perp subcommand set (`transfer`, `approve-builder-fee`, `orders`, `account`, `meta`, `screener` and `leaderboard` were missing). It also stops describing the combined top-level `perp` command as a deprecated analytics alias. README lists the same wallet set, and `nansen schema wallet` now documents `forget-password` and `secure` with descriptions plus an example for every wallet subcommand. Help text, README, runtime command help and schema are pinned together by a new drift-guard test.
62
+
63
+ - [#677](https://github.com/nansen-ai/nansen-cli/pull/677) [`b91e108`](https://github.com/nansen-ai/nansen-cli/commit/b91e10878d8606aa419b71a12493fbd8d273e731) Thanks [@0xShadowX](https://github.com/0xShadowX)! - Read a pretty-printed WalletConnect `sign-typed-data` result on the x402 payment path instead of failing after the user has already approved the payment in their wallet
64
+
65
+ - [#673](https://github.com/nansen-ai/nansen-cli/pull/673) [`05a2056`](https://github.com/nansen-ai/nansen-cli/commit/05a20562edb6875541998db57ec47375e2dbb2ab) Thanks [@0xShadowX](https://github.com/0xShadowX)! - `web search --num-results` now rejects a malformed value (`5abc`, `2.5`, `abc`, a repeated or valueless flag) with `INVALID_PARAMS`. Previously `5abc` was silently truncated to 5, `2.5` to 2, and a non-numeric value fell back to the API default instead of reporting the mistake.
66
+
67
+ ## 1.45.0
68
+
69
+ ### Minor Changes
70
+
71
+ - [#624](https://github.com/nansen-ai/nansen-cli/pull/624) [`8bd2f00`](https://github.com/nansen-ai/nansen-cli/commit/8bd2f0057fce09d1fce8c91dd5d2128c3c9ce25d) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `nansen research profiler counterparties-batch` — top counterparties for up to 10 wallets in a single request. Takes `--addresses "0xabc,0xdef"` (comma-separated or a JSON array) or `--file`, validates the 10-address and 90-day limits client-side, and returns rows tagged with the `wallet_address` they belong to (results are not aggregated across wallets). `--chain` defaults to `all`, which auto-detects the ecosystem; one ecosystem per request, as EVM and Solana addresses cannot be mixed.
72
+
73
+ ### Patch Changes
74
+
75
+ - [#643](https://github.com/nansen-ai/nansen-cli/pull/643) [`b459772`](https://github.com/nansen-ai/nansen-cli/commit/b4597722c26b95dbd4eedb5b93f8a5dd9042be10) Thanks [@Codier](https://github.com/Codier)! - Ignore failed and malformed OpenAPI responses when refreshing the credit-cost cache. A non-2xx response that still returned JSON replaced the cached cost map with an empty one and stamped it fresh, so credit estimates went missing for up to 24 hours and the next refresh was suppressed.
76
+
77
+ - [#634](https://github.com/nansen-ai/nansen-cli/pull/634) [`a5a3b27`](https://github.com/nansen-ai/nansen-cli/commit/a5a3b27d9f8fe58ba87a37bec24c2cc627d64fda) Thanks [@Bruce039](https://github.com/Bruce039)! - Avoid caching failed or malformed update-check responses as fresh results, so transient registry errors are retried instead of suppressing checks for 24 hours.
78
+
79
+ - [#637](https://github.com/nansen-ai/nansen-cli/pull/637) [`a0f889d`](https://github.com/nansen-ai/nansen-cli/commit/a0f889d02b9b5bcb729ba82a7ad150a2dadc31c9) Thanks [@gulshngill](https://github.com/gulshngill)! - Fix the `--chain` allowlist on `nansen research profiler counterparties-batch`. It was built from the CLI's internal EVM chain list, which disagreed with the endpoint in both directions: `scroll` and `ronin` were accepted and always 422'd upstream, while every non-EVM chain the profiler serves (`bitcoin`, `tron`, `sui`, `ton`, `near`, `injective`, `mantra`, `robinhood`, `arc`, `starknet`) was rejected client-side. The allowlist is now the endpoint's own `ProfilerChain` enum, and `--chain bsc` is accepted and sent as `bnb`. Addresses on a chain whose format the CLI cannot check are still required to be address-shaped, so a newline `--file` cannot post arbitrary lines as wallet addresses; TON accepts both friendly and raw (`0:`/`-1:` plus 64 hex) addresses.
80
+
81
+ - [#645](https://github.com/nansen-ai/nansen-cli/pull/645) [`dda318e`](https://github.com/nansen-ai/nansen-cli/commit/dda318e72812fc567d3abd1c0e8282aa3c367133) Thanks [@gulshngill](https://github.com/gulshngill)! - Declare the `DELETE /api/v1/smart-alert/{alertId}` route the `alerts delete` command already calls in `src/schema.json`. This was the last route in the parity checker's schema-drift list; the sibling routes (list/create/update/toggle/account/web/agent) were declared in #549.
82
+
83
+ - [#640](https://github.com/nansen-ai/nansen-cli/pull/640) [`60961cf`](https://github.com/nansen-ai/nansen-cli/commit/60961cf9bcb828bc85caccb7b55c09b664e46aac) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Fix `parseArgs` treating an explicit empty-string option value (`--flag ""`) as a boolean flag and leaking the `""` into positional arguments. `nansen web fetch <url> --question ""` now reports the blank-question error instead of `Invalid URL: ""`.
84
+
85
+ Register `--all`, `--max`, `--gasless`, `--auto-slippage`, and `--unsafe-no-password` as valueless flags. They are read only as booleans, so a following token such as `nansen perp meta --all` plus an asset name was parsed as their value and the switch went dead.
86
+
87
+ Reject a blank `nansen mcp verify --url ""` instead of falling back to the default Nansen endpoint, which reported the default URL as verified when the caller passed an unset shell variable.
88
+
89
+ Reject a blank `--slippage` or `--max-auto-slippage` on `nansen trade quote`. An empty string became `0` in the range check, satisfied the rule that `--swap-mode exactOut --auto-slippage` needs an explicit cap, and was then dropped when the request was built, so the ERC-20 approval was scoped by a cap that never reached the server.
90
+
91
+ Reject a blank `nansen web fetch --url ""` instead of dropping it and fetching only the positional URLs.
92
+
93
+ - [#644](https://github.com/nansen-ai/nansen-cli/pull/644) [`14bbd9b`](https://github.com/nansen-ai/nansen-cli/commit/14bbd9b273a570953d02900acb21aeed81ac1bfe) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Reject explicitly blank quote options, execute and limit-order wallet selectors, limit-order expiry and list options, wallet creation names and send options, and research chain/timeframe, days, buy-or-sell, and profiler batch/trace tuning options with an actionable error instead of selecting defaults. Preserve numeric zero slippage caps in programmatic quote requests.
94
+
95
+ - [#542](https://github.com/nansen-ai/nansen-cli/pull/542) [`055488a`](https://github.com/nansen-ai/nansen-cli/commit/055488a1b9a9a85994b12af0245e3a9139b8238f) Thanks [@gulshngill](https://github.com/gulshngill)! - Stop calling the removed points leaderboard API route. Both `points leaderboard` and `research points leaderboard` now return a structured unavailable error and exit with a failure status, without suggesting the other unavailable command as a replacement.
96
+
97
+ - [#549](https://github.com/nansen-ai/nansen-cli/pull/549) [`28714c6`](https://github.com/nansen-ai/nansen-cli/commit/28714c6a2f89fbd8965e84916e9f185883b3cd27) Thanks [@gulshngill](https://github.com/gulshngill)! - Declare the API routes `alerts`, `account`, `web` and `agent` already call in `src/schema.json`. The schema is what shell completions, `--help` and docs tooling read, so eight routes the code requests were invisible to them (and to the API/MCP/CLI parity check).
98
+
99
+ - [#647](https://github.com/nansen-ai/nansen-cli/pull/647) [`2b84502`](https://github.com/nansen-ai/nansen-cli/commit/2b8450254515a2e0aa1b3e973332a2362a85f8ea) Thanks [@kome12](https://github.com/kome12)! - Reject invalid profiler trace width values instead of returning an empty-looking trace.
100
+
101
+ - [#642](https://github.com/nansen-ai/nansen-cli/pull/642) [`b6c928f`](https://github.com/nansen-ai/nansen-cli/commit/b6c928fc458a216aff3ac1f4961f8aaf4a02eceb) Thanks [@kome12](https://github.com/kome12)! - Validate `nansen alerts` string/array options (`--chains`, `--token`/`--exclude-token`, `--subject`/`--counterparty`/`--caller`/`--contract` and their `--exclude-*` variants, `--events`, `--signature-hash`, `--token-sector`/`--exclude-token-sector`, and `alerts list --token-address`/`--chain`) so JSON primitives (e.g. `--chains true`) produce actionable `INVALID_PARAMS` errors instead of a raw `TypeError` crash or being silently dropped/passed through into the alert payload.
102
+
103
+ - [#630](https://github.com/nansen-ai/nansen-cli/pull/630) [`7cb8bb2`](https://github.com/nansen-ai/nansen-cli/commit/7cb8bb2ecd4cd2e1a302b43de73ef2b015dc42d6) Thanks [@kriss39](https://github.com/kriss39)! - Validate supported analytics `--days` values as non-negative integers with a representable date range instead of truncating malformed inputs or forwarding `NaN`.
104
+
105
+ - [#639](https://github.com/nansen-ai/nansen-cli/pull/639) [`17e4f64`](https://github.com/nansen-ai/nansen-cli/commit/17e4f648412057c0012cd5ea464be10363be893e) Thanks [@kome12](https://github.com/kome12)! - Validate more CLI string options (`profiler batch --include`, `perp screener --sectors-filter`/`--sm-label-filter`/`--trader-label-filter`, `prediction-market market-screener`/`event-screener --tags`, and `--fields`) so JSON primitives produce actionable `INVALID_PARAMS` errors instead of raw `.split()`/`.trim()` TypeErrors.
106
+
107
+ - [#632](https://github.com/nansen-ai/nansen-cli/pull/632) [`d9c7e6e`](https://github.com/nansen-ai/nansen-cli/commit/d9c7e6e6ea9615ee9534cafc960d54a2dadc0160) Thanks [@Bruce039](https://github.com/Bruce039)! - Reject malformed or valueless `--date` inputs instead of silently falling back to the rolling `--days` range.
108
+
109
+ - [#631](https://github.com/nansen-ai/nansen-cli/pull/631) [`17cbed5`](https://github.com/nansen-ai/nansen-cli/commit/17cbed5e8a286ebebaefe893ee6a0198188ff379) Thanks [@Bruce039](https://github.com/Bruce039)! - Reject malformed and non-finite prediction-market screener numeric filters before they can be serialized as `null` or silently ignored.
110
+
111
+ - [#629](https://github.com/nansen-ai/nansen-cli/pull/629) [`b802bca`](https://github.com/nansen-ai/nansen-cli/commit/b802bca7ad5352ba03226fdbc64e97a3f4496d03) Thanks [@kriss39](https://github.com/kriss39)! - Reject malformed, fractional, non-finite, repeated, or valueless `profiler trace --depth` inputs while preserving the existing 1-5 clamping behavior for valid integers.
112
+
113
+ - [#633](https://github.com/nansen-ai/nansen-cli/pull/633) [`901f63e`](https://github.com/nansen-ai/nansen-cli/commit/901f63e522cdbbf773f055d928a415f99d02bf94) Thanks [@Bruce039](https://github.com/Bruce039)! - Validate web `--query` and `--question` option types so JSON primitives produce actionable CLI errors instead of raw `.trim()` TypeErrors.
114
+
3
115
  ## 1.44.3
4
116
 
5
117
  ### Patch Changes
package/README.md CHANGED
@@ -55,7 +55,9 @@ nansen completion <bash|zsh|fish> # shell completions (no API key needed)
55
55
  nansen schema [command] [--pretty] # full command reference (no API key needed)
56
56
  ```
57
57
 
58
- **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`, `points`
58
+ **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`
59
+
60
+ 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.
59
61
 
60
62
  **Direct research subcommands:**
61
63
  - `nansen research chain-rank [--timeframe-days 7|30|365] [--chain-type all|evm]` — rank chains by growth metrics
@@ -70,7 +72,7 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
70
72
 
71
73
  **Trade:** `quote`, `execute`, `bridge-status`, `limit-order` — DEX swaps on Solana and Base, cross-chain bridges, and Solana limit orders.
72
74
 
73
- **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local or Privy server-side wallets (EVM + Solana).
75
+ **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send`, `forget-password`, `secure` — local or Privy server-side wallets (EVM + Solana).
74
76
 
75
77
  Run `nansen schema --pretty` for the full subcommand and field reference.
76
78
 
@@ -161,6 +163,24 @@ nansen trade execute --quote <quoteId> --gasless # Relay-only: solver pays
161
163
  nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
162
164
  ```
163
165
 
166
+ ### Before broadcasting
167
+
168
+ `trade execute` and `bridge execute` move funds irreversibly, so both accept:
169
+
170
+ ```bash
171
+ nansen trade execute --quote <quoteId> --dry-run # validate + print the plan, broadcast nothing
172
+ nansen trade execute --quote <quoteId> --yes # skip the confirmation prompt (also: -y)
173
+ ```
174
+
175
+ `--dry-run` runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints what *would* be sent (chain, tokens, amounts, recipient, approvals, fees); and stops before wallet credentials, signing, or broadcast — no wallet password needed, the quote stays usable, exit code 0. Real execution still resolves and revalidates the live signer before signing.
176
+
177
+ When stdin is an interactive terminal, execute prints that plan and asks `Broadcast this transaction? [y/N]` first; anything but `y`/`yes` aborts with exit code 1 and nothing signed. `--yes`, or `NANSEN_YES=1`, skips the question. **When stdin is not a terminal — agents, CI, pipes — nothing changes: the command proceeds without prompting**, and `--yes` is accepted as a no-op so it is always safe to pass.
178
+
179
+ | Exit code | Meaning |
180
+ |-----------|---------|
181
+ | `0` | Broadcast succeeded, or the dry run completed |
182
+ | `1` | Declined at the confirmation prompt, or the execution failed |
183
+
164
184
  Amounts are in base units (lamports, wei) by default — use `--amount-unit token|usd|percent` for friendlier inputs. Common symbols (`SOL`, `ETH`, `USDC`, `USDT`) resolve automatically. A wallet is required — set one with `nansen wallet default <name>`.
165
185
 
166
186
  ## Limit Orders
@@ -211,11 +231,12 @@ Move USDC between EVM chains and Hyperliquid via `nansen bridge`. Uses the same
211
231
  ```bash
212
232
  nansen bridge quote --from-chain base --to-chain hyperliquid --from-token USDC --amount 1000000
213
233
  nansen bridge execute --quote <quoteId>
234
+ nansen bridge execute --quote <quoteId> --dry-run # preview, nothing is broadcast
214
235
  nansen bridge execute --quote <quoteId> --nonce 20 --priority-fee 5 # replace a stuck EVM deposit
215
236
  nansen bridge status --request-id <id>
216
237
  ```
217
238
 
218
- Supported routes: `base → hyperliquid` (deposit), and `hyperliquid → base`/`ethereum`/`arbitrum` (withdraw). Deposits broadcast an EVM transaction locally, so only Base is offered on the deposit side; run `nansen bridge help` for the current list. `--amount` is a base-unit integer by default; pass `--amount-unit token` for a human amount. `--recipient` defaults to the wallet's own EVM address. `--priority-fee`/`--max-fee` (gwei) and `--nonce` apply only to EVM deposit legs and let a stuck transaction be replaced. Bridge transfers are irreversible once signed.
239
+ Supported routes: `base → hyperliquid` (deposit), and `hyperliquid → base`/`ethereum`/`arbitrum` (withdraw). Deposits broadcast an EVM transaction locally, so only Base is offered on the deposit side; run `nansen bridge help` for the current list. `--amount` is a base-unit integer by default; pass `--amount-unit token` for a human amount. `--recipient` defaults to the wallet's own EVM address. `--priority-fee`/`--max-fee` (gwei) and `--nonce` apply only to EVM deposit legs and let a stuck transaction be replaced. Bridge transfers are irreversible once signed, so `bridge execute` takes the same `--dry-run` and `--yes`/`NANSEN_YES` gate as `trade execute` (see [Before broadcasting](#before-broadcasting)); on a multi-step transfer, a dry run stops before the first step.
219
240
 
220
241
  ## Wallet
221
242
 
@@ -225,6 +246,8 @@ nansen wallet create --name my-wallet --provider privy # server-side via Privy
225
246
  nansen wallet list
226
247
  nansen wallet default <name>
227
248
  nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
249
+ nansen wallet secure # move a saved password into the OS keychain
250
+ nansen wallet forget-password # drop the saved password from every store
228
251
  ```
229
252
 
230
253
  **Local wallets** are password-encrypted. Set `NANSEN_WALLET_PASSWORD` to skip the prompt.
@@ -294,7 +317,7 @@ after upgrading the CLI to pick up new commands.
294
317
  | `--chain <chain>` | Blockchain to query |
295
318
  | `--limit <n>` | Result count |
296
319
  | `--timeframe <tf>` | Time window: `5m` `1h` `6h` `24h` `7d` `30d` |
297
- | `--fields <list>` | Comma-separated fields (reduces response size) |
320
+ | `--fields <list>` | Comma-separated fields (reduces response size); a bare name matches at any depth, a dotted path such as `data.results.address` only at that position |
298
321
  | `--sort <field:dir>` | Sort results, e.g. `--sort value_usd:desc` |
299
322
  | `--pretty` | Human-readable JSON |
300
323
  | `--table` | Table format |
@@ -304,7 +327,7 @@ after upgrading the CLI to pick up new commands.
304
327
 
305
328
  ## Supported Chains
306
329
 
307
- `ethereum` `solana` `base` `bnb` `arbitrum` `polygon` `optimism` `avalanche` `linea` `scroll` `mantle` `ronin` `sei` `plasma` `sonic` `monad` `hyperevm` `iotaevm`
330
+ `algorand` `aptos` `arbitrum` `arc` `avalanche` `base` `bitcoin` `bitlayer` `bnb` `chiliz` `citrea` `ethereum` `gravity` `hyperevm` `hyperliquid` `injective` `iotaevm` `linea` `mantle` `mantra` `monad` `near` `optimism` `plasma` `polygon` `robinhood` `sei` `solana` `sonic` `stacks` `starknet` `stellar` `sui` `ton` `tron` `viction`
308
331
 
309
332
  > Run `nansen schema` to get the current chain list (source of truth).
310
333
 
@@ -334,7 +357,12 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
334
357
  | `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
335
358
  | `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
336
359
  | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
360
+ | `PLAN_UPGRADE_REQUIRED` | The endpoint or option needs a higher subscription plan. Do not retry. |
361
+ | `GEO_BLOCKED` | Not available in your region. Do not retry. |
337
362
  | `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
363
+ | `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
364
+
365
+ 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.
338
366
 
339
367
  **Error metadata.** When the API reports them, `details` carries:
340
368
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nansen-cli",
3
- "version": "1.44.3",
3
+ "version": "1.46.0",
4
4
  "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
@@ -54,8 +54,23 @@ For cross-chain swaps, each token is checked against its own chain (from vs `--c
54
54
 
55
55
  ```bash
56
56
  nansen trade execute --quote <quote-id>
57
+ nansen trade execute --quote <quote-id> --dry-run # preview only, nothing is broadcast
58
+ nansen trade execute --quote <quote-id> --yes # skip the confirmation prompt
57
59
  ```
58
60
 
61
+ **`--dry-run`** runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints the trade that *would* be sent (chain, tokens, amounts, recipient, approval, fees); and stops before wallet credentials or signing. No wallet password is needed, the quote is not consumed, and the command exits 0. Real execution still resolves and revalidates the live signer. On Base, preview also reads the current token allowance and runs the pre-broadcast revert simulation when no approval is outstanding.
62
+
63
+ **Confirmation.** When stdin is an interactive terminal, `execute` prints the plan and asks `Broadcast this transaction? [y/N]` before broadcasting. Answering anything but `y`/`yes` aborts with exit code 1 and nothing signed. Pass `--yes` (`-y`), or set `NANSEN_YES=1`, to skip the question.
64
+
65
+ **Agents and CI are unaffected:** when stdin is *not* a terminal (a pipe, a CI job, an agent shell) the command proceeds without prompting, exactly as before. `--yes` is accepted there and is simply a no-op, so it is safe to always pass it. The same flags and rules apply to `nansen bridge execute`.
66
+
67
+ ### Exit codes (`trade execute`, `bridge execute`)
68
+
69
+ | Code | Meaning |
70
+ |------|---------|
71
+ | `0` | Broadcast succeeded, or the dry run completed |
72
+ | `1` | Declined at the confirmation prompt, or the execution failed |
73
+
59
74
  ## Cross-Chain Swap
60
75
 
61
76
  Bridge tokens between Solana and Base using `--to-chain`:
@@ -167,6 +182,8 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
167
182
  | `--wallet` | Wallet name (default: default wallet) |
168
183
  | `--quote-index` | Pin a specific quote by index (0-based) when multiple quotes were returned |
169
184
  | `--no-simulate` | Skip pre-broadcast simulation |
185
+ | `--dry-run` | Validate and print what would be sent, then stop. Nothing is signed or broadcast |
186
+ | `--yes`, `-y` | Skip the confirmation prompt (same as `NANSEN_YES=1`); no-op when stdin is not a terminal |
170
187
 
171
188
  ### `trade bridge-status` flags
172
189
 
@@ -181,7 +198,8 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
181
198
  | Var | Purpose |
182
199
  |-----|---------|
183
200
  | `NANSEN_WALLET_PASSWORD` | **Required for `trade execute`.** Wallet encryption password — persisted in `~/.nansen/.env`. Source before executing: `source ~/.nansen/.env && nansen trade execute ...` |
184
- | `NANSEN_API_KEY` | API key (also set via `nansen login`) |
201
+ | `NANSEN_API_KEY` | API key (also set via `nansen login`). `trade quote` and `trade execute` need it for the pre-trade compliance screen below. |
202
+ | `NANSEN_YES` | Set to `1` to skip the `execute` confirmation prompt, like `--yes` |
185
203
 
186
204
  > **Agents:** Never hold a wallet password only in session memory. If `NANSEN_WALLET_PASSWORD` is not in `~/.nansen/.env`, follow the setup flow in the nansen-wallet-manager skill Password Policy to generate and persist one before proceeding.
187
205
 
@@ -189,6 +207,7 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
189
207
 
190
208
  - Quotes expire after ~1 hour. If execute fails, get a fresh quote.
191
209
  - A wallet is required even for quotes (the API builds sender-specific transactions).
210
+ - Compliance screen: `trade quote` and `trade execute` check the signing wallet (and any distinct `--to-wallet` destination) against the compliance blocklist through the Nansen API before requesting a quote or signing — the same fail-closed check `bridge` and `perp` run. A flagged address aborts with code `SANCTIONED`; if the screening call itself fails the command aborts with `SCREENING_UNAVAILABLE`. Nothing is signed or broadcast in either case.
192
211
  - ERC-20 swaps may require an approval step — execute handles this automatically.
193
212
 
194
213
  # Perp Trading
@@ -28,7 +28,19 @@ On confirm, re-run steps 1-2 on it. Reserve step 3 (counterparties) for the seed
28
28
 
29
29
  ## L2 Coverage
30
30
 
31
- When step 3 returns sparse results on a mainnet EVM address, extend to L2s (4 calls):
31
+ When step 3 returns sparse results on a mainnet EVM address, extend to L2s. `--chain all`
32
+ detects each address's chain and covers the EVM chains in a single call, and takes up to
33
+ 10 addresses at once (every row carries the wallet_address it belongs to):
34
+
35
+ ```bash
36
+ nansen research profiler counterparties-batch --addresses "$ADDR" --chain all --days 90 --limit 50
37
+ ```
38
+
39
+ Rows come back as contiguous per-wallet blocks ordered by wallet address, so with several
40
+ addresses a small page holds one wallet only — raise `--limit` and page with `--page N`.
41
+
42
+ `counterparties-batch` is capped at 90 days. For a wider window, fall back to the
43
+ per-chain loop:
32
44
 
33
45
  ```bash
34
46
  for CHAIN in base arbitrum optimism polygon; do
@@ -39,5 +51,5 @@ done
39
51
  ## Cost Warnings
40
52
 
41
53
  - `trace` is credit-heavy; keep `--width 3` or lower
42
- - L2 counterparty checks above add 4 API calls per address
54
+ - The per-chain L2 loop above costs 4 API calls per address; `counterparties-batch --chain all` is 1
43
55
  - Historical balances reveal past holdings on drained wallets — useful fingerprint
@@ -30,6 +30,11 @@ nansen research profiler labels --address $ADDR --chain $CHAIN
30
30
  nansen research profiler related-wallets --address $ADDR --chain $CHAIN
31
31
  # 3. Counterparties (paginate with --page N; widen with --days 365 if empty)
32
32
  nansen research profiler counterparties --address $ADDR --chain $CHAIN --days 90
33
+ # 3b. Once a cluster is confirmed: counterparties for up to 10 of its wallets in one call
34
+ # (max --days 90; one ecosystem per request — EVM and Solana cannot be mixed). Rows are
35
+ # contiguous per-wallet blocks ordered by wallet address: raise --limit and page with
36
+ # --page N to reach later wallets.
37
+ nansen research profiler counterparties-batch --addresses "addr1,addr2" --chain $CHAIN --days 90 --limit 50
33
38
  # 4. Batch profile cluster
34
39
  nansen research profiler batch --addresses "addr1,addr2" --chain $CHAIN --include labels,balance,pnl
35
40
  # 5. Compare pairs → shared_counterparties, shared_tokens, balances
@@ -50,7 +50,7 @@ Interpret `x402.password.source`:
50
50
  - `null` → password not persisted anywhere (Path C or D)
51
51
  - `"env"` → `NANSEN_WALLET_PASSWORD` is set; check where it is being exported from (a `.env` file → Path A)
52
52
 
53
- Do NOT use `nansen wallet export` to probe the password state — it prints private keys.
53
+ Do NOT use `nansen wallet export` to probe the password state — the default is redacted and never loads the password, so it proves nothing (and `--reveal` prints private keys).
54
54
 
55
55
  ## Migration paths
56
56
 
@@ -76,13 +76,15 @@ source ~/.nansen/.env 2>/dev/null && nansen wallet secure
76
76
  **Step 3 — Verify the password actually decrypts the wallet:**
77
77
 
78
78
  ```bash
79
- # Unset env var to prove keychain works, then export to verify decryption
79
+ # Unset env var to prove keychain works, then run a decrypting export with
80
+ # all output discarded — the exit code alone is the signal, so no key
81
+ # material can land in a transcript or log
80
82
  unset NANSEN_WALLET_PASSWORD
81
- nansen wallet export default 2>&1
83
+ if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi
82
84
  ```
83
85
 
84
- If export succeeds (shows private keys), the migration worked. If it shows
85
- `Incorrect password`, the wrong password was migrated — run `nansen wallet
86
+ If the export exits 0 (`decryption OK`), the migration worked. If it fails,
87
+ the wrong password was migrated — run `nansen wallet
86
88
  forget-password` and retry with the correct password.
87
89
 
88
90
  **Step 4 — Clean up the insecure file:**
@@ -102,10 +104,11 @@ nansen wallet secure
102
104
  If the keychain is still unavailable (e.g. containerized Linux without D-Bus),
103
105
  `nansen wallet secure` will explain the situation and suggest alternatives.
104
106
 
105
- After migrating, verify decryption works:
107
+ After migrating, verify decryption works (output discarded on purpose —
108
+ branch on the exit code):
106
109
 
107
110
  ```bash
108
- nansen wallet export default 2>&1
111
+ if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi
109
112
  ```
110
113
 
111
114
  ### Path C: Password only in `NANSEN_WALLET_PASSWORD` env var
@@ -115,11 +118,12 @@ nansen wallet export default 2>&1
115
118
  nansen wallet secure
116
119
  ```
117
120
 
118
- Then verify without the env var:
121
+ Then verify without the env var (exit code is the signal; output is
122
+ discarded so no keys are disclosed):
119
123
 
120
124
  ```bash
121
125
  unset NANSEN_WALLET_PASSWORD
122
- nansen wallet export default 2>&1
126
+ if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi
123
127
  ```
124
128
 
125
129
  ### Path D: Password lost entirely
@@ -147,11 +151,12 @@ the keychain password can actually decrypt the wallet:
147
151
  # Unset env var to prove keychain works
148
152
  unset NANSEN_WALLET_PASSWORD
149
153
 
150
- # This MUST succeed — it proves the keychain password decrypts the wallet
151
- nansen wallet export default 2>&1
154
+ # This MUST exit 0 — it proves the keychain password decrypts the wallet.
155
+ # Output is discarded on purpose: the exit code alone is the signal.
156
+ if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi
152
157
  ```
153
158
 
154
- If export shows `Incorrect password`, the wrong password was saved to the
159
+ If the export fails, the wrong password was saved to the
155
160
  keychain. Fix with:
156
161
 
157
162
  ```bash
@@ -182,4 +187,4 @@ wallet operations will require `NANSEN_WALLET_PASSWORD` env var or re-running
182
187
  - **NEVER use `--human` flag** — interactive prompts break agents
183
188
  - If the human authorizes reading `~/.nansen/.env`, read it in the same command
184
189
  (`source ~/.nansen/.env && nansen wallet secure`) — do not echo or log the value
185
- - **ALWAYS verify after migration** with `nansen wallet export default` — `wallet show` does NOT prove the password works (it never loads the password)
190
+ - **ALWAYS verify after migration** with `nansen wallet export default --reveal > /dev/null 2>&1` (branch on the exit code; never let the output print) — `wallet show` does NOT prove the password works (it never loads the password)
@@ -152,11 +152,23 @@ nansen wallet send --to <addr> --amount 1.0 --chain evm --dry-run
152
152
  ## Export & Delete
153
153
 
154
154
  ```bash
155
- # Password auto-resolved from keychain
155
+ # Default is REDACTED — shows addresses only, never private keys
156
156
  nansen wallet export <name>
157
+
158
+ # Write private keys to a file only the owner can read (0600, refuses to overwrite)
159
+ nansen wallet export <name> --file <path>
160
+
161
+ # Print private keys in plaintext to stdout (explicit acknowledgement required;
162
+ # warns on stderr when stdout is an interactive terminal)
163
+ nansen wallet export <name> --reveal
164
+
165
+ # Password auto-resolved from keychain (needed for --reveal / --file)
157
166
  nansen wallet delete <name>
158
167
  ```
159
168
 
169
+ Prefer `--file` over `--reveal`: plaintext on stdout ends up in terminal
170
+ scrollback, shell logs, and agent transcripts.
171
+
160
172
  ## Forget Password
161
173
 
162
174
  ```bash
@@ -182,6 +194,8 @@ For detailed migration steps (from `~/.nansen/.env`, `.credentials`, or env-var-
182
194
  | `--max` | Send entire balance |
183
195
  | `--dry-run` | Preview without broadcasting |
184
196
  | `--provider` | Wallet provider: `local` (default, encrypted on disk) or `privy` (server-side via Privy API) |
197
+ | `--reveal` | Export only: print private keys in plaintext to stdout (required acknowledgement) |
198
+ | `--file` | Export only: write private keys to this path (created 0600, refuses to overwrite) |
185
199
  | `--human` | Enable interactive prompts (human terminal use only — agents must NOT use this) |
186
200
  | `--unsafe-no-password` | Skip encryption (keys stored in plaintext — NOT recommended) |
187
201
 
@@ -49,6 +49,17 @@ nansen research profiler historical-balances --address <addr> --chain solana --d
49
49
  ```bash
50
50
  nansen research profiler related-wallets --address <addr> --chain ethereum
51
51
  nansen research profiler counterparties --address <addr> --chain ethereum --days 30
52
+
53
+ # Counterparties for up to 10 wallets in one call (max --days 90).
54
+ # Results are not aggregated — every row carries the wallet_address it belongs to.
55
+ # One ecosystem per request: EVM and Solana addresses cannot be mixed; `all` auto-detects it.
56
+ # --chain also takes any single chain the profiler serves, EVM or not: arbitrum, arc,
57
+ # avalanche, base, bitcoin, bnb (`bsc` is accepted too), ethereum, hyperevm, injective,
58
+ # iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, sei,
59
+ # solana, sonic, starknet, sui, ton, tron.
60
+ # Rows come back as contiguous per-wallet blocks ordered by wallet address, so a small page
61
+ # holds one wallet only — raise --limit and page with --page N to reach later wallets.
62
+ nansen research profiler counterparties-batch --addresses "0xabc,0xdef" --days 30 --limit 50
52
63
  ```
53
64
 
54
65
  ## Perps (no --chain)
@@ -81,6 +92,7 @@ nansen research profiler compare --addresses "0xabc,0xdef" --chain ethereum
81
92
  | `--chain` | Required except for perps and search |
82
93
  | `--days` | Lookback period (default 30) |
83
94
  | `--limit` | Number of results |
95
+ | `--addresses` | Comma-separated wallets for `batch`, `compare`, `counterparties-batch` |
84
96
  | `--include` | Batch fields: `labels,balance,pnl` |
85
97
  | `--depth` | Trace depth 1-5 (default 2) |
86
98
  | `--width` | Trace width — keep low to save credits |