nansen-cli 2.5.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#828](https://github.com/nansen-ai/nansen-cli/pull/828) [`f143625`](https://github.com/nansen-ai/nansen-cli/commit/f1436251fe7b07314980918f2202bf31fe9e6577) Thanks [@kome12](https://github.com/kome12)! - One flag name per input across commands, with the old names still accepted: `--token` for a token address (historical-\* commands, `alerts list`, `trade limit-order list`; `--token-address` and `--mint` still work), `--days` for a lookback in days (`chain-rank`, `smart-money-pnl-leaderboard`, `historical-token-screener`; `--timeframe-days` still works), `--interval` for the candle size on `token ohlcv` and `historical-token-ohlcv` (`--timeframe` still works), and `--symbol` for a perp market (`perp order/cancel/close/leverage`, and research perp commands now accept `--coin`). Giving one input under two names now fails instead of silently using one of them. `--days` on `token screener`, `info` or `flow-intelligence` now points to `--timeframe`.
8
+
9
+ - [#829](https://github.com/nansen-ai/nansen-cli/pull/829) [`61520f7`](https://github.com/nansen-ai/nansen-cli/commit/61520f75c23a76ddfb0267a67354ed6ef1a02cfe) Thanks [@kome12](https://github.com/kome12)! - Research commands now report the chain they used when `--chain` is left out, as `_meta.defaults.chain` in the JSON response. `--help` and `nansen schema` now show the default chain each command actually uses: `token indicators` defaults to `solana` (it said `ethereum`), the wallet `profiler` commands default to `all` (they said `ethereum`), and `smart-money-pnl-leaderboard`, `historical-smart-money-balances` and `historical-token-screener` now document their `solana` default. No command's default chain changed.
10
+
11
+ - [#820](https://github.com/nansen-ai/nansen-cli/pull/820) [`f04ecb2`](https://github.com/nansen-ai/nansen-cli/commit/f04ecb2e2c9fb5e8c763a5d6aabff39d1b280316) Thanks [@kome12](https://github.com/kome12)! - `--help` for every command now prints one line per option with what it does (from the schema), plus its aliases, default, allowed values and whether it is repeatable or required. Research and wallet commands used to list only option names on one `Params` line. `nansen alerts delete --help` now lists `--reveal`.
12
+
13
+ - [#825](https://github.com/nansen-ai/nansen-cli/pull/825) [`774eb34`](https://github.com/nansen-ai/nansen-cli/commit/774eb342eeea5191ee821b80d1f06ec945269ef0) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - **Removed `nansen web fetch` and the `nansen-web-fetcher` skill.** The Nansen API removed `POST /api/v1/search/web-fetch`, the only endpoint the command called, so it no longer returns results on any CLI version. `nansen web fetch` now fails with the usual unknown-subcommand error listing `search`. There is no replacement command.
14
+
15
+ This removes a published subcommand and its `schema.json` entry. It ships as a minor because it was released only after the endpoint was gone, as with the points leaderboard removal (#542).
16
+
17
+ - [#827](https://github.com/nansen-ai/nansen-cli/pull/827) [`156cfef`](https://github.com/nansen-ai/nansen-cli/commit/156cfefb7d328a1fb566384cc7ca7d68b5a167cd) Thanks [@kome12](https://github.com/kome12)! - Add `NANSEN_REQUIRE_CONFIRM=1`, an opt-in stop point for agents: when stdin is not a terminal, `trade execute`, `bridge execute`, `trade limit-order create`/`cancel` and `perp order`/`close`/`cancel`/`leverage` run without `--yes` (or `NANSEN_YES=1`) now fail with `CONFIRMATION_REQUIRED` before any request or signature. `--dry-run` still previews. Unset, behaviour is unchanged.
18
+
19
+ - [#821](https://github.com/nansen-ai/nansen-cli/pull/821) [`420e123`](https://github.com/nansen-ai/nansen-cli/commit/420e1235e6c768b23a32104374f12d98cbf0ea19) Thanks [@kome12](https://github.com/kome12)! - Shorter top-level help. `nansen` and `nansen --help` now print a short index (get-started commands, the command list, and where to find more) instead of 82 lines, and make no network call: no credit-cost fetch before printing, and no update check or update notice. The detail moved behind `nansen help <topic>` (`auth`, `options`, `examples`, `chains`, `labels`, `deprecated`, `telemetry`). `nansen help <command> [subcommand]` prints the same as `nansen <command> [subcommand] --help`, and `nansen help <unknown>` now fails with `UNKNOWN_COMMAND` instead of printing the full page.
20
+
21
+ ### Patch Changes
22
+
23
+ - [#833](https://github.com/nansen-ai/nansen-cli/pull/833) [`b542d75`](https://github.com/nansen-ai/nansen-cli/commit/b542d75538aa3dc6b89f3b29fdd185bb176dc172) Thanks [@kome12](https://github.com/kome12)! - `nansen schema` now lists the `alerts list` filters: `--type`, `--enabled`, `--disabled`, `--chain`, `--limit` and `--offset`.
24
+
25
+ - [#831](https://github.com/nansen-ai/nansen-cli/pull/831) [`378e96c`](https://github.com/nansen-ai/nansen-cli/commit/378e96ca6adbdb4a2cb2795061034a31b78687b1) Thanks [@kome12](https://github.com/kome12)! - Show a non-interactive skills install command (`npx -y skills add nansen-ai/nansen-cli --skill "*" -y`) in the README, top-level help and install messages. The plain command opens a picker that agents cannot drive; the README and the install prompt now also say that space selects a skill and enter confirms.
26
+
27
+ - [#832](https://github.com/nansen-ai/nansen-cli/pull/832) [`cac6ee8`](https://github.com/nansen-ai/nansen-cli/commit/cac6ee8d212d73c34acf640a69f085d09a9ec5ff) Thanks [@kome12](https://github.com/kome12)! - The global-install onboarding now recognises Nansen skills installed with `skills add nansen-ai/nansen-cli` (in `~/.agents/skills` or `~/.claude/skills`) and no longer offers to install them again on every upgrade.
28
+
29
+ - [#822](https://github.com/nansen-ai/nansen-cli/pull/822) [`bd44df9`](https://github.com/nansen-ai/nansen-cli/commit/bd44df90d21e81d01802abe4dec46ee42548c01b) Thanks [@erkancamli](https://github.com/erkancamli)! - x402 auto-payment with a Privy default wallet now tries the payment options cheapest first, like the local wallet and WalletConnect. It used to sign them in the server's order (every EVM option before Solana), so a 402 that listed a pricier option first was paid that one. Privy also no longer signs a Permit2 (`permit2-exact`) or unknown `assetTransferMethod` option as an EIP-3009 authorization the server cannot settle; it skips that option with the reason and tries the next one. A failed Privy wallet lookup now skips only that chain's options, so an option on the other chain can still be paid; when no option can be signed, the lookup error is still reported.
30
+
31
+ - [#830](https://github.com/nansen-ai/nansen-cli/pull/830) [`da57038`](https://github.com/nansen-ai/nansen-cli/commit/da570383b2d81c2c9e92ba090d8dcccb3f2601de) Thanks [@omerbek](https://github.com/omerbek)! - Report the original API error when a profiler trace's root lookup fails instead of returning a successful empty graph. Keep later branch lookups best-effort after a successful root lookup.
32
+
3
33
  ## 2.5.0
4
34
 
5
35
  ### 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`) 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,16 +329,16 @@ 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
@@ -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.0",
4
4
  "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
@@ -4,7 +4,7 @@
4
4
  * Post-install onboarding for nansen-cli.
5
5
  *
6
6
  * Runs after `npm install -g nansen-cli` and offers two optional steps:
7
- * 1. Install the Nansen AI coding skill (`npx skills add nansen-ai/nansen-cli`)
7
+ * 1. Install the Nansen AI coding skills (prints `npx -y skills add nansen-ai/nansen-cli --skill "*" -y`)
8
8
  * 2. Check account status to verify the effective credential (0 credits)
9
9
  *
10
10
  * Non-interactive environments (CI, piped stdin) get a one-liner tip instead.
@@ -13,7 +13,7 @@
13
13
 
14
14
  import { createInterface } from "readline";
15
15
  import { execFileSync, spawn } from "child_process";
16
- import { existsSync, realpathSync } from "fs";
16
+ import { existsSync, readdirSync, realpathSync } from "fs";
17
17
  import { join, dirname } from "path";
18
18
  import { fileURLToPath } from "url";
19
19
 
@@ -27,6 +27,10 @@ const CYAN = "\x1b[36m";
27
27
  const RESET = "\x1b[0m";
28
28
 
29
29
  const SKILL_REPO = "nansen-ai/nansen-cli";
30
+ // Non-interactive: the first -y skips npx's own install prompt, --skill "*" -y
31
+ // skips the skills picker. Agents cannot drive the picker. Double quotes, not
32
+ // single: Windows cmd.exe keeps single quotes and would pass a literal '*'.
33
+ const SKILL_INSTALL_CMD = `npx -y skills add ${SKILL_REPO} --skill "*" -y`;
30
34
  const TEST_QUERY = ["account"];
31
35
  const TEST_QUERY_DISPLAY = "nansen account";
32
36
 
@@ -60,13 +64,31 @@ function hasNpx() {
60
64
  }
61
65
  }
62
66
 
67
+ // `skills add nansen-ai/nansen-cli` writes one directory per skill, named after
68
+ // the skill, into ~/.agents/skills and links it into each agent's skills
69
+ // directory (~/.claude/skills for Claude Code). Match the skill names shipped in
70
+ // this package rather than a `nansen-` prefix, which unrelated skills also use.
71
+ // The legacy names cover installs from before the skills were split.
72
+ const PACKAGED_SKILLS_DIR = join(__dirname, "..", "skills");
73
+ const LEGACY_SKILL_NAMES = ["nansen-cli", "nansen-ai--nansen-cli"];
74
+
75
+ function packagedSkillNames() {
76
+ try {
77
+ return readdirSync(PACKAGED_SKILLS_DIR, { withFileTypes: true })
78
+ .filter((entry) => entry.isDirectory())
79
+ .map((entry) => entry.name);
80
+ } catch {
81
+ return [];
82
+ }
83
+ }
84
+
63
85
  function isSkillInstalled() {
64
86
  const home = process.env.HOME || process.env.USERPROFILE || "";
65
- const locations = [
66
- join(home, ".claude", "skills", "nansen-cli"),
67
- join(home, ".claude", "skills", "nansen-ai--nansen-cli"),
68
- ];
69
- return locations.some((loc) => existsSync(loc));
87
+ const roots = [join(home, ".agents", "skills"), join(home, ".claude", "skills")];
88
+ const names = packagedSkillNames();
89
+ const installed = roots.some((root) => names.some((name) => existsSync(join(root, name, "SKILL.md"))));
90
+ const legacy = LEGACY_SKILL_NAMES.some((name) => existsSync(join(home, ".claude", "skills", name)));
91
+ return installed || legacy;
70
92
  }
71
93
 
72
94
  function prompt(question) {
@@ -97,7 +119,7 @@ async function installSkill() {
97
119
  }
98
120
 
99
121
  if (!hasNpx()) {
100
- log(`${DIM}Tip: Run 'npx skills add ${SKILL_REPO}' to install the Nansen AI coding skill.${RESET}`);
122
+ log(`${DIM}Tip: Run ${SKILL_INSTALL_CMD} to install the Nansen AI coding skills.${RESET}`);
101
123
  return;
102
124
  }
103
125
 
@@ -106,14 +128,15 @@ async function installSkill() {
106
128
  const answer = await prompt(` Install Nansen skill for your AI coding agent? [y/N] `);
107
129
 
108
130
  if (!/^y(es)?$/i.test(answer)) {
109
- log(`Skipped. You can install it later with: ${CYAN}npx skills add ${SKILL_REPO}${RESET}`);
131
+ log(`Skipped. You can install it later with: ${CYAN}${SKILL_INSTALL_CMD}${RESET}`);
110
132
  return;
111
133
  }
112
134
 
113
135
  log(`Installing Nansen skill...`);
136
+ log(`In the picker, space selects a skill and enter confirms.`);
114
137
  const ok = await runCommand(...npxInvocation(["-y", "skills", "add", SKILL_REPO]));
115
138
  if (!ok) {
116
- log(`${YELLOW}Skill installation failed. You can retry with: npx skills add ${SKILL_REPO}${RESET}`);
139
+ log(`${YELLOW}Skill installation failed. You can retry with: ${SKILL_INSTALL_CMD}${RESET}`);
117
140
  }
118
141
  }
119
142
 
@@ -170,7 +193,9 @@ export async function main() {
170
193
  if (!hasTTY()) {
171
194
  log(`${BOLD}Nansen CLI installed!${RESET}`);
172
195
  log();
173
- log(`Tip: Run '${CYAN}npx skills add ${SKILL_REPO}${RESET}' to install the Nansen AI coding skill.`);
196
+ if (!isSkillInstalled()) {
197
+ log(`Tip: Run ${CYAN}${SKILL_INSTALL_CMD}${RESET} to install the Nansen AI coding skills.`);
198
+ }
174
199
  log(`Tip: Run '${CYAN}nansen login${RESET}' for browser approval, or use NANSEN_API_KEY directly.`);
175
200
  log(`Tip: To trade, first create a wallet with '${CYAN}nansen wallet create${RESET}', then quote with '${CYAN}nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000${RESET}' and execute with '${CYAN}nansen trade execute --quote <id>${RESET}'.`);
176
201
  return;
@@ -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
@@ -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
 
@@ -206,6 +208,7 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
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
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`, 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
 
@@ -222,15 +225,15 @@ Use `nansen perp` for Hyperliquid perpetual trading. Uses the same wallet and `N
222
225
 
223
226
  Subcommands: `order`, `cancel`, `close`, `leverage`, `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
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, and `leverage` shows the new setting next to the asset maximum.
@@ -239,16 +242,16 @@ nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --yes # sk
239
242
 
240
243
  **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
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`. `transfer` and `approve-builder-fee` are unchanged.
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);