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 +30 -0
- package/README.md +18 -12
- package/docs/error-codes.md +1 -0
- package/package.json +1 -1
- package/scripts/postinstall.js +36 -11
- package/skills/nansen-limit-orders/SKILL.md +6 -3
- package/skills/nansen-token-research/SKILL.md +1 -1
- package/skills/nansen-trading/SKILL.md +14 -11
- package/skills/nansen-web-searcher/SKILL.md +1 -1
- package/src/api.js +0 -14
- package/src/cli.js +150 -116
- package/src/commands/alerts.js +13 -4
- package/src/commands/completion.js +0 -1
- package/src/commands/research.js +35 -35
- package/src/error-codes.js +1 -0
- package/src/execute-guard.js +43 -3
- package/src/input-validation.js +32 -3
- package/src/limit-order.js +12 -4
- package/src/perp.js +14 -9
- package/src/privy.js +145 -103
- package/src/schema.json +152 -88
- package/skills/nansen-web-fetcher/SKILL.md +0 -53
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 #
|
|
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 [--
|
|
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] [--
|
|
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 `--
|
|
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 --
|
|
333
|
-
nansen perp order --
|
|
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 --
|
|
336
|
-
nansen perp cancel --
|
|
337
|
-
nansen perp leverage --
|
|
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`,
|
|
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 `--
|
|
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
|
|
package/docs/error-codes.md
CHANGED
|
@@ -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
package/scripts/postinstall.js
CHANGED
|
@@ -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
|
|
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
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
return
|
|
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
|
|
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}
|
|
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:
|
|
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
|
-
|
|
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 --
|
|
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`, `--
|
|
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
|
|
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 --
|
|
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 `--
|
|
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 --
|
|
233
|
-
nansen perp order --
|
|
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
|
-
**
|
|
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 --
|
|
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 --
|
|
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 --
|
|
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 --
|
|
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 --
|
|
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 --
|
|
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).
|
|
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);
|