nansen-cli 2.4.0 → 2.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +78 -0
- package/README.md +49 -20
- package/docs/error-codes.md +3 -0
- package/package.json +1 -1
- package/scripts/postinstall.js +36 -11
- package/skills/nansen-agent-guide/SKILL.md +3 -3
- package/skills/nansen-alerts-webhook-listener/SKILL.md +16 -13
- package/skills/nansen-limit-orders/SKILL.md +13 -2
- package/skills/nansen-smart-alerts/SKILL.md +3 -1
- package/skills/nansen-token-research/SKILL.md +1 -1
- package/skills/nansen-trading/SKILL.md +33 -9
- package/skills/nansen-wallet-manager/SKILL.md +10 -4
- package/skills/nansen-web-searcher/SKILL.md +1 -1
- package/src/api.js +80 -41
- package/src/auth-key-input.js +57 -9
- package/src/auto-paginate.js +25 -7
- package/src/cache-inspect.js +16 -6
- package/src/cli.js +239 -146
- package/src/commands/alerts.js +103 -15
- package/src/commands/completion.js +4 -2
- package/src/commands/research.js +35 -35
- package/src/ens.js +14 -5
- package/src/error-codes.js +3 -0
- package/src/execute-guard.js +51 -6
- package/src/input-validation.js +40 -7
- package/src/limit-order.js +129 -57
- package/src/perp.js +368 -41
- package/src/privy.js +147 -108
- package/src/query-options.js +17 -1
- package/src/response-cache-files.js +65 -0
- package/src/response-meta.js +8 -2
- package/src/schema.json +264 -94
- package/src/telemetry-flags.js +75 -0
- package/src/trading.js +71 -8
- package/src/transfer.js +72 -11
- package/src/wallet.js +35 -12
- package/src/walletconnect-x402.js +13 -1
- package/skills/nansen-web-fetcher/SKILL.md +0 -53
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,83 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2.6.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#828](https://github.com/nansen-ai/nansen-cli/pull/828) [`f143625`](https://github.com/nansen-ai/nansen-cli/commit/f1436251fe7b07314980918f2202bf31fe9e6577) Thanks [@kome12](https://github.com/kome12)! - One flag name per input across commands, with the old names still accepted: `--token` for a token address (historical-\* commands, `alerts list`, `trade limit-order list`; `--token-address` and `--mint` still work), `--days` for a lookback in days (`chain-rank`, `smart-money-pnl-leaderboard`, `historical-token-screener`; `--timeframe-days` still works), `--interval` for the candle size on `token ohlcv` and `historical-token-ohlcv` (`--timeframe` still works), and `--symbol` for a perp market (`perp order/cancel/close/leverage`, and research perp commands now accept `--coin`). Giving one input under two names now fails instead of silently using one of them. `--days` on `token screener`, `info` or `flow-intelligence` now points to `--timeframe`.
|
|
8
|
+
|
|
9
|
+
- [#829](https://github.com/nansen-ai/nansen-cli/pull/829) [`61520f7`](https://github.com/nansen-ai/nansen-cli/commit/61520f75c23a76ddfb0267a67354ed6ef1a02cfe) Thanks [@kome12](https://github.com/kome12)! - Research commands now report the chain they used when `--chain` is left out, as `_meta.defaults.chain` in the JSON response. `--help` and `nansen schema` now show the default chain each command actually uses: `token indicators` defaults to `solana` (it said `ethereum`), the wallet `profiler` commands default to `all` (they said `ethereum`), and `smart-money-pnl-leaderboard`, `historical-smart-money-balances` and `historical-token-screener` now document their `solana` default. No command's default chain changed.
|
|
10
|
+
|
|
11
|
+
- [#820](https://github.com/nansen-ai/nansen-cli/pull/820) [`f04ecb2`](https://github.com/nansen-ai/nansen-cli/commit/f04ecb2e2c9fb5e8c763a5d6aabff39d1b280316) Thanks [@kome12](https://github.com/kome12)! - `--help` for every command now prints one line per option with what it does (from the schema), plus its aliases, default, allowed values and whether it is repeatable or required. Research and wallet commands used to list only option names on one `Params` line. `nansen alerts delete --help` now lists `--reveal`.
|
|
12
|
+
|
|
13
|
+
- [#825](https://github.com/nansen-ai/nansen-cli/pull/825) [`774eb34`](https://github.com/nansen-ai/nansen-cli/commit/774eb342eeea5191ee821b80d1f06ec945269ef0) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - **Removed `nansen web fetch` and the `nansen-web-fetcher` skill.** The Nansen API removed `POST /api/v1/search/web-fetch`, the only endpoint the command called, so it no longer returns results on any CLI version. `nansen web fetch` now fails with the usual unknown-subcommand error listing `search`. There is no replacement command.
|
|
14
|
+
|
|
15
|
+
This removes a published subcommand and its `schema.json` entry. It ships as a minor because it was released only after the endpoint was gone, as with the points leaderboard removal (#542).
|
|
16
|
+
|
|
17
|
+
- [#827](https://github.com/nansen-ai/nansen-cli/pull/827) [`156cfef`](https://github.com/nansen-ai/nansen-cli/commit/156cfefb7d328a1fb566384cc7ca7d68b5a167cd) Thanks [@kome12](https://github.com/kome12)! - Add `NANSEN_REQUIRE_CONFIRM=1`, an opt-in stop point for agents: when stdin is not a terminal, `trade execute`, `bridge execute`, `trade limit-order create`/`cancel` and `perp order`/`close`/`cancel`/`leverage` run without `--yes` (or `NANSEN_YES=1`) now fail with `CONFIRMATION_REQUIRED` before any request or signature. `--dry-run` still previews. Unset, behaviour is unchanged.
|
|
18
|
+
|
|
19
|
+
- [#821](https://github.com/nansen-ai/nansen-cli/pull/821) [`420e123`](https://github.com/nansen-ai/nansen-cli/commit/420e1235e6c768b23a32104374f12d98cbf0ea19) Thanks [@kome12](https://github.com/kome12)! - Shorter top-level help. `nansen` and `nansen --help` now print a short index (get-started commands, the command list, and where to find more) instead of 82 lines, and make no network call: no credit-cost fetch before printing, and no update check or update notice. The detail moved behind `nansen help <topic>` (`auth`, `options`, `examples`, `chains`, `labels`, `deprecated`, `telemetry`). `nansen help <command> [subcommand]` prints the same as `nansen <command> [subcommand] --help`, and `nansen help <unknown>` now fails with `UNKNOWN_COMMAND` instead of printing the full page.
|
|
20
|
+
|
|
21
|
+
### Patch Changes
|
|
22
|
+
|
|
23
|
+
- [#833](https://github.com/nansen-ai/nansen-cli/pull/833) [`b542d75`](https://github.com/nansen-ai/nansen-cli/commit/b542d75538aa3dc6b89f3b29fdd185bb176dc172) Thanks [@kome12](https://github.com/kome12)! - `nansen schema` now lists the `alerts list` filters: `--type`, `--enabled`, `--disabled`, `--chain`, `--limit` and `--offset`.
|
|
24
|
+
|
|
25
|
+
- [#831](https://github.com/nansen-ai/nansen-cli/pull/831) [`378e96c`](https://github.com/nansen-ai/nansen-cli/commit/378e96ca6adbdb4a2cb2795061034a31b78687b1) Thanks [@kome12](https://github.com/kome12)! - Show a non-interactive skills install command (`npx -y skills add nansen-ai/nansen-cli --skill "*" -y`) in the README, top-level help and install messages. The plain command opens a picker that agents cannot drive; the README and the install prompt now also say that space selects a skill and enter confirms.
|
|
26
|
+
|
|
27
|
+
- [#832](https://github.com/nansen-ai/nansen-cli/pull/832) [`cac6ee8`](https://github.com/nansen-ai/nansen-cli/commit/cac6ee8d212d73c34acf640a69f085d09a9ec5ff) Thanks [@kome12](https://github.com/kome12)! - The global-install onboarding now recognises Nansen skills installed with `skills add nansen-ai/nansen-cli` (in `~/.agents/skills` or `~/.claude/skills`) and no longer offers to install them again on every upgrade.
|
|
28
|
+
|
|
29
|
+
- [#822](https://github.com/nansen-ai/nansen-cli/pull/822) [`bd44df9`](https://github.com/nansen-ai/nansen-cli/commit/bd44df90d21e81d01802abe4dec46ee42548c01b) Thanks [@erkancamli](https://github.com/erkancamli)! - x402 auto-payment with a Privy default wallet now tries the payment options cheapest first, like the local wallet and WalletConnect. It used to sign them in the server's order (every EVM option before Solana), so a 402 that listed a pricier option first was paid that one. Privy also no longer signs a Permit2 (`permit2-exact`) or unknown `assetTransferMethod` option as an EIP-3009 authorization the server cannot settle; it skips that option with the reason and tries the next one. A failed Privy wallet lookup now skips only that chain's options, so an option on the other chain can still be paid; when no option can be signed, the lookup error is still reported.
|
|
30
|
+
|
|
31
|
+
- [#830](https://github.com/nansen-ai/nansen-cli/pull/830) [`da57038`](https://github.com/nansen-ai/nansen-cli/commit/da570383b2d81c2c9e92ba090d8dcccb3f2601de) Thanks [@omerbek](https://github.com/omerbek)! - Report the original API error when a profiler trace's root lookup fails instead of returning a successful empty graph. Keep later branch lookups best-effort after a successful root lookup.
|
|
32
|
+
|
|
33
|
+
## 2.5.0
|
|
34
|
+
|
|
35
|
+
### Minor Changes
|
|
36
|
+
|
|
37
|
+
- [#801](https://github.com/nansen-ai/nansen-cli/pull/801) [`c7446fb`](https://github.com/nansen-ai/nansen-cli/commit/c7446fb17e076d2cd2731b40efe3d58ffef7e280) Thanks [@kome12](https://github.com/kome12)! - `nansen alerts create` and `nansen alerts update` accept the webhook signing secret from `--webhook-secret-stdin` (pipe or redirected file) or the `NANSEN_WEBHOOK_SECRET` environment variable, so it no longer has to appear on the command line, in shell history or in the process list. `--webhook-secret` still works; it cannot be combined with `--webhook-secret-stdin`, and either flag overrides the environment variable, which is read only when `--webhook` is given. `--webhook-secret` with no value or an empty value is now rejected instead of being silently ignored.
|
|
38
|
+
|
|
39
|
+
- [#767](https://github.com/nansen-ai/nansen-cli/pull/767) [`f5d9331`](https://github.com/nansen-ai/nansen-cli/commit/f5d93318ddf539531ac1ae237d049f9d4238c1bc) Thanks [@Kewe63](https://github.com/Kewe63)! - Add non-consuming `--dry-run` previews and interactive confirmation guards to limit-order create and cancel, with `--yes`/`-y` and `NANSEN_YES=1` prompt bypasses.
|
|
40
|
+
|
|
41
|
+
- [#809](https://github.com/nansen-ai/nansen-cli/pull/809) [`a69dc08`](https://github.com/nansen-ai/nansen-cli/commit/a69dc086dd070580318ff3b07634c42508c8208f) Thanks [@kome12](https://github.com/kome12)! - `perp order`, `perp close`, `perp cancel` and `perp leverage` now accept `--dry-run`, which runs the normal validation, prints the plan (coin, side, rounded size, price and type, estimated notional, leverage, builder fee) and exits 0 without signing or submitting anything. No wallet password is needed for a dry run, and the one-time builder-fee approval is not submitted.
|
|
42
|
+
|
|
43
|
+
These four commands now ask for confirmation before signing when stdin is an interactive terminal, the same way `trade execute` and `bridge execute` do. Answering anything but `y` exits 1 with nothing signed. `--yes`, `-y` or `NANSEN_YES=1` skips the question. **Scripts and agents whose stdin is not a terminal (pipes, CI, agent shells) see no change:** the commands submit without asking, as before, and `--yes` is a no-op there. A script that runs these commands from an interactive terminal, or an agent that runs them under a pseudo-terminal, will now be asked; add `--yes` or set `NANSEN_YES=1` to keep the old behaviour.
|
|
44
|
+
|
|
45
|
+
### Patch Changes
|
|
46
|
+
|
|
47
|
+
- [#811](https://github.com/nansen-ai/nansen-cli/pull/811) [`c1a9e39`](https://github.com/nansen-ai/nansen-cli/commit/c1a9e39892183227d1e9b66891fe6b4aee2a46c9) Thanks [@Ravan002](https://github.com/Ravan002)! - An API error response whose body is the JSON value `null` is now reported as a normal API error for its status (and retried when the status is retryable) instead of crashing with `Cannot read properties of null (reading 'message')`.
|
|
48
|
+
|
|
49
|
+
- [#817](https://github.com/nansen-ai/nansen-cli/pull/817) [`a732073`](https://github.com/nansen-ai/nansen-cli/commit/a7320733580b2fa860feb5e17db0c5ae19948b59) Thanks [@0xcfloki](https://github.com/0xcfloki)! - ENS names now still resolve when the ensideas API is unavailable. The on-chain fallback was pinned to `eth.llamarpc.com`, which answers HTTP 525, so any ensideas outage failed every `.eth` lookup. It now uses the same Ethereum RPC as the rest of the CLI (`NANSEN_EVM_RPC`, or the shared default), and keeps the port and query string of a custom RPC URL.
|
|
50
|
+
|
|
51
|
+
- [#807](https://github.com/nansen-ai/nansen-cli/pull/807) [`a38b217`](https://github.com/nansen-ai/nansen-cli/commit/a38b217e11c4c0adcfc1e3dc42440223a459d43f) Thanks [@Snan0M](https://github.com/Snan0M)! - A `--paginate` result that mixes cached and live pages is no longer reported as a cache hit. The merged result kept page 1's `_meta.fromCache`/`cacheAge`, and telemetry's `from_cache` followed page 1's marker or the last page's cache state; both now say cached only when every page came from the cache.
|
|
52
|
+
|
|
53
|
+
- [#814](https://github.com/nansen-ai/nansen-cli/pull/814) [`05fd62a`](https://github.com/nansen-ai/nansen-cli/commit/05fd62ad6e2e42527ee7e8d365286d58570f1470) Thanks [@kome12](https://github.com/kome12)! - `nansen perp close --dry-run` now exits 1 with `NO_OPEN_POSITION` when the wallet has no open position in that coin, instead of printing a plan and exiting 0 for a close Hyperliquid would reject. The error is retryable, because the positions data can lag a fill that just happened. A real close still goes to Hyperliquid; when it prompts, its plan shows a warning instead. If positions cannot be loaded, or the data for that coin is malformed, the dry run still prints the plan with "Open position: could not be loaded".
|
|
54
|
+
|
|
55
|
+
- [#797](https://github.com/nansen-ai/nansen-cli/pull/797) [`585ac67`](https://github.com/nansen-ai/nansen-cli/commit/585ac674b7cb46d1d5d851eb7afb499c0abdf47c) Thanks [@kome12](https://github.com/kome12)! - `perp positions` now shows each position's leverage and margin mode (`lev=1x cross`) next to the liquidation price, so a liquidation price on a low-leverage cross-margin position has context.
|
|
56
|
+
|
|
57
|
+
- [#789](https://github.com/nansen-ai/nansen-cli/pull/789) [`5edcb66`](https://github.com/nansen-ai/nansen-cli/commit/5edcb662e7e0496d5f752f0a831feb3d0dbfc646) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Show API warning headers on stderr and preserve them on cached responses.
|
|
58
|
+
|
|
59
|
+
- [#804](https://github.com/nansen-ai/nansen-cli/pull/804) [`ca8b77d`](https://github.com/nansen-ai/nansen-cli/commit/ca8b77dd10d437ac0b81cbb6583983d72500e86e) Thanks [@Ravan002](https://github.com/Ravan002)! - `wallet create` now rejects the names `config` (any case), `wc` and `walletconnect`. A wallet named `config` was saved as `wallets/config.json` and then overwritten by the wallet settings, losing its keys; `wc` and `walletconnect` are read as WalletConnect by `wallet send` and limit orders.
|
|
60
|
+
|
|
61
|
+
- [#803](https://github.com/nansen-ai/nansen-cli/pull/803) [`622b684`](https://github.com/nansen-ai/nansen-cli/commit/622b6846ac0a9a6cb47834a81af0d1ce0338ddb4) Thanks [@kome12](https://github.com/kome12)! - Response cache (`--cache`) no longer grows without bound. After a cached write, entries older than 24 hours (or the longest `--cache-ttl` that run reads with, if longer) and temp files left by an interrupted write are removed, at most once an hour per run. `nansen cache clear` also removes those leftover temp files, but never one younger than 10 minutes, which may be a write in progress.
|
|
62
|
+
|
|
63
|
+
- [#802](https://github.com/nansen-ai/nansen-cli/pull/802) [`28483ea`](https://github.com/nansen-ai/nansen-cli/commit/28483ea8f5bc0d98628ec552d6e5cf99a3023ae6) Thanks [@kome12](https://github.com/kome12)! - `nansen schema` no longer lists `research points leaderboard`, whose endpoint was removed, and now lists `--stream` (NDJSON output, alias `-s`) under global options. The points command is also left out of `nansen research` help and "did you mean" suggestions. Calling it, including with `--help`, still returns `COMMAND_UNAVAILABLE`.
|
|
64
|
+
|
|
65
|
+
- [#813](https://github.com/nansen-ai/nansen-cli/pull/813) [`58ee954`](https://github.com/nansen-ai/nansen-cli/commit/58ee954c59fdaaef61554e5feef489e3e72b83d0) Thanks [@0xcfloki](https://github.com/0xcfloki)! - `wallet send` on Solana no longer tells you to top up your wallet when a SOL send fails because the recipient would hold less than the rent-exempt minimum. Solana rejects a transfer that leaves a new address below about 0.00089 SOL, naming that account by its index; any account other than your wallet now gets an error that says so and gives the minimum, instead of the insufficient-balance advice meant for the wallet itself.
|
|
66
|
+
|
|
67
|
+
- [#812](https://github.com/nansen-ai/nansen-cli/pull/812) [`e2331f7`](https://github.com/nansen-ai/nansen-cli/commit/e2331f763f02c710fbd30ee41fbc585a44457ba5) Thanks [@Ravan002](https://github.com/Ravan002)! - `--sort` now rejects extra colon segments (`--sort value_usd:desc:asc`) instead of silently dropping them, and `--order-by` rejects anything that is not a JSON array of `{ "field", "direction" }` objects instead of sending it to the API unchecked.
|
|
68
|
+
|
|
69
|
+
- [#805](https://github.com/nansen-ai/nansen-cli/pull/805) [`11558d5`](https://github.com/nansen-ai/nansen-cli/commit/11558d57ff4a52da3ef6a1856d3119a0df5dafe1) Thanks [@Ravan002](https://github.com/Ravan002)! - Telemetry events no longer include positional values in the command path. `nansen search vitalik.eth` was reported as `/search/vitalik.eth` and `nansen 0x…` as `/0x…`; only command and subcommand names the CLI defines are sent now, and an unknown command is reported as `unknown`.
|
|
70
|
+
|
|
71
|
+
- [#808](https://github.com/nansen-ai/nansen-cli/pull/808) [`5bb3e75`](https://github.com/nansen-ai/nansen-cli/commit/5bb3e7546d974bd311825760dcd7270e1fb41895) Thanks [@kome12](https://github.com/kome12)! - Telemetry events now list only option names the CLI defines for the command being run (plus global options and built-in switches such as `--help`). Any other name is sent as `--<unknown>`. Previously a value that starts with `-` and is passed as a separate argument, as in `--webhook-secret -abc123`, was parsed as a flag and its text was sent as a flag name.
|
|
72
|
+
|
|
73
|
+
- [#810](https://github.com/nansen-ai/nansen-cli/pull/810) [`8703d39`](https://github.com/nansen-ai/nansen-cli/commit/8703d39aa489c0927b565b079a1cc9dfc0cce7de) Thanks [@kome12](https://github.com/kome12)! - `trade execute`: when the standard execution route rejects a swap before broadcasting it (quote expired, simulation failed, minimum return not reached, insufficient balance, input transfer failed), the CLI now releases the quote and tries the next candidate quote instead of aborting and marking the quote spent. Every other error response still stops the run.
|
|
74
|
+
|
|
75
|
+
- [#818](https://github.com/nansen-ai/nansen-cli/pull/818) [`3f5f059`](https://github.com/nansen-ai/nansen-cli/commit/3f5f059e4e6366ac6f9ea6a527ece3272bef9213) Thanks [@erkancamli](https://github.com/erkancamli)! - `wallet send` on EVM keeps the leading zero bytes of the recipient (or token contract) address in the signed transaction. They were stripped, so a send to an address such as `0x00000000219ab540356cBB839Cbe05303d7705Fa`, or of a token such as TrueUSD (`0x0000000000085d4780B73119b644AE5ecd22b376`), was rejected by the node, and a send to the zero address was signed as a contract creation.
|
|
76
|
+
|
|
77
|
+
- [#798](https://github.com/nansen-ai/nansen-cli/pull/798) [`9457798`](https://github.com/nansen-ai/nansen-cli/commit/9457798f1c69d7cc8e9753c07a8eed0bcd379e17) Thanks [@kome12](https://github.com/kome12)! - `wallet send --token` now accepts `USDC` and `USDT` on every chain it supports (`evm`/`ethereum`, `base`, `solana`) instead of failing with "Invalid params", and rejects any other non-address value with the accepted symbols. `wallet create --help`, `wallet send --help` and `nansen schema` now list every option (`--name`, `--provider`, `--human`, `--token`, `--wallet`, `--dry-run`) and explain that `wallet create` reads the password from `NANSEN_WALLET_PASSWORD` (it prompts only with `--human`) and saves it to the OS keychain or the `.credentials` fallback.
|
|
78
|
+
|
|
79
|
+
- [#806](https://github.com/nansen-ai/nansen-cli/pull/806) [`3f61a36`](https://github.com/nansen-ai/nansen-cli/commit/3f61a36e151f2f12dcdca7828819e63c260f2540) Thanks [@Ravan002](https://github.com/Ravan002)! - WalletConnect x402 payments now bound the authorization's `validBefore`. A `maxTimeoutSeconds` sent as a string (`"60"`) was concatenated onto the current time, giving a `validBefore` thousands of years out, and a large number was used as is; the timeout is now read as a whole number of seconds and capped at one hour, the window the local signer uses.
|
|
80
|
+
|
|
3
81
|
## 2.4.0
|
|
4
82
|
|
|
5
83
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -11,9 +11,11 @@ Use it for both analytics and execution: `nansen research ...` returns structure
|
|
|
11
11
|
|
|
12
12
|
```bash
|
|
13
13
|
npm install -g nansen-cli
|
|
14
|
-
npx skills add nansen-ai/nansen-cli #
|
|
14
|
+
npx -y skills add nansen-ai/nansen-cli --skill "*" -y # install every agent skill, no prompts
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
+
Without `--skill "*" -y`, `skills add` opens a picker: space selects a skill, enter confirms.
|
|
18
|
+
|
|
17
19
|
## Feedback
|
|
18
20
|
|
|
19
21
|
Send product feedback to Nansen with your configured API key or login session:
|
|
@@ -141,8 +143,8 @@ The check calls `tools/list` for reachability, then calls the paid `nansen_score
|
|
|
141
143
|
|
|
142
144
|
```
|
|
143
145
|
nansen research <category> <subcommand> [options]
|
|
144
|
-
nansen agent "<question>" # AI research agent (
|
|
145
|
-
nansen agent "<question>" --expert # deeper analysis (
|
|
146
|
+
nansen agent "<question>" # AI research agent (100 credits)
|
|
147
|
+
nansen agent "<question>" --expert # deeper analysis (400 credits)
|
|
146
148
|
nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
|
|
147
149
|
nansen trade execute --quote <quoteId>
|
|
148
150
|
nansen wallet <subcommand> [options]
|
|
@@ -154,13 +156,13 @@ nansen cache stats # what the local caches hold (no API key n
|
|
|
154
156
|
|
|
155
157
|
**Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`
|
|
156
158
|
|
|
157
|
-
The points leaderboard API has been removed. `nansen research points leaderboard` and the legacy command `nansen points leaderboard` return `success: false` with code `COMMAND_UNAVAILABLE` and exit status `1`, without making an API request.
|
|
159
|
+
The points leaderboard API has been removed. `nansen research points leaderboard` and the legacy command `nansen points leaderboard` return `success: false` with code `COMMAND_UNAVAILABLE` and exit status `1`, without making an API request (with `--help` too). The command is no longer listed in `nansen schema`, help or completions.
|
|
158
160
|
|
|
159
161
|
**Direct research subcommands:**
|
|
160
|
-
- `nansen research chain-rank [--
|
|
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
|
|
@@ -171,6 +173,16 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
|
|
|
171
173
|
|
|
172
174
|
**Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send`, `forget-password`, `secure` — local or Privy server-side wallets (EVM + Solana).
|
|
173
175
|
|
|
176
|
+
**Alerts:** `list`, `create`, `update`, `toggle`, `delete` — smart alerts delivered to Telegram, Slack, Discord or a webhook. Give a webhook's signing secret through stdin or the environment, not on the command line, so it stays out of shell history and the process list:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
nansen alerts create --name 'ETH SM inflow' --type sm-token-flows --chains ethereum --inflow-1h-min 1000000 \
|
|
180
|
+
--webhook https://example.com/hook --webhook-secret-stdin < webhook-secret.txt
|
|
181
|
+
NANSEN_WEBHOOK_SECRET="$(cat webhook-secret.txt)" nansen alerts update <id> --webhook https://example.com/hook
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
`--webhook-secret <secret>` still works. It cannot be combined with `--webhook-secret-stdin`, and either flag overrides `NANSEN_WEBHOOK_SECRET`, which is read only when `--webhook` is given. Alerts output redacts channel credentials unless you pass `--reveal`.
|
|
185
|
+
|
|
174
186
|
Run `nansen schema --pretty` for the full subcommand and field reference.
|
|
175
187
|
|
|
176
188
|
## MCP
|
|
@@ -265,23 +277,29 @@ nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
|
|
|
265
277
|
|
|
266
278
|
### Before broadcasting
|
|
267
279
|
|
|
268
|
-
`trade execute` and `
|
|
280
|
+
`trade execute`, `bridge execute`, and the signing limit-order operations (`limit-order create` and `limit-order cancel`) accept:
|
|
269
281
|
|
|
270
282
|
```bash
|
|
271
283
|
nansen trade execute --quote <quoteId> --dry-run # validate + print the plan, broadcast nothing
|
|
272
284
|
nansen trade execute --quote <quoteId> --yes # skip the confirmation prompt (also: -y)
|
|
285
|
+
nansen trade limit-order create ... --dry-run # preview intent; no API request or signature
|
|
286
|
+
nansen trade limit-order cancel --order <id> --dry-run # does not request/consume a cancellation tx
|
|
273
287
|
```
|
|
274
288
|
|
|
275
289
|
`--dry-run` runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints what *would* be sent (chain, tokens, amounts, recipient, approvals, fees); and stops before wallet credentials, signing, or broadcast — no wallet password needed, the quote stays usable, exit code 0. Real execution still resolves and revalidates the live signer before signing.
|
|
276
290
|
|
|
277
291
|
On EVM, both commands refuse a transaction whose worst-case gas cost (fee cap × gas limit) is above 1 ETH, before anything is signed, approvals included. That is a backstop against an anomalous quote, the same kind of cap geth and reth apply to `eth_sendTransaction`. `--max-tx-fee <eth>` changes it, and `--max-tx-fee 0` turns it off. WalletConnect transactions are not checked, since the wallet shows the fee before signing.
|
|
278
292
|
|
|
279
|
-
|
|
293
|
+
For limit orders, `--dry-run` is a non-consuming intent preview built from locally validated arguments and the wallet's public address. It returns before limit-order authentication, custom-token metadata RPC lookups, transaction crafting, transaction signing, or final submission. Create preview does not submit an order; cancel preview does not request or consume the API's one-time cancellation transaction. Real execution performs the existing transaction and outcome validation after acknowledgement.
|
|
294
|
+
|
|
295
|
+
When stdin is an interactive terminal, each guarded command prints its plan and asks for confirmation first (`Broadcast this transaction?`, `Create this limit order?`, or `Cancel this limit order?`); anything but `y`/`yes` aborts with exit code 1 and nothing signed. `--yes`, `-y`, or `NANSEN_YES=1` skips only the question. **When stdin is not a terminal — agents, CI, pipes — nothing changes: the command proceeds without prompting**, and `--yes` is accepted as a no-op so it is always safe to pass.
|
|
296
|
+
|
|
297
|
+
To make an agent stop for your go-ahead, set `NANSEN_REQUIRE_CONFIRM=1` in its environment. Then, when stdin is not a terminal, every guarded command (`trade execute`, `bridge execute`, `trade limit-order create`/`cancel`, `perp order`/`close`/`cancel`/`leverage`) run without `--yes` or `NANSEN_YES=1` fails with exit code 1 and code `CONFIRMATION_REQUIRED` before it makes any request or signs anything. `--dry-run` still previews. Unset (the default), behaviour is unchanged.
|
|
280
298
|
|
|
281
299
|
| Exit code | Meaning |
|
|
282
300
|
|-----------|---------|
|
|
283
301
|
| `0` | Broadcast succeeded, or the dry run completed |
|
|
284
|
-
| `1` | Declined at the confirmation prompt, or the execution failed |
|
|
302
|
+
| `1` | Declined at the confirmation prompt, refused by `NANSEN_REQUIRE_CONFIRM`, or the execution failed |
|
|
285
303
|
|
|
286
304
|
Amounts are in base units (lamports, wei) by default — use `--amount-unit token|usd|percent` for friendlier inputs. Common symbols (`SOL`, `ETH`, `USDC`, `USDT`) resolve automatically. A wallet is required — set one with `nansen wallet default <name>`.
|
|
287
305
|
|
|
@@ -305,26 +323,28 @@ nansen trade limit-order update --order <orderId> --trigger-price 85
|
|
|
305
323
|
|
|
306
324
|
`--amount` is in token units (`1.5` = 1.5 SOL). `--slippage-bps` is basis points (`300` = 3%, `100` = 1%); omit for auto. Minimum order value ~$10 (server-enforced). Local, Privy, and WalletConnect wallets all work.
|
|
307
325
|
|
|
326
|
+
Add `--dry-run` to `create` or `cancel` for a no-API, no-signature intent preview. In an interactive terminal these two commands otherwise ask for confirmation; pass `--yes`/`-y` (or set `NANSEN_YES=1`) to skip the prompt. Non-TTY automation remains unprompted.
|
|
327
|
+
|
|
308
328
|
For EVM chains, there's no native limit-order surface — pair an external venue's resting order with a `common-token-transfer` smart alert on the settlement wallet as a best-effort fill signal. See the `nansen-limit-orders` skill for details.
|
|
309
329
|
|
|
310
330
|
## Perpetuals
|
|
311
331
|
|
|
312
|
-
Hyperliquid perpetual trading via `nansen perp`. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading (requires an EVM wallet). Select the asset with `--
|
|
332
|
+
Hyperliquid perpetual trading via `nansen perp`. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading (requires an EVM wallet). Select the asset with `--symbol` (`--coin` is accepted as an alias).
|
|
313
333
|
|
|
314
334
|
```bash
|
|
315
335
|
nansen perp meta --filter ETH # list assets + max leverage
|
|
316
|
-
nansen perp order --
|
|
317
|
-
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 \
|
|
318
338
|
--take-profit 90000 --stop-loss 98000
|
|
319
|
-
nansen perp close --
|
|
320
|
-
nansen perp cancel --
|
|
321
|
-
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
|
|
322
342
|
nansen perp transfer --direction spot-to-perp --amount 25 # Spot<->Perps (or perp-to-spot)
|
|
323
343
|
nansen perp positions
|
|
324
344
|
nansen perp account # value, unrealized PnL, margin, spot USDC
|
|
325
345
|
```
|
|
326
346
|
|
|
327
|
-
`--side` is `buy`/`long` or `sell`/`short` to open (`buy`/`sell` to close); `--tif` is `Gtc`/`Ioc`/`Alo`; `--slippage` is a decimal in `[0,1]`; `--leverage` is a whole integer capped at the asset max. Perp orders are irreversible once signed. USDC sent to a wallet via Hyperliquid's **Send** lands in the **Spot** balance (shown as `Spot USDC`); move it to Perps with `perp transfer` before trading. See the `nansen-trading` skill for details.
|
|
347
|
+
`--side` is `buy`/`long` or `sell`/`short` to open (`buy`/`sell` to close); `--tif` is `Gtc`/`Ioc`/`Alo`; `--slippage` is a decimal in `[0,1]`; `--leverage` is a whole integer capped at the asset max. Perp orders are irreversible once signed: add `--dry-run` to `order`, `close`, `cancel` or `leverage` to print the plan without signing anything. In an interactive terminal these four commands ask for confirmation first (`--yes`/`-y` or `NANSEN_YES=1` skips it); off a terminal they submit without asking, as before. USDC sent to a wallet via Hyperliquid's **Send** lands in the **Spot** balance (shown as `Spot USDC`); move it to Perps with `perp transfer` before trading. `perp positions` prints each position's leverage and margin mode next to Hyperliquid's liquidation price (`lev=1x cross liq=1.37`). On cross margin the liquidation price depends on the whole account's equity, so even a 1x position can have one close to the market price; `liq=n/a` means the exchange reports no liquidation price. See the `nansen-trading` skill for details.
|
|
328
348
|
|
|
329
349
|
## Bridge
|
|
330
350
|
|
|
@@ -348,11 +368,18 @@ nansen wallet create --name my-wallet --provider privy # server-side via Privy
|
|
|
348
368
|
nansen wallet list
|
|
349
369
|
nansen wallet default <name>
|
|
350
370
|
nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
|
|
351
|
-
nansen wallet
|
|
371
|
+
nansen wallet send --to <addr> --amount 25 --chain base --token USDC # USDC, USDT or a token address
|
|
372
|
+
nansen wallet secure # move a password from .credentials or the env var into the OS keychain
|
|
352
373
|
nansen wallet forget-password # drop the saved password from every store
|
|
353
374
|
```
|
|
354
375
|
|
|
355
|
-
**Local wallets** are password
|
|
376
|
+
**Local wallets** are encrypted with a password of at least 12 characters. `wallet create` reads it from `NANSEN_WALLET_PASSWORD`, or reuses the password an earlier `wallet create` saved, and does not prompt; without one the command fails with `PASSWORD_REQUIRED` (agents: ask the user for a password, never make one up). When no password is set or saved, pass `--human` to be prompted for one in an interactive terminal. On success the CLI saves the password to the OS keychain, or to `~/.nansen/wallets/.credentials` (plaintext) when no keychain is available, and later wallet commands read it from there. If neither can be written, the wallet is still created but the password is not saved: keep `NANSEN_WALLET_PASSWORD` set for every later wallet command. `nansen wallet secure` moves a password from that file or the env var into the keychain.
|
|
377
|
+
|
|
378
|
+
```bash
|
|
379
|
+
NANSEN_WALLET_PASSWORD='<password-from-user>' nansen wallet create --name my-wallet
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
`wallet send --token` takes `USDC`, `USDT` or a token contract (EVM) or mint (Solana) address; omit it to send the native currency. `--chain` is `evm` (Ethereum), `ethereum`, `base` or `solana`.
|
|
356
383
|
|
|
357
384
|
**Privy wallets** are server-side — no password, no local key storage. Requires `PRIVY_APP_ID` and `PRIVY_APP_SECRET` env vars. Get credentials at [dashboard.privy.io](https://dashboard.privy.io).
|
|
358
385
|
|
|
@@ -446,7 +473,7 @@ that cannot change the command line.
|
|
|
446
473
|
|
|
447
474
|
With `--cache` on, every read the CLI makes through the Nansen API client is
|
|
448
475
|
cached — all of `nansen research ...`, plus `alerts list` and `alerts get`.
|
|
449
|
-
Never cached: `account`, `web search`,
|
|
476
|
+
Never cached: `account`, `web search`, the `alerts`
|
|
450
477
|
create/update/toggle/delete commands, `agent`, every `trade`, `bridge`, `wallet`
|
|
451
478
|
and `mcp` command, and `perp` trading. The analytics commands `perp screener`
|
|
452
479
|
and `perp leaderboard` are cached.
|
|
@@ -583,6 +610,8 @@ Every failure exits 1. The full list of codes is in [docs/error-codes.md](docs/e
|
|
|
583
610
|
|
|
584
611
|
Research commands check their options before calling the API: an unknown or ignored option, a missing required option, a bad value or a chain the endpoint does not accept fails locally with the option named. `nansen schema <command>` lists each command's options and `supportedChains`.
|
|
585
612
|
|
|
613
|
+
`nansen research profiler trace` fails with the original API error if the root lookup fails, rather than reporting an empty graph as a success. Once the root lookup succeeds, later lookups remain best-effort: a failed branch is skipped while traversal continues through the others.
|
|
614
|
+
|
|
586
615
|
**Error metadata.** When the API reports them, `details` carries:
|
|
587
616
|
|
|
588
617
|
| Field | Meaning |
|
|
@@ -603,7 +632,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
|
|
|
603
632
|
| MCP client lists tools but paid calls fail | Run `npx -y nansen-cli mcp verify` with the saved key or `NANSEN_API_KEY`, and ensure that same key is in the client's `NANSEN-API-KEY` header |
|
|
604
633
|
| Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
|
|
605
634
|
| Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
|
|
606
|
-
| `perp` _trading_ prints the usage banner | Trading needs `--
|
|
635
|
+
| `perp` _trading_ prints the usage banner | Trading needs `--symbol BTC` (`--coin` also works); see the Perpetuals section. |
|
|
607
636
|
| `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |
|
|
608
637
|
| Huge JSON response | Use `--fields` to select columns. |
|
|
609
638
|
|
package/docs/error-codes.md
CHANGED
|
@@ -38,6 +38,7 @@ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could
|
|
|
38
38
|
| --- | --- | --- |
|
|
39
39
|
| `INVALID_PARAMS` | An option or request field has an invalid value, or the command does not accept it. `details.errors[]` names each field. | No |
|
|
40
40
|
| `MISSING_PARAM` | A required option or request field is missing. `details.errors[]` names each field. | No |
|
|
41
|
+
| `NOT_A_PIPE` | An option that reads a secret from stdin (`--api-key-stdin`, `--webhook-secret-stdin`) was used with a terminal on stdin. Pipe the value or redirect a file. | No |
|
|
41
42
|
| `MISSING_ARGS` | A trade or wallet command is missing required arguments; the message shows the usage. | No |
|
|
42
43
|
| `INVALID_INPUT` | A trade, bridge, perp or wallet argument failed local validation. | No |
|
|
43
44
|
| `INVALID_ADDRESS` | An address does not match the format of the selected chain. | No |
|
|
@@ -184,6 +185,7 @@ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could
|
|
|
184
185
|
| `RPC_JSON_ERROR` | The RPC answered with a body that is not JSON. | No |
|
|
185
186
|
| `RPC_NETWORK_ERROR` | The CLI could not reach the RPC. | Yes |
|
|
186
187
|
| `CONFIRMATION_DECLINED` | The confirmation prompt was declined; nothing was signed. | No |
|
|
188
|
+
| `CONFIRMATION_REQUIRED` | NANSEN_REQUIRE_CONFIRM is set and stdin is not a terminal; nothing was signed. Pass --yes to proceed or --dry-run to preview. | No |
|
|
187
189
|
| `CONFIRMATION_UNAVAILABLE` | Confirmation is required but no terminal is available. Pass --yes to confirm. | No |
|
|
188
190
|
|
|
189
191
|
### Bridge
|
|
@@ -208,6 +210,7 @@ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could
|
|
|
208
210
|
| `BUILDER_FEE_TOO_HIGH` | The builder fee is above the allowed ceiling. | No |
|
|
209
211
|
| `BUILDER_FEE_UNAVAILABLE` | The builder fee could not be read or approved. | No |
|
|
210
212
|
| `META_UNAVAILABLE` | Hyperliquid asset metadata is not available. | Yes |
|
|
213
|
+
| `NO_OPEN_POSITION` | perp close --dry-run found no open position in that coin, so a real close would be rejected. The positions data can lag a fill that just happened, so retry after a few seconds if the position was opened moments ago. | Yes |
|
|
211
214
|
| `SANCTIONED` | The address failed sanctions screening. | No |
|
|
212
215
|
| `SCREENING_UNAVAILABLE` | Sanctions screening is not available, so the action was refused. | Yes |
|
|
213
216
|
| `UNSUPPORTED_NETWORK` | The network is not supported for this perp action. | No |
|
package/package.json
CHANGED
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;
|
|
@@ -37,10 +37,10 @@ Public agent fast/expert and direct API commands accept the selected nansen:api
|
|
|
37
37
|
```bash
|
|
38
38
|
nansen agent "What are top smart money tokens on Solana today and why?"
|
|
39
39
|
nansen agent "Analyse wallet 0x123... -- is this a smart trader?"
|
|
40
|
-
nansen agent "..." --expert # deeper analysis,
|
|
40
|
+
nansen agent "..." --expert # deeper analysis, 400 credits
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
Cost:
|
|
43
|
+
Cost: 100 credits (fast) / 400 credits (expert)
|
|
44
44
|
|
|
45
45
|
## Use direct CLI commands when
|
|
46
46
|
|
|
@@ -58,7 +58,7 @@ Cost: 5-50 credits per call
|
|
|
58
58
|
|
|
59
59
|
## Anti-patterns
|
|
60
60
|
|
|
61
|
-
- Don't use `nansen agent` for simple data fetches --
|
|
61
|
+
- Don't use `nansen agent` for simple data fetches -- it costs more than a direct call and returns prose, not data
|
|
62
62
|
- Don't use raw CLI for open-ended analysis -- returns data, not interpretation
|
|
63
63
|
- Don't chain 3+ agent calls -- get raw data via CLI, call agent once for synthesis
|
|
64
64
|
|
|
@@ -85,11 +85,13 @@ If the user prefers localtunnel or can't install ngrok, proceed with localtunnel
|
|
|
85
85
|
|
|
86
86
|
### Step 1: Generate a webhook secret
|
|
87
87
|
|
|
88
|
+
Write the secret straight to a file that only the user can read, so it never appears in the terminal, the shell history or the transcript:
|
|
89
|
+
|
|
88
90
|
```bash
|
|
89
|
-
node -e "
|
|
91
|
+
(umask 077 && node -e "process.stdout.write(require('crypto').randomBytes(32).toString('hex'))" > nansen-webhook-secret.txt)
|
|
90
92
|
```
|
|
91
93
|
|
|
92
|
-
|
|
94
|
+
The server and the alert both read it from this file (`WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)"` for the server, `--webhook-secret-stdin < nansen-webhook-secret.txt` for `nansen alerts`). **Never log, echo or paste the secret.**
|
|
93
95
|
|
|
94
96
|
### Step 2: Write the webhook receiver script
|
|
95
97
|
|
|
@@ -257,7 +259,7 @@ server.listen(PORT, '127.0.0.1', () => {
|
|
|
257
259
|
Start the server:
|
|
258
260
|
|
|
259
261
|
```bash
|
|
260
|
-
WEBHOOK_SECRET=
|
|
262
|
+
WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs
|
|
261
263
|
```
|
|
262
264
|
|
|
263
265
|
Then start a public tunnel so Nansen's servers can reach it.
|
|
@@ -287,9 +289,9 @@ Prints a URL like `https://xxx.loca.lt`. The webhook URL is `https://xxx.loca.lt
|
|
|
287
289
|
**Do NOT create or modify any alerts.** Instead, print a clear summary for the user explaining what was set up and what they need to do next.
|
|
288
290
|
|
|
289
291
|
The summary MUST include:
|
|
290
|
-
1. Confirmation of what was created (the server script path and the
|
|
291
|
-
2. The commands to start the server and tunnel (
|
|
292
|
-
3. The exact `nansen alerts create` or `nansen alerts update` command they should run, with
|
|
292
|
+
1. Confirmation of what was created (the server script path and the secret file path; never the secret itself)
|
|
293
|
+
2. The commands to start the server and tunnel (reading the secret from the file)
|
|
294
|
+
3. The exact `nansen alerts create` or `nansen alerts update` command they should run, with `--webhook` filled in with the tunnel URL and `--webhook-secret-stdin < nansen-webhook-secret.txt` for the secret (do not put the secret on the command line with `--webhook-secret`; it lands in shell history and the process list) — but leave the alert-specific flags (`--name`, `--type`, `--chains`, etc.) as placeholders for the user to fill in
|
|
293
295
|
4. A reminder that the server and tunnel must be running before the alert is created (Nansen validates the webhook endpoint on creation)
|
|
294
296
|
5. A note that tunnel URLs are ephemeral and will change on restart
|
|
295
297
|
|
|
@@ -299,12 +301,13 @@ Example summary format:
|
|
|
299
301
|
## Webhook listener ready
|
|
300
302
|
|
|
301
303
|
**Server script:** ./nansen-webhook-server.mjs
|
|
304
|
+
**Secret file:** ./nansen-webhook-secret.txt (readable only by you)
|
|
302
305
|
**Port:** 9477
|
|
303
306
|
|
|
304
307
|
### To start receiving alerts:
|
|
305
308
|
|
|
306
309
|
1. Start the server (keep this terminal open):
|
|
307
|
-
WEBHOOK_SECRET=
|
|
310
|
+
WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs
|
|
308
311
|
|
|
309
312
|
2. In a new terminal, start the tunnel:
|
|
310
313
|
ngrok http 9477 # recommended
|
|
@@ -316,13 +319,13 @@ Example summary format:
|
|
|
316
319
|
--type <sm-token-flows|common-token-transfer|smart-contract-call> \
|
|
317
320
|
--chains <chains> \
|
|
318
321
|
--webhook 'https://<your-tunnel-url>/webhook' \
|
|
319
|
-
--webhook-secret
|
|
320
|
-
[type-specific flags...]
|
|
322
|
+
--webhook-secret-stdin \
|
|
323
|
+
[type-specific flags...] < nansen-webhook-secret.txt
|
|
321
324
|
|
|
322
325
|
Or add the webhook to an existing alert:
|
|
323
326
|
nansen alerts update <alert-id> \
|
|
324
327
|
--webhook 'https://<your-tunnel-url>/webhook' \
|
|
325
|
-
--webhook-secret
|
|
328
|
+
--webhook-secret-stdin < nansen-webhook-secret.txt
|
|
326
329
|
|
|
327
330
|
Note: The tunnel URL changes each time you restart. Update the alert
|
|
328
331
|
webhook URL if you restart the tunnel.
|
|
@@ -343,11 +346,11 @@ See `nansen alerts create --help` for full flag reference per alert type.
|
|
|
343
346
|
|
|
344
347
|
| Symptom | Fix |
|
|
345
348
|
|---|---|
|
|
346
|
-
| "Invalid signature" on every request | Ensure the **
|
|
349
|
+
| "Invalid signature" on every request | Ensure the server and the alert read the **same secret** (the same `nansen-webhook-secret.txt`). Re-run `nansen alerts update <id> --webhook '<url>/webhook' --webhook-secret-stdin < nansen-webhook-secret.txt` after changing it |
|
|
347
350
|
| "Failed to send welcome message" on alert create | Start the server and tunnel **before** creating the alert |
|
|
348
351
|
| No alerts arriving | Check `nansen alerts list --table` — is the alert enabled? Is the webhook URL correct (includes `/webhook`)? |
|
|
349
352
|
| Tunnel URL expired / tunnel died | Restart the tunnel, get the new URL, then `nansen alerts update <id> --webhook '<new-url>/webhook'`. If this keeps happening, switch from localtunnel to ngrok. |
|
|
350
|
-
| Port already in use | Set a different port: `PORT=9478 WEBHOOK_SECRET=
|
|
353
|
+
| Port already in use | Set a different port: `PORT=9478 WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs` and update the tunnel accordingly |
|
|
351
354
|
|
|
352
355
|
## OpenClaw Integration
|
|
353
356
|
|
|
@@ -365,7 +368,7 @@ If the user is running OpenClaw locally on the same machine, the webhook server
|
|
|
365
368
|
### Start command (with OpenClaw forwarding)
|
|
366
369
|
|
|
367
370
|
```bash
|
|
368
|
-
WEBHOOK_SECRET=
|
|
371
|
+
WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" \
|
|
369
372
|
OPENCLAW_GATEWAY_URL='http://localhost:3000' \
|
|
370
373
|
OPENCLAW_AUTH_TOKEN='<token>' \
|
|
371
374
|
node nansen-webhook-server.mjs
|
|
@@ -100,11 +100,11 @@ Constraints (all enforced server-side — surface errors to the user as-is):
|
|
|
100
100
|
nansen trade limit-order list # default
|
|
101
101
|
nansen trade limit-order list --state active # only open
|
|
102
102
|
nansen trade limit-order list --state past # filled or cancelled
|
|
103
|
-
nansen trade limit-order list --
|
|
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
|
|
|
@@ -117,6 +117,17 @@ nansen trade limit-order cancel --order <orderId>
|
|
|
117
117
|
Cancelling submits a withdrawal transaction; surface the tx signature from the
|
|
118
118
|
CLI output so the user can verify on Solscan.
|
|
119
119
|
|
|
120
|
+
### Preview and confirm
|
|
121
|
+
|
|
122
|
+
`create` and `cancel` accept `--dry-run` (print the plan and exit 0; no API
|
|
123
|
+
request, no signature, nothing submitted) and `--yes`/`-y` (skip the
|
|
124
|
+
confirmation prompt, same as `NANSEN_YES=1`). The prompt only appears in an
|
|
125
|
+
interactive terminal; agents and CI run unprompted, unless the user set
|
|
126
|
+
`NANSEN_REQUIRE_CONFIRM=1`: then a non-terminal run without `--yes` fails with
|
|
127
|
+
`CONFIRMATION_REQUIRED` before any request, so show the `--dry-run` plan and
|
|
128
|
+
re-run with `--yes` only after the user approves. Use `--dry-run` to show the
|
|
129
|
+
user what will be created or cancelled before running it for real.
|
|
130
|
+
|
|
120
131
|
### Update
|
|
121
132
|
|
|
122
133
|
```bash
|
|
@@ -45,7 +45,8 @@ nansen alerts delete <id>
|
|
|
45
45
|
| `--slack` | webhook URL | optional | | |
|
|
46
46
|
| `--discord` | webhook URL | optional | | |
|
|
47
47
|
| `--webhook` | endpoint URL | optional | optional | |
|
|
48
|
-
| `--webhook-secret` | optional (webhook only) | optional | | |
|
|
48
|
+
| `--webhook-secret-stdin` | optional (webhook only) | optional | | |
|
|
49
|
+
| `--webhook-secret` | optional (webhook only; prefer `--webhook-secret-stdin`) | optional | | |
|
|
49
50
|
| `--description` | optional | optional | | |
|
|
50
51
|
| `--enabled` | | flag | flag | |
|
|
51
52
|
| `--disabled` | flag | flag | flag | |
|
|
@@ -139,6 +140,7 @@ nansen alerts create \
|
|
|
139
140
|
- Multiple channels can be combined: `--telegram 123 --slack https://... --webhook https://...`
|
|
140
141
|
- `--webhook <url>` sends a POST request with the alert payload to any HTTP/HTTPS endpoint. Useful for server deployments, Zapier, n8n, or custom integrations. The endpoint must be publicly reachable and return a 2xx response.
|
|
141
142
|
- Alert output redacts channel credentials (Slack/Discord/webhook URLs and webhook signing secrets), e.g. `https://hooks.slack.com/services/T000/****`. Webhook URLs grant post access to the channel, so keep them out of shared output; pass `--reveal` only when the full value is needed. Never pass a redacted value back to `--slack`/`--discord`/`--webhook`; the CLI rejects it.
|
|
143
|
+
- Webhook signing secret (minimum 16 characters): pipe it with `--webhook-secret-stdin < secret.txt` or set `NANSEN_WEBHOOK_SECRET` (read only when `--webhook` is given). `--webhook-secret <secret>` still works but puts the secret in shell history, the process list and agent transcripts, so do not use it from an agent. `--webhook-secret` and `--webhook-secret-stdin` cannot be combined; either one overrides `NANSEN_WEBHOOK_SECRET`.
|
|
142
144
|
- `--data '<json>'` merges raw JSON on top of named flags (escape hatch for fields without named flags).
|
|
143
145
|
- Alert endpoints retain their normal ownership, plan and quota checks for both selected credentials.
|
|
144
146
|
- Use single quotes for names with `$` or special characters: `--name 'SM >$1M'`
|
|
@@ -34,7 +34,7 @@ All commands: `nansen research token <sub> [options]`
|
|
|
34
34
|
|
|
35
35
|
```bash
|
|
36
36
|
nansen research token info --token <addr> --chain solana
|
|
37
|
-
nansen research token ohlcv --token <addr> --chain solana --
|
|
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`
|