nansen-cli 1.45.0 → 2.0.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.
Files changed (85) hide show
  1. package/CHANGELOG.md +172 -0
  2. package/README.md +158 -18
  3. package/docs/browser-login.md +117 -0
  4. package/package.json +11 -2
  5. package/scripts/postinstall.js +35 -30
  6. package/skills/nansen-agent-guide/SKILL.md +13 -2
  7. package/skills/nansen-alerts-webhook-listener/SKILL.md +5 -2
  8. package/skills/nansen-dca-tracker/SKILL.md +10 -2
  9. package/skills/nansen-defi-positions/SKILL.md +5 -2
  10. package/skills/nansen-exit-signals/SKILL.md +10 -2
  11. package/skills/nansen-fund-tracker/SKILL.md +10 -2
  12. package/skills/nansen-general-search/SKILL.md +10 -2
  13. package/skills/nansen-holder-analysis/SKILL.md +10 -2
  14. package/skills/nansen-limit-orders/SKILL.md +6 -3
  15. package/skills/nansen-perp-screener/SKILL.md +10 -2
  16. package/skills/nansen-perp-trader-profile/SKILL.md +10 -2
  17. package/skills/nansen-polymarket-deep-dive/SKILL.md +10 -2
  18. package/skills/nansen-polymarket-insider-scan/SKILL.md +10 -2
  19. package/skills/nansen-polymarket-trader-profile/SKILL.md +10 -2
  20. package/skills/nansen-portfolio-tracker/SKILL.md +10 -2
  21. package/skills/nansen-prediction-markets/SKILL.md +10 -2
  22. package/skills/nansen-sm-cross-chain-flows/SKILL.md +10 -2
  23. package/skills/nansen-smart-alerts/SKILL.md +9 -4
  24. package/skills/nansen-smart-money-alpha/SKILL.md +10 -2
  25. package/skills/nansen-smart-money-tracker/SKILL.md +10 -2
  26. package/skills/nansen-smart-money-trend/SKILL.md +10 -2
  27. package/skills/nansen-token-research/SKILL.md +10 -2
  28. package/skills/nansen-token-screener/SKILL.md +14 -4
  29. package/skills/nansen-token-transfer-analysis/SKILL.md +10 -2
  30. package/skills/nansen-trading/SKILL.md +27 -2
  31. package/skills/nansen-wallet-batch/SKILL.md +10 -2
  32. package/skills/nansen-wallet-clustering/SKILL.md +10 -2
  33. package/skills/nansen-wallet-deep-dive/SKILL.md +10 -2
  34. package/skills/nansen-wallet-keychain-migration/SKILL.md +23 -15
  35. package/skills/nansen-wallet-manager/SKILL.md +26 -10
  36. package/skills/nansen-wallet-profiler/SKILL.md +10 -2
  37. package/skills/nansen-web-fetcher/SKILL.md +5 -2
  38. package/skills/nansen-web-searcher/SKILL.md +5 -2
  39. package/src/api.js +319 -129
  40. package/src/auth-browser.js +16 -0
  41. package/src/auth-credentials.js +73 -0
  42. package/src/auth-device.js +242 -0
  43. package/src/auth-key-input.js +46 -0
  44. package/src/auth-login.js +90 -0
  45. package/src/auth-state.js +487 -0
  46. package/src/auth-store-native.js +20 -0
  47. package/src/auth-store-worker.js +64 -0
  48. package/src/auth-store.js +140 -0
  49. package/src/auto-paginate.js +272 -0
  50. package/src/bridge.js +309 -85
  51. package/src/cache-inspect.js +345 -0
  52. package/src/chain-ids.js +1 -2
  53. package/src/cli.js +779 -286
  54. package/src/commands/agent.js +20 -9
  55. package/src/commands/alerts.js +1 -1
  56. package/src/commands/completion.js +2 -15
  57. package/src/commands/mcp.js +22 -20
  58. package/src/commands/research.js +4 -2
  59. package/src/cost-cache.js +16 -2
  60. package/src/debug.js +348 -0
  61. package/src/doctor.js +22 -45
  62. package/src/ens.js +3 -1
  63. package/src/execute-guard.js +116 -0
  64. package/src/hl-action.js +41 -13
  65. package/src/limit-order.js +9 -1
  66. package/src/mcp-client-config.js +169 -0
  67. package/src/mcp-client-config.json +17 -0
  68. package/src/mcp-verify.js +6 -5
  69. package/src/perp.js +61 -9
  70. package/src/privy.js +12 -12
  71. package/src/query-options.js +38 -6
  72. package/src/response-meta.js +57 -2
  73. package/src/rpc-urls.js +9 -11
  74. package/src/schema.json +309 -30
  75. package/src/semver.js +23 -4
  76. package/src/swap-simulation.js +35 -30
  77. package/src/telemetry.js +20 -0
  78. package/src/trading.js +806 -40
  79. package/src/transfer.js +75 -9
  80. package/src/update-check.js +9 -1
  81. package/src/wallet.js +240 -20
  82. package/src/walletconnect-trading.js +29 -8
  83. package/src/walletconnect-x402.js +9 -5
  84. package/src/x402-svm.js +123 -64
  85. package/src/x402.js +46 -14
