nansen-cli 2.2.0 → 2.4.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 +108 -0
- package/README.md +109 -33
- package/docs/auth.md +56 -0
- package/docs/browser-login.md +101 -7
- package/docs/error-codes.md +249 -0
- package/package.json +10 -4
- package/skills/nansen-agent-guide/SKILL.md +54 -1
- package/skills/nansen-alerts-webhook-listener/SKILL.md +1 -1
- package/skills/nansen-dca-tracker/SKILL.md +1 -1
- package/skills/nansen-defi-positions/SKILL.md +1 -1
- package/skills/nansen-exit-signals/SKILL.md +2 -2
- package/skills/nansen-fund-tracker/SKILL.md +1 -1
- package/skills/nansen-general-search/SKILL.md +1 -1
- package/skills/nansen-holder-analysis/SKILL.md +2 -2
- package/skills/nansen-limit-orders/SKILL.md +1 -1
- package/skills/nansen-mpp-payment/SKILL.md +2 -2
- package/skills/nansen-perp-screener/SKILL.md +1 -1
- package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
- package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
- package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
- package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
- package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
- package/skills/nansen-prediction-markets/SKILL.md +1 -1
- package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
- package/skills/nansen-smart-alerts/SKILL.md +2 -1
- package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
- package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
- package/skills/nansen-smart-money-trend/SKILL.md +1 -1
- package/skills/nansen-token-research/SKILL.md +1 -1
- package/skills/nansen-token-screener/SKILL.md +1 -1
- package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
- package/skills/nansen-trading/SKILL.md +1 -1
- package/skills/nansen-wallet-batch/SKILL.md +1 -1
- package/skills/nansen-wallet-clustering/SKILL.md +1 -1
- package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
- package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
- package/skills/nansen-wallet-manager/SKILL.md +1 -1
- package/skills/nansen-wallet-profiler/SKILL.md +1 -1
- package/skills/nansen-web-fetcher/SKILL.md +1 -1
- package/skills/nansen-web-searcher/SKILL.md +1 -1
- package/src/api-endpoints.json +1605 -0
- package/src/api.js +336 -121
- package/src/auth-credentials.js +1 -0
- package/src/auth-state.js +2 -2
- package/src/auth-store-native.js +6 -1
- package/src/auth-store-worker.js +1 -1
- package/src/auth-store.js +9 -4
- package/src/bridge.js +19 -10
- package/src/cli.js +258 -107
- package/src/commands/agent.js +2 -3
- package/src/commands/alerts.js +277 -9
- package/src/commands/completion.js +6 -1
- package/src/commands/feedback.js +413 -0
- package/src/commands/mcp.js +1 -1
- package/src/commands/research.js +14 -37
- package/src/cost-cache.js +33 -7
- package/src/doctor.js +14 -5
- package/src/error-codes.js +226 -0
- package/src/feedback-journal.js +86 -0
- package/src/input-validation.js +551 -0
- package/src/limit-order.js +12 -3
- package/src/perp.js +2 -1
- package/src/privy.js +144 -48
- package/src/query-options.js +30 -7
- package/src/rpc-urls.js +3 -1
- package/src/schema.json +1254 -150
- package/src/solana-tx.js +4 -0
- package/src/telemetry.js +5 -1
- package/src/trade-validation.js +190 -21
- package/src/trading.js +229 -129
- package/src/transfer.js +7 -1
- package/src/update-check.js +32 -5
- package/src/wallet.js +220 -57
- package/src/walletconnect-x402.js +152 -52
- package/src/x402-audit.js +191 -0
- package/src/x402-payment-balance.js +90 -0
- package/src/x402-policy.js +151 -4
- package/src/x402.js +51 -22
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,113 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2.4.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#773](https://github.com/nansen-ai/nansen-cli/pull/773) [`47eb68d`](https://github.com/nansen-ai/nansen-cli/commit/47eb68db976b140be32fc776c7b44dcc630ea7bf) Thanks [@gulshngill](https://github.com/gulshngill)! - Every failure now exits 1 with `success: false`, and research commands check their input before calling the API (API-1080, API-1081).
|
|
8
|
+
|
|
9
|
+
- Subcommand typos (also with `--fields`) and unknown commands return `UNKNOWN_COMMAND` with the closest match, instead of `success: true` with the error inside `data`.
|
|
10
|
+
- Unknown options (`--turbo`), options a command used to ignore (`--limit` on `token ohlcv`, `--address` on `prediction-market position-detail`), options without a value (`--chain` with nothing after it), `--page 0`, `--format xml`, bad enum values and invalid dates (`--from-date 2024-13-45`) are rejected with the option named, in the REST API's wording ("Option '--timefrme' is not recognized by ... Did you mean '--timeframe'?").
|
|
11
|
+
- Missing required options (for example `--address`) fail locally instead of returning "API request failed (422)".
|
|
12
|
+
- `--chain`/`--chains` are checked against the chains each endpoint accepts; `nansen schema` lists them as `supportedChains`. Case and the API's chain aliases (`bsc`, `eth`, ...) are normalised first, as the API does. An invalid bitcoin token address now names native BTC (`1111111111111111111114oLvT2`).
|
|
13
|
+
- `--fields` names that match nothing in the response are an error instead of `{}`.
|
|
14
|
+
- `profiler balance` now sends `--limit`/`--page`, and `smart-money holdings --token` filters by token. Mixed-case EVM addresses in `--filters` are lowercased, so they match.
|
|
15
|
+
- List options are sent as lists, whether given comma-separated, repeated or as a JSON array: `token screener --chains ethereum,solana` no longer sends one `"ethereum,solana"` string, `smart-money --labels` accepts a comma-separated list, and a repeated `--addresses` or `research ... --chains` value that itself holds a comma-separated list is split. An empty list (`--chains ,`) is rejected.
|
|
16
|
+
- `prediction-market market-screener` and `event-screener` no longer accept `--min-unique-traders-24h` or `--max-volume-24hr`. The REST API has no such filters and rejected every request that used them; the CLI now says so before the request. `--max-unique-traders-24h` and `--min-volume-24hr` are unchanged.
|
|
17
|
+
- API validation errors keep the field name (`details.param`, `details.errors[]`), also for browser-session logins, and the message is no longer repeated inside `details`.
|
|
18
|
+
- A connection failure (`NETWORK_ERROR`) now says the API key was not checked; a rejected key (`UNAUTHORIZED`) says the connection works.
|
|
19
|
+
- All error codes are listed in `docs/error-codes.md`.
|
|
20
|
+
|
|
21
|
+
### Patch Changes
|
|
22
|
+
|
|
23
|
+
- [#768](https://github.com/nansen-ai/nansen-cli/pull/768) [`3600f66`](https://github.com/nansen-ai/nansen-cli/commit/3600f66c95977cf048555c077c3f586dbef20c0a) Thanks [@kome12](https://github.com/kome12)! - `nansen alerts` now redacts channel credentials (Slack, Discord and webhook URLs, webhook signing secrets) in its output and error messages by default. Pass `--reveal` to show the full values; scripts that read `channels[].data` values from `nansen alerts` output need it.
|
|
24
|
+
|
|
25
|
+
- [#760](https://github.com/nansen-ai/nansen-cli/pull/760) [`c776ae0`](https://github.com/nansen-ai/nansen-cli/commit/c776ae0310bc5c7dd2143a8509c9338b57a200ae) Thanks [@Kewe63](https://github.com/Kewe63)! - Bind Privy wallet IDs to their authoritative addresses before previews, screening, or signing wallet sends, limit orders, perp actions, and Hyperliquid bridge withdrawals.
|
|
26
|
+
|
|
27
|
+
- [#794](https://github.com/nansen-ai/nansen-cli/pull/794) [`3cca1af`](https://github.com/nansen-ai/nansen-cli/commit/3cca1affb349c83b10f864f8c72feea6d0047c5e) Thanks [@Snan0M](https://github.com/Snan0M)! - A call answered from the response cache (`--cache`) now prints `Credits: 0 (cached)` on stderr instead of a spec estimate for a request that was never made.
|
|
28
|
+
|
|
29
|
+
- [#787](https://github.com/nansen-ai/nansen-cli/pull/787) [`3830386`](https://github.com/nansen-ai/nansen-cli/commit/383038637c52385934c16b13fc60615ab3aa646e) Thanks [@Ravan002](https://github.com/Ravan002)! - Reject a comma-separated `--chain` (for example `--chain eth,sol`) with a message pointing to `--chains`, instead of sending it to the API as one unresolvable chain name.
|
|
30
|
+
|
|
31
|
+
- [#781](https://github.com/nansen-ai/nansen-cli/pull/781) [`5002e66`](https://github.com/nansen-ai/nansen-cli/commit/5002e664d603706a5ccb553bc393edbe30567ac8) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Use chain-valid research examples, consistent bridge routes, command-specific trade help with option descriptions, and explicit wallet naming in doctor guidance.
|
|
32
|
+
|
|
33
|
+
- [#775](https://github.com/nansen-ai/nansen-cli/pull/775) [`3185171`](https://github.com/nansen-ai/nansen-cli/commit/3185171d1e5de1820853b234de22ef0d38ca8eab) Thanks [@kome12](https://github.com/kome12)! - `trade execute` on Solana now waits for the transaction signature to be confirmed on chain before it reports success, as EVM swaps already do. A transaction that lands with an error fails with `TX_REVERTED`, and one that is not confirmed within 90 seconds fails with `RECEIPT_TIMEOUT` (it may still land, so check the explorer before retrying). Previously both cases printed "Transaction successful" and exited 0.
|
|
34
|
+
|
|
35
|
+
- [#799](https://github.com/nansen-ai/nansen-cli/pull/799) [`98b2dd7`](https://github.com/nansen-ai/nansen-cli/commit/98b2dd70580dc61bc53dee2e36f91525babd802c) Thanks [@kome12](https://github.com/kome12)! - Fix `wallet send --chain ethereum` (and `--chain evm`) failing with "Unauthorized: You must authenticate your request with an API key": the default Ethereum RPC now requires a key, so the CLI uses `https://ethereum-rpc.publicnode.com` instead. `NANSEN_EVM_RPC` still overrides it.
|
|
36
|
+
|
|
37
|
+
- [#770](https://github.com/nansen-ai/nansen-cli/pull/770) [`cdc4094`](https://github.com/nansen-ai/nansen-cli/commit/cdc4094e7163d72afa0e219fa16dc14ce4518005) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - List the feedback report categories and fields in `feedback submit --help`, the schema, the README and the agent skill. Show the feedback ID in `feedback get --help`, name a rejected API key when feedback cannot verify the account or read the preference, trace feedback requests with `--debug`, and drop explicit-ID advice from generated-ID recovery messages.
|
|
38
|
+
|
|
39
|
+
- [#793](https://github.com/nansen-ai/nansen-cli/pull/793) [`c1d1422`](https://github.com/nansen-ai/nansen-cli/commit/c1d14225768280f5d20249640d63502b0d5ac8c6) Thanks [@Snan0M](https://github.com/Snan0M)! - A blank (`--fields ' , '`, bare `--fields`) or repeated `--fields` is now rejected before the request is made, instead of after a billed call or by silently returning every field.
|
|
40
|
+
|
|
41
|
+
- [#766](https://github.com/nansen-ai/nansen-cli/pull/766) [`19c80ef`](https://github.com/nansen-ai/nansen-cli/commit/19c80efa3e1b73e8e5a392628acf87106de15db9) Thanks [@Kewe63](https://github.com/Kewe63)! - Harden response-cache reads against linked or non-regular entries, and atomically publish private cache writes without following linked destinations.
|
|
42
|
+
|
|
43
|
+
- [#777](https://github.com/nansen-ai/nansen-cli/pull/777) [`ff846d5`](https://github.com/nansen-ai/nansen-cli/commit/ff846d50af6de61645753011cb66d1902c16dea4) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Explain how to use NANSEN_API_KEY directly when browser login lacks an interactive terminal, secure credential storage, or native authentication locking.
|
|
44
|
+
|
|
45
|
+
- [#784](https://github.com/nansen-ai/nansen-cli/pull/784) [`c6fcb27`](https://github.com/nansen-ai/nansen-cli/commit/c6fcb27b680733fdca950f604f09521e16f25eec) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Help and `nansen schema` now show when label history starts: 2025-03-11 for the whale, public figure, top PnL and exchange segments of `research historical-token-flow-summary`, and for entity labels in `research historical-tx-lookup`.
|
|
46
|
+
|
|
47
|
+
- [#792](https://github.com/nansen-ai/nansen-cli/pull/792) [`82e1199`](https://github.com/nansen-ai/nansen-cli/commit/82e119914943b13a7528432cb0eae75e785842e0) Thanks [@Snan0M](https://github.com/Snan0M)! - `trade limit-order list --offset N` now prints the correct "Showing …" range and next-page offset, and rejects an offset that is not a non-negative integer.
|
|
48
|
+
|
|
49
|
+
- [#778](https://github.com/nansen-ai/nansen-cli/pull/778) [`f5209cb`](https://github.com/nansen-ai/nansen-cli/commit/f5209cb7add6fbf5e736ea0506bd8bab551b8e9a) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Qualify saved browser login on Debian 12 x64 over SSH with GNOME Keyring, document setup and reboot recovery, and distinguish dismissed unlock prompts from missing native bindings.
|
|
50
|
+
|
|
51
|
+
- [#785](https://github.com/nansen-ai/nansen-cli/pull/785) [`3543112`](https://github.com/nansen-ai/nansen-cli/commit/354311207d06c6f45351eac8a0ee7c8e3110ec94) Thanks [@gulshngill](https://github.com/gulshngill)! - List valid options and response fields for unknown input names instead of suggesting a similar name that can mean something else. Clarify that common options also apply, list all supported pagination controls, and label truncated response-field lists with their total count.
|
|
52
|
+
|
|
53
|
+
- [#795](https://github.com/nansen-ai/nansen-cli/pull/795) [`3d15212`](https://github.com/nansen-ai/nansen-cli/commit/3d15212f4c71095c886bbf346cc9f61396674578) Thanks [@Snan0M](https://github.com/Snan0M)! - `trade execute --quote-index` now rejects values that are not whole numbers (`1.9`, `1abc`, `1e0`) instead of pinning the quote at their leading digits.
|
|
54
|
+
|
|
55
|
+
- [#780](https://github.com/nansen-ai/nansen-cli/pull/780) [`6f83f98`](https://github.com/nansen-ai/nansen-cli/commit/6f83f989513340b8b215911f54c2d9a74db5fd4d) Thanks [@kome12](https://github.com/kome12)! - Wallet create, default and delete now wait for each other instead of racing. Two overlapping first `wallet create` runs with different passwords could both report success while leaving one wallet impossible to unlock.
|
|
56
|
+
|
|
57
|
+
- [#786](https://github.com/nansen-ai/nansen-cli/pull/786) [`eb30fc8`](https://github.com/nansen-ai/nansen-cli/commit/eb30fc8612f3e0f4af9c2d8423a63232423b8698) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Show one credit cost in help and post-call estimates when Free and Pro pay the same, and show the 150-credit `--premium-labels` price on commands that have it.
|
|
58
|
+
|
|
59
|
+
- [#779](https://github.com/nansen-ai/nansen-cli/pull/779) [`bdbab83`](https://github.com/nansen-ai/nansen-cli/commit/bdbab834a3a38899a7ebda0473ed02cca34c127c) Thanks [@kome12](https://github.com/kome12)! - Drop `Fund` from the Smart Money label list in `nansen schema`, the examples and the default labels for `--smart-money`. The help text now says `Fund` is no longer a Smart Money label. Fund wallets left the Smart Money cohort on 2026-09-09, so `Fund` matched no wallets there.
|
|
60
|
+
|
|
61
|
+
- [#752](https://github.com/nansen-ai/nansen-cli/pull/752) [`d074c1d`](https://github.com/nansen-ai/nansen-cli/commit/d074c1d9d1033a6772a7634335446b947b5b0a8b) Thanks [@kome12](https://github.com/kome12)! - `trade execute` on Solana now checks, before signing, that the wallet holds enough SOL for the transaction's actual network fee (base plus priority fee, priced by the cluster). A quote the wallet cannot pay the fee for is skipped with an actionable error instead of being broadcast to fail on-chain. The check runs even with `--no-verify-outcome`, and if the balance lookup fails it warns and proceeds.
|
|
62
|
+
|
|
63
|
+
- [#771](https://github.com/nansen-ai/nansen-cli/pull/771) [`6a24e25`](https://github.com/nansen-ai/nansen-cli/commit/6a24e259893ad659e8af1960e7667acd09fbb542) Thanks [@kome12](https://github.com/kome12)! - The update notice and `nansen doctor` now say when the latest release needs a newer Node.js than the one running, instead of suggesting `npm i -g nansen-cli`, which npm resolves back to the installed version on an older Node.
|
|
64
|
+
|
|
65
|
+
- [#796](https://github.com/nansen-ai/nansen-cli/pull/796) [`6ed3486`](https://github.com/nansen-ai/nansen-cli/commit/6ed348627f57ddf7f5217d3fa3a0bdcda5b5d64a) Thanks [@Snan0M](https://github.com/Snan0M)! - The WalletConnect x402 approval line on stderr now shows the amount the payment policy priced (e.g. `0.01 USD1`) instead of reading 18-decimal BNB Chain tokens as 6-decimal (`10000000000 Token`).
|
|
66
|
+
|
|
67
|
+
## 2.3.0
|
|
68
|
+
|
|
69
|
+
### Minor Changes
|
|
70
|
+
|
|
71
|
+
- [#747](https://github.com/nansen-ai/nansen-cli/pull/747) [`32a4ab2`](https://github.com/nansen-ai/nansen-cli/commit/32a4ab2bd9f9999a7ce9bd654af25c5783683ca2) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Add feedback submit and receipt lookup with explicit submission IDs, account authentication, safe retries, and JSON or human output.
|
|
72
|
+
|
|
73
|
+
Explain the agent preference rule in CLI guidance: ask before sending when the saved preference is off, unset or unavailable.
|
|
74
|
+
|
|
75
|
+
Explain paused submissions: report the unavailable feature, stop repeated attempts, and preserve the ID and report for a later retry.
|
|
76
|
+
|
|
77
|
+
Preserve field-level validation errors and uncertain submissions across session failures, recognize gateway authentication errors, and keep malformed feedback arguments out of telemetry.
|
|
78
|
+
|
|
79
|
+
- [#755](https://github.com/nansen-ai/nansen-cli/pull/755) [`84ba0b0`](https://github.com/nansen-ai/nansen-cli/commit/84ba0b04a2920114417b19d640ed7aff158b3d5b) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Read account feedback preferences and stop automatic retries when feedback is not enabled for the account.
|
|
80
|
+
|
|
81
|
+
- [#754](https://github.com/nansen-ai/nansen-cli/pull/754) [`4dddcec`](https://github.com/nansen-ai/nansen-cli/commit/4dddceccd500c3dff9641fcc4bea99d8909ccc20) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Save feedback submissions before sending when no ID is supplied. Resume the same report after a restart, with account and environment checks, private storage, concurrency protection, and local expiry and erasure.
|
|
82
|
+
|
|
83
|
+
- [#744](https://github.com/nansen-ai/nansen-cli/pull/744) [`f56cdbb`](https://github.com/nansen-ai/nansen-cli/commit/f56cdbba8049dcf349dd0bb4ca94552334085762) Thanks [@kome12](https://github.com/kome12)! - **Removed `--gasless` from `trade execute`.** The flag never worked. The deprecated broadcast route it posted to validates its request body strictly and has never accepted the `gasless` or `steps` fields, so every gasless swap was rejected with `Unrecognized keys` before anything was broadcast — on Base and on Solana alike. Passing `--gasless` now fails fast with `GASLESS_REMOVED` instead of signing, posting and failing; re-run without it and the wallet pays its own gas as usual. There is no replacement flag.
|
|
84
|
+
|
|
85
|
+
This corrects the 2.2.0 release note, which said "Gasless swaps stay on the deprecated route". They did, but that route rejected them; there was no working gasless path to keep.
|
|
86
|
+
|
|
87
|
+
This removes a published option and its `schema.json` entry, so anything enumerating `trade execute`'s options will see it disappear and any wrapper still passing it will fail. It is released as a minor rather than a major because the flag never completed a swap on any chain: every call already ended in a failed execution, so no working integration can depend on it.
|
|
88
|
+
|
|
89
|
+
**Removed the `$10` gas-balance bypass.** `trade quote` skipped its native-balance pre-check for any trade worth $10 or more, on the theory that such trades could use a solver-paid route. It never checked whether one was actually in use, so a wallet with no native token passed validation and then failed at broadcast. Gas is now checked on every trade, and the error says to fund the wallet rather than suggesting the removed feature.
|
|
90
|
+
|
|
91
|
+
The Solana floor comes down from `0.01` SOL to `0.005` SOL in the same change. It had drifted above the `0.005` SOL the CLI itself holds back when you sell the maximum amount of SOL, so a wallet left sitting on exactly that reserve would have been refused its next quote — a contradiction the `$10` bypass had been hiding from every trade worth $10 or more. `0.005` SOL is still a wide margin over a real swap (a 5000-lamport base fee plus at most ~0.00204 SOL of account rent). The Base floor is unchanged.
|
|
92
|
+
|
|
93
|
+
- [#751](https://github.com/nansen-ai/nansen-cli/pull/751) [`0a87eae`](https://github.com/nansen-ai/nansen-cli/commit/0a87eae89fadbadf0fa1869546f71f8d9afa5d80) Thanks [@kome12](https://github.com/kome12)! - Add `NANSEN_X402_SESSION_MAX_AMOUNT` to cap the total USD of x402 auto-payments one CLI process can sign
|
|
94
|
+
|
|
95
|
+
### Patch Changes
|
|
96
|
+
|
|
97
|
+
- [#757](https://github.com/nansen-ai/nansen-cli/pull/757) [`19b7cfc`](https://github.com/nansen-ai/nansen-cli/commit/19b7cfcb562bac2beb85775833fb8b87edfd0037) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Report feedback edge blocks as rejections, keep preference failures on the ask-before-sending path, and preserve the actual submission outcome when resuming saved reports.
|
|
98
|
+
|
|
99
|
+
- [#732](https://github.com/nansen-ai/nansen-cli/pull/732) [`94815d4`](https://github.com/nansen-ai/nansen-cli/commit/94815d409cb67b6e93fe32bd5d5bbd9081084c57) Thanks [@Ahmett101](https://github.com/Ahmett101)! - Render profiler perp positions as individual rows in table and CSV output while preserving the original JSON response and account summaries. Table and CSV output also falls back to showing the payload when a response's rows carry no fields, instead of printing blank lines.
|
|
100
|
+
|
|
101
|
+
- [#742](https://github.com/nansen-ai/nansen-cli/pull/742) [`facbb45`](https://github.com/nansen-ai/nansen-cli/commit/facbb4536b7bb6e2667f8272ada3a4b34a06dd79) Thanks [@gulshngill](https://github.com/gulshngill)! - Check EVM token balances before signing automatic x402 payments. Skip unfunded options for local and Privy wallets and continue to a funded token, using exact amounts and bounded RPC checks.
|
|
102
|
+
|
|
103
|
+
- [#748](https://github.com/nansen-ai/nansen-cli/pull/748) [`fb96a5d`](https://github.com/nansen-ai/nansen-cli/commit/fb96a5d96d26e7610e7b580a000b1d85bd3fcfc4) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Use stable v1 API routes for ten historical research commands before their beta aliases are retired.
|
|
104
|
+
|
|
105
|
+
- [#750](https://github.com/nansen-ai/nansen-cli/pull/750) [`2c38b44`](https://github.com/nansen-ai/nansen-cli/commit/2c38b44b10329eb3570b3c44566e198bd60b4693) Thanks [@kome12](https://github.com/kome12)! - Record x402 auto-payments in a local audit log at `~/.nansen/x402/payments.jsonl`: one line when a signed payment is sent and one for its outcome (accepted, rejected or ambiguous), with the amount, network, asset, recipient and request path. Signatures, request and response bodies, and query strings are never written, and a failed write warns without blocking the payment.
|
|
106
|
+
|
|
107
|
+
- [#745](https://github.com/nansen-ai/nansen-cli/pull/745) [`5a77e0d`](https://github.com/nansen-ai/nansen-cli/commit/5a77e0d160507d97e67b50bfe38917a2005d13c5) Thanks [@gulshngill](https://github.com/gulshngill)! - Skip unfunded x402 payment options on every signing path. WalletConnect payments now try each compatible option cheapest first, check the connected wallet's token balance before asking for approval, and move on to the next option after a clean server rejection instead of failing on the first. Solana payments from local and Privy wallets check the USDC balance before signing. Privy payments now report the token they paid with, so the low-balance warning checks the right token.
|
|
108
|
+
|
|
109
|
+
- [#749](https://github.com/nansen-ai/nansen-cli/pull/749) [`221371b`](https://github.com/nansen-ai/nansen-cli/commit/221371b055d08bd88ad9bf8da409e21f01baa85c) Thanks [@kome12](https://github.com/kome12)! - x402: report on stderr when the server rejects a payment because the wallet's token balance is too low, and include the network in the "Paid via WalletConnect" log line.
|
|
110
|
+
|
|
3
111
|
## 2.2.0
|
|
4
112
|
|
|
5
113
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -14,34 +14,118 @@ npm install -g nansen-cli
|
|
|
14
14
|
npx skills add nansen-ai/nansen-cli # load agent skill files
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
##
|
|
17
|
+
## Feedback
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Send product feedback to Nansen with your configured API key or login session:
|
|
20
20
|
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
21
|
+
```json
|
|
22
|
+
{
|
|
23
|
+
"category": "missing_capability",
|
|
24
|
+
"description": "I need to compare labels across 50 wallets but cannot find a bulk lookup.",
|
|
25
|
+
"goal": "Compare labels across a wallet list."
|
|
26
|
+
}
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
`category` and `description` are required. `category` is one of `bug`,
|
|
30
|
+
`data_quality`, `documentation`, `missing_capability`, `usability` or `other`.
|
|
31
|
+
A feature request or product gap is `missing_capability`. `description` says
|
|
32
|
+
what happened and what was needed, in up to 2,000 characters. Optional fields
|
|
33
|
+
are `endpoint` and `tool` (up to 256 characters each), `goal`,
|
|
34
|
+
`expected_behavior`, `observed_behavior` and `workaround` (up to 2,000
|
|
35
|
+
characters each), `request_ids` (up to 10 of your own request IDs) and
|
|
36
|
+
`client` (`{"name": ..., "version": ...}`, attribution only). The API rejects
|
|
37
|
+
any other field or category with a 422, so leave out fields such as `title`,
|
|
38
|
+
`summary` or `severity`. Write plain sentences without Markdown or code
|
|
39
|
+
formatting. `nansen feedback submit --help` prints the same list.
|
|
40
|
+
|
|
41
|
+
Save the report as `feedback.json`. Omit the ID to save private recovery data before sending:
|
|
30
42
|
|
|
31
|
-
|
|
43
|
+
```bash
|
|
44
|
+
nansen feedback submit --file feedback.json --json
|
|
45
|
+
nansen feedback resume --json
|
|
46
|
+
nansen feedback get fb_123 --json
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`resume` uses the saved ID and exact report bytes, even if the input file is gone.
|
|
50
|
+
Changing the account, API environment or report stops replay. After confirmation,
|
|
51
|
+
`resume` reads the receipt without sending another report. To deliberately start
|
|
52
|
+
another report, use `feedback submit --new --file feedback.json`.
|
|
53
|
+
|
|
54
|
+
One recovery entry lives in `~/.nansen/feedback/recovery.json`, with private
|
|
55
|
+
permissions and a process lock. Confirmed receipts remove report content and keep
|
|
56
|
+
only the submission ID, feedback ID, account, environment and expiry. Feedback
|
|
57
|
+
recovery operations erase expired data when they next open the journal. Pending
|
|
58
|
+
reports expire after one calendar year. No cleanup runs while the CLI is closed.
|
|
59
|
+
`nansen feedback forget` erases local recovery data
|
|
60
|
+
offline, leaving a content-free marker that prevents accidental replay. It does
|
|
61
|
+
not delete your input file or a report on the server. A missing or erased server
|
|
62
|
+
receipt also clears the local entry. Validation rejections erase the saved payload;
|
|
63
|
+
correct the input and use --new to submit again. Forget also erases damaged journals.
|
|
64
|
+
Do not back up pending report content.
|
|
65
|
+
|
|
66
|
+
Automatic IDs require POSIX private storage and the optional native locking
|
|
67
|
+
binding. On Windows or when storage cannot be secured, supply a caller-managed
|
|
68
|
+
`--submission-id report-123` and keep that ID and the unchanged file for retries.
|
|
69
|
+
This explicit-ID path does not save a local report. Recovery format version 1
|
|
70
|
+
survives upgrades; unsupported or damaged journals stop rather than start fresh.
|
|
71
|
+
Older explicit-ID-only CLI releases do not read recovery journals; finish recovery
|
|
72
|
+
with a supporting version before rolling back.
|
|
73
|
+
|
|
74
|
+
Remove `--json` for human output. `received` means
|
|
75
|
+
saved, `reviewed` means triaged, and `closed` means review is complete. Review does
|
|
76
|
+
not promise a fix or a date.
|
|
77
|
+
|
|
78
|
+
Feedback is free, with seven accepted reports per account each week, resetting
|
|
79
|
+
Monday at 00:00 UTC. An exhausted allowance exits with its reset time; accepted
|
|
80
|
+
IDs can still be replayed. Feedback bypasses caching and payment fallback.
|
|
81
|
+
Remove secrets and unnecessary personal details from your report. A backend
|
|
82
|
+
without feedback support reports an unavailable capability.
|
|
83
|
+
|
|
84
|
+
New submissions may be paused before release or during an outage. HTTP 503 with
|
|
85
|
+
`reason: feedback_admissions_paused` means this attempt accepted no new report
|
|
86
|
+
and used no weekly allowance. Tell the user feedback is unavailable, then stop;
|
|
87
|
+
do not keep retrying or ask for approval again in the same session. Keep the ID
|
|
88
|
+
and unchanged file for a later retry. Accepted-ID replays and receipt reads
|
|
89
|
+
remain available during a pause.
|
|
90
|
+
|
|
91
|
+
Agents should check the saved account preference before sending feedback on their
|
|
92
|
+
own. If enabled, they may send without asking again, subject to their host's
|
|
93
|
+
controls. If off, unset or unavailable, show the proposed report and ask first.
|
|
94
|
+
Approval for one report does not change the preference. Never enable it
|
|
95
|
+
automatically. Use `nansen feedback preferences --json` for a fresh account read
|
|
96
|
+
before each new automatic report. Without `--json`, it prints a human summary.
|
|
97
|
+
Reads use no credits or report quota. Change the lasting choice in Superapp settings.
|
|
98
|
+
An explicit user request to send the report needs no additional preference
|
|
99
|
+
check. The submit command sends the report without an interactive prompt.
|
|
100
|
+
|
|
101
|
+
HTTP 403 with `reason: feedback_not_enabled` means feedback is not enabled for
|
|
102
|
+
this account. Stop automatic retries. Approval or an enabled preference does
|
|
103
|
+
not override rollout. Keep the ID and unchanged report for recovery; an earlier
|
|
104
|
+
uncertain attempt remains uncertain. Never switch accounts or pay to bypass denial.
|
|
105
|
+
|
|
106
|
+
## Auth
|
|
32
107
|
|
|
33
|
-
|
|
108
|
+
Pick one of three ways to authenticate and pay for API calls.
|
|
109
|
+
|
|
110
|
+
**Nansen account.** Calls use your account's plan and credits. `nansen login` approves the CLI in your browser and saves a session. On a server, in a container or in CI, set `NANSEN_API_KEY` to a key from [the API page](https://app.nansen.ai/api) instead.
|
|
34
111
|
|
|
35
112
|
```bash
|
|
36
|
-
nansen login
|
|
113
|
+
nansen login
|
|
37
114
|
```
|
|
38
115
|
|
|
39
|
-
|
|
116
|
+
**x402.** Pay per call from a CLI wallet funded with USDC on Base or Solana, or USDT0 on X Layer. When the API answers with HTTP 402, the CLI pays from your default wallet and retries. Each payment is capped at $1.00 by default; set `NANSEN_X402_MAX_AMOUNT` to change it. Your first wallet becomes the default. The wallet needs a password of at least 12 characters. The CLI saves it for later payments, in the OS keychain when one is available.
|
|
40
117
|
|
|
41
|
-
|
|
118
|
+
```bash
|
|
119
|
+
NANSEN_WALLET_PASSWORD='<your-wallet-password>' nansen wallet create --name my-wallet
|
|
120
|
+
```
|
|
42
121
|
|
|
43
|
-
|
|
44
|
-
|
|
122
|
+
**MPP via tempo.** Pay per call through the separate [tempo CLI](https://docs.tempo.xyz). The Nansen CLI does not sign MPP payments. After the [one-time tempo setup](#mpp--tempo):
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
[docs/auth.md](docs/auth.md) covers headless setup, saving an API key, browser-session storage and how x402 payment works with each credential.
|
|
45
129
|
|
|
46
130
|
## Verify your MCP setup
|
|
47
131
|
|
|
@@ -89,18 +173,6 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
|
|
|
89
173
|
|
|
90
174
|
Run `nansen schema --pretty` for the full subcommand and field reference.
|
|
91
175
|
|
|
92
|
-
## Browser login compatibility and scope
|
|
93
|
-
|
|
94
|
-
Browser login requests `nansen:api` for the same account/API permissions as a pasted API key, including smart-alert CRUD, public agent, portfolio, web, beta and existing trading API operations. The same endpoint ownership, plan, credit, quota, sanctions and geographic checks apply. Existing OAuth/MCP `nansen:read` grants keep their existing semantics. Wallet signing remains separate.
|
|
95
|
-
|
|
96
|
-
Plain `nansen login` always starts fresh browser approval, whether no credential, an environment key, a saved key or a saved session exists. It preflights secure storage, shows a link/code, verifies the approved account through the free account endpoint, then replaces the single saved API credential. `nansen login --no-browser` lets you approve on another device without opening a browser on the CLI machine. It does not remove the native-storage or supported-platform requirements. Browser login requires both stdin and stdout to be terminals; without either, it exits immediately with `NOT_A_TTY` and points to `nansen login --human` with `NANSEN_API_KEY` or `nansen login --api-key-stdin`. In a terminal, `--json` emits NDJSON pending and terminal events; the private device code and tokens are never printed.
|
|
97
|
-
|
|
98
|
-
`NANSEN_API_KEY` still overrides the saved session. Login verifies the new account independently and explains this override. Failed approval or installation preserves the previous selection. `nansen auth status` is offline and labels saved metadata as cached/unverified; `nansen account` checks the effective credential live. `nansen logout` removes saved API authentication and attempts family retirement, preserving wallets and environment keys. Remote revocation and physical deletion failures are reported separately.
|
|
99
|
-
|
|
100
|
-
This is a breaking change for scripts that used plain login to persist an environment key. Use explicit `nansen login --human` with that environment key, or `--api-key <key>` with its existing shell-history risk. Direct key-authenticated commands need no migration. Existing API-key x402 payment behavior is preserved and also applies to browser sessions: a supported HTTP 402 challenge can trigger wallet payment under the existing policy and spending limits. A paid retry does not change the saved credential or top up account credits. Invalid credentials never cause an account switch or payment; login verification remains free and never pays.
|
|
101
|
-
|
|
102
|
-
Browser login is enabled in production. Saved browser-session storage is [qualified on macOS arm64](docs/browser-login.md#preview-platform-scope); Linux qualification is pending, and Windows and SSH/background sessions are not qualified. Selected sessions renew automatically near expiry. If a refresh response is lost before a complete replacement is stored, follow the fresh-login guidance; the CLI never retries a consumed refresh credential. Browser sessions have the same account API permissions as API keys, subject to existing endpoint checks. They add no wallet-signing or internal-service authority and cannot be exported as MCP API keys. See [storage and recovery](docs/browser-login.md).
|
|
103
|
-
|
|
104
176
|
## MCP
|
|
105
177
|
|
|
106
178
|
<!-- BEGIN GENERATED: mcp. Do not edit by hand. Edit src/mcp-client-config.json (values) or scripts/templates/readme-mcp.md (prose), not README.md, then run: npm run mcp:generate. -->
|
|
@@ -188,7 +260,6 @@ Cross-chain swaps work the same way — add `--to-chain`. Bridge providers (Li.F
|
|
|
188
260
|
```bash
|
|
189
261
|
nansen trade quote --chain base --to-chain solana --from ETH --to SOL --amount 0.0003 --amount-unit token
|
|
190
262
|
nansen trade execute --quote <quoteId> # signed broadcast
|
|
191
|
-
nansen trade execute --quote <quoteId> --gasless # Relay-only: solver pays gas
|
|
192
263
|
nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
|
|
193
264
|
```
|
|
194
265
|
|
|
@@ -302,7 +373,7 @@ tempo wallet fund # follow the on-screen instructions to deposit USDC
|
|
|
302
373
|
**Calling the Nansen API via tempo:**
|
|
303
374
|
|
|
304
375
|
```bash
|
|
305
|
-
tempo request POST https://api.nansen.ai/api/v1/smart-money/netflow \
|
|
376
|
+
tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow \
|
|
306
377
|
--json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
|
|
307
378
|
```
|
|
308
379
|
|
|
@@ -497,7 +568,10 @@ Default JSON output still contains the complete response body.
|
|
|
497
568
|
| Code | Action |
|
|
498
569
|
|------|--------|
|
|
499
570
|
| `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api?tab=api](https://app.nansen.ai/api?tab=api). |
|
|
500
|
-
| `UNAUTHORIZED` |
|
|
571
|
+
| `UNAUTHORIZED` | The API rejected the key (the connection works). Re-auth. |
|
|
572
|
+
| `NETWORK_ERROR` | The CLI could not reach the API, so the key was not checked. Fix the connection (`nansen doctor`); do not replace the key. |
|
|
573
|
+
| `INVALID_PARAMS` / `MISSING_PARAM` | Fix the option or field named in `details.param` and `details.errors[]` (each `{ field, message, code }`), then retry. |
|
|
574
|
+
| `UNKNOWN_COMMAND` | The command or subcommand does not exist; the message suggests the closest one. |
|
|
501
575
|
| `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
|
|
502
576
|
| `UNSUPPORTED_FILTER` | Remove the filter and retry. |
|
|
503
577
|
| `PLAN_UPGRADE_REQUIRED` | The endpoint or option needs a higher subscription plan. Do not retry. |
|
|
@@ -505,7 +579,9 @@ Default JSON output still contains the complete response body.
|
|
|
505
579
|
| `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
|
|
506
580
|
| `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
|
|
507
581
|
|
|
508
|
-
Every code documented on the API's [error-handling page](https://docs.nansen.ai/getting-started/error-handling) maps onto a stable CLI error code; a code the CLI does not recognise is passed through unchanged.
|
|
582
|
+
Every failure exits 1. The full list of codes is in [docs/error-codes.md](docs/error-codes.md). Every code documented on the API's [error-handling page](https://docs.nansen.ai/getting-started/error-handling) maps onto a stable CLI error code; a code the CLI does not recognise is passed through unchanged.
|
|
583
|
+
|
|
584
|
+
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`.
|
|
509
585
|
|
|
510
586
|
**Error metadata.** When the API reports them, `details` carries:
|
|
511
587
|
|
|
@@ -522,7 +598,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
|
|
|
522
598
|
| Symptom | Fix |
|
|
523
599
|
|---------|-----|
|
|
524
600
|
| `command not found` | `npm install -g nansen-cli` |
|
|
525
|
-
| Global install reports an older version | `npm i -g nansen-cli@latest --registry=https://registry.npmjs.org/ --prefer-online
|
|
601
|
+
| Global install reports an older version | Check `node -v` first: current releases need Node.js >= 22. On an older Node, `npm i -g nansen-cli` installs the newest release that still supports it without an error, and `npm i -g nansen-cli@latest` installs the current release with an `EBADENGINE` warning (or fails under `engine-strict`). Upgrade Node, then run `npm i -g nansen-cli@latest --registry=https://registry.npmjs.org/ --prefer-online` and check `which -a nansen` for stale binaries |
|
|
526
602
|
| `UNAUTHORIZED` after login | `nansen auth status` shows the effective credential and cached/unverified session metadata. Correct an invalid environment key first; browser login does not override it. Use fresh `nansen login` for a rejected session, or explicit legacy key setup for integration credentials |
|
|
527
603
|
| 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 |
|
|
528
604
|
| Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
|
package/docs/auth.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Authentication
|
|
2
|
+
|
|
3
|
+
The Nansen API accepts three ways to authenticate and pay for calls: a Nansen account, x402 and MPP via tempo. The [README](../README.md#auth) shows one command for each. This page has the details.
|
|
4
|
+
|
|
5
|
+
## Nansen account: browser login or API key
|
|
6
|
+
|
|
7
|
+
Plain `nansen login` requests fresh browser approval and saves a session automatically. No API-key copying or PEM setup is needed. Selected sessions renew automatically; rejected or uncertain renewal requires fresh login.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
nansen login # approve the displayed code, account and CLI
|
|
11
|
+
nansen login --no-browser # approve on another device; same storage requirements
|
|
12
|
+
nansen auth status # offline, cached/unverified credential selection
|
|
13
|
+
nansen account # free live check, including with zero research credits
|
|
14
|
+
nansen logout # clear saved API auth; preserve wallets and environment keys
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Browser login is available in Nansen CLI 2.0.0 and enabled in production. Saved browser sessions are qualified on macOS arm64 in a local GUI Terminal with an unlocked login Keychain, and on Debian 12 x64 over SSH with Node 22.23.4, user D-Bus and an unlocked GNOME Keyring 42.1. Both require a local home directory. Other configurations still need qualification. See [storage, supported scope and recovery](browser-login.md). Email/password and Google sign-in are supported by the device-flow contract. Apple device sign-in remains deferred.
|
|
18
|
+
|
|
19
|
+
Existing API-key users can run commands directly with `NANSEN_API_KEY`. It overrides the saved session, even after successful browser login. To deliberately save an injected key, use explicit `nansen login --human`; without an environment key this prompts in a human terminal. `nansen login --api-key <key>` remains available but puts the key in shell history. Saved-auth mutations require the native lock binding. Get a conventional key at [agent setup](https://app.nansen.ai/auth/agent-setup); MCP installation exports a separate persistent API key; it does not export browser sessions.
|
|
20
|
+
|
|
21
|
+
On a server, in a container, or in CI without a credential store, get your key from [the API page](https://app.nansen.ai/api) and use it directly:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
export NANSEN_API_KEY='<your-api-key>'
|
|
25
|
+
nansen account
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
No `nansen login` is needed. Core API commands using the environment key require neither secure storage nor native authentication locking. The variable stays set for this terminal session; for automation, inject it through your platform's secret manager. See [headless setup, including PowerShell](browser-login.md#servers-containers-and-ci-without-secure-storage).
|
|
29
|
+
|
|
30
|
+
To save a key for later commands on a machine with native authentication locking, pipe it from your secret manager into `nansen login --api-key-stdin`, or redirect a protected key file:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
nansen login --api-key-stdin --json < /path/to/protected-api-key
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
This reads one key (up to 4096 bytes, with an optional trailing newline), verifies it, and saves it without printing it. Input must close within 30 seconds. `--json` prints one `saved` event with the effective credential source; errors exit nonzero. As with existing API-key login, the key is stored in `~/.nansen/config.json` using an atomic write with owner-only file permissions (`0600` on POSIX), not in the OS keychain. The native lock binding is required for saving credentials. It does not create an account or issue a key. Avoid commands containing literal secrets, which may enter shell history. Do not combine it with `--api-key`, `--human`, or `--no-browser`. An existing `NANSEN_API_KEY` still overrides the saved credential until you unset it.
|
|
37
|
+
|
|
38
|
+
### Browser login compatibility and scope
|
|
39
|
+
|
|
40
|
+
Browser login requests `nansen:api` for the same account/API permissions as a pasted API key, including smart-alert CRUD, public agent, portfolio, web, beta and existing trading API operations. The same endpoint ownership, plan, credit, quota, sanctions and geographic checks apply. Existing OAuth/MCP `nansen:read` grants keep their existing semantics. Wallet signing remains separate.
|
|
41
|
+
|
|
42
|
+
Plain `nansen login` always starts fresh browser approval, whether no credential, an environment key, a saved key or a saved session exists. It preflights secure storage, shows a link/code, verifies the approved account through the free account endpoint, then replaces the single saved API credential. `nansen login --no-browser` lets you approve on another device without opening a browser on the CLI machine. It does not remove the native-storage or supported-platform requirements. Browser login requires both stdin and stdout to be terminals; without either, it exits immediately with `NOT_A_TTY` and explains how to use `NANSEN_API_KEY` directly without login. Deliberately saving a key with `--human` or `--api-key-stdin` still requires native locking. In a terminal, `--json` emits NDJSON pending and terminal events; the private device code and tokens are never printed.
|
|
43
|
+
|
|
44
|
+
`NANSEN_API_KEY` still overrides the saved session. Login verifies the new account independently and explains this override. Failed approval or installation preserves the previous selection. `nansen auth status` is offline and labels saved metadata as cached/unverified; `nansen account` checks the effective credential live. `nansen logout` removes saved API authentication and attempts family retirement, preserving wallets and environment keys. Remote revocation and physical deletion failures are reported separately.
|
|
45
|
+
|
|
46
|
+
This is a breaking change for scripts that used plain login to persist an environment key. Use explicit `nansen login --human` with that environment key, or `--api-key <key>` with its existing shell-history risk. Direct key-authenticated commands need no migration. Existing API-key x402 payment behavior is preserved and also applies to browser sessions: a supported HTTP 402 challenge can trigger wallet payment under the existing policy and spending limits. A paid retry does not change the saved credential or top up account credits. Invalid credentials never cause an account switch or payment; login verification remains free and never pays.
|
|
47
|
+
|
|
48
|
+
Browser login is enabled in production. Saved browser-session storage is [qualified on macOS arm64 and the documented Debian 12 x64 SSH configuration](browser-login.md#preview-platform-scope). Windows, Alpine/musl and unattended background sessions are not qualified. Selected sessions renew automatically near expiry. If a refresh response is lost before a complete replacement is stored, follow the fresh-login guidance; the CLI never retries a consumed refresh credential. Browser sessions have the same account API permissions as API keys, subject to existing endpoint checks. They add no wallet-signing or internal-service authority and cannot be exported as MCP API keys. See [storage and recovery](browser-login.md).
|
|
49
|
+
|
|
50
|
+
## x402
|
|
51
|
+
|
|
52
|
+
Create and fund a wallet with USDC on Base/Solana or USDT0 on X Layer. API keys, browser sessions and anonymous requests can all pay a supported HTTP 402 challenge under the same wallet policy and spending limits. The paid retry sends `Payment-Signature` without the account credential. Authentication or authorization failures never trigger payment. Explicit manual API-key payment signatures remain supported.
|
|
53
|
+
|
|
54
|
+
## MPP via tempo
|
|
55
|
+
|
|
56
|
+
Install the separate tempo CLI and use `tempo request`. Browser login does not configure a wallet, sign MPP credentials or purchase credits. See [MPP / Tempo](../README.md#mpp--tempo).
|
package/docs/browser-login.md
CHANGED
|
@@ -4,11 +4,18 @@ Browser login saves a session after you approve the CLI in your browser. It is a
|
|
|
4
4
|
|
|
5
5
|
## Preview platform scope
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Saved browser login is qualified on the configurations below. Both require a local home directory and an unlocked persistent OS credential store. Network or synchronized home directories and unattended background agents are not qualified.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
| OS / architecture | Terminal and storage | Qualification |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| macOS arm64 | Local GUI Terminal, unlocked login Keychain, local home | Initial preview |
|
|
12
|
+
| Debian 12 x64, glibc 2.36, Node 22.23.4 | SSH with a TTY, user D-Bus, GNOME Keyring 42.1, password-protected login collection, local home | Live approval, durable save, fresh-process account access, renewal, locked/unavailable recovery, reboot/unlock persistence and logout verified |
|
|
13
|
+
| Linux desktop prompts, arm64 or other providers/distributions | Secret Service adapter exists | Not qualified |
|
|
14
|
+
| Alpine/musl, Windows | See native compatibility below | Excluded |
|
|
15
|
+
|
|
16
|
+
Linux qualification used the packaged CLI on Debian 12.15 x64 in a disposable VM, kernel 6.1, a user systemd bus and a local ext4 home. The user manager was kept available between SSH connections with `loginctl enable-linger`; this does not unlock the keyring. A fresh SSH login after a real guest reboot recovered the same renewed session after manual unlock. Renewal was triggered by a near-expiry clock injected into the test state owner; proof signing, the issuer and account verification used real time. Concurrent renewal and interrupted-operation recovery are additionally covered by the real-store synthetic-issuer check and process tests. Desktop unlock prompts remain unqualified.
|
|
10
17
|
|
|
11
|
-
Browser login requires enabled server access and working native credential storage. If the store is locked, unlock it and retry from the supported Terminal context. Repeating browser approval does not repair
|
|
18
|
+
Browser login requires enabled server access and working native credential storage. If the store is locked, unlock it and retry from the supported Terminal context. Repeating browser approval does not repair credential-store access. If optional dependencies were omitted, reinstall with them enabled. A platform without a compatible prebuild still cannot use saved authentication. There is no plaintext session-storage fallback.
|
|
12
19
|
|
|
13
20
|
## Commands and selection
|
|
14
21
|
|
|
@@ -22,7 +29,7 @@ nansen logout
|
|
|
22
29
|
|
|
23
30
|
Plain `nansen login` always requests fresh browser approval, even when you already have a saved session or API key. Check the displayed code, account, client and requested access before approving. Visiting the link alone grants nothing. Email/password and Google are the documented sign-in methods; Apple device sign-in is not supported by this flow.
|
|
24
31
|
|
|
25
|
-
Browser login needs both stdin and stdout connected to a terminal.
|
|
32
|
+
Browser login needs both stdin and stdout connected to a terminal. Plain login and `--no-browser` fail immediately without a terminal rather than waiting for device approval.
|
|
26
33
|
|
|
27
34
|
`--no-browser` runs the same flow without opening a browser automatically. You can approve on another device; the terminal needs no inbound callback and still needs usable native storage.
|
|
28
35
|
|
|
@@ -43,6 +50,93 @@ Login verifies the approved account without charging for research. Research uses
|
|
|
43
50
|
|
|
44
51
|
An invalid selected credential fails with an error. The CLI does not silently switch accounts, restore an older saved key or pay after authentication or authorization fails. A supported HTTP 402 payment challenge uses the same automatic x402 flow for API keys, browser sessions and anonymous requests, subject to existing wallet authorization, token/recipient policy and spending limits. The paid retry sends only the payment credential; it does not change saved authentication or top up account credits. Login verification never pays. Browser Bearer requests cannot be combined with an API key or a manually supplied payment signature. Explicit manual API-key payment remains supported.
|
|
45
52
|
|
|
53
|
+
## Linux Secret Service setup
|
|
54
|
+
|
|
55
|
+
Linux browser sessions require the native binding, a user D-Bus, a running Secret Service provider and an unlocked default collection. These are separate requirements. The adapter explicitly selects `secret-service`; it never falls back to the kernel's memory-only keyring. The setup below targets Debian 12 x64 with GNOME Keyring and a local home directory. Qualification limits are listed above.
|
|
56
|
+
|
|
57
|
+
1. Install the service and diagnostic tools, then install the CLI with optional dependencies:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
sudo apt-get update
|
|
61
|
+
sudo apt-get install --no-install-recommends dbus dbus-user-session gnome-keyring libsecret-tools libglib2.0-bin
|
|
62
|
+
npm install -g nansen-cli --include=optional
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
2. Run the remaining commands as your normal user. Check the user bus with `busctl --user list`. If your terminal has no user bus, start a private session and stay inside its shell:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
dbus-run-session -- bash
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
For SSH, allocate a TTY and run the commands on the Linux host. An unlocked store on your laptop does not unlock the server's store. A private bus ends when its shell exits; a later shell needs its own service connection and unlock.
|
|
72
|
+
|
|
73
|
+
3. Start or unlock GNOME Keyring from Bash. On first use, choose a non-empty keyring password; later, use the same password. This password protects the OS keyring, and is separate from your Nansen account password.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
(
|
|
77
|
+
set +x
|
|
78
|
+
IFS= read -r -s -p 'Keyring password: ' keyring_password </dev/tty || exit 1
|
|
79
|
+
printf '\n' >/dev/tty
|
|
80
|
+
[ -n "$keyring_password" ] || exit 1
|
|
81
|
+
printf '%s' "$keyring_password" |
|
|
82
|
+
gnome-keyring-daemon --daemonize --unlock --components=secrets
|
|
83
|
+
)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The password goes through stdin, without being saved in a file or placed in process arguments. Keep the provider's encrypted keyring files in your persistent home directory. Do not use an empty password. On a desktop, use the provider's unlock UI instead. If another daemon owns the bus and the unlocked collection remains inaccessible, GNOME Keyring's `--replace` option can reconcile the daemon. It can interrupt other applications using that daemon; see its [manual](https://manpages.debian.org/bookworm/gnome-keyring/gnome-keyring-daemon.1.en.html).
|
|
87
|
+
|
|
88
|
+
4. Check which collection the provider uses, then check its lock state:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
busctl --user call org.freedesktop.secrets \
|
|
92
|
+
/org/freedesktop/secrets org.freedesktop.Secret.Service ReadAlias s default
|
|
93
|
+
busctl --user get-property org.freedesktop.secrets \
|
|
94
|
+
/org/freedesktop/secrets/collection/login org.freedesktop.Secret.Collection Locked
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The second command assumes the first returned `/org/freedesktop/secrets/collection/login`; otherwise use the returned path. `b false` means unlocked. A default alias of `/` means no default collection exists. Create/select one using the provider's tools before login. See the [Secret Service specification](https://specifications.freedesktop.org/secret-service/latest-single/).
|
|
98
|
+
|
|
99
|
+
5. In the same terminal, run `nansen login --no-browser`. Approve the displayed code in a trusted browser, then run `nansen account` in a fresh process. For a fresh shell, reconnect to the same user bus or repeat the private-bus setup and unlock the persisted keyring first. After OS login, reboot or provider restart, unlock again unless your distribution's login integration already does so. SSH public-key authentication does not itself provide the keyring password. The tested SSH setup keeps the user manager available with `sudo loginctl enable-linger "$USER"`; use this only when you want user services to continue after logout. It starts the user bus again after reboot, but the persisted keyring still needs unlocking. If no user bus is available, use the private-session setup above.
|
|
100
|
+
|
|
101
|
+
### Linux storage recovery
|
|
102
|
+
|
|
103
|
+
| Failure | Recovery |
|
|
104
|
+
| --- | --- |
|
|
105
|
+
| Native credential-store binding could not load | Reinstall with `--include=optional` on a listed architecture. Service installation cannot repair a missing native prebuild. `nansen doctor --offline` does not test the native bindings or open the credential store. |
|
|
106
|
+
| User bus or Secret Service unavailable | Check `busctl --user list`, connect to your user bus, install/start GNOME Keyring and check the default alias. Run as the same user, without `sudo`. Installing the npm binding alone does not supply a service. |
|
|
107
|
+
| Locked collection or dismissed unlock prompt | Unlock with the provider's UI or the stdin command above, on the same bus. A headless terminal cannot display GNOME's graphical unlock prompt. Starting the daemon alone does not unlock existing entries. |
|
|
108
|
+
| Default collection missing or inconsistent | Check the alias and provider state. Reconcile competing daemons using provider tools. Preserve existing keyring files and auth journals. |
|
|
109
|
+
|
|
110
|
+
The CLI recognizes GNOME Keyring's dismissed-unlock response. Other provider failures and timeouts retain the broader unavailable-or-locked message; it does not guess that credentials are absent. Fix storage before repeating approval. Login preflight fails before requesting a browser code and preserves the selected credential. A later failure still uses the existing journal and cleanup rules. `NANSEN_API_KEY` remains usable without either native dependency.
|
|
111
|
+
|
|
112
|
+
Maintainers can run the isolated real-storage check from a checkout:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
node src/__tests__/fixtures/linux-store-qualification.js
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
It creates a disposable password-protected GNOME keyring and private D-Bus, with no access to the invoking user's credentials. It tests save, fresh-process read, locked/unavailable preflight preservation, service restart/unlock, concurrent renewal and logout using a synthetic issuer. It does not establish live browser, SSH, graphical prompt or OS login/reboot support. The setup uses the same provider requirements described in [Git Credential Manager's headless guide](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/secretservice-headless.md).
|
|
119
|
+
|
|
120
|
+
## Servers, containers and CI without secure storage
|
|
121
|
+
|
|
122
|
+
Core API commands work without a credential store or native authentication locking when you supply `NANSEN_API_KEY`. Get your key from [the API page](https://app.nansen.ai/api), set it in your terminal, and check access:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
export NANSEN_API_KEY='<your-api-key>'
|
|
126
|
+
nansen account
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
On Windows PowerShell:
|
|
130
|
+
|
|
131
|
+
```powershell
|
|
132
|
+
$env:NANSEN_API_KEY = '<your-api-key>'
|
|
133
|
+
nansen account
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
You don't need to run `nansen login`. The variable stays set for this terminal session. In CI or automation, inject `NANSEN_API_KEY` through your platform's secret manager. The CLI uses it directly without saving the key to config or opening the browser-session store. The key overrides any saved session until you unset it.
|
|
137
|
+
|
|
138
|
+
To deliberately save an API key, use `nansen login --human` or `nansen login --api-key-stdin`. Both require native authentication locking, so they are not a workaround when that binding is unavailable. Saved browser login also requires a working OS credential store and a supported terminal environment. See [preview platform scope](#preview-platform-scope) for recovery guidance. Wallet passwords have a separate, older plaintext-file fallback; browser-session secrets never use that fallback.
|
|
139
|
+
|
|
46
140
|
## Permissions and credential safety
|
|
47
141
|
|
|
48
142
|
Browser login requests `nansen:api` for the account's API permissions. Ownership, plan, credit, quota and endpoint restrictions still apply. Wallet signing and trade confirmation remain separately authorized. Existing OAuth/MCP read-only grants are unchanged; older read-only sessions require fresh approval for API access.
|
|
@@ -68,11 +162,11 @@ Browser access tokens, refresh tokens and the private device key are stored in t
|
|
|
68
162
|
|
|
69
163
|
The CLI coordinates reads and writes across processes with native locking. Only local filesystems are intended. A login approved earlier cannot overwrite a later completed login or logout. Failed approval or storage leaves the previous selected credential intact.
|
|
70
164
|
|
|
71
|
-
Native lock and keyring bindings are optional package dependencies, but are required for saved-auth writes and browser-session storage. Help, offline diagnostics and direct environment/API-key requests do not open the browser-session store. macOS uses Keychain, Linux uses persistent Secret Service, and the Windows adapter uses Credential Manager.
|
|
165
|
+
Native lock and keyring bindings are optional package dependencies, but are required for saved-auth writes and browser-session storage. Help, offline diagnostics and direct environment/API-key requests do not open the browser-session store. macOS uses Keychain, Linux uses persistent Secret Service, and the Windows adapter uses Credential Manager. Only the combinations qualified above are supported. Windows persistence may roam according to OS policy; device-local-only storage is not promised.
|
|
72
166
|
|
|
73
|
-
|
|
167
|
+
Stock Alpine Linux on x64 remains excluded from saved authentication because it cannot load native locking. Its musl install includes `fs-native-extensions@1.5.1`, but that package has no `linux-x64-musl` prebuild. `nansen login --human` and `nansen logout` return `AUTH_LOCK_UNAVAILABLE` even with optional dependencies enabled. The musl keyring binding loads, but this does not establish that a persistent Secret Service is available. The published `fs-native-extensions@1.5.2` archive and upstream prebuild matrix also lack a musl target; upgrading to it does not close this gap. This change retains `1.5.1` and the existing lock protocol.
|
|
74
168
|
|
|
75
|
-
On Alpine, pass `NANSEN_API_KEY` in the environment for ordinary commands and do not rely on saved-auth writes or logout. Follow the offline recovery guidance below if you already have saved authentication to remove. Linux
|
|
169
|
+
On Alpine, pass `NANSEN_API_KEY` in the environment for ordinary commands and do not rely on saved-auth writes or logout. Follow the offline recovery guidance below if you already have saved authentication to remove. Other Linux configurations require the lifecycle qualification listed above, even when both native bindings load.
|
|
76
170
|
|
|
77
171
|
The session format uses chunked secure entries and a manifest. Incomplete, mixed or corrupt entries are rejected. Larger-than-supported sessions fail without replacing the previous credential. Do not manually modify these entries.
|
|
78
172
|
|