nansen-cli 1.46.0 → 2.0.1

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 (78) hide show
  1. package/CHANGELOG.md +122 -0
  2. package/README.md +157 -14
  3. package/docs/browser-login.md +123 -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 +8 -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 +5 -2
  35. package/skills/nansen-wallet-manager/SKILL.md +11 -9
  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 +202 -104
  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 +89 -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 +288 -0
  50. package/src/bridge.js +126 -21
  51. package/src/cache-inspect.js +345 -0
  52. package/src/cli.js +473 -199
  53. package/src/commands/agent.js +15 -7
  54. package/src/commands/completion.js +2 -15
  55. package/src/commands/mcp.js +20 -18
  56. package/src/cost-cache.js +16 -2
  57. package/src/debug.js +348 -0
  58. package/src/doctor.js +22 -45
  59. package/src/hl-action.js +41 -13
  60. package/src/limit-order.js +1 -1
  61. package/src/mcp-client-config.js +169 -0
  62. package/src/mcp-client-config.json +17 -0
  63. package/src/mcp-verify.js +6 -5
  64. package/src/perp.js +41 -0
  65. package/src/privy.js +12 -12
  66. package/src/response-meta.js +56 -1
  67. package/src/rpc-urls.js +9 -11
  68. package/src/schema.json +185 -8
  69. package/src/semver.js +23 -4
  70. package/src/swap-simulation.js +35 -30
  71. package/src/telemetry.js +20 -0
  72. package/src/trading.js +266 -29
  73. package/src/transfer.js +53 -6
  74. package/src/update-check.js +9 -1
  75. package/src/wallet.js +107 -17
  76. package/src/walletconnect-trading.js +24 -5
  77. package/src/x402-svm.js +123 -64
  78. package/src/x402.js +46 -14
@@ -4,8 +4,6 @@ description: Manage smart alerts — list, create, update, toggle, delete. Use w
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,10 +13,15 @@ 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
+
20
+
18
21
 
19
22
  # Smart Alerts
20
23
 
21
- CRUD management for smart alerts. Alerts are internal-only (requires Nansen internal API key).
24
+ CRUD management for smart alerts. Browser sessions and API keys use the same account and endpoint checks; privileged or internal service identity is not granted by login.
22
25
 
23
26
  ## Quick Reference
24
27
 
@@ -136,5 +139,7 @@ nansen alerts create \
136
139
  - Multiple channels can be combined: `--telegram 123 --slack https://... --webhook https://...`
137
140
  - `--webhook <url>` sends a POST request with the alert payload to any HTTP/HTTPS endpoint. Useful for server deployments, Zapier, n8n, or custom integrations. The endpoint must be publicly reachable and return a 2xx response.
138
141
  - `--data '<json>'` merges raw JSON on top of named flags (escape hatch for fields without named flags).
139
- - Alert endpoints are internal-only. Non-internal users receive 404.
142
+ - Alert endpoints retain their normal ownership, plan and quota checks for both selected credentials.
140
143
  - Use single quotes for names with `$` or special characters: `--name 'SM >$1M'`
144
+
145
+ Browser login uses `nansen:api` with the same account API permissions as an API key, subject to existing plan/account/endpoint checks. Trading still requires a separately configured wallet and its signing authorization. Hosted simulation uses the selected credential only on the matching trusted Nansen API origin; arbitrary RPC endpoints never receive Nansen credentials.
@@ -4,8 +4,6 @@ description: "What tokens is smart money accumulating before they pump? Token sc
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
 
19
27
  # Alpha Discovery
20
28
 
@@ -4,8 +4,6 @@ description: Smart money tracking — netflow, trades, holdings, perp trades. Us
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
 
19
27
  # Smart Money
20
28
 
