nansen-cli 2.5.0 → 2.6.1

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,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.6.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#834](https://github.com/nansen-ai/nansen-cli/pull/834) [`c2e511e`](https://github.com/nansen-ai/nansen-cli/commit/c2e511efbbfc32174083dc9b3f00eda8e0fef519) Thanks [@kome12](https://github.com/kome12)! - `nansen schema` and shell completion now list the type-specific filter options of `alerts create` and `alerts update` (flow thresholds, token, sector, market cap, FDV, event, value and subject filters), with the alert types each one applies to.
8
+
9
+ - [#841](https://github.com/nansen-ai/nansen-cli/pull/841) [`9888c7a`](https://github.com/nansen-ai/nansen-cli/commit/9888c7a3ed3a624fc465965104434d91aa9db221) Thanks [@kome12](https://github.com/kome12)! - `bridge execute` now refuses a Hyperliquid withdrawal quote that has more than one withdrawal leg, or whose withdrawal is not sent to Relay's deposit address, before signing anything.
10
+
11
+ - [#843](https://github.com/nansen-ai/nansen-cli/pull/843) [`16413a9`](https://github.com/nansen-ai/nansen-cli/commit/16413a9f6685d78997b41ec7020d80fd79ef7cf0) Thanks [@kome12](https://github.com/kome12)! - `trade execute` now refuses a native-token EVM swap whose transaction value does not match the quote's input amount (the same field the request check reads) or exceeds the maximum spend saved with the quote, even when swap-outcome verification is off.
12
+
13
+ - [#839](https://github.com/nansen-ai/nansen-cli/pull/839) [`f621b35`](https://github.com/nansen-ai/nansen-cli/commit/f621b35c67ab27194925d3e2bbec8f330d10e764) Thanks [@kome12](https://github.com/kome12)! - `nansen perp transfer` and `nansen perp approve-builder-fee` now honour `--dry-run` and `--yes` like the other perp commands that change state: `--dry-run` prints the plan and signs nothing, an interactive terminal asks before signing, and `NANSEN_REQUIRE_CONFIRM=1` applies off a terminal. Previously both signed and submitted even with `--dry-run`.
14
+
15
+ `perp transfer` also refuses an `--amount` it cannot sign exactly (more than 8 decimal places, or too large to hold exactly) instead of rounding it.
16
+
17
+ - [#842](https://github.com/nansen-ai/nansen-cli/pull/842) [`020c455`](https://github.com/nansen-ai/nansen-cli/commit/020c455a1a151bdefb04891d42d4aa2f703b627e) Thanks [@kome12](https://github.com/kome12)! - Pin the runtime dependencies (`@noble/curves`, `@noble/hashes`, `@scure/base`, `@ethereumjs/rlp`) to exact versions, so a global install no longer picks up a newly published release of a signing library before it has been reviewed.
18
+
19
+ - [#835](https://github.com/nansen-ai/nansen-cli/pull/835) [`197996b`](https://github.com/nansen-ai/nansen-cli/commit/197996b565823ca4e4239dc3dd2376ca510c3eff) Thanks [@kome12](https://github.com/kome12)! - `wallet send --dry-run` from a Privy wallet now rejects a malformed, zero or too-small SPL token amount on Solana, as the real send does, instead of previewing it as a success.
20
+
21
+ - [#837](https://github.com/nansen-ai/nansen-cli/pull/837) [`478eab1`](https://github.com/nansen-ai/nansen-cli/commit/478eab1d4630db3f6b28eccb07b10845864bba42) Thanks [@kome12](https://github.com/kome12)! - `nansen alerts create` and `update` no longer offer the `smart-contract-call` alert type, which the Nansen API retired and now rejects. Passing `--type smart-contract-call`, or one of the flags only that type used (`--signature-hash`, `--caller`, `--contract`, `--exclude-caller`, `--exclude-contract`), now fails with an `INVALID_PARAMS` error that says the type was retired, before any request is sent. An unknown `--type` value is rejected the same way, with the valid types listed. `nansen schema` now lists the valid `--type` values as an enum.
22
+
23
+ - [#838](https://github.com/nansen-ai/nansen-cli/pull/838) [`ead3a57`](https://github.com/nansen-ai/nansen-cli/commit/ead3a570d8c4c22f53471221f8dab90dddc96480) Thanks [@kome12](https://github.com/kome12)! - `wallet send` now refuses sends that would lose funds: a mixed-case EVM `--to` or `--token` address with an invalid EIP-55 checksum (all-lowercase and all-uppercase addresses still work), an ERC-20 sent to its own contract, and on Solana a recipient that is not a wallet (a token account, mint, program or other program-owned account). `--amount <number>` together with `--max` is now rejected with `INVALID_INPUT` instead of sending the whole balance.
24
+
25
+ ## 2.6.0
26
+
27
+ ### Minor Changes
28
+
29
+ - [#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`.
30
+
31
+ - [#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.
32
+
33
+ - [#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`.
34
+
35
+ - [#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.
36
+
37
+ 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).
38
+
39
+ - [#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.
40
+
41
+ - [#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.
42
+
43
+ ### Patch Changes
44
+
45
+ - [#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`.
46
+
47
+ - [#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.
48
+
49
+ - [#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.
50
+
51
+ - [#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.
52
+
53
+ - [#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.
54
+
3
55
  ## 2.5.0
4
56
 
5
57
  ### 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:
@@ -157,10 +159,10 @@ nansen cache stats # what the local caches hold (no API key n
157
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
@@ -292,10 +294,12 @@ For limit orders, `--dry-run` is a non-consuming intent preview built from local
292
294
 
293
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.
294
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`/`transfer`/`approve-builder-fee`) 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.
298
+
295
299
  | Exit code | Meaning |
296
300
  |-----------|---------|
297
301
  | `0` | Broadcast succeeded, or the dry run completed |
298
- | `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 |
299
303
 
300
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>`.
301
305
 
@@ -325,22 +329,22 @@ For EVM chains, there's no native limit-order surface — pair an external venue
325
329
 
326
330
  ## Perpetuals
327
331
 
328
- 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).
329
333
 
330
334
  ```bash
331
335
  nansen perp meta --filter ETH # list assets + max leverage
332
- nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --type limit
333
- 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 \
334
338
  --take-profit 90000 --stop-loss 98000
335
- nansen perp close --coin ETH --size 0.1 --price 1600 --side sell # sell closes a long
336
- nansen perp cancel --coin ETH --oid <orderId>
337
- 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
338
342
  nansen perp transfer --direction spot-to-perp --amount 25 # Spot<->Perps (or perp-to-spot)
339
343
  nansen perp positions
340
344
  nansen perp account # value, unrealized PnL, margin, spot USDC
341
345
  ```
342
346
 
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.
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`, `leverage`, `transfer` or `approve-builder-fee` to print the plan without signing anything. In an interactive terminal these 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.
344
348
 
345
349
  ## Bridge
346
350
 
@@ -469,7 +473,7 @@ that cannot change the command line.
469
473
 
470
474
  With `--cache` on, every read the CLI makes through the Nansen API client is
471
475
  cached — all of `nansen research ...`, plus `alerts list` and `alerts get`.
472
- Never cached: `account`, `web search`, `web fetch`, the `alerts`
476
+ Never cached: `account`, `web search`, the `alerts`
473
477
  create/update/toggle/delete commands, `agent`, every `trade`, `bridge`, `wallet`
474
478
  and `mcp` command, and `perp` trading. The analytics commands `perp screener`
475
479
  and `perp leaderboard` are cached.
@@ -606,6 +610,8 @@ Every failure exits 1. The full list of codes is in [docs/error-codes.md](docs/e
606
610
 
607
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`.
608
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
+
609
615
  **Error metadata.** When the API reports them, `details` carries:
610
616
 
611
617
  | Field | Meaning |
@@ -626,7 +632,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
626
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 |
627
633
  | Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
628
634
  | Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
629
- | `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. |
630
636
  | `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |
631
637
  | Huge JSON response | Use `--fields` to select columns. |
632
638
 
@@ -185,6 +185,7 @@ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could
185
185
  | `RPC_JSON_ERROR` | The RPC answered with a body that is not JSON. | No |
186
186
  | `RPC_NETWORK_ERROR` | The CLI could not reach the RPC. | Yes |
187
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 |
188
189
  | `CONFIRMATION_UNAVAILABLE` | Confirmation is required but no terminal is available. Pass --yes to confirm. | No |
189
190
 
190
191
  ### Bridge
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nansen-cli",
3
- "version": "2.5.0",
3
+ "version": "2.6.1",
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",
@@ -83,10 +83,10 @@
83
83
  "vitest": "^4.1.12"
84
84
  },
85
85
  "dependencies": {
86
- "@ethereumjs/rlp": "^10.1.1",
87
- "@noble/curves": "^2.4.0",
88
- "@noble/hashes": "^2.4.0",
89
- "@scure/base": "^2.0.0"
86
+ "@ethereumjs/rlp": "10.1.1",
87
+ "@noble/curves": "2.4.0",
88
+ "@noble/hashes": "2.4.0",
89
+ "@scure/base": "2.0.0"
90
90
  },
91
91
  "optionalDependencies": {
92
92
  "@napi-rs/keyring": "2.1.0",
@@ -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;
@@ -316,7 +316,7 @@ Example summary format:
316
316
  3. Create an alert pointing to your webhook (fill in your alert details):
317
317
  nansen alerts create \
318
318
  --name '<your alert name>' \
319
- --type <sm-token-flows|common-token-transfer|smart-contract-call> \
319
+ --type <sm-token-flows|common-token-transfer> \
320
320
  --chains <chains> \
321
321
  --webhook 'https://<your-tunnel-url>/webhook' \
322
322
  --webhook-secret-stdin \
@@ -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
 
@@ -122,7 +122,10 @@ CLI output so the user can verify on Solscan.
122
122
  `create` and `cancel` accept `--dry-run` (print the plan and exit 0; no API
123
123
  request, no signature, nothing submitted) and `--yes`/`-y` (skip the
124
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
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
126
129
  user what will be created or cancelled before running it for real.
127
130
 
128
131
  ### Update
@@ -113,27 +113,6 @@ nansen alerts create \
113
113
  --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48:ethereum
114
114
  ```
115
115
 
116
- ### 3. `smart-contract-call` — Smart Contract Interactions
117
-
118
- Track contract calls matching specified criteria.
119
-
120
- **Type-specific flags:**
121
- - `--usd-min/max <usd>`
122
- - `--signature-hash <hash>` (repeatable, e.g. `0x095ea7b3` for `approve`)
123
- - `--caller <type:value>` / `--exclude-caller <type:value>` (repeatable)
124
- - `--contract <type:value>` / `--exclude-contract <type:value>` (repeatable)
125
-
126
- **Example:**
127
- ```bash
128
- nansen alerts create \
129
- --name 'Uniswap V3 Large Swaps' \
130
- --type smart-contract-call \
131
- --chains ethereum \
132
- --telegram 123456789 \
133
- --usd-min 1000000 \
134
- --contract entity:"Uniswap V3"
135
- ```
136
-
137
116
  ## Notes
138
117
 
139
118
  - Chain aliases: Hyperliquid = `hyperevm`, BSC = `bnb`.
@@ -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`
@@ -68,6 +68,8 @@ nansen trade execute --quote <quote-id> --yes # skip the confirmation prom
68
68
 
69
69
  **Agents and CI are unaffected:** when stdin is *not* a terminal (a pipe, a CI job, an agent shell) the command proceeds without prompting, exactly as before. `--yes` is accepted there and is simply a no-op, so it is safe to always pass it. The same flags and rules apply to `nansen bridge execute`.
70
70
 
71
+ **Operator stop point (`NANSEN_REQUIRE_CONFIRM=1`).** If the user has set `NANSEN_REQUIRE_CONFIRM=1`, a non-terminal run without `--yes` fails with `CONFIRMATION_REQUIRED` (exit 1) before any request or signature. That means the user wants to approve each broadcast: show them the `--dry-run` plan, and only re-run with `--yes` after they say go. Do not unset the variable to get around it.
72
+
71
73
  ### Exit codes (`trade execute`, `bridge execute`)
72
74
 
73
75
  | Code | Meaning |
@@ -189,7 +191,7 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
189
191
  | `--quote-index` | Pin a specific quote by index (0-based) when multiple quotes were returned |
190
192
  | `--no-simulate` | Skip pre-broadcast simulation |
191
193
  | `--dry-run` | Validate and print what would be sent, then stop. Nothing is signed or broadcast |
192
- | `--yes`, `-y` | Skip the confirmation prompt (same as `NANSEN_YES=1`); no-op when stdin is not a terminal |
194
+ | `--yes`, `-y` | Skip the confirmation prompt (same as `NANSEN_YES=1`); no-op when stdin is not a terminal, unless `NANSEN_REQUIRE_CONFIRM=1` is set, which makes it required there |
193
195
 
194
196
  ### `trade bridge-status` flags
195
197
 
@@ -205,7 +207,8 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
205
207
  |-----|---------|
206
208
  | `NANSEN_WALLET_PASSWORD` | **Required for `trade execute`.** Wallet encryption password — persisted in `~/.nansen/.env`. Source before executing: `source ~/.nansen/.env && nansen trade execute ...` |
207
209
  | `NANSEN_API_KEY` | API key (also set via explicit `nansen login --human`; browser sessions are not wallet or RPC keys) |
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` |
210
+ | `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`/`transfer`/`approve-builder-fee`, like `--yes` |
211
+ | `NANSEN_REQUIRE_CONFIRM` | Set to `1` to make those same commands fail with `CONFIRMATION_REQUIRED`, before any request or signature, when stdin is not a terminal and neither `--yes` nor `NANSEN_YES=1` is given. `--dry-run` still works. Opt-in; unset keeps today's behaviour |
209
212
 
210
213
  > **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.
211
214
 
@@ -220,35 +223,35 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
220
223
 
221
224
  Use `nansen perp` for Hyperliquid perpetual trading. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading; requires an **EVM** wallet. **Perp orders are irreversible once signed.**
222
225
 
223
- Subcommands: `order`, `cancel`, `close`, `leverage`, `positions`, `orders`, `account`, `meta`.
226
+ Subcommands: `order`, `cancel`, `close`, `leverage`, `transfer`, `approve-builder-fee`, `positions`, `orders`, `account`, `meta`.
224
227
 
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).
228
+ The asset is selected with `--symbol` (e.g. `BTC`, `ETH`); `--coin` 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).
226
229
 
227
230
  ## Preview and confirm (`--dry-run`, `--yes`)
228
231
 
229
232
  `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
233
 
231
234
  ```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
235
+ nansen perp order --symbol ETH --side buy --size 0.1 --price 1600 --dry-run # preview only, nothing is signed
236
+ nansen perp order --symbol ETH --side buy --size 0.1 --price 1600 --yes # skip the confirmation prompt
234
237
  ```
235
238
 
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.
239
+ **`--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, `leverage` shows the new setting next to the asset maximum, `transfer` shows the direction and the exact USDC amount, and `approve-builder-fee` shows the builder address and maximum fee rate (or says the fee is already approved, with nothing to preview).
237
240
 
238
241
  **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
242
 
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.
243
+ **Confirmation.** When stdin is an interactive terminal, these commands (`order`, `close`, `cancel`, `leverage`, `transfer`, `approve-builder-fee`) 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
244
 
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.
245
+ **When stdin is *not* a terminal** (agents, CI) the commands submit without prompting, exactly as before, and `--yes` is a no-op. **Exception:** if `NANSEN_REQUIRE_CONFIRM=1` is set, they fail with `CONFIRMATION_REQUIRED` (exit 1) before any request or signature unless `--yes` or `NANSEN_YES=1` is given; follow the operator stop point described above. These are the same rules as `trade execute` and `bridge execute`.
243
246
 
244
247
  ## Open a position
245
248
 
246
249
  ```bash
247
250
  # Limit long: 0.1 ETH at $1600
248
- nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --type limit
251
+ nansen perp order --symbol ETH --side buy --size 0.1 --price 1600 --type limit
249
252
 
250
253
  # Market short with optional take-profit / stop-loss
251
- nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type market \
254
+ nansen perp order --symbol BTC --side sell --size 0.001 --price 95000 --type market \
252
255
  --take-profit 90000 --stop-loss 98000
253
256
  ```
254
257
 
@@ -258,22 +261,22 @@ nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type marke
258
261
  - `--type`: `limit` (default) or `market`. `--tif`: `Gtc` (default), `Ioc`, `Alo`.
259
262
  - `--slippage`: decimal in `[0,1]` for market orders (default `0.03` = 3%).
260
263
 
261
- On success the command prints the Hyperliquid order id (`oid`) and the fill (size @ avg price). A resting (unfilled) order also prints a ready-to-run `nansen perp cancel --coin <coin> --oid <oid>`. Attached take-profit/stop-loss legs are labelled and each print their own `oid`.
264
+ On success the command prints the Hyperliquid order id (`oid`) and the fill (size @ avg price). A resting (unfilled) order also prints a ready-to-run `nansen perp cancel --symbol <symbol> --oid <oid>`. Attached take-profit/stop-loss legs are labelled and each print their own `oid`.
262
265
 
263
266
  ## Close / cancel
264
267
 
265
268
  ```bash
266
269
  # Close: sell to close a long, buy to close a short (validated against your open position)
267
- nansen perp close --coin ETH --size 0.1 --price 1600 --side sell
270
+ nansen perp close --symbol ETH --size 0.1 --price 1600 --side sell
268
271
 
269
272
  # Cancel a resting order by id
270
- nansen perp cancel --coin ETH --oid 123456
273
+ nansen perp cancel --symbol ETH --oid 123456
271
274
  ```
272
275
 
273
276
  ## Leverage, transfers & account
274
277
 
275
278
  ```bash
276
- nansen perp leverage --coin ETH --leverage 5 --margin-type cross # or isolated
279
+ nansen perp leverage --symbol ETH --leverage 5 --margin-type cross # or isolated
277
280
  nansen perp transfer --direction spot-to-perp --amount 25 # or perp-to-spot
278
281
  nansen perp positions
279
282
  nansen perp account # account value, unrealized PnL, margin used, withdrawable, spot USDC
@@ -39,4 +39,4 @@ Positional args and `--query` flags can be combined — all become queries.
39
39
 
40
40
  Returns `results[]` — one entry per query, each with `organic[]` (title, link, snippet, date) and optional `knowledge_graph`.
41
41
 
42
- **Note:** Some domains are excluded from results (paywalled/unfetchable sites like bloomberg.com, twitter.com). Use `nansen web fetch` to retrieve content from specific URLs.
42
+ **Note:** Some domains are excluded from results (paywalled/unfetchable sites like bloomberg.com, twitter.com).
package/src/api.js CHANGED
@@ -1717,20 +1717,6 @@ export class NansenAPI {
1717
1717
  }, { cache: false });
1718
1718
  }
1719
1719
 
1720
- async webFetch(params = {}) {
1721
- const { urls, question } = params;
1722
- if (!urls || urls.length === 0) {
1723
- throw new NansenError('At least one URL is required', ErrorCode.MISSING_PARAM);
1724
- }
1725
- if (!question) {
1726
- throw new NansenError('A question is required', ErrorCode.MISSING_PARAM);
1727
- }
1728
- return this.request('/api/v1/search/web-fetch', {
1729
- urls,
1730
- question,
1731
- }, { cache: false });
1732
- }
1733
-
1734
1720
  async addressHistoricalBalances(params = {}) {
1735
1721
  const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
1736
1722
  if (address) requireValidAddress(address, chain);
package/src/bridge.js CHANGED
@@ -430,6 +430,19 @@ const HL_SENDASSET_FIELDS = [
430
430
  { name: 'nonce', type: 'uint64' },
431
431
  ];
432
432
 
433
+ // Relay's Hyperliquid deposit address: the only `destination` a bridge
434
+ // withdrawal's sendAsset may name. The signature commits to `destination`
435
+ // (it is in HL_SENDASSET_FIELDS), so leaving it unchecked would let a tampered
436
+ // quote send the withdrawal to any HL address. Captured from real read-only
437
+ // `bridge quote` responses for all three withdrawal routes (HL -> base,
438
+ // ethereum, arbitrum) on 2026-08-28 and again on 2026-11-16: identical every
439
+ // time. Lower-cased for comparison. If Relay rotates this address, every HL
440
+ // withdrawal fails closed until nansen-cli is updated (the same trade-off as
441
+ // BRIDGE_DEPOSIT_TARGETS on the EVM deposit leg).
442
+ export const HL_BRIDGE_RELAYER_DESTINATIONS = new Set([
443
+ '0x66cf0aace1b4e562593bec10ec7868fba9932224',
444
+ ]);
445
+
433
446
  // Parse a non-negative decimal string ("2", "2.000000", "1.97859") to an integer
434
447
  // scaled by `decimals`, via digit slicing (never parseFloat) so it is exact.
435
448
  export function decimalToScaled(raw, decimals = 8) {
@@ -447,10 +460,12 @@ export function decimalToScaled(raw, decimals = 8) {
447
460
  // action; it says nothing about what the action does. Static only, no RPC.
448
461
  //
449
462
  // NOTE ON DESTINATION: in the relayer-mediated flow, action.destination is the
450
- // RELAYER's deposit address, not the user's — so it is deliberately NOT bound to
451
- // the recipient (doing so would reject every legitimate withdrawal). The final
452
- // payout recipient is held off-chain by the relayer and is not in anything we
453
- // sign; the amount cap below is what bounds the loss.
463
+ // RELAYER's deposit address, not the user's — so it is NOT bound to the
464
+ // recipient (doing so would reject every legitimate withdrawal). It IS pinned
465
+ // to the relayer (HL_BRIDGE_RELAYER_DESTINATIONS), so the withdrawal can only
466
+ // go to Relay. The final payout recipient is held off-chain by the relayer and
467
+ // is not in anything we sign; the amount cap below bounds the loss per leg, and
468
+ // preflightHlBridgeSteps bounds the number of legs to one.
454
469
  //
455
470
  // Every check below fails CLOSED (throws) rather than silently skipping when
456
471
  // its anchor is missing. An earlier version skipped the amount cap whenever
@@ -485,6 +500,15 @@ export function assertHlBridgeActionIntent(action, intent, context = 'Bridge act
485
500
  'UNEXPECTED_NETWORK',
486
501
  );
487
502
  }
503
+ // D. destination — must be Relay's deposit address. Fails closed when absent.
504
+ const destination = action.destination ?? action.parameters?.destination;
505
+ if (typeof destination !== 'string' || !HL_BRIDGE_RELAYER_DESTINATIONS.has(destination.toLowerCase())) {
506
+ throw new CommandError(
507
+ `${context} sends to ${destination}, not the Relay deposit address. `
508
+ + `Refusing to sign. Update nansen-cli if Relay changed its deposit address, otherwise request a new quote.`,
509
+ 'UNEXPECTED_ACTION',
510
+ );
511
+ }
488
512
  // B. amount cap — required, not optional. sendAsset's entire purpose is
489
513
  // moving a nonzero amount; an action.type we allowlisted but with no amount
490
514
  // to check is not a smaller withdrawal, it is a signal something is wrong
@@ -666,9 +690,20 @@ function buildHlBridgeAction(signData) {
666
690
  // endpoint pin, and the EIP-712 type-list guard — so this is a strict
667
691
  // superset of the per-step processors' checks, run up front across the whole
668
692
  // plan first.
693
+ //
694
+ // Per-item checks cannot bound a REPEATED plan: [authorize, sendAsset,
695
+ // sendAsset, ...] passes them leg by leg, each sendAsset within the amount cap,
696
+ // and would withdraw N times the reviewed amount. So, mirroring
697
+ // preflightEvmBridgeSteps, count the legs: at most one incomplete authorize,
698
+ // and exactly one sendAsset in total (completed sendAsset legs count toward
699
+ // the total, since a real withdrawal never has two) which is still incomplete.
669
700
  function preflightHlBridgeSteps(steps, intent) {
701
+ let authorizeCount = 0;
702
+ let actionCount = 0;
703
+ let totalActionCount = 0;
670
704
  for (const step of steps) {
671
705
  for (const item of step.items || []) {
706
+ if (item.data?.action) totalActionCount++;
672
707
  // Skip already-signed-and-submitted items, matching the processors
673
708
  // (:769/:838): on resume of a partially-executed bridge, re-validating a
674
709
  // completed step against these now-stricter checks could wedge it.
@@ -684,9 +719,11 @@ function preflightHlBridgeSteps(steps, intent) {
684
719
  assertHlBridgeAuthorizeIntent(signData.sign, intent.signerAddress, `Bridge step "${step.id}"`);
685
720
  resolveRelayTargetUrl(signData.post?.endpoint, `Bridge step "${step.id}"`);
686
721
  assertEip712TypeListNonEmpty(signData.sign.types, signData.sign.primaryType, `Bridge step "${step.id}"`);
722
+ authorizeCount++;
687
723
  } else if (signData.action) {
688
724
  assertHlBridgeActionIntent(buildHlBridgeAction(signData), intent, `Bridge step "${step.id}"`);
689
725
  assertHlSendAssetEip712Shape(signData.eip712Types, signData.eip712PrimaryType, `Bridge step "${step.id}"`);
726
+ actionCount++;
690
727
  } else {
691
728
  // A leg matching neither is never something to sign — the local
692
729
  // processor would silently no-op it (reporting success having signed
@@ -698,6 +735,13 @@ function preflightHlBridgeSteps(steps, intent) {
698
735
  }
699
736
  }
700
737
  }
738
+ if (authorizeCount > 1 || totalActionCount !== 1 || actionCount !== 1) {
739
+ throw new CommandError(
740
+ `Bridge plan has ${authorizeCount} authorize and ${totalActionCount} sendAsset leg(s) (${actionCount} pending); a legitimate withdrawal is at most one authorize and exactly one sendAsset. `
741
+ + `Refusing to sign — repeated legs could withdraw more than the amount you requested. Request a new quote.`,
742
+ 'UNEXPECTED_ACTION',
743
+ );
744
+ }
701
745
  }
702
746
 
703
747
  // ── Step processors ──────────────────────────────────────────────────