nansen-cli 2.4.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,53 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.5.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#801](https://github.com/nansen-ai/nansen-cli/pull/801) [`c7446fb`](https://github.com/nansen-ai/nansen-cli/commit/c7446fb17e076d2cd2731b40efe3d58ffef7e280) Thanks [@kome12](https://github.com/kome12)! - `nansen alerts create` and `nansen alerts update` accept the webhook signing secret from `--webhook-secret-stdin` (pipe or redirected file) or the `NANSEN_WEBHOOK_SECRET` environment variable, so it no longer has to appear on the command line, in shell history or in the process list. `--webhook-secret` still works; it cannot be combined with `--webhook-secret-stdin`, and either flag overrides the environment variable, which is read only when `--webhook` is given. `--webhook-secret` with no value or an empty value is now rejected instead of being silently ignored.
8
+
9
+ - [#767](https://github.com/nansen-ai/nansen-cli/pull/767) [`f5d9331`](https://github.com/nansen-ai/nansen-cli/commit/f5d93318ddf539531ac1ae237d049f9d4238c1bc) Thanks [@Kewe63](https://github.com/Kewe63)! - Add non-consuming `--dry-run` previews and interactive confirmation guards to limit-order create and cancel, with `--yes`/`-y` and `NANSEN_YES=1` prompt bypasses.
10
+
11
+ - [#809](https://github.com/nansen-ai/nansen-cli/pull/809) [`a69dc08`](https://github.com/nansen-ai/nansen-cli/commit/a69dc086dd070580318ff3b07634c42508c8208f) Thanks [@kome12](https://github.com/kome12)! - `perp order`, `perp close`, `perp cancel` and `perp leverage` now accept `--dry-run`, which runs the normal validation, prints the plan (coin, side, rounded size, price and type, estimated notional, leverage, builder fee) and exits 0 without signing or submitting anything. No wallet password is needed for a dry run, and the one-time builder-fee approval is not submitted.
12
+
13
+ These four commands now ask for confirmation before signing when stdin is an interactive terminal, the same way `trade execute` and `bridge execute` do. Answering anything but `y` exits 1 with nothing signed. `--yes`, `-y` or `NANSEN_YES=1` skips the question. **Scripts and agents whose stdin is not a terminal (pipes, CI, agent shells) see no change:** the commands submit without asking, as before, and `--yes` is a no-op there. A script that runs these commands from an interactive terminal, or an agent that runs them under a pseudo-terminal, will now be asked; add `--yes` or set `NANSEN_YES=1` to keep the old behaviour.
14
+
15
+ ### Patch Changes
16
+
17
+ - [#811](https://github.com/nansen-ai/nansen-cli/pull/811) [`c1a9e39`](https://github.com/nansen-ai/nansen-cli/commit/c1a9e39892183227d1e9b66891fe6b4aee2a46c9) Thanks [@Ravan002](https://github.com/Ravan002)! - An API error response whose body is the JSON value `null` is now reported as a normal API error for its status (and retried when the status is retryable) instead of crashing with `Cannot read properties of null (reading 'message')`.
18
+
19
+ - [#817](https://github.com/nansen-ai/nansen-cli/pull/817) [`a732073`](https://github.com/nansen-ai/nansen-cli/commit/a7320733580b2fa860feb5e17db0c5ae19948b59) Thanks [@0xcfloki](https://github.com/0xcfloki)! - ENS names now still resolve when the ensideas API is unavailable. The on-chain fallback was pinned to `eth.llamarpc.com`, which answers HTTP 525, so any ensideas outage failed every `.eth` lookup. It now uses the same Ethereum RPC as the rest of the CLI (`NANSEN_EVM_RPC`, or the shared default), and keeps the port and query string of a custom RPC URL.
20
+
21
+ - [#807](https://github.com/nansen-ai/nansen-cli/pull/807) [`a38b217`](https://github.com/nansen-ai/nansen-cli/commit/a38b217e11c4c0adcfc1e3dc42440223a459d43f) Thanks [@Snan0M](https://github.com/Snan0M)! - A `--paginate` result that mixes cached and live pages is no longer reported as a cache hit. The merged result kept page 1's `_meta.fromCache`/`cacheAge`, and telemetry's `from_cache` followed page 1's marker or the last page's cache state; both now say cached only when every page came from the cache.
22
+
23
+ - [#814](https://github.com/nansen-ai/nansen-cli/pull/814) [`05fd62a`](https://github.com/nansen-ai/nansen-cli/commit/05fd62ad6e2e42527ee7e8d365286d58570f1470) Thanks [@kome12](https://github.com/kome12)! - `nansen perp close --dry-run` now exits 1 with `NO_OPEN_POSITION` when the wallet has no open position in that coin, instead of printing a plan and exiting 0 for a close Hyperliquid would reject. The error is retryable, because the positions data can lag a fill that just happened. A real close still goes to Hyperliquid; when it prompts, its plan shows a warning instead. If positions cannot be loaded, or the data for that coin is malformed, the dry run still prints the plan with "Open position: could not be loaded".
24
+
25
+ - [#797](https://github.com/nansen-ai/nansen-cli/pull/797) [`585ac67`](https://github.com/nansen-ai/nansen-cli/commit/585ac674b7cb46d1d5d851eb7afb499c0abdf47c) Thanks [@kome12](https://github.com/kome12)! - `perp positions` now shows each position's leverage and margin mode (`lev=1x cross`) next to the liquidation price, so a liquidation price on a low-leverage cross-margin position has context.
26
+
27
+ - [#789](https://github.com/nansen-ai/nansen-cli/pull/789) [`5edcb66`](https://github.com/nansen-ai/nansen-cli/commit/5edcb662e7e0496d5f752f0a831feb3d0dbfc646) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Show API warning headers on stderr and preserve them on cached responses.
28
+
29
+ - [#804](https://github.com/nansen-ai/nansen-cli/pull/804) [`ca8b77d`](https://github.com/nansen-ai/nansen-cli/commit/ca8b77dd10d437ac0b81cbb6583983d72500e86e) Thanks [@Ravan002](https://github.com/Ravan002)! - `wallet create` now rejects the names `config` (any case), `wc` and `walletconnect`. A wallet named `config` was saved as `wallets/config.json` and then overwritten by the wallet settings, losing its keys; `wc` and `walletconnect` are read as WalletConnect by `wallet send` and limit orders.
30
+
31
+ - [#803](https://github.com/nansen-ai/nansen-cli/pull/803) [`622b684`](https://github.com/nansen-ai/nansen-cli/commit/622b6846ac0a9a6cb47834a81af0d1ce0338ddb4) Thanks [@kome12](https://github.com/kome12)! - Response cache (`--cache`) no longer grows without bound. After a cached write, entries older than 24 hours (or the longest `--cache-ttl` that run reads with, if longer) and temp files left by an interrupted write are removed, at most once an hour per run. `nansen cache clear` also removes those leftover temp files, but never one younger than 10 minutes, which may be a write in progress.
32
+
33
+ - [#802](https://github.com/nansen-ai/nansen-cli/pull/802) [`28483ea`](https://github.com/nansen-ai/nansen-cli/commit/28483ea8f5bc0d98628ec552d6e5cf99a3023ae6) Thanks [@kome12](https://github.com/kome12)! - `nansen schema` no longer lists `research points leaderboard`, whose endpoint was removed, and now lists `--stream` (NDJSON output, alias `-s`) under global options. The points command is also left out of `nansen research` help and "did you mean" suggestions. Calling it, including with `--help`, still returns `COMMAND_UNAVAILABLE`.
34
+
35
+ - [#813](https://github.com/nansen-ai/nansen-cli/pull/813) [`58ee954`](https://github.com/nansen-ai/nansen-cli/commit/58ee954c59fdaaef61554e5feef489e3e72b83d0) Thanks [@0xcfloki](https://github.com/0xcfloki)! - `wallet send` on Solana no longer tells you to top up your wallet when a SOL send fails because the recipient would hold less than the rent-exempt minimum. Solana rejects a transfer that leaves a new address below about 0.00089 SOL, naming that account by its index; any account other than your wallet now gets an error that says so and gives the minimum, instead of the insufficient-balance advice meant for the wallet itself.
36
+
37
+ - [#812](https://github.com/nansen-ai/nansen-cli/pull/812) [`e2331f7`](https://github.com/nansen-ai/nansen-cli/commit/e2331f763f02c710fbd30ee41fbc585a44457ba5) Thanks [@Ravan002](https://github.com/Ravan002)! - `--sort` now rejects extra colon segments (`--sort value_usd:desc:asc`) instead of silently dropping them, and `--order-by` rejects anything that is not a JSON array of `{ "field", "direction" }` objects instead of sending it to the API unchecked.
38
+
39
+ - [#805](https://github.com/nansen-ai/nansen-cli/pull/805) [`11558d5`](https://github.com/nansen-ai/nansen-cli/commit/11558d57ff4a52da3ef6a1856d3119a0df5dafe1) Thanks [@Ravan002](https://github.com/Ravan002)! - Telemetry events no longer include positional values in the command path. `nansen search vitalik.eth` was reported as `/search/vitalik.eth` and `nansen 0x…` as `/0x…`; only command and subcommand names the CLI defines are sent now, and an unknown command is reported as `unknown`.
40
+
41
+ - [#808](https://github.com/nansen-ai/nansen-cli/pull/808) [`5bb3e75`](https://github.com/nansen-ai/nansen-cli/commit/5bb3e7546d974bd311825760dcd7270e1fb41895) Thanks [@kome12](https://github.com/kome12)! - Telemetry events now list only option names the CLI defines for the command being run (plus global options and built-in switches such as `--help`). Any other name is sent as `--<unknown>`. Previously a value that starts with `-` and is passed as a separate argument, as in `--webhook-secret -abc123`, was parsed as a flag and its text was sent as a flag name.
42
+
43
+ - [#810](https://github.com/nansen-ai/nansen-cli/pull/810) [`8703d39`](https://github.com/nansen-ai/nansen-cli/commit/8703d39aa489c0927b565b079a1cc9dfc0cce7de) Thanks [@kome12](https://github.com/kome12)! - `trade execute`: when the standard execution route rejects a swap before broadcasting it (quote expired, simulation failed, minimum return not reached, insufficient balance, input transfer failed), the CLI now releases the quote and tries the next candidate quote instead of aborting and marking the quote spent. Every other error response still stops the run.
44
+
45
+ - [#818](https://github.com/nansen-ai/nansen-cli/pull/818) [`3f5f059`](https://github.com/nansen-ai/nansen-cli/commit/3f5f059e4e6366ac6f9ea6a527ece3272bef9213) Thanks [@erkancamli](https://github.com/erkancamli)! - `wallet send` on EVM keeps the leading zero bytes of the recipient (or token contract) address in the signed transaction. They were stripped, so a send to an address such as `0x00000000219ab540356cBB839Cbe05303d7705Fa`, or of a token such as TrueUSD (`0x0000000000085d4780B73119b644AE5ecd22b376`), was rejected by the node, and a send to the zero address was signed as a contract creation.
46
+
47
+ - [#798](https://github.com/nansen-ai/nansen-cli/pull/798) [`9457798`](https://github.com/nansen-ai/nansen-cli/commit/9457798f1c69d7cc8e9753c07a8eed0bcd379e17) Thanks [@kome12](https://github.com/kome12)! - `wallet send --token` now accepts `USDC` and `USDT` on every chain it supports (`evm`/`ethereum`, `base`, `solana`) instead of failing with "Invalid params", and rejects any other non-address value with the accepted symbols. `wallet create --help`, `wallet send --help` and `nansen schema` now list every option (`--name`, `--provider`, `--human`, `--token`, `--wallet`, `--dry-run`) and explain that `wallet create` reads the password from `NANSEN_WALLET_PASSWORD` (it prompts only with `--human`) and saves it to the OS keychain or the `.credentials` fallback.
48
+
49
+ - [#806](https://github.com/nansen-ai/nansen-cli/pull/806) [`3f61a36`](https://github.com/nansen-ai/nansen-cli/commit/3f61a36e151f2f12dcdca7828819e63c260f2540) Thanks [@Ravan002](https://github.com/Ravan002)! - WalletConnect x402 payments now bound the authorization's `validBefore`. A `maxTimeoutSeconds` sent as a string (`"60"`) was concatenated onto the current time, giving a `validBefore` thousands of years out, and a large number was used as is; the timeout is now read as a whole number of seconds and capped at one hour, the window the local signer uses.
50
+
3
51
  ## 2.4.0
4
52
 
5
53
  ### Minor Changes
package/README.md CHANGED
@@ -141,8 +141,8 @@ The check calls `tools/list` for reachability, then calls the paid `nansen_score
141
141
 
142
142
  ```
143
143
  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)
144
+ nansen agent "<question>" # AI research agent (100 credits)
145
+ nansen agent "<question>" --expert # deeper analysis (400 credits)
146
146
  nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
147
147
  nansen trade execute --quote <quoteId>
148
148
  nansen wallet <subcommand> [options]
@@ -154,7 +154,7 @@ nansen cache stats # what the local caches hold (no API key n
154
154
 
155
155
  **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`
156
156
 
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.
157
+ The points leaderboard API has been removed. `nansen research points leaderboard` and the legacy command `nansen points leaderboard` return `success: false` with code `COMMAND_UNAVAILABLE` and exit status `1`, without making an API request (with `--help` too). The command is no longer listed in `nansen schema`, help or completions.
158
158
 
159
159
  **Direct research subcommands:**
160
160
  - `nansen research chain-rank [--timeframe-days 7|30|365] [--chain-type all|evm]` — rank chains by growth metrics
@@ -171,6 +171,16 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
171
171
 
172
172
  **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send`, `forget-password`, `secure` — local or Privy server-side wallets (EVM + Solana).
173
173
 
174
+ **Alerts:** `list`, `create`, `update`, `toggle`, `delete` — smart alerts delivered to Telegram, Slack, Discord or a webhook. Give a webhook's signing secret through stdin or the environment, not on the command line, so it stays out of shell history and the process list:
175
+
176
+ ```bash
177
+ nansen alerts create --name 'ETH SM inflow' --type sm-token-flows --chains ethereum --inflow-1h-min 1000000 \
178
+ --webhook https://example.com/hook --webhook-secret-stdin < webhook-secret.txt
179
+ NANSEN_WEBHOOK_SECRET="$(cat webhook-secret.txt)" nansen alerts update <id> --webhook https://example.com/hook
180
+ ```
181
+
182
+ `--webhook-secret <secret>` still works. It cannot be combined with `--webhook-secret-stdin`, and either flag overrides `NANSEN_WEBHOOK_SECRET`, which is read only when `--webhook` is given. Alerts output redacts channel credentials unless you pass `--reveal`.
183
+
174
184
  Run `nansen schema --pretty` for the full subcommand and field reference.
175
185
 
176
186
  ## MCP
@@ -265,18 +275,22 @@ nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
265
275
 
266
276
  ### Before broadcasting
267
277
 
268
- `trade execute` and `bridge execute` move funds irreversibly, so both accept:
278
+ `trade execute`, `bridge execute`, and the signing limit-order operations (`limit-order create` and `limit-order cancel`) accept:
269
279
 
270
280
  ```bash
271
281
  nansen trade execute --quote <quoteId> --dry-run # validate + print the plan, broadcast nothing
272
282
  nansen trade execute --quote <quoteId> --yes # skip the confirmation prompt (also: -y)
283
+ nansen trade limit-order create ... --dry-run # preview intent; no API request or signature
284
+ nansen trade limit-order cancel --order <id> --dry-run # does not request/consume a cancellation tx
273
285
  ```
274
286
 
275
287
  `--dry-run` runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints what *would* be sent (chain, tokens, amounts, recipient, approvals, fees); and stops before wallet credentials, signing, or broadcast — no wallet password needed, the quote stays usable, exit code 0. Real execution still resolves and revalidates the live signer before signing.
276
288
 
277
289
  On EVM, both commands refuse a transaction whose worst-case gas cost (fee cap × gas limit) is above 1 ETH, before anything is signed, approvals included. That is a backstop against an anomalous quote, the same kind of cap geth and reth apply to `eth_sendTransaction`. `--max-tx-fee <eth>` changes it, and `--max-tx-fee 0` turns it off. WalletConnect transactions are not checked, since the wallet shows the fee before signing.
278
290
 
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.
291
+ For limit orders, `--dry-run` is a non-consuming intent preview built from locally validated arguments and the wallet's public address. It returns before limit-order authentication, custom-token metadata RPC lookups, transaction crafting, transaction signing, or final submission. Create preview does not submit an order; cancel preview does not request or consume the API's one-time cancellation transaction. Real execution performs the existing transaction and outcome validation after acknowledgement.
292
+
293
+ When stdin is an interactive terminal, each guarded command prints its plan and asks for confirmation first (`Broadcast this transaction?`, `Create this limit order?`, or `Cancel this limit order?`); anything but `y`/`yes` aborts with exit code 1 and nothing signed. `--yes`, `-y`, or `NANSEN_YES=1` skips only the question. **When stdin is not a terminal — agents, CI, pipes — nothing changes: the command proceeds without prompting**, and `--yes` is accepted as a no-op so it is always safe to pass.
280
294
 
281
295
  | Exit code | Meaning |
282
296
  |-----------|---------|
@@ -305,6 +319,8 @@ nansen trade limit-order update --order <orderId> --trigger-price 85
305
319
 
306
320
  `--amount` is in token units (`1.5` = 1.5 SOL). `--slippage-bps` is basis points (`300` = 3%, `100` = 1%); omit for auto. Minimum order value ~$10 (server-enforced). Local, Privy, and WalletConnect wallets all work.
307
321
 
322
+ Add `--dry-run` to `create` or `cancel` for a no-API, no-signature intent preview. In an interactive terminal these two commands otherwise ask for confirmation; pass `--yes`/`-y` (or set `NANSEN_YES=1`) to skip the prompt. Non-TTY automation remains unprompted.
323
+
308
324
  For EVM chains, there's no native limit-order surface — pair an external venue's resting order with a `common-token-transfer` smart alert on the settlement wallet as a best-effort fill signal. See the `nansen-limit-orders` skill for details.
309
325
 
310
326
  ## Perpetuals
@@ -324,7 +340,7 @@ nansen perp positions
324
340
  nansen perp account # value, unrealized PnL, margin, spot USDC
325
341
  ```
326
342
 
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.
343
+ `--side` is `buy`/`long` or `sell`/`short` to open (`buy`/`sell` to close); `--tif` is `Gtc`/`Ioc`/`Alo`; `--slippage` is a decimal in `[0,1]`; `--leverage` is a whole integer capped at the asset max. Perp orders are irreversible once signed: add `--dry-run` to `order`, `close`, `cancel` or `leverage` to print the plan without signing anything. In an interactive terminal these four commands ask for confirmation first (`--yes`/`-y` or `NANSEN_YES=1` skips it); off a terminal they submit without asking, as before. USDC sent to a wallet via Hyperliquid's **Send** lands in the **Spot** balance (shown as `Spot USDC`); move it to Perps with `perp transfer` before trading. `perp positions` prints each position's leverage and margin mode next to Hyperliquid's liquidation price (`lev=1x cross liq=1.37`). On cross margin the liquidation price depends on the whole account's equity, so even a 1x position can have one close to the market price; `liq=n/a` means the exchange reports no liquidation price. See the `nansen-trading` skill for details.
328
344
 
329
345
  ## Bridge
330
346
 
@@ -348,11 +364,18 @@ nansen wallet create --name my-wallet --provider privy # server-side via Privy
348
364
  nansen wallet list
349
365
  nansen wallet default <name>
350
366
  nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
351
- nansen wallet secure # move a saved password into the OS keychain
367
+ nansen wallet send --to <addr> --amount 25 --chain base --token USDC # USDC, USDT or a token address
368
+ nansen wallet secure # move a password from .credentials or the env var into the OS keychain
352
369
  nansen wallet forget-password # drop the saved password from every store
353
370
  ```
354
371
 
355
- **Local wallets** are password-encrypted. Set `NANSEN_WALLET_PASSWORD` to skip the prompt.
372
+ **Local wallets** are encrypted with a password of at least 12 characters. `wallet create` reads it from `NANSEN_WALLET_PASSWORD`, or reuses the password an earlier `wallet create` saved, and does not prompt; without one the command fails with `PASSWORD_REQUIRED` (agents: ask the user for a password, never make one up). When no password is set or saved, pass `--human` to be prompted for one in an interactive terminal. On success the CLI saves the password to the OS keychain, or to `~/.nansen/wallets/.credentials` (plaintext) when no keychain is available, and later wallet commands read it from there. If neither can be written, the wallet is still created but the password is not saved: keep `NANSEN_WALLET_PASSWORD` set for every later wallet command. `nansen wallet secure` moves a password from that file or the env var into the keychain.
373
+
374
+ ```bash
375
+ NANSEN_WALLET_PASSWORD='<password-from-user>' nansen wallet create --name my-wallet
376
+ ```
377
+
378
+ `wallet send --token` takes `USDC`, `USDT` or a token contract (EVM) or mint (Solana) address; omit it to send the native currency. `--chain` is `evm` (Ethereum), `ethereum`, `base` or `solana`.
356
379
 
357
380
  **Privy wallets** are server-side — no password, no local key storage. Requires `PRIVY_APP_ID` and `PRIVY_APP_SECRET` env vars. Get credentials at [dashboard.privy.io](https://dashboard.privy.io).
358
381
 
@@ -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 |
@@ -208,6 +209,7 @@ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could
208
209
  | `BUILDER_FEE_TOO_HIGH` | The builder fee is above the allowed ceiling. | No |
209
210
  | `BUILDER_FEE_UNAVAILABLE` | The builder fee could not be read or approved. | No |
210
211
  | `META_UNAVAILABLE` | Hyperliquid asset metadata is not available. | Yes |
212
+ | `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
213
  | `SANCTIONED` | The address failed sanctions screening. | No |
212
214
  | `SCREENING_UNAVAILABLE` | Sanctions screening is not available, so the action was refused. | Yes |
213
215
  | `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.5.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",
@@ -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
@@ -117,6 +117,14 @@ 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. Use `--dry-run` to show the
126
+ user what will be created or cancelled before running it for real.
127
+
120
128
  ### Update
121
129
 
122
130
  ```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'`
@@ -121,6 +121,8 @@ nansen trade limit-order update --order <order-id> --trigger-price 85
121
121
 
122
122
  `--slippage-bps` is basis points (`300` = 3%, `100` = 1%); omit for auto.
123
123
 
124
+ `create` and `cancel` take the same `--dry-run` and `--yes` as `trade execute`. `--dry-run` prints the order (or cancellation) plan from the arguments and the wallet's public address and exits 0, with no API request, signature or submission; a cancel preview does not request the one-time cancellation transaction. In an interactive terminal they ask before signing; agents and CI run unprompted, and `--yes` is a no-op there.
125
+
124
126
  ## Agent pattern
125
127
 
126
128
  ```bash
@@ -203,7 +205,7 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
203
205
  |-----|---------|
204
206
  | `NANSEN_WALLET_PASSWORD` | **Required for `trade execute`.** Wallet encryption password — persisted in `~/.nansen/.env`. Source before executing: `source ~/.nansen/.env && nansen trade execute ...` |
205
207
  | `NANSEN_API_KEY` | API key (also set via explicit `nansen login --human`; browser sessions are not wallet or RPC keys) |
206
- | `NANSEN_YES` | Set to `1` to skip the `execute` confirmation prompt, like `--yes` |
208
+ | `NANSEN_YES` | Set to `1` to skip the confirmation prompt of `trade execute`, `bridge execute`, `trade limit-order create`/`cancel` and `perp order`/`close`/`cancel`/`leverage`, like `--yes` |
207
209
 
208
210
  > **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.
209
211
 
@@ -222,6 +224,23 @@ Subcommands: `order`, `cancel`, `close`, `leverage`, `positions`, `orders`, `acc
222
224
 
223
225
  The asset is selected with `--coin` (e.g. `BTC`, `ETH`); `--symbol` is accepted as an alias. List tradable assets and their max leverage with `nansen perp meta` (use `--filter <text>` or `--all` to see beyond the first 20).
224
226
 
227
+ ## Preview and confirm (`--dry-run`, `--yes`)
228
+
229
+ `order`, `close`, `cancel` and `leverage` have no quote step, so a typo in `--size` or `--price` would otherwise go straight to the exchange. Preview first:
230
+
231
+ ```bash
232
+ nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --dry-run # preview only, nothing is signed
233
+ nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --yes # skip the confirmation prompt
234
+ ```
235
+
236
+ **`--dry-run`** runs the normal validation and read-only lookups (asset metadata, builder fee, open position, compliance screen), prints the plan (coin, side, rounded size, price and type, take-profit/stop-loss, estimated notional, leverage, builder fee) and exits 0. Nothing is signed or sent to Hyperliquid, no wallet password is needed, and the one-time builder-fee approval is not submitted. `close` also shows the worst fill price after slippage and the open position, `cancel` shows the open order it would cancel, and `leverage` shows the new setting next to the asset maximum.
237
+
238
+ **Exception: `close --dry-run` exits 1 with `NO_OPEN_POSITION` when the wallet has no open position in that coin.** That is a definite "nothing to close" answer, not a crash. If the position was opened moments ago, the positions data may not show it yet: retry after a few seconds. A real `close` skips this check and lets Hyperliquid decide; with a prompt, its plan shows a warning instead.
239
+
240
+ **Confirmation.** When stdin is an interactive terminal, these four commands print the plan and ask, for example, `Submit this order to Hyperliquid? [y/N]` before signing. Answering anything but `y`/`yes` exits 1 with nothing signed (code `CONFIRMATION_DECLINED`). Pass `--yes` (`-y`), or set `NANSEN_YES=1`, to skip the question.
241
+
242
+ **Agents and CI are unaffected:** when stdin is *not* a terminal the commands submit without prompting, exactly as before, and `--yes` is a no-op. These are the same rules as `trade execute` and `bridge execute`. `transfer` and `approve-builder-fee` are unchanged.
243
+
225
244
  ## Open a position
226
245
 
227
246
  ```bash
@@ -262,6 +281,8 @@ nansen perp account # account value, unrealized PnL, margin used, withdrawab
262
281
 
263
282
  `--leverage` must be a whole integer and is capped at the asset's maximum (see `perp meta`).
264
283
 
284
+ **Reading `perp positions`:** each line shows the leverage setting and margin mode before the liquidation price, e.g. `lev=1x cross liq=1.37`. The liquidation price is Hyperliquid's own figure. On cross margin it depends on the whole account's equity (fees, funding, losses on other cross positions), so a 1x position can still have a liquidation price near the market. `liq=n/a` means the exchange reports none.
285
+
265
286
  **Spot vs Perps:** perp trading draws from the **Perps** balance, but USDC sent to a wallet via Hyperliquid's **Send** lands in **Spot** (and shows as `Spot USDC` in `perp account`). Move it across with `perp transfer --direction spot-to-perp --amount <usdc>` before trading. (Deposits via the bridge land in Perps directly.)
266
287
 
267
288
  ## Source
@@ -90,7 +90,9 @@ After creation, the CLI automatically saves the password:
90
90
  - **OS keychain** (macOS Keychain, Linux secret-tool, Windows Credential Manager) — secure, preferred
91
91
  - **~/.nansen/wallets/.credentials file** — insecure fallback when no keychain is available (e.g. containers, CI)
92
92
 
93
- **All future wallet operations retrieve the password automatically** — no env var or human input needed.
93
+ **Once the password is saved, future wallet operations retrieve it automatically** — no env var or human input needed (unless it could not be saved; see below).
94
+
95
+ If neither store can be written, `wallet create` still succeeds but prints `CRITICAL: Password could not be saved anywhere`. The password is then not persisted: keep `NANSEN_WALLET_PASSWORD` set for every later wallet command, or the wallet cannot be decrypted.
94
96
 
95
97
  If the `.credentials` file fallback is used, the CLI prints a warning on every operation. To migrate to secure storage later, run `nansen wallet secure`.
96
98
 
@@ -106,7 +108,7 @@ If the `.credentials` file fallback is used, the CLI prints a warning on every o
106
108
  - **NEVER generate a password yourself** — always ask the human user
107
109
  - **NEVER store the password** in files, memory, logs, or conversation history
108
110
  - **NEVER use `--human` flag** — that enables interactive prompts which agents cannot handle
109
- - After wallet creation, you do NOT need the password for future operations — the keychain handles it
111
+ - After wallet creation, you do NOT need the password for future operations if it was saved (keychain or `.credentials`). If create printed `CRITICAL: Password could not be saved anywhere`, keep `NANSEN_WALLET_PASSWORD` set
110
112
  - If you get a `PASSWORD_REQUIRED` error, ask the user to provide their password again
111
113
 
112
114
  ## Create
@@ -144,6 +146,9 @@ nansen wallet default <name>
144
146
  # Send native token (SOL, ETH) — password auto-resolved from keychain
145
147
  nansen wallet send --to <addr> --amount 1.5 --chain solana
146
148
 
149
+ # Send a token: USDC, USDT, or the token's contract/mint address
150
+ nansen wallet send --to <addr> --amount 25 --chain base --token USDC
151
+
147
152
  # Send entire balance
148
153
  nansen wallet send --to <addr> --chain evm --max
149
154
 
@@ -192,7 +197,8 @@ For detailed migration steps (from `~/.nansen/.env`, `.credentials`, or env-var-
192
197
  |------|---------|
193
198
  | `--to` | Recipient address |
194
199
  | `--amount` | Amount to send |
195
- | `--chain` | `evm` or `solana` |
200
+ | `--chain` | `evm` (Ethereum), `ethereum`, `base` or `solana` |
201
+ | `--token` | Token to send: `USDC`, `USDT`, or a contract/mint address (native if omitted) |
196
202
  | `--max` | Send entire balance |
197
203
  | `--dry-run` | Preview without broadcasting |
198
204
  | `--provider` | Wallet provider: `local` (default, encrypted on disk) or `privy` (server-side via Privy API) |
@@ -205,7 +211,7 @@ For detailed migration steps (from `~/.nansen/.env`, `.credentials`, or env-var-
205
211
 
206
212
  | Var | Purpose |
207
213
  |-----|---------|
208
- | `NANSEN_WALLET_PASSWORD` | Wallet encryption password — only needed for initial `wallet create`. After that, the OS keychain handles it. |
214
+ | `NANSEN_WALLET_PASSWORD` | Wallet encryption password — only needed for initial `wallet create` when the password is saved (keychain or `.credentials`). If it could not be saved, keep it set for every wallet command. |
209
215
  | `NANSEN_API_KEY` | API key (can also be saved via `nansen login --human`) |
210
216
  | `PRIVY_APP_ID` | Privy application ID (required for `--provider privy`) |
211
217
  | `PRIVY_APP_SECRET` | Privy application secret (required for `--provider privy`) |