@@ -4,8 +4,6 @@ description: "Has SM been in this token for weeks, or did they just enter? Are t
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
  ```bash
19
27
  TOKEN=<address> CHAIN=ethereum
20
28
  nansen research smart-money netflow --chain $CHAIN --limit 200
@@ -4,8 +4,6 @@ description: Token deep dive — info, OHLCV, holders, flows, flow intelligence,
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
 
19
27
  # Token Deep Dive
20
28
 
@@ -4,8 +4,6 @@ description: "Discover trending tokens — screener, SM holdings, Nansen indicat
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
 
19
27
  # Token Discovery
20
28
 
@@ -30,7 +38,9 @@ nansen research token screener --chain $CHAIN --timeframe 24h --limit 20
30
38
  # Smart money only
31
39
  nansen research token screener --chain $CHAIN --timeframe 24h --smart-money --limit 20
32
40
 
33
- # Search within screener results (client-side filter)
41
+ # Search within screener results (client-side filter over the fetched candidates).
42
+ # Check _meta.search: complete=false means lower-ranked tokens were not searched —
43
+ # widen with --limit 1000 or --paginate, or narrow with --filters.
34
44
  nansen research token screener --chain $CHAIN --search "bonk"
35
45
 
36
46
  # Smart money holdings — what SM wallets are holding
@@ -46,7 +56,7 @@ nansen research token indicators --token $TOKEN --chain $CHAIN
46
56
  nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
47
57
  # → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets, public_figure
48
58
 
49
- # Nansen Score Top Tokens — "what should I buy?" (public endpoint, any authenticated API key)
59
+ # Nansen Score Top Tokens — "what should I buy?" (account API endpoint; normal entitlements apply)
50
60
  # Use this FIRST for discovery, then drill into individual tokens with `indicators` above
51
61
  nansen research token top-tokens --limit 25
52
62
  nansen research token top-tokens --market-cap largecap --limit 10
@@ -4,8 +4,6 @@ description: "Where is this token moving and why? Large transfers, flow trends o
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
 
19
27
  # Token Forensics
20
28
 
@@ -5,7 +5,6 @@ metadata:
5
5
  openclaw:
6
6
  requires:
7
7
  env:
8
- - NANSEN_API_KEY
9
8
  - NANSEN_WALLET_PASSWORD
10
9
  bins:
11
10
  - nansen
@@ -16,6 +15,11 @@ metadata:
16
15
  bins: [nansen]
17
16
  allowed-tools: Bash(nansen:*)
18
17
  ---
18
+ ## Authentication
19
+
20
+ 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
21
+
22
+
19
23
 
20
24
  # Trade
21
25
 
@@ -198,7 +202,7 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
198
202
  | Var | Purpose |
199
203
  |-----|---------|
200
204
  | `NANSEN_WALLET_PASSWORD` | **Required for `trade execute`.** Wallet encryption password — persisted in `~/.nansen/.env`. Source before executing: `source ~/.nansen/.env && nansen trade execute ...` |
201
- | `NANSEN_API_KEY` | API key (also set via `nansen login`). `trade quote` and `trade execute` need it for the pre-trade compliance screen below. |
205
+ | `NANSEN_API_KEY` | API key (also set via explicit `nansen login --human`; browser sessions are not wallet or RPC keys) |
202
206
  | `NANSEN_YES` | Set to `1` to skip the `execute` confirmation prompt, like `--yes` |
203
207
 
204
208
  > **Agents:** Never hold a wallet password only in session memory. If `NANSEN_WALLET_PASSWORD` is not in `~/.nansen/.env`, follow the setup flow in the nansen-wallet-manager skill Password Policy to generate and persist one before proceeding.
@@ -264,3 +268,5 @@ nansen perp account # account value, unrealized PnL, margin used, withdrawab
264
268
 
265
269
  - npm: https://www.npmjs.com/package/nansen-cli
266
270
  - GitHub: https://github.com/nansen-ai/nansen-cli
271
+
272
+ Browser login uses `nansen:api` with the same account API permissions as an API key, subject to existing plan/account/endpoint checks. Trading still requires a separately configured wallet and its signing authorization. Hosted simulation uses the selected credential only on the matching trusted Nansen API origin; arbitrary RPC endpoints never receive Nansen credentials.
@@ -4,8 +4,6 @@ description: "Which of these addresses are smart money? Batch-profile a list in
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
  ```bash
19
27
  ADDRESSES="0xaddr1,0xaddr2,0xaddr3,..." CHAIN=ethereum
20
28
  nansen research profiler batch --addresses "$ADDRESSES" --chain $CHAIN --include labels,balance
@@ -4,8 +4,6 @@ description: "Cluster and attribute related wallets — funding chains, shared s
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
 
19
27
  # Wallet Attribution
20
28
 
@@ -4,8 +4,6 @@ description: "Who is this wallet and what have they been doing? Identity labels,
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
 
19
27
  # Wallet Analysis
20
28
 
@@ -4,8 +4,6 @@ description: Migrate an existing nansen-cli wallet from insecure password storag
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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
+
20
+
18
21
 
19
22
  # Wallet Migration — Old Flow to Secure Keychain
20
23
 
@@ -4,8 +4,6 @@ description: Wallet management — create (local or Privy server-side), list, sh
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,21 +13,25 @@ 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
+
20
+
18
21
 
19
22
  # Wallet
20
23
 
21
24
  ## Auth Setup
22
25
 
23
- ```bash
24
- # Save API key interactively
25
- nansen login --human
26
- # Or use NANSEN_API_KEY after provisioning it through your environment/secret manager
27
- nansen login
26
+ Use a selected nansen:api browser session or conventional API key for Nansen account API calls. Agents should inject `NANSEN_API_KEY` through their environment or secret manager and use commands directly; no login is needed to persist it. Human terminal users can use explicit `nansen login --human` for legacy key setup. With an already injected environment key, that explicit mode saves it without prompting and requires the native auth lock binding.
28
27
 
29
- # Verify
30
- nansen research profiler labels --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum
28
+ ```bash
29
+ # Free live check of the effective API credential
30
+ nansen account
31
31
  ```
32
32
 
33
+ Plain `nansen login` instead requests fresh browser approval. It does not save an environment key or grant wallet signing/RPC authority. Wallet custody and provider credentials below remain separate.
34
+
33
35
  ## Wallet Providers
34
36
 
35
37
  The CLI supports two wallet providers:
@@ -4,8 +4,6 @@ description: Wallet profiler — balance, PnL, labels, transactions, counterpart
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,16 @@ metadata:
15
13
  bins: [nansen]
16
14
  allowed-tools: Bash(nansen:*)
17
15
  ---
16
+ ## Authentication
17
+
18
+ Browser login requests `nansen:api` for API-key-equivalent account API permissions; existing OAuth/MCP `nansen:read` semantics and separate wallet authorization are unchanged.
19
+
20
+ 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.
21
+
22
+ Use `nansen login` for fresh browser approval within the documented platform scope, 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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
+
24
+ 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.
25
+
18
26
 
19
27
  # Wallet Profiler
20
28
 
@@ -4,8 +4,6 @@ description: Fetch and analyze content from one or more URLs using AI (Gemini 2.
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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
+
20
+
18
21
 
19
22
  # Web Fetch
20
23
 
@@ -4,8 +4,6 @@ description: Search the web for one or more queries in parallel. Use when you ne
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 login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
+
20
+
18
21
 
19
22
  # Web Search
20
23