@@ -0,0 +1,117 @@
1
+ # Browser login
2
+
3
+ Browser login saves a session after you approve the CLI in your browser. This source includes browser login, but normal-release acceptance is still pending. No published browser-login cohort is established by these docs. Existing direct API-key commands remain available.
4
+
5
+ ## Preview platform scope
6
+
7
+ The proposed initial preview is limited to macOS arm64, a local Terminal in a GUI login session, an unlocked login Keychain and a local home directory. It remains subject to release approval. Background agents, SSH sessions and network or synchronized home directories are not qualified by a successful local Terminal login.
8
+
9
+ Linux live remote-login qualification is pending. Windows is excluded from the initial preview. The presence of an OS adapter or native prebuilt package does not establish support. Desktop prompt cancellation and OS login/reboot persistence remain unverified.
10
+
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 Keychain access. Missing native dependencies require reinstalling with optional dependencies enabled. There is no plaintext session-storage fallback.
12
+
13
+ ## Commands and selection
14
+
15
+ ```bash
16
+ nansen login
17
+ nansen login --no-browser
18
+ nansen auth status
19
+ nansen account
20
+ nansen logout
21
+ ```
22
+
23
+ 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
+
25
+ `--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.
26
+
27
+ Ordinary commands prefer an existing supported explicit credential override, then `NANSEN_API_KEY`, then the active saved credential. Plain login does not copy an environment key into config. The candidate browser session is checked independently before it replaces a saved credential. An environment key still takes precedence afterward; unset it to use the saved session.
28
+
29
+ Explicit legacy key setup remains available through `nansen login --human` and `nansen login --api-key <key>`. Prefer the hidden prompt over placing secrets in shell arguments. Legacy setup retains option, environment, then hidden-prompt precedence. No new global key option or named profile is introduced.
30
+
31
+ | Starting state | Plain login | Ordinary commands after success |
32
+ | --- | --- | --- |
33
+ | No credentials | Fresh approval installs B | B |
34
+ | Environment key A only | Verify B independently, save B, report override | A until the key is unset, then B |
35
+ | Saved key A | Fresh approval replaces A after durable install | B; failed approval/install preserves A |
36
+ | Saved session A | Fresh approval installs B and retires A | B; failed approval/install preserves A |
37
+ | Environment A and saved B | Fresh approval is independent of A | A still wins; status distinguishes saved and effective |
38
+ | Missing/locked store | Fail before approval with recovery guidance | Existing direct API-key access remains usable |
39
+
40
+ Login verifies the approved account without charging for research. Research uses the effective account's credits, plan and endpoint permissions. Login does not purchase credits or create a subscription. Existing server-side account billing settings remain separate.
41
+
42
+ 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.
43
+
44
+ ## Permissions and credential safety
45
+
46
+ 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.
47
+
48
+ API resource requests use Bearer authentication. Anyone holding a copied access token can use it until the server rejects it or it expires. Device-key proof applies to pairing, refresh and revocation; it is not required on each API resource request. Treat access tokens, refresh tokens and device keys as secrets.
49
+
50
+ Only matching trusted Nansen API origins receive session credentials. Arbitrary RPCs and separate wallet/trading authorization flows do not receive the browser token. MCP installation provisions a separate integration key and cannot export a browser session as an API key.
51
+
52
+ ## Machine output
53
+
54
+ `login --json` and non-TTY login emit NDJSON. There is one pending event and one terminal event on a normal approval attempt. Preflight failure emits only the terminal error. Human progress goes to stderr in machine mode.
55
+
56
+ ```json
57
+ {"version":1,"event":"pending","verification_uri":"https://idp.nansen.ai/device?user_code=ABCD-EFGH","user_code":"ABCD-EFGH","expires_at":"2026-09-19T00:10:00.000Z"}
58
+ {"version":1,"event":"saved","account_id":"example-account","effective_source":"session","cleanup":[]}
59
+ ```
60
+
61
+ Failure/cancellation events contain a fixed code, message and cleanup outcomes. Events never contain device_code, access/refresh token, private JWK, proof or nonce. Public user codes are displayed only for approval, never telemetry. Local diagnostics are cached/unverified; the native store is not opened by status because it could prompt. `storage_access:not_checked_no_prompt` is deliberate, not a success claim.
62
+
63
+ ## Secure storage and compatibility
64
+
65
+ Browser access tokens, refresh tokens and the private device key are stored in the OS credential store. Config and recovery journals retain bounded metadata and credential references. Legacy saved API keys retain their existing config-file storage policy. Do not share config, journals or store contents in public bug reports.
66
+
67
+ 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.
68
+
69
+ 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. These implementations do not widen the preview platform scope above. Windows persistence may roam according to OS policy; device-local-only storage is not promised.
70
+
71
+ 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.
72
+
73
+ Renewal upgrades authentication metadata to v2. Logout retains v2 metadata, so installing an older pre-v2 CLI after logout is not a supported in-place downgrade. Use a tested compatible recovery version. Never force a metadata version, delete journals or restore a superseded key to make an older binary run. Do not run older and newer auth writers concurrently.
74
+
75
+ ## Automatic session renewal
76
+
77
+ Ordinary commands renew the selected session near access-token expiry or after expiry. They do not open the browser. Explicit/environment keys bypass inactive saved sessions. Concurrent commands coordinate renewal through the same authentication owner.
78
+
79
+ A known non-consuming refusal can be retried with backoff. Repeated refusals eventually require fresh login. During a long cooldown, `nansen login` requests new approval. Unexpired access may still be used during a cooldown; expired access is never used.
80
+
81
+ A lost or malformed refresh response can mean the server consumed the refresh token. The CLI does not replay an uncertain token. If a complete replacement was saved, retrying the command can recover it; otherwise follow the error's fresh-login guidance. Storage-access errors require repairing storage first. Correct system time when the error indicates clock skew. API authentication failure never triggers account switching or payment fallback.
82
+
83
+ `nansen auth status` reports cached, unverified metadata without opening the store or renewing a session. Its renewal state does not prove that the server currently accepts the token. `nansen account` is the live check for the effective credential.
84
+
85
+ If an approval expires or was consumed before token issuance completed, run `nansen login` again and approve the new code. The CLI cannot assume that a failed or lost response issued no credentials.
86
+
87
+ ## Logout and uncertainty
88
+
89
+ `nansen logout` clears saved API authentication and attempts to retire its browser session. It preserves wallets, wallet passwords, environment variables and independently managed API keys. It does not sign out unrelated sessions.
90
+
91
+ Local removal, a server retirement receipt and observed API rejection are separate outcomes. Revocation can take time to reach API caches. A receipt marked recorded/pending is not an immediate-rejection guarantee. Legacy refresh-only retirement can leave access tokens usable until expiry; the CLI reports that limitation. No fixed propagation time is promised here.
92
+
93
+ A locked store can allow deselection while preventing physical deletion. Unlock it and rerun logout. If remote retirement is unconfirmed, treat the remote session as potentially usable and contact support through a private channel. A missing local credential is not proof of remote revocation.
94
+
95
+ ## Offline recovery without native locking
96
+
97
+ Restore the native optional dependencies before modifying saved authentication. Environment/API-key requests, help and offline diagnostics remain usable without opening the browser-session store. Do not use an incompatible older CLI as a recovery shortcut. Platforms without a verified working native binding are outside the browser-login preview.
98
+
99
+ For emergency removal of a **legacy saved API key only**, first stop every CLI/auth process, including older CLI versions. If any pending, corrupt or unrecognized auth-operations journal exists, stop and use a compatible recovery binary or support-assisted reconciliation instead. Back up config.json securely without displaying its contents. In `~/.nansen/config.json`, remove only `apiKey` and replace `auth` with `{"version":1,"selectionEpoch":"<fresh UUID>","active":{"kind":"none"}}`. If the existing auth version is 2, retain version 2 in this legacy-key-only tombstone; do not downgrade it. Generate the UUID with `node -e 'console.log(require("node:crypto").randomUUID())'`; it is not a secret. Preserve every other config field, file permissions and all wallet files. Do not modify a config whose `auth.active.kind` is `session`: restore native locking instead so its generation remains available for retirement. Do not delete `auth-operations`, lock files or OS credential entries. This offline edit removes saved-key selection only; it does not revoke an API key or remove an environment override. Once native support is restored, rerun `nansen logout` to drain pending cleanup. The packaged copy of this document is available under `docs/browser-login.md` in the installed package.
100
+
101
+ ## Damaged or unrecognized journals
102
+
103
+ `AUTH_JOURNAL_INVALID` means recovery metadata could not be read safely. `AUTH_STATE_INVALID` can indicate disagreement between the selected credential and its journal. Logout may already have cleared selection while leaving cleanup incomplete. These errors do not prove the secure entries were removed or the remote session was revoked.
104
+
105
+ Do not delete, rename or quarantine journals to make login succeed. Stop all CLI/auth processes and preserve the config, journals and secure-store entries. Restore a known-valid backup only for the same operation and current state, preserving ownership and permissions. Otherwise contact support privately to reconcile the metadata. Never post credential-bearing files or store contents publicly.
106
+
107
+ After validated recovery, rerun logout and inspect its cleanup result. Cleanup is bounded per invocation; locked storage may require another attempt after unlocking. Damaged metadata requires reconciliation, not repeated unlocks or fresh approvals.
108
+
109
+ ## Telemetry preferences
110
+
111
+ Set `DO_NOT_TRACK=1` or `NANSEN_NO_TELEMETRY=1` to disable telemetry. Login/logout telemetry uses fixed command paths and bounded outcome/error categories. It excludes tokens, device/user codes, private keys, flag values and raw hostnames. Local status and offline doctor remain offline; cached metadata is not proof of validity or unlocked storage.
112
+
113
+ ## Release status
114
+
115
+ Browser-login publication and production access require separate release approval. The proposed platform scope above is not a normal-release support claim. Current source code or a passing test does not establish that browser login is enabled for your account. Use the documented API-key setup if browser access is unavailable.
116
+
117
+ Maintainers should use the [release checklist](https://github.com/nansen-ai/nansen-cli/blob/main/docs/releases/browser-login-checklist.md) in the repository. Internal validation captures, deployment inventories and incident records belong in access-controlled project records, not the public package.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nansen-cli",
3
- "version": "1.45.0",
3
+ "version": "2.0.0",
4
4
  "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
@@ -13,7 +13,8 @@
13
13
  "!src/__tests__/**",
14
14
  "skills/**",
15
15
  "scripts/postinstall.js",
16
- "CHANGELOG.md"
16
+ "CHANGELOG.md",
17
+ "docs/browser-login.md"
17
18
  ],
18
19
  "scripts": {
19
20
  "postinstall": "node scripts/postinstall.js",
@@ -27,6 +28,10 @@
27
28
  "test:send": "vitest run --config vitest.e2e.config.js src/__tests__/send.e2e.test.js",
28
29
  "test:privy": "vitest run --config vitest.e2e.config.js src/__tests__/privy.e2e.test.js",
29
30
  "lint": "eslint .",
31
+ "mcp:generate": "node scripts/generate-mcp-docs.js",
32
+ "mcp:check": "node scripts/generate-mcp-docs.js --check",
33
+ "mcp:check-pin": "node scripts/check-mcp-remote-pin.js",
34
+ "mcp:check-consumers": "node scripts/check-mcp-consumers.js",
30
35
  "lint:fix": "eslint . --fix",
31
36
  "changeset": "changeset",
32
37
  "changeset:version": "changeset version && npm install --package-lock-only",
@@ -76,5 +81,9 @@
76
81
  "@noble/curves": "^2.4.0",
77
82
  "@noble/hashes": "^2.4.0",
78
83
  "@scure/base": "^2.0.0"
84
+ },
85
+ "optionalDependencies": {
86
+ "@napi-rs/keyring": "2.1.0",
87
+ "fs-native-extensions": "1.5.1"
79
88
  }
80
89
  }
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * Runs after `npm install -g nansen-cli` and offers two optional steps:
7
7
  * 1. Install the Nansen AI coding skill (`npx skills add nansen-ai/nansen-cli`)
8
- * 2. Check account status to verify the API key works (0 credits)
8
+ * 2. Check account status to verify the effective credential (0 credits)
9
9
  *
10
10
  * Non-interactive environments (CI, piped stdin) get a one-liner tip instead.
11
11
  * Always exits 0 — onboarding failures must never break installation.
@@ -13,7 +13,7 @@
13
13
 
14
14
  import { createInterface } from "readline";
15
15
  import { execFileSync, spawn } from "child_process";
16
- import { existsSync, readFileSync } from "fs";
16
+ import { existsSync, realpathSync } from "fs";
17
17
  import { join, dirname } from "path";
18
18
  import { fileURLToPath } from "url";
19
19
 
@@ -60,18 +60,6 @@ function hasNpx() {
60
60
  }
61
61
  }
62
62
 
63
- function isLoggedIn() {
64
- const home = process.env.HOME || process.env.USERPROFILE || "";
65
- const configFile = join(home, ".nansen", "config.json");
66
- if (!existsSync(configFile)) return false;
67
- try {
68
- const config = JSON.parse(readFileSync(configFile, "utf8"));
69
- return !!(config.apiKey || config.api_key);
70
- } catch {
71
- return false;
72
- }
73
- }
74
-
75
63
  function isSkillInstalled() {
76
64
  const home = process.env.HOME || process.env.USERPROFILE || "";
77
65
  const locations = [
@@ -115,9 +103,9 @@ async function installSkill() {
115
103
 
116
104
  log(`The Nansen skill lets AI coding agents (Cursor, Claude Code, etc.) query`);
117
105
  log(`on-chain data, track smart money, analyze tokens, and use nansen trade.`);
118
- const answer = await prompt(` Install Nansen skill for your AI coding agent? [Y/n] `);
106
+ const answer = await prompt(` Install Nansen skill for your AI coding agent? [y/N] `);
119
107
 
120
- if (/^n/i.test(answer)) {
108
+ if (!/^y(es)?$/i.test(answer)) {
121
109
  log(`Skipped. You can install it later with: ${CYAN}npx skills add ${SKILL_REPO}${RESET}`);
122
110
  return;
123
111
  }
@@ -130,20 +118,31 @@ async function installSkill() {
130
118
  }
131
119
 
132
120
  async function testQuery() {
133
- if (!isLoggedIn()) {
121
+ // Selection reads metadata only. Never open storage or verify during install.
122
+ let selection;
123
+ try {
124
+ const { resolveCredential, assertUsableSelection } = await import("../src/auth-credentials.js");
125
+ selection = resolveCredential();
126
+ assertUsableSelection(selection);
127
+ } catch {
128
+ log(`Saved or selected authentication needs attention. Run: nansen auth status`);
129
+ return;
130
+ }
131
+ if (selection.kind === "anonymous") {
134
132
  log();
135
- log(`Not logged in yet. Run ${CYAN}nansen login --human${RESET} to authenticate.`);
136
- log(`Get your API key at: ${CYAN}https://app.nansen.ai/auth/agent-setup${RESET}`);
133
+ log(`Run ${CYAN}nansen login${RESET} for browser approval, or use NANSEN_API_KEY directly.`);
134
+ log(`Browser login requires a supported OS credential store and enabled server admission. See docs/browser-login.md in this package.`);
137
135
  return;
