nansen-cli 2.3.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 +64 -0
- package/README.md +32 -32
- 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 +17 -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 +202 -97
- 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 +188 -89
- package/src/commands/agent.js +2 -3
- package/src/commands/alerts.js +277 -9
- package/src/commands/feedback.js +98 -37
- 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/input-validation.js +551 -0
- package/src/limit-order.js +12 -3
- package/src/perp.js +2 -1
- package/src/privy.js +89 -11
- package/src/query-options.js +30 -7
- package/src/rpc-urls.js +3 -1
- package/src/schema.json +1137 -145
- package/src/solana-tx.js +4 -0
- package/src/trade-validation.js +167 -8
- package/src/trading.js +172 -12
- package/src/transfer.js +7 -1
- package/src/update-check.js +32 -5
- package/src/wallet.js +211 -57
- package/src/walletconnect-x402.js +14 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,69 @@
|
|
|
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
|
+
|
|
3
67
|
## 2.3.0
|
|
4
68
|
|
|
5
69
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -26,6 +26,18 @@ Send product feedback to Nansen with your configured API key or login session:
|
|
|
26
26
|
}
|
|
27
27
|
```
|
|
28
28
|
|
|
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
|
+
|
|
29
41
|
Save the report as `feedback.json`. Omit the ID to save private recovery data before sending:
|
|
30
42
|
|
|
31
43
|
```bash
|
|
@@ -93,32 +105,27 @@ uncertain attempt remains uncertain. Never switch accounts or pay to bypass deni
|
|
|
93
105
|
|
|
94
106
|
## Auth
|
|
95
107
|
|
|
96
|
-
|
|
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.
|
|
97
111
|
|
|
98
112
|
```bash
|
|
99
|
-
nansen login
|
|
100
|
-
nansen login --no-browser # approve on another device; same storage requirements
|
|
101
|
-
nansen auth status # offline, cached/unverified credential selection
|
|
102
|
-
nansen account # free live check, including with zero research credits
|
|
103
|
-
nansen logout # clear saved API auth; preserve wallets and environment keys
|
|
113
|
+
nansen login
|
|
104
114
|
```
|
|
105
115
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
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.
|
|
109
|
-
|
|
110
|
-
For automation, pipe a key from your secret manager into `nansen login --api-key-stdin`, or redirect a protected key file:
|
|
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.
|
|
111
117
|
|
|
112
118
|
```bash
|
|
113
|
-
nansen
|
|
119
|
+
NANSEN_WALLET_PASSWORD='<your-wallet-password>' nansen wallet create --name my-wallet
|
|
114
120
|
```
|
|
115
121
|
|
|
116
|
-
|
|
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):
|
|
117
123
|
|
|
118
|
-
|
|
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
|
+
```
|
|
119
127
|
|
|
120
|
-
|
|
121
|
-
- **MPP:** 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](#mpp--tempo).
|
|
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.
|
|
122
129
|
|
|
123
130
|
## Verify your MCP setup
|
|
124
131
|
|
|
@@ -166,18 +173,6 @@ Plus the `historical-*` point-in-time commands — run `nansen research help` fo
|
|
|
166
173
|
|
|
167
174
|
Run `nansen schema --pretty` for the full subcommand and field reference.
|
|
168
175
|
|
|
169
|
-
## Browser login compatibility and scope
|
|
170
|
-
|
|
171
|
-
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.
|
|
172
|
-
|
|
173
|
-
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.
|
|
174
|
-
|
|
175
|
-
`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.
|
|
176
|
-
|
|
177
|
-
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.
|
|
178
|
-
|
|
179
|
-
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).
|
|
180
|
-
|
|
181
176
|
## MCP
|
|
182
177
|
|
|
183
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. -->
|
|
@@ -378,7 +373,7 @@ tempo wallet fund # follow the on-screen instructions to deposit USDC
|
|
|
378
373
|
**Calling the Nansen API via tempo:**
|
|
379
374
|
|
|
380
375
|
```bash
|
|
381
|
-
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 \
|
|
382
377
|
--json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
|
|
383
378
|
```
|
|
384
379
|
|
|
@@ -573,7 +568,10 @@ Default JSON output still contains the complete response body.
|
|
|
573
568
|
| Code | Action |
|
|
574
569
|
|------|--------|
|
|
575
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). |
|
|
576
|
-
| `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. |
|
|
577
575
|
| `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
|
|
578
576
|
| `UNSUPPORTED_FILTER` | Remove the filter and retry. |
|
|
579
577
|
| `PLAN_UPGRADE_REQUIRED` | The endpoint or option needs a higher subscription plan. Do not retry. |
|
|
@@ -581,7 +579,9 @@ Default JSON output still contains the complete response body.
|
|
|
581
579
|
| `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
|
|
582
580
|
| `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
|
|
583
581
|
|
|
584
|
-
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`.
|
|
585
585
|
|
|
586
586
|
**Error metadata.** When the API reports them, `details` carries:
|
|
587
587
|
|
|
@@ -598,7 +598,7 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
|
|
|
598
598
|
| Symptom | Fix |
|
|
599
599
|
|---------|-----|
|
|
600
600
|
| `command not found` | `npm install -g nansen-cli` |
|
|
601
|
-
| 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 |
|
|
602
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 |
|
|
603
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 |
|
|
604
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
|
|