nansen-cli 2.4.0 → 2.6.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,83 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#828](https://github.com/nansen-ai/nansen-cli/pull/828) [`f143625`](https://github.com/nansen-ai/nansen-cli/commit/f1436251fe7b07314980918f2202bf31fe9e6577) Thanks [@kome12](https://github.com/kome12)! - One flag name per input across commands, with the old names still accepted: `--token` for a token address (historical-\* commands, `alerts list`, `trade limit-order list`; `--token-address` and `--mint` still work), `--days` for a lookback in days (`chain-rank`, `smart-money-pnl-leaderboard`, `historical-token-screener`; `--timeframe-days` still works), `--interval` for the candle size on `token ohlcv` and `historical-token-ohlcv` (`--timeframe` still works), and `--symbol` for a perp market (`perp order/cancel/close/leverage`, and research perp commands now accept `--coin`). Giving one input under two names now fails instead of silently using one of them. `--days` on `token screener`, `info` or `flow-intelligence` now points to `--timeframe`.
8
+
9
+ - [#829](https://github.com/nansen-ai/nansen-cli/pull/829) [`61520f7`](https://github.com/nansen-ai/nansen-cli/commit/61520f75c23a76ddfb0267a67354ed6ef1a02cfe) Thanks [@kome12](https://github.com/kome12)! - Research commands now report the chain they used when `--chain` is left out, as `_meta.defaults.chain` in the JSON response. `--help` and `nansen schema` now show the default chain each command actually uses: `token indicators` defaults to `solana` (it said `ethereum`), the wallet `profiler` commands default to `all` (they said `ethereum`), and `smart-money-pnl-leaderboard`, `historical-smart-money-balances` and `historical-token-screener` now document their `solana` default. No command's default chain changed.
10
+
11
+ - [#820](https://github.com/nansen-ai/nansen-cli/pull/820) [`f04ecb2`](https://github.com/nansen-ai/nansen-cli/commit/f04ecb2e2c9fb5e8c763a5d6aabff39d1b280316) Thanks [@kome12](https://github.com/kome12)! - `--help` for every command now prints one line per option with what it does (from the schema), plus its aliases, default, allowed values and whether it is repeatable or required. Research and wallet commands used to list only option names on one `Params` line. `nansen alerts delete --help` now lists `--reveal`.
12
+
13
+ - [#825](https://github.com/nansen-ai/nansen-cli/pull/825) [`774eb34`](https://github.com/nansen-ai/nansen-cli/commit/774eb342eeea5191ee821b80d1f06ec945269ef0) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - **Removed `nansen web fetch` and the `nansen-web-fetcher` skill.** The Nansen API removed `POST /api/v1/search/web-fetch`, the only endpoint the command called, so it no longer returns results on any CLI version. `nansen web fetch` now fails with the usual unknown-subcommand error listing `search`. There is no replacement command.
14
+
15
+ This removes a published subcommand and its `schema.json` entry. It ships as a minor because it was released only after the endpoint was gone, as with the points leaderboard removal (#542).
16
+
17
+ - [#827](https://github.com/nansen-ai/nansen-cli/pull/827) [`156cfef`](https://github.com/nansen-ai/nansen-cli/commit/156cfefb7d328a1fb566384cc7ca7d68b5a167cd) Thanks [@kome12](https://github.com/kome12)! - Add `NANSEN_REQUIRE_CONFIRM=1`, an opt-in stop point for agents: when stdin is not a terminal, `trade execute`, `bridge execute`, `trade limit-order create`/`cancel` and `perp order`/`close`/`cancel`/`leverage` run without `--yes` (or `NANSEN_YES=1`) now fail with `CONFIRMATION_REQUIRED` before any request or signature. `--dry-run` still previews. Unset, behaviour is unchanged.
18
+
19
+ - [#821](https://github.com/nansen-ai/nansen-cli/pull/821) [`420e123`](https://github.com/nansen-ai/nansen-cli/commit/420e1235e6c768b23a32104374f12d98cbf0ea19) Thanks [@kome12](https://github.com/kome12)! - Shorter top-level help. `nansen` and `nansen --help` now print a short index (get-started commands, the command list, and where to find more) instead of 82 lines, and make no network call: no credit-cost fetch before printing, and no update check or update notice. The detail moved behind `nansen help <topic>` (`auth`, `options`, `examples`, `chains`, `labels`, `deprecated`, `telemetry`). `nansen help <command> [subcommand]` prints the same as `nansen <command> [subcommand] --help`, and `nansen help <unknown>` now fails with `UNKNOWN_COMMAND` instead of printing the full page.
20
+
21
+ ### Patch Changes
22
+
23
+ - [#833](https://github.com/nansen-ai/nansen-cli/pull/833) [`b542d75`](https://github.com/nansen-ai/nansen-cli/commit/b542d75538aa3dc6b89f3b29fdd185bb176dc172) Thanks [@kome12](https://github.com/kome12)! - `nansen schema` now lists the `alerts list` filters: `--type`, `--enabled`, `--disabled`, `--chain`, `--limit` and `--offset`.
24
+
25
+ - [#831](https://github.com/nansen-ai/nansen-cli/pull/831) [`378e96c`](https://github.com/nansen-ai/nansen-cli/commit/378e96ca6adbdb4a2cb2795061034a31b78687b1) Thanks [@kome12](https://github.com/kome12)! - Show a non-interactive skills install command (`npx -y skills add nansen-ai/nansen-cli --skill "*" -y`) in the README, top-level help and install messages. The plain command opens a picker that agents cannot drive; the README and the install prompt now also say that space selects a skill and enter confirms.
26
+
27
+ - [#832](https://github.com/nansen-ai/nansen-cli/pull/832) [`cac6ee8`](https://github.com/nansen-ai/nansen-cli/commit/cac6ee8d212d73c34acf640a69f085d09a9ec5ff) Thanks [@kome12](https://github.com/kome12)! - The global-install onboarding now recognises Nansen skills installed with `skills add nansen-ai/nansen-cli` (in `~/.agents/skills` or `~/.claude/skills`) and no longer offers to install them again on every upgrade.
28
+
29
+ - [#822](https://github.com/nansen-ai/nansen-cli/pull/822) [`bd44df9`](https://github.com/nansen-ai/nansen-cli/commit/bd44df90d21e81d01802abe4dec46ee42548c01b) Thanks [@erkancamli](https://github.com/erkancamli)! - x402 auto-payment with a Privy default wallet now tries the payment options cheapest first, like the local wallet and WalletConnect. It used to sign them in the server's order (every EVM option before Solana), so a 402 that listed a pricier option first was paid that one. Privy also no longer signs a Permit2 (`permit2-exact`) or unknown `assetTransferMethod` option as an EIP-3009 authorization the server cannot settle; it skips that option with the reason and tries the next one. A failed Privy wallet lookup now skips only that chain's options, so an option on the other chain can still be paid; when no option can be signed, the lookup error is still reported.
30
+
31
+ - [#830](https://github.com/nansen-ai/nansen-cli/pull/830) [`da57038`](https://github.com/nansen-ai/nansen-cli/commit/da570383b2d81c2c9e92ba090d8dcccb3f2601de) Thanks [@omerbek](https://github.com/omerbek)! - Report the original API error when a profiler trace's root lookup fails instead of returning a successful empty graph. Keep later branch lookups best-effort after a successful root lookup.
32
+
33
+ ## 2.5.0
34
+
35
+ ### Minor Changes
36
+
37
+ - [#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.
38
+
39
+ - [#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.
40
+
41
+ - [#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.
42
+
43
+ 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.
44
+
45
+ ### Patch Changes
46
+
47
+ - [#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')`.
48
+
49
+ - [#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.
50
+
51
+ - [#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.
52
+
53
+ - [#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".
54
+
55
+ - [#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.
56
+
57
+ - [#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.
58
+
59
+ - [#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.
60
+
61
+ - [#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.
62
+
63
+ - [#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`.
64
+
65
+ - [#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.
66
+
67
+ - [#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.
68
+
69
+ - [#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`.
70
+
71
+ - [#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.
72
+
73
+ - [#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.
74
+
75
+ - [#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.
76
+
77
+ - [#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.
78
+
79
+ - [#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.
80
+
3
81
  ## 2.4.0
4
82
 
5
83
  ### Minor Changes
package/README.md CHANGED
@@ -11,9 +11,11 @@ Use it for both analytics and execution: `nansen research ...` returns structure
11
11
 
12
12
  ```bash
13
13
  npm install -g nansen-cli
14
- npx skills add nansen-ai/nansen-cli # load agent skill files
14
+ npx -y skills add nansen-ai/nansen-cli --skill "*" -y # install every agent skill, no prompts
15
15
  ```
16
16
 
17
+ Without `--skill "*" -y`, `skills add` opens a picker: space selects a skill, enter confirms.
18
+
17
19
  ## Feedback
18
20
 
19
21
  Send product feedback to Nansen with your configured API key or login session:
@@ -141,8 +143,8 @@ The check calls `tools/list` for reachability, then calls the paid `nansen_score
141
143
 
142
144
  ```
143
145
  nansen research <category> <subcommand> [options]
144
- nansen agent "<question>" # AI research agent (200 credits, Pro)
145
- nansen agent "<question>" --expert # deeper analysis (750 credits, Pro)
146
+ nansen agent "<question>" # AI research agent (100 credits)
147
+ nansen agent "<question>" --expert # deeper analysis (400 credits)
146
148
  nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
147
149
  nansen trade execute --quote <quoteId>
148
150
  nansen wallet <subcommand> [options]
@@ -154,13 +156,13 @@ nansen cache stats # what the local caches hold (no API key n
154
156
 
155
157
  **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`
156
158
 
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.
159
+ 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.
158
160
 
159
161
  **Direct research subcommands:**
160
- - `nansen research chain-rank [--timeframe-days 7|30|365] [--chain-type all|evm]` — rank chains by growth metrics
162
+ - `nansen research chain-rank [--days 7|30|365] [--chain-type all|evm]` — rank chains by growth metrics
161
163
  - `nansen research token-sectors` — list token sectors available for filtering
162
164
  - `nansen research address-premium-labels --address <addr> [--chain <chain>] [--page <n>] [--limit <n>]` — get all labels for an address, including premium labels
163
- - `nansen research smart-money-pnl-leaderboard [--chains c1,c2] [--timeframe-days 1|7|30|90|180] [--filters '<json>'] [--sort <field[:asc|desc]>] [--page <n>] [--limit <n>]` — rank smart money wallets by PnL
165
+ - `nansen research smart-money-pnl-leaderboard [--chains c1,c2] [--days 1|7|30|90|180] [--filters '<json>'] [--sort <field[:asc|desc]>] [--page <n>] [--limit <n>]` — rank smart money wallets by PnL
164
166
  - `nansen research position-intelligence --symbol <symbol>` — aggregate Hyperliquid positions by trader cohort
165
167
  - `nansen research perp-pnl-summary --address <addr> --from-date <date> --to-date <date>` — summarize realized Hyperliquid PnL for an address
166
168
  - `nansen research transaction-with-token-transfer-lookup --transaction-hash <hash> [--chain <chain>] [--block-timestamp "YYYY-MM-DD HH:MM:SS"]` — look up a transaction and its token/NFT transfers
@@ -171,6 +173,16 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
171
173
 
172
174
  **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send`, `forget-password`, `secure` — local or Privy server-side wallets (EVM + Solana).
173
175
 
176
+ **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:
177
+
178
+ ```bash
179
+ nansen alerts create --name 'ETH SM inflow' --type sm-token-flows --chains ethereum --inflow-1h-min 1000000 \
180
+ --webhook https://example.com/hook --webhook-secret-stdin < webhook-secret.txt
181
+ NANSEN_WEBHOOK_SECRET="$(cat webhook-secret.txt)" nansen alerts update <id> --webhook https://example.com/hook
182
+ ```
183
+
184
+ `--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`.
185
+
174
186
  Run `nansen schema --pretty` for the full subcommand and field reference.
175
187
 
176
188
  ## MCP
@@ -265,23 +277,29 @@ nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
265
277
 
266
278
  ### Before broadcasting
267
279
 
268
- `trade execute` and `bridge execute` move funds irreversibly, so both accept:
280
+ `trade execute`, `bridge execute`, and the signing limit-order operations (`limit-order create` and `limit-order cancel`) accept:
269
281
 
270
282
  ```bash
271
283
  nansen trade execute --quote <quoteId> --dry-run # validate + print the plan, broadcast nothing
272
284
  nansen trade execute --quote <quoteId> --yes # skip the confirmation prompt (also: -y)
285
+ nansen trade limit-order create ... --dry-run # preview intent; no API request or signature
286
+ nansen trade limit-order cancel --order <id> --dry-run # does not request/consume a cancellation tx
273
287
  ```
274
288
 
275
289
  `--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.
276
290
 
277
291
  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.
278
292
 
279
- 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.
293
+ 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.
294
+
295
+ 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.
296
+
297
+ To make an agent stop for your go-ahead, set `NANSEN_REQUIRE_CONFIRM=1` in its environment. Then, when stdin is not a terminal, every guarded command (`trade execute`, `bridge execute`, `trade limit-order create`/`cancel`, `perp order`/`close`/`cancel`/`leverage`) run without `--yes` or `NANSEN_YES=1` fails with exit code 1 and code `CONFIRMATION_REQUIRED` before it makes any request or signs anything. `--dry-run` still previews. Unset (the default), behaviour is unchanged.
280
298
 
281
299
  | Exit code | Meaning |
282
300
  |-----------|---------|
283
301
  | `0` | Broadcast succeeded, or the dry run completed |
284
- | `1` | Declined at the confirmation prompt, or the execution failed |
302
+ | `1` | Declined at the confirmation prompt, refused by `NANSEN_REQUIRE_CONFIRM`, or the execution failed |
285
303
 
286
304
  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>`.
287
305
 
@@ -305,26 +323,28 @@ nansen trade limit-order update --order <orderId> --trigger-price 85
305
323
 
306
324
  `--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.
307
325
 
326
+ 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.
327
+
308
328
  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.
309
329
 
310
330
  ## Perpetuals
311
331
 
312
- Hyperliquid perpetual trading via `nansen perp`. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading (requires an EVM wallet). Select the asset with `--coin` (`--symbol` is accepted as an alias).
332
+ Hyperliquid perpetual trading via `nansen perp`. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading (requires an EVM wallet). Select the asset with `--symbol` (`--coin` is accepted as an alias).
313
333
 
314
334
  ```bash
315
335
  nansen perp meta --filter ETH # list assets + max leverage
316
- nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --type limit
317
- nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type market \
336
+ nansen perp order --symbol ETH --side buy --size 0.1 --price 1600 --type limit
337
+ nansen perp order --symbol BTC --side sell --size 0.001 --price 95000 --type market \
318
338
  --take-profit 90000 --stop-loss 98000
319
- nansen perp close --coin ETH --size 0.1 --price 1600 --side sell # sell closes a long
320
- nansen perp cancel --coin ETH --oid <orderId>
321
- nansen perp leverage --coin ETH --leverage 5 --margin-type cross # or isolated
339
+ nansen perp close --symbol ETH --size 0.1 --price 1600 --side sell # sell closes a long
340
+ nansen perp cancel --symbol ETH --oid <orderId>
341
+ nansen perp leverage --symbol ETH --leverage 5 --margin-type cross # or isolated
322
342
  nansen perp transfer --direction spot-to-perp --amount 25 # Spot<->Perps (or perp-to-spot)
323
343
  nansen perp positions
324
344
  nansen perp account # value, unrealized PnL, margin, spot USDC
325
345
  ```
326
346
 
327
- `--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.
347
+ `--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.
328
348
 
329
349
  ## Bridge
330
350
 
@@ -348,11 +368,18 @@ nansen wallet create --name my-wallet --provider privy # server-side via Privy
348
368
  nansen wallet list
349
369
  nansen wallet default <name>
350
370
  nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
351
- nansen wallet secure # move a saved password into the OS keychain
371
+ nansen wallet send --to <addr> --amount 25 --chain base --token USDC # USDC, USDT or a token address
372
+ nansen wallet secure # move a password from .credentials or the env var into the OS keychain
352
373
  nansen wallet forget-password # drop the saved password from every store
353
374
  ```
354
375
 
355
- **Local wallets** are password-encrypted. Set `NANSEN_WALLET_PASSWORD` to skip the prompt.
376
+ **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.
377
+
378
+ ```bash
379
+ NANSEN_WALLET_PASSWORD='<password-from-user>' nansen wallet create --name my-wallet
380
+ ```
381
+
382
+ `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`.
356
383
 
357
384
  **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).
358
385
 
@@ -446,7 +473,7 @@ that cannot change the command line.
446
473
 
447
474
  With `--cache` on, every read the CLI makes through the Nansen API client is
448
475
  cached — all of `nansen research ...`, plus `alerts list` and `alerts get`.
449
- Never cached: `account`, `web search`, `web fetch`, the `alerts`
476
+ Never cached: `account`, `web search`, the `alerts`
450
477
  create/update/toggle/delete commands, `agent`, every `trade`, `bridge`, `wallet`
451
478
  and `mcp` command, and `perp` trading. The analytics commands `perp screener`
452
479
  and `perp leaderboard` are cached.
@@ -583,6 +610,8 @@ Every failure exits 1. The full list of codes is in [docs/error-codes.md](docs/e
583
610
 
584
611
  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
612
 
613
+ `nansen research profiler trace` fails with the original API error if the root lookup fails, rather than reporting an empty graph as a success. Once the root lookup succeeds, later lookups remain best-effort: a failed branch is skipped while traversal continues through the others.
614
+
586
615
  **Error metadata.** When the API reports them, `details` carries:
587
616
 
588
617
  | Field | Meaning |
@@ -603,7 +632,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
603
632
  | 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
633
  | Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
605
634
  | Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
606
- | `perp` _trading_ prints the usage banner | Trading needs `--coin BTC` (`--symbol` also works); see the Perpetuals section. |
635
+ | `perp` _trading_ prints the usage banner | Trading needs `--symbol BTC` (`--coin` also works); see the Perpetuals section. |
607
636
  | `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |
608
637
  | Huge JSON response | Use `--fields` to select columns. |
609
638
 
@@ -38,6 +38,7 @@ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could
38
38
  | --- | --- | --- |
39
39
  | `INVALID_PARAMS` | An option or request field has an invalid value, or the command does not accept it. `details.errors[]` names each field. | No |
40
40
  | `MISSING_PARAM` | A required option or request field is missing. `details.errors[]` names each field. | No |
41
+ | `NOT_A_PIPE` | An option that reads a secret from stdin (`--api-key-stdin`, `--webhook-secret-stdin`) was used with a terminal on stdin. Pipe the value or redirect a file. | No |
41
42
  | `MISSING_ARGS` | A trade or wallet command is missing required arguments; the message shows the usage. | No |
42
43
  | `INVALID_INPUT` | A trade, bridge, perp or wallet argument failed local validation. | No |
43
44
  | `INVALID_ADDRESS` | An address does not match the format of the selected chain. | No |
@@ -184,6 +185,7 @@ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could
184
185
  | `RPC_JSON_ERROR` | The RPC answered with a body that is not JSON. | No |
185
186
  | `RPC_NETWORK_ERROR` | The CLI could not reach the RPC. | Yes |
186
187
  | `CONFIRMATION_DECLINED` | The confirmation prompt was declined; nothing was signed. | No |
188
+ | `CONFIRMATION_REQUIRED` | NANSEN_REQUIRE_CONFIRM is set and stdin is not a terminal; nothing was signed. Pass --yes to proceed or --dry-run to preview. | No |
187
189
  | `CONFIRMATION_UNAVAILABLE` | Confirmation is required but no terminal is available. Pass --yes to confirm. | No |
188
190
 
189
191
  ### Bridge
@@ -208,6 +210,7 @@ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could
208
210
  | `BUILDER_FEE_TOO_HIGH` | The builder fee is above the allowed ceiling. | No |
209
211
  | `BUILDER_FEE_UNAVAILABLE` | The builder fee could not be read or approved. | No |
210
212
  | `META_UNAVAILABLE` | Hyperliquid asset metadata is not available. | Yes |
213
+ | `NO_OPEN_POSITION` | perp close --dry-run found no open position in that coin, so a real close would be rejected. The positions data can lag a fill that just happened, so retry after a few seconds if the position was opened moments ago. | Yes |
211
214
  | `SANCTIONED` | The address failed sanctions screening. | No |
212
215
  | `SCREENING_UNAVAILABLE` | Sanctions screening is not available, so the action was refused. | Yes |
213
216
  | `UNSUPPORTED_NETWORK` | The network is not supported for this perp action. | No |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nansen-cli",
3
- "version": "2.4.0",
3
+ "version": "2.6.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",
@@ -4,7 +4,7 @@
4
4
  * Post-install onboarding for nansen-cli.
5
5
  *
6
6
  * Runs after `npm install -g nansen-cli` and offers two optional steps:
7
- * 1. Install the Nansen AI coding skill (`npx skills add nansen-ai/nansen-cli`)
7
+ * 1. Install the Nansen AI coding skills (prints `npx -y skills add nansen-ai/nansen-cli --skill "*" -y`)
8
8
  * 2. Check account status to verify the effective credential (0 credits)
9
9
  *
10
10
  * Non-interactive environments (CI, piped stdin) get a one-liner tip instead.
@@ -13,7 +13,7 @@
13
13
 
14
14
  import { createInterface } from "readline";
15
15
  import { execFileSync, spawn } from "child_process";
16
- import { existsSync, realpathSync } from "fs";
16
+ import { existsSync, readdirSync, realpathSync } from "fs";
17
17
  import { join, dirname } from "path";
18
18
  import { fileURLToPath } from "url";
19
19
 
@@ -27,6 +27,10 @@ const CYAN = "\x1b[36m";
27
27
  const RESET = "\x1b[0m";
28
28
 
29
29
  const SKILL_REPO = "nansen-ai/nansen-cli";
30
+ // Non-interactive: the first -y skips npx's own install prompt, --skill "*" -y
31
+ // skips the skills picker. Agents cannot drive the picker. Double quotes, not
32
+ // single: Windows cmd.exe keeps single quotes and would pass a literal '*'.
33
+ const SKILL_INSTALL_CMD = `npx -y skills add ${SKILL_REPO} --skill "*" -y`;
30
34
  const TEST_QUERY = ["account"];
31
35
  const TEST_QUERY_DISPLAY = "nansen account";
32
36
 
@@ -60,13 +64,31 @@ function hasNpx() {
60
64
  }
61
65
  }
62
66
 
67
+ // `skills add nansen-ai/nansen-cli` writes one directory per skill, named after
68
+ // the skill, into ~/.agents/skills and links it into each agent's skills
69
+ // directory (~/.claude/skills for Claude Code). Match the skill names shipped in
70
+ // this package rather than a `nansen-` prefix, which unrelated skills also use.
71
+ // The legacy names cover installs from before the skills were split.
72
+ const PACKAGED_SKILLS_DIR = join(__dirname, "..", "skills");
73
+ const LEGACY_SKILL_NAMES = ["nansen-cli", "nansen-ai--nansen-cli"];
74
+
75
+ function packagedSkillNames() {
76
+ try {
77
+ return readdirSync(PACKAGED_SKILLS_DIR, { withFileTypes: true })
78
+ .filter((entry) => entry.isDirectory())
79
+ .map((entry) => entry.name);
80
+ } catch {
81
+ return [];
82
+ }
83
+ }
84
+
63
85
  function isSkillInstalled() {
64
86
  const home = process.env.HOME || process.env.USERPROFILE || "";
65
- const locations = [
66
- join(home, ".claude", "skills", "nansen-cli"),
67
- join(home, ".claude", "skills", "nansen-ai--nansen-cli"),
68
- ];
69
- return locations.some((loc) => existsSync(loc));
87
+ const roots = [join(home, ".agents", "skills"), join(home, ".claude", "skills")];
88
+ const names = packagedSkillNames();
89
+ const installed = roots.some((root) => names.some((name) => existsSync(join(root, name, "SKILL.md"))));
90
+ const legacy = LEGACY_SKILL_NAMES.some((name) => existsSync(join(home, ".claude", "skills", name)));
91
+ return installed || legacy;
70
92
  }
71
93
 
72
94
  function prompt(question) {
@@ -97,7 +119,7 @@ async function installSkill() {
97
119
  }
98
120
 
99
121
  if (!hasNpx()) {
100
- log(`${DIM}Tip: Run 'npx skills add ${SKILL_REPO}' to install the Nansen AI coding skill.${RESET}`);
122
+ log(`${DIM}Tip: Run ${SKILL_INSTALL_CMD} to install the Nansen AI coding skills.${RESET}`);
101
123
  return;
102
124
  }
103
125
 
@@ -106,14 +128,15 @@ async function installSkill() {
106
128
  const answer = await prompt(` Install Nansen skill for your AI coding agent? [y/N] `);
107
129
 
108
130
  if (!/^y(es)?$/i.test(answer)) {
109
- log(`Skipped. You can install it later with: ${CYAN}npx skills add ${SKILL_REPO}${RESET}`);
131
+ log(`Skipped. You can install it later with: ${CYAN}${SKILL_INSTALL_CMD}${RESET}`);
110
132
  return;
111
133
  }
112
134
 
113
135
  log(`Installing Nansen skill...`);
136
+ log(`In the picker, space selects a skill and enter confirms.`);
114
137
  const ok = await runCommand(...npxInvocation(["-y", "skills", "add", SKILL_REPO]));
115
138
  if (!ok) {
116
- log(`${YELLOW}Skill installation failed. You can retry with: npx skills add ${SKILL_REPO}${RESET}`);
139
+ log(`${YELLOW}Skill installation failed. You can retry with: ${SKILL_INSTALL_CMD}${RESET}`);
117
140
  }
118
141
  }
119
142
 
@@ -170,7 +193,9 @@ export async function main() {
170
193
  if (!hasTTY()) {
171
194
  log(`${BOLD}Nansen CLI installed!${RESET}`);
172
195
  log();
173
- log(`Tip: Run '${CYAN}npx skills add ${SKILL_REPO}${RESET}' to install the Nansen AI coding skill.`);
196
+ if (!isSkillInstalled()) {
197
+ log(`Tip: Run ${CYAN}${SKILL_INSTALL_CMD}${RESET} to install the Nansen AI coding skills.`);
198
+ }
174
199
  log(`Tip: Run '${CYAN}nansen login${RESET}' for browser approval, or use NANSEN_API_KEY directly.`);
175
200
  log(`Tip: To trade, first create a wallet with '${CYAN}nansen wallet create${RESET}', then quote with '${CYAN}nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000${RESET}' and execute with '${CYAN}nansen trade execute --quote <id>${RESET}'.`);
176
201
  return;
@@ -37,10 +37,10 @@ Public agent fast/expert and direct API commands accept the selected nansen:api
37
37
  ```bash
38
38
  nansen agent "What are top smart money tokens on Solana today and why?"
39
39
  nansen agent "Analyse wallet 0x123... -- is this a smart trader?"
40
- nansen agent "..." --expert # deeper analysis, 750 credits
40
+ nansen agent "..." --expert # deeper analysis, 400 credits
41
41
  ```
42
42
 
43
- Cost: 200 credits (fast) / 750 credits (expert)
43
+ Cost: 100 credits (fast) / 400 credits (expert)
44
44
 
45
45
  ## Use direct CLI commands when
46
46
 
@@ -58,7 +58,7 @@ Cost: 5-50 credits per call
58
58
 
59
59
  ## Anti-patterns
60
60
 
61
- - Don't use `nansen agent` for simple data fetches -- 40x more expensive
61
+ - Don't use `nansen agent` for simple data fetches -- it costs more than a direct call and returns prose, not data
62
62
  - Don't use raw CLI for open-ended analysis -- returns data, not interpretation
63
63
  - Don't chain 3+ agent calls -- get raw data via CLI, call agent once for synthesis
64
64
 
@@ -85,11 +85,13 @@ If the user prefers localtunnel or can't install ngrok, proceed with localtunnel
85
85
 
86
86
  ### Step 1: Generate a webhook secret
87
87
 
88
+ Write the secret straight to a file that only the user can read, so it never appears in the terminal, the shell history or the transcript:
89
+
88
90
  ```bash
89
- node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
91
+ (umask 077 && node -e "process.stdout.write(require('crypto').randomBytes(32).toString('hex'))" > nansen-webhook-secret.txt)
90
92
  ```
91
93
 
92
- Store the output — you need it for both the server and the alert configuration. **Never log or echo the secret after this point.**
94
+ The server and the alert both read it from this file (`WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)"` for the server, `--webhook-secret-stdin < nansen-webhook-secret.txt` for `nansen alerts`). **Never log, echo or paste the secret.**
93
95
 
94
96
  ### Step 2: Write the webhook receiver script
95
97
 
@@ -257,7 +259,7 @@ server.listen(PORT, '127.0.0.1', () => {
257
259
  Start the server:
258
260
 
259
261
  ```bash
260
- WEBHOOK_SECRET='<secret>' node nansen-webhook-server.mjs
262
+ WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs
261
263
  ```
262
264
 
263
265
  Then start a public tunnel so Nansen's servers can reach it.
@@ -287,9 +289,9 @@ Prints a URL like `https://xxx.loca.lt`. The webhook URL is `https://xxx.loca.lt
287
289
  **Do NOT create or modify any alerts.** Instead, print a clear summary for the user explaining what was set up and what they need to do next.
288
290
 
289
291
  The summary MUST include:
290
- 1. Confirmation of what was created (the server script path and the generated secret)
291
- 2. The commands to start the server and tunnel (with the actual secret filled in)
292
- 3. The exact `nansen alerts create` or `nansen alerts update` command they should run, with the `--webhook` and `--webhook-secret` flags filled in with the tunnel URL and secret — but leave the alert-specific flags (`--name`, `--type`, `--chains`, etc.) as placeholders for the user to fill in
292
+ 1. Confirmation of what was created (the server script path and the secret file path; never the secret itself)
293
+ 2. The commands to start the server and tunnel (reading the secret from the file)
294
+ 3. The exact `nansen alerts create` or `nansen alerts update` command they should run, with `--webhook` filled in with the tunnel URL and `--webhook-secret-stdin < nansen-webhook-secret.txt` for the secret (do not put the secret on the command line with `--webhook-secret`; it lands in shell history and the process list) — but leave the alert-specific flags (`--name`, `--type`, `--chains`, etc.) as placeholders for the user to fill in
293
295
  4. A reminder that the server and tunnel must be running before the alert is created (Nansen validates the webhook endpoint on creation)
294
296
  5. A note that tunnel URLs are ephemeral and will change on restart
295
297
 
@@ -299,12 +301,13 @@ Example summary format:
299
301
  ## Webhook listener ready
300
302
 
301
303
  **Server script:** ./nansen-webhook-server.mjs
304
+ **Secret file:** ./nansen-webhook-secret.txt (readable only by you)
302
305
  **Port:** 9477
303
306
 
304
307
  ### To start receiving alerts:
305
308
 
306
309
  1. Start the server (keep this terminal open):
307
- WEBHOOK_SECRET='<actual-secret>' node nansen-webhook-server.mjs
310
+ WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs
308
311
 
309
312
  2. In a new terminal, start the tunnel:
310
313
  ngrok http 9477 # recommended
@@ -316,13 +319,13 @@ Example summary format:
316
319
  --type <sm-token-flows|common-token-transfer|smart-contract-call> \
317
320
  --chains <chains> \
318
321
  --webhook 'https://<your-tunnel-url>/webhook' \
319
- --webhook-secret '<actual-secret>' \
320
- [type-specific flags...]
322
+ --webhook-secret-stdin \
323
+ [type-specific flags...] < nansen-webhook-secret.txt
321
324
 
322
325
  Or add the webhook to an existing alert:
323
326
  nansen alerts update <alert-id> \
324
327
  --webhook 'https://<your-tunnel-url>/webhook' \
325
- --webhook-secret '<actual-secret>'
328
+ --webhook-secret-stdin < nansen-webhook-secret.txt
326
329
 
327
330
  Note: The tunnel URL changes each time you restart. Update the alert
328
331
  webhook URL if you restart the tunnel.
@@ -343,11 +346,11 @@ See `nansen alerts create --help` for full flag reference per alert type.
343
346
 
344
347
  | Symptom | Fix |
345
348
  |---|---|
346
- | "Invalid signature" on every request | Ensure the **exact same secret** is in `WEBHOOK_SECRET` and `--webhook-secret` |
349
+ | "Invalid signature" on every request | Ensure the server and the alert read the **same secret** (the same `nansen-webhook-secret.txt`). Re-run `nansen alerts update <id> --webhook '<url>/webhook' --webhook-secret-stdin < nansen-webhook-secret.txt` after changing it |
347
350
  | "Failed to send welcome message" on alert create | Start the server and tunnel **before** creating the alert |
348
351
  | No alerts arriving | Check `nansen alerts list --table` — is the alert enabled? Is the webhook URL correct (includes `/webhook`)? |
349
352
  | Tunnel URL expired / tunnel died | Restart the tunnel, get the new URL, then `nansen alerts update <id> --webhook '<new-url>/webhook'`. If this keeps happening, switch from localtunnel to ngrok. |
350
- | Port already in use | Set a different port: `PORT=9478 WEBHOOK_SECRET='...' node nansen-webhook-server.mjs` and update the tunnel accordingly |
353
+ | Port already in use | Set a different port: `PORT=9478 WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs` and update the tunnel accordingly |
351
354
 
352
355
  ## OpenClaw Integration
353
356
 
@@ -365,7 +368,7 @@ If the user is running OpenClaw locally on the same machine, the webhook server
365
368
  ### Start command (with OpenClaw forwarding)
366
369
 
367
370
  ```bash
368
- WEBHOOK_SECRET='<secret>' \
371
+ WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" \
369
372
  OPENCLAW_GATEWAY_URL='http://localhost:3000' \
370
373
  OPENCLAW_AUTH_TOKEN='<token>' \
371
374
  node nansen-webhook-server.mjs
@@ -100,11 +100,11 @@ Constraints (all enforced server-side — surface errors to the user as-is):
100
100
  nansen trade limit-order list # default
101
101
  nansen trade limit-order list --state active # only open
102
102
  nansen trade limit-order list --state past # filled or cancelled
103
- nansen trade limit-order list --mint <mintAddr> # filter by token
103
+ nansen trade limit-order list --token <mintAddr> # filter by token
104
104
  nansen trade limit-order list --limit 50 --offset 0 --dir desc
105
105
  ```
106
106
 
107
- Options: `--state active|past`, `--mint <addr>`, `--limit <n>` (default 20),
107
+ Options: `--state active|past`, `--token <addr>`, `--limit <n>` (default 20),
108
108
  `--offset <n>`, `--sort <field>`, `--dir asc|desc` (default `desc`),
109
109
  `--wallet <name>`.
110
110
 
@@ -117,6 +117,17 @@ nansen trade limit-order cancel --order <orderId>
117
117
  Cancelling submits a withdrawal transaction; surface the tx signature from the
118
118
  CLI output so the user can verify on Solscan.
119
119
 
120
+ ### Preview and confirm
121
+
122
+ `create` and `cancel` accept `--dry-run` (print the plan and exit 0; no API
123
+ request, no signature, nothing submitted) and `--yes`/`-y` (skip the
124
+ confirmation prompt, same as `NANSEN_YES=1`). The prompt only appears in an
125
+ interactive terminal; agents and CI run unprompted, unless the user set
126
+ `NANSEN_REQUIRE_CONFIRM=1`: then a non-terminal run without `--yes` fails with
127
+ `CONFIRMATION_REQUIRED` before any request, so show the `--dry-run` plan and
128
+ re-run with `--yes` only after the user approves. Use `--dry-run` to show the
129
+ user what will be created or cancelled before running it for real.
130
+
120
131
  ### Update
121
132
 
122
133
  ```bash
@@ -45,7 +45,8 @@ nansen alerts delete <id>
45
45
  | `--slack` | webhook URL | optional | | |
46
46
  | `--discord` | webhook URL | optional | | |
47
47
  | `--webhook` | endpoint URL | optional | optional | |
48
- | `--webhook-secret` | optional (webhook only) | optional | | |
48
+ | `--webhook-secret-stdin` | optional (webhook only) | optional | | |
49
+ | `--webhook-secret` | optional (webhook only; prefer `--webhook-secret-stdin`) | optional | | |
49
50
  | `--description` | optional | optional | | |
50
51
  | `--enabled` | | flag | flag | |
51
52
  | `--disabled` | flag | flag | flag | |
@@ -139,6 +140,7 @@ nansen alerts create \
139
140
  - Multiple channels can be combined: `--telegram 123 --slack https://... --webhook https://...`
140
141
  - `--webhook <url>` sends a POST request with the alert payload to any HTTP/HTTPS endpoint. Useful for server deployments, Zapier, n8n, or custom integrations. The endpoint must be publicly reachable and return a 2xx response.
141
142
  - Alert output redacts channel credentials (Slack/Discord/webhook URLs and webhook signing secrets), e.g. `https://hooks.slack.com/services/T000/****`. Webhook URLs grant post access to the channel, so keep them out of shared output; pass `--reveal` only when the full value is needed. Never pass a redacted value back to `--slack`/`--discord`/`--webhook`; the CLI rejects it.
143
+ - Webhook signing secret (minimum 16 characters): pipe it with `--webhook-secret-stdin < secret.txt` or set `NANSEN_WEBHOOK_SECRET` (read only when `--webhook` is given). `--webhook-secret <secret>` still works but puts the secret in shell history, the process list and agent transcripts, so do not use it from an agent. `--webhook-secret` and `--webhook-secret-stdin` cannot be combined; either one overrides `NANSEN_WEBHOOK_SECRET`.
142
144
  - `--data '<json>'` merges raw JSON on top of named flags (escape hatch for fields without named flags).
143
145
  - Alert endpoints retain their normal ownership, plan and quota checks for both selected credentials.
144
146
  - Use single quotes for names with `$` or special characters: `--name 'SM >$1M'`
@@ -34,7 +34,7 @@ All commands: `nansen research token <sub> [options]`
34
34
 
35
35
  ```bash
36
36
  nansen research token info --token <addr> --chain solana
37
- nansen research token ohlcv --token <addr> --chain solana --timeframe 1h
37
+ nansen research token ohlcv --token <addr> --chain solana --interval 1h
38
38
  ```
39
39
 
40
40
  Timeframes: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `1d`, `1w`, `1M`