138
136
  }
139
137
 
140
138
  log();
141
- log(`Your API key is configured. Let's verify it works.`);
142
- const answer = await prompt(` Check account status? (${DIM}${TEST_QUERY_DISPLAY}${RESET}) [Y/n] `);
139
+ log(selection.kind === "session"
140
+ ? `A browser session is configured; cached metadata is unverified and storage has not been checked.`
141
+ : `An API key is configured; it has not been verified.`);
142
+ const answer = await prompt(` Check account status? (${DIM}${TEST_QUERY_DISPLAY}${RESET}, free; may renew a session) [y/N] `);
143
143
 
144
- if (/^n/i.test(answer)) {
145
- log(`Skipped. You're all set! Try: ${CYAN}nansen research smart-money netflow --chain solana${RESET}`);
146
- log(`For trading: ${CYAN}nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000${RESET}`);
144
+ if (!/^y(es)?$/i.test(answer)) {
145
+ log(`Skipped account verification. Run ${CYAN}nansen account${RESET} when ready.`);
147
146
  return;
148
147
  }
149
148
 
@@ -156,11 +155,11 @@ async function testQuery() {
156
155
  log(`${GREEN}✓${RESET} All set! Run ${CYAN}nansen help${RESET} to see all available commands.`);
157
156
  } else {
158
157
  log();
159
- log(`${YELLOW}Query failed. Check your API key with: nansen auth status${RESET}`);
158
+ log(`${YELLOW}Account check failed. Inspect the effective credential with: nansen auth status${RESET}`);
160
159
  }
161
160
  }
162
161
 
163
- async function main() {
162
+ export async function main() {
164
163
  // Only run for global installs; skip local npm install / npm ci
165
164
  if (process.env.npm_lifecycle_event === "postinstall" && process.env.npm_config_global !== "true") {
166
165
  return;
@@ -172,7 +171,7 @@ async function main() {
172
171
  log(`${BOLD}Nansen CLI installed!${RESET}`);
173
172
  log();
174
173
  log(`Tip: Run '${CYAN}npx skills add ${SKILL_REPO}${RESET}' to install the Nansen AI coding skill.`);
175
- log(`Tip: Run '${CYAN}nansen login --human${RESET}' to authenticate.`);
174
+ log(`Tip: Run '${CYAN}nansen login${RESET}' for browser approval, or use NANSEN_API_KEY directly.`);
176
175
  log(`Tip: To trade, first create a wallet with '${CYAN}nansen wallet create${RESET}', then quote with '${CYAN}nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000${RESET}' and execute with '${CYAN}nansen trade execute --quote <id>${RESET}'.`);
177
176
  return;
178
177
  }
@@ -186,6 +185,12 @@ async function main() {
186
185
  log();
187
186
  }
188
187
 
189
- main().catch(() => {
190
- // Never fail installation due to onboarding errors
191
- });
188
+ // Node resolves the module URL through symlinks, but argv may retain them.
189
+ // An unavailable entry path or onboarding failure must never fail installation.
190
+ try {
191
+ if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
192
+ main().catch(() => {});
193
+ }
194
+ } catch {
195
+ // Importing with a missing/non-file argv entry remains silent.
196
+ }
@@ -4,8 +4,6 @@ description: Routing guide -- when to use `nansen agent` (AI research) vs direct
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -15,9 +13,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Nansen account API calls accept a selected `nansen:api` browser session or conventional API key with the same permissions. `NANSEN_API_KEY` takes precedence; optional `primaryEnv` preserves configured-key injection. Run `nansen auth status` for offline selection. Cached access expiry alone permits automatic renewal during an authorized task. Stop on anonymous selection, invalid state, blocked/uncertain renewal or actual auth failure; never drop a credential or fall back to anonymous x402 payment. Browser login does not grant wallet signing, privileged service identity or a persistent MCP integration key. Preserve all confirmation, signing, sanctions and geographic checks below. Browser rollout acceptance is still pending.
19
+
20
+
18
21
 
19
22
  # Agent vs CLI Routing
20
23
 
24
+ Public agent fast/expert and direct API commands accept the selected nansen:api browser session or conventional API key under the same account permissions.
25
+
21
26
  | Need a... | Use |
22
27
  |-----------|-----|
23
28
  | **take** (analysis, interpretation) | `nansen agent` |
@@ -56,3 +61,9 @@ Cost: 5-50 credits per call
56
61
  - Don't use `nansen agent` for simple data fetches -- 40x more expensive
57
62
  - Don't use raw CLI for open-ended analysis -- returns data, not interpretation
58
63
  - Don't chain 3+ agent calls -- get raw data via CLI, call agent once for synthesis
64
+
65
+ ## Browser session scope
66
+
67
+ Plain `nansen login` requests fresh browser approval; `--no-browser` prints the link/code for remote use. NANSEN_API_KEY overrides the single saved credential. Use `nansen auth status` for offline cached/unverified selection details and `nansen account` for a free live check. Explicit `login --human` or `login --api-key` retains legacy key setup. Selected browser sessions renew automatically; uncertain renewal requires fresh login without replay or fallback to another account/payment.
68
+
69
+ Browser nansen:api grants have API-key-equivalent account permissions, subject to enabled admission and the same endpoint restrictions. Internal service identity and wallet signing are not granted. Browser sessions cannot authorize wallet signing or be exported as MCP keys. Normal-release acceptance and a published cohort remain pending.
@@ -4,8 +4,6 @@ description: Set up a local webhook server to receive Nansen smart alerts in rea
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  - node
@@ -16,6 +14,11 @@ metadata:
16
14
  bins: [nansen]
17
15
  allowed-tools: Bash(nansen:*), Bash(node:*), Bash(npx:*), Bash(ngrok:*), Write
18
16
  ---
17
+ ## Authentication
18
+
19
+ Nansen account API calls accept a selected `nansen:api` browser session or conventional API key with the same permissions. `NANSEN_API_KEY` takes precedence; optional `primaryEnv` preserves configured-key injection. Run `nansen auth status` for offline selection. Cached access expiry alone permits automatic renewal during an authorized task. Stop on anonymous selection, invalid state, blocked/uncertain renewal or actual auth failure; never drop a credential or fall back to anonymous x402 payment. Browser login does not grant wallet signing, privileged service identity or a persistent MCP integration key. Preserve all confirmation, signing, sanctions and geographic checks below. Browser rollout acceptance is still pending.
20
+
21
+
19
22
 
20
23
  # Alert Webhook Listener
21
24
 
@@ -4,8 +4,6 @@ description: "What tokens are whales dollar-cost averaging into? Jupiter DCA str
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -16,6 +14,16 @@ metadata:
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
18
16
 
17
+ ## Authentication
18
+
19
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
20
+
21
+ Before any research command or loop, require an explicitly selected API key or saved browser session. Run `nansen auth status` first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free `nansen account` check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.
22
+
23
+ Use `nansen login` for fresh browser approval when server admission and the supported platform cohort are enabled, or configure a conventional API key. `NANSEN_API_KEY` overrides the saved session. OpenClaw's optional `primaryEnv` mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser rollout acceptance is still pending.
24
+
25
+ API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and `nansen account` never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.
26
+
19
27
  # DCA Watch
20
28
 
21
29
  **Answers:** "What tokens are whales dollar-cost averaging into on Solana?"
@@ -4,8 +4,6 @@ description: "What DeFi positions does a wallet hold? Protocol-by-protocol break
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -15,6 +13,11 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Nansen account API calls accept a selected `nansen:api` browser session or conventional API key with the same permissions. `NANSEN_API_KEY` takes precedence; optional `primaryEnv` preserves configured-key injection. Run `nansen auth status` for offline selection. Cached access expiry alone permits automatic renewal during an authorized task. Stop on anonymous selection, invalid state, blocked/uncertain renewal or actual auth failure; never drop a credential or fall back to anonymous x402 payment. Browser login does not grant wallet signing, privileged service identity or a persistent MCP integration key. Preserve all confirmation, signing, sanctions and geographic checks below. Browser rollout acceptance is still pending.
19
+
20
+
18
21
 
19
22
  # DeFi Exposure
20
23
 
@@ -4,8 +4,6 @@ description: "Is smart money exiting a token I hold? Net flow direction, seller
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -16,6 +14,16 @@ metadata:
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
18
16
 
17
+ ## Authentication
18
+
19
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
20
+
21
+ Before any research command or loop, require an explicitly selected API key or saved browser session. Run `nansen auth status` first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free `nansen account` check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.
22
+
23
+ Use `nansen login` for fresh browser approval when server admission and the supported platform cohort are enabled, or configure a conventional API key. `NANSEN_API_KEY` overrides the saved session. OpenClaw's optional `primaryEnv` mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser rollout acceptance is still pending.
24
+
25
+ API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and `nansen account` never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.
26
+
19
27
  # Exit Signal
20
28
 
21
29
  **Answers:** "Is smart money exiting a token I hold? Should I be worried?"
@@ -4,8 +4,6 @@ description: "What are crypto funds and VCs holding right now? Cross-chain fund
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -16,6 +14,16 @@ metadata:
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
18
16
 
17
+ ## Authentication
18
+
19
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
20
+
21
+ Before any research command or loop, require an explicitly selected API key or saved browser session. Run `nansen auth status` first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free `nansen account` check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.
22
+
23
+ Use `nansen login` for fresh browser approval when server admission and the supported platform cohort are enabled, or configure a conventional API key. `NANSEN_API_KEY` overrides the saved session. OpenClaw's optional `primaryEnv` mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser rollout acceptance is still pending.
24
+
25
+ API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and `nansen account` never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.
26
+
19
27
  # Fund Watch
20
28
 
21
29
  **Answers:** "What are crypto funds and VCs holding right now?"
@@ -4,8 +4,6 @@ description: Search for tokens or entities by name. Use when you have a token na
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -16,6 +14,16 @@ metadata:
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
18
16
 
17
+ ## Authentication
18
+
19
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
20
+
21
+ Before any research command or loop, require an explicitly selected API key or saved browser session. Run `nansen auth status` first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free `nansen account` check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.
22
+
23
+ Use `nansen login` for fresh browser approval when server admission and the supported platform cohort are enabled, or configure a conventional API key. `NANSEN_API_KEY` overrides the saved session. OpenClaw's optional `primaryEnv` mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser rollout acceptance is still pending.
24
+
25
+ API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and `nansen account` never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.
26
+
19
27
  # Search
20
28
 
21
29
  ```bash
@@ -4,8 +4,6 @@ description: "Is this token held by quality wallets or retail noise? SM holder r
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -16,6 +14,16 @@ metadata:
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
18
16
 
17
+ ## Authentication
18
+
19
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
20
+
21
+ Before any research command or loop, require an explicitly selected API key or saved browser session. Run `nansen auth status` first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free `nansen account` check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.
22
+
23
+ Use `nansen login` for fresh browser approval when server admission and the supported platform cohort are enabled, or configure a conventional API key. `NANSEN_API_KEY` overrides the saved session. OpenClaw's optional `primaryEnv` mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser rollout acceptance is still pending.
24
+
25
+ API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and `nansen account` never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.
26
+
19
27
  # Holder Quality
20
28
 
21
29
  **Answers:** "Is this token held by quality wallets or retail noise?"
@@ -4,8 +4,6 @@ description: Guide users through native limit orders on Solana via `nansen trade
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -15,6 +13,11 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Nansen account API calls accept a selected `nansen:api` browser session or conventional API key with the same permissions. `NANSEN_API_KEY` takes precedence; optional `primaryEnv` preserves configured-key injection. Run `nansen auth status` for offline selection. Cached access expiry alone permits automatic renewal during an authorized task. Stop on anonymous selection, invalid state, blocked/uncertain renewal or actual auth failure; never drop a credential or fall back to anonymous x402 payment. Browser login does not grant wallet signing, privileged service identity or a persistent MCP integration key. Preserve all confirmation, signing, sanctions and geographic checks below. Browser rollout acceptance is still pending.
19
+
20
+
18
21
 
19
22
  # Limit Orders
20
23
 
@@ -38,7 +41,7 @@ distinct paths — pick the one that matches the user's chain:
38
41
  - The wallet must hold the sell token plus a small amount of SOL for fees.
39
42
  - For the alert fallback: a notification channel (Telegram chat ID, Slack or
40
43
  Discord webhook, or generic webhook URL).
41
- - `NANSEN_API_KEY`. Smart alerts are internal-only; non-internal users get 404.
44
+ - A selected nansen:api browser session or conventional API key for smart alerts; existing endpoint restrictions still apply.
42
45
  - First-time `trade limit-order create` auto-registers a trading vault and
43
46
  caches a JWT at `~/.nansen/limit-order-auth.json` for ~23h.
44
47
 
@@ -4,8 +4,6 @@ description: "What is the state of the Hyperliquid perp market? Top contracts by
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -16,6 +14,16 @@ metadata:
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
18
16
 
17
+ ## Authentication
18
+
19
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
20
+
21
+ Before any research command or loop, require an explicitly selected API key or saved browser session. Run `nansen auth status` first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free `nansen account` check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.
22
+
23
+ Use `nansen login` for fresh browser approval when server admission and the supported platform cohort are enabled, or configure a conventional API key. `NANSEN_API_KEY` overrides the saved session. OpenClaw's optional `primaryEnv` mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser rollout acceptance is still pending.
24
+
25
+ API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and `nansen account` never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.
26
+
19
27
  # Perp Market Scan
20
28
 
21
29
  **Answers:** "What's the state of the Hyperliquid perp market right now?"
@@ -4,8 +4,6 @@ description: "Deep dive on a Hyperliquid perp trader. Identity, open positions,
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -16,6 +14,16 @@ metadata:
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
18
16
 
17
+ ## Authentication
18
+
19
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
20
+
21
+ Before any research command or loop, require an explicitly selected API key or saved browser session. Run `nansen auth status` first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free `nansen account` check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.
22
+
23
+ Use `nansen login` for fresh browser approval when server admission and the supported platform cohort are enabled, or configure a conventional API key. `NANSEN_API_KEY` overrides the saved session. OpenClaw's optional `primaryEnv` mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser rollout acceptance is still pending.
24
+
25
+ API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and `nansen account` never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.
26
+
19
27
  # Perp Trader
20
28
 
21
29
  **Answers:** "What is this perp trader doing? What are their positions and track record?"
@@ -4,8 +4,6 @@ description: "Deep dive on a Polymarket market — OHLCV, orderbook, top holders
4
4
  metadata:
5
5
  openclaw:
6
6
  requires:
7
- env:
8
- - NANSEN_API_KEY
9
7
  bins:
10
8
  - nansen
11
9
  primaryEnv: NANSEN_API_KEY
@@ -16,6 +14,16 @@ metadata:
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
18
16
 
17
+ ## Authentication
18
+
19
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
20
+
21
+ Before any research command or loop, require an explicitly selected API key or saved browser session. Run `nansen auth status` first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free `nansen account` check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.
22
+
23
+ Use `nansen login` for fresh browser approval when server admission and the supported platform cohort are enabled, or configure a conventional API key. `NANSEN_API_KEY` overrides the saved session. OpenClaw's optional `primaryEnv` mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser rollout acceptance is still pending.
24
+
25
+ API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and `nansen account` never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.
26
+
19
27
  # Prediction Market Deep Dive
20
28
 
21
29
  **Answers:** "What's happening in this specific market? Who holds it, who's trading it?"