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
@@ -4,8 +4,6 @@ description: "Scan a resolved Polymarket market for wallets exhibiting suspiciou
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
  # PM Suspicious Wallet Scanner
20
28
 
21
29
  **Answers:** "Are there wallets with suspicious trading patterns in this Polymarket market?"
@@ -4,8 +4,6 @@ description: "What is a Polymarket trader betting on? Trades by address, PnL bre
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
  # Polymarket Wallet Activity
20
28
 
21
29
  **Answers:** "What is this Polymarket trader betting on? Are they profitable?"
@@ -4,8 +4,6 @@ description: "How has a wallet's portfolio changed over time? Historical balance
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
  # Portfolio History
20
28
 
21
29
  **Answers:** "How has this wallet's portfolio evolved over the past month?"
@@ -4,8 +4,6 @@ description: "Polymarket screeners — discover trending events, top markets 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
  # Prediction Market Screeners
20
28
 
21
29
  All commands: `nansen research prediction-market <sub> [options]` (alias: `nansen research pm <sub>`)
@@ -4,8 +4,6 @@ description: "Is SM buying this token on one chain but selling on another? Detec
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 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.
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_SYMBOL=<symbol e.g. "AAVE"> CHAINS=(ethereum solana base bnb)
20
28
  for chain in "${CHAINS[@]}"; do
@@ -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 rollout acceptance is still pending.
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 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.
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 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.
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 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.
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 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.
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 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.
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 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.
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 rollout acceptance is still pending.
21
+
22
+
19
23
 
20
24
  # Trade
21
25
 
@@ -54,8 +58,23 @@ For cross-chain swaps, each token is checked against its own chain (from vs `--c
54
58
 
55
59
  ```bash
56
60
  nansen trade execute --quote <quote-id>
61
+ nansen trade execute --quote <quote-id> --dry-run # preview only, nothing is broadcast
62
+ nansen trade execute --quote <quote-id> --yes # skip the confirmation prompt
57
63
  ```
58
64
 
65
+ **`--dry-run`** runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints the trade that *would* be sent (chain, tokens, amounts, recipient, approval, fees); and stops before wallet credentials or signing. No wallet password is needed, the quote is not consumed, and the command exits 0. Real execution still resolves and revalidates the live signer. On Base, preview also reads the current token allowance and runs the pre-broadcast revert simulation when no approval is outstanding.
66
+
67
+ **Confirmation.** When stdin is an interactive terminal, `execute` prints the plan and asks `Broadcast this transaction? [y/N]` before broadcasting. Answering anything but `y`/`yes` aborts with exit code 1 and nothing signed. Pass `--yes` (`-y`), or set `NANSEN_YES=1`, to skip the question.
68
+
69
+ **Agents and CI are unaffected:** when stdin is *not* a terminal (a pipe, a CI job, an agent shell) the command proceeds without prompting, exactly as before. `--yes` is accepted there and is simply a no-op, so it is safe to always pass it. The same flags and rules apply to `nansen bridge execute`.
70
+
71
+ ### Exit codes (`trade execute`, `bridge execute`)
72
+
73
+ | Code | Meaning |
74
+ |------|---------|
75
+ | `0` | Broadcast succeeded, or the dry run completed |
76
+ | `1` | Declined at the confirmation prompt, or the execution failed |
77
+
59
78
  ## Cross-Chain Swap
60
79
 
61
80
  Bridge tokens between Solana and Base using `--to-chain`:
@@ -167,6 +186,8 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
167
186
  | `--wallet` | Wallet name (default: default wallet) |
168
187
  | `--quote-index` | Pin a specific quote by index (0-based) when multiple quotes were returned |
169
188
  | `--no-simulate` | Skip pre-broadcast simulation |
189
+ | `--dry-run` | Validate and print what would be sent, then stop. Nothing is signed or broadcast |
190
+ | `--yes`, `-y` | Skip the confirmation prompt (same as `NANSEN_YES=1`); no-op when stdin is not a terminal |
170
191
 
171
192
  ### `trade bridge-status` flags
172
193
 
@@ -181,7 +202,8 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
181
202
  | Var | Purpose |
182
203
  |-----|---------|
183
204
  | `NANSEN_WALLET_PASSWORD` | **Required for `trade execute`.** Wallet encryption password — persisted in `~/.nansen/.env`. Source before executing: `source ~/.nansen/.env && nansen trade execute ...` |
184
- | `NANSEN_API_KEY` | API key (also set via `nansen login`) |
205
+ | `NANSEN_API_KEY` | API key (also set via explicit `nansen login --human`; browser sessions are not wallet or RPC keys) |
206
+ | `NANSEN_YES` | Set to `1` to skip the `execute` confirmation prompt, like `--yes` |
185
207
 
186
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.
187
209
 
@@ -189,6 +211,7 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
189
211
 
190
212
  - Quotes expire after ~1 hour. If execute fails, get a fresh quote.
191
213
  - A wallet is required even for quotes (the API builds sender-specific transactions).
214
+ - Compliance screen: `trade quote` and `trade execute` check the signing wallet (and any distinct `--to-wallet` destination) against the compliance blocklist through the Nansen API before requesting a quote or signing — the same fail-closed check `bridge` and `perp` run. A flagged address aborts with code `SANCTIONED`; if the screening call itself fails the command aborts with `SCREENING_UNAVAILABLE`. Nothing is signed or broadcast in either case.
192
215
  - ERC-20 swaps may require an approval step — execute handles this automatically.
193
216
 
194
217
  # Perp Trading
@@ -245,3 +268,5 @@ nansen perp account # account value, unrealized PnL, margin used, withdrawab
245
268
 
246
269
  - npm: https://www.npmjs.com/package/nansen-cli
247
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 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.
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 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.
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 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.
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 rollout acceptance is still pending.
19
+
20
+
18
21
 
19
22
  # Wallet Migration — Old Flow to Secure Keychain
20
23
 
@@ -50,7 +53,7 @@ Interpret `x402.password.source`:
50
53
  - `null` → password not persisted anywhere (Path C or D)
51
54
  - `"env"` → `NANSEN_WALLET_PASSWORD` is set; check where it is being exported from (a `.env` file → Path A)
52
55
 
53
- Do NOT use `nansen wallet export` to probe the password state — it prints private keys.
56
+ Do NOT use `nansen wallet export` to probe the password state — the default is redacted and never loads the password, so it proves nothing (and `--reveal` prints private keys).
54
57
 
55
58
  ## Migration paths
56
59
 
@@ -76,13 +79,15 @@ source ~/.nansen/.env 2>/dev/null && nansen wallet secure
76
79
  **Step 3 — Verify the password actually decrypts the wallet:**
77
80
 
78
81
  ```bash
79
- # Unset env var to prove keychain works, then export to verify decryption
82
+ # Unset env var to prove keychain works, then run a decrypting export with
83
+ # all output discarded — the exit code alone is the signal, so no key
84
+ # material can land in a transcript or log
80
85
  unset NANSEN_WALLET_PASSWORD
81
- nansen wallet export default 2>&1
86
+ if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi
82
87
  ```
83
88
 
84
- If export succeeds (shows private keys), the migration worked. If it shows
85
- `Incorrect password`, the wrong password was migrated — run `nansen wallet
89
+ If the export exits 0 (`decryption OK`), the migration worked. If it fails,
90
+ the wrong password was migrated — run `nansen wallet
86
91
  forget-password` and retry with the correct password.
87
92
 
88
93
  **Step 4 — Clean up the insecure file:**
@@ -102,10 +107,11 @@ nansen wallet secure
102
107
  If the keychain is still unavailable (e.g. containerized Linux without D-Bus),
103
108
  `nansen wallet secure` will explain the situation and suggest alternatives.
104
109
 
105
- After migrating, verify decryption works:
110
+ After migrating, verify decryption works (output discarded on purpose —
111
+ branch on the exit code):
106
112
 
107
113
  ```bash
108
- nansen wallet export default 2>&1
114
+ if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi
109
115
  ```
110
116
 
111
117
  ### Path C: Password only in `NANSEN_WALLET_PASSWORD` env var
@@ -115,11 +121,12 @@ nansen wallet export default 2>&1
115
121
  nansen wallet secure
116
122
  ```
117
123
 
118
- Then verify without the env var:
124
+ Then verify without the env var (exit code is the signal; output is
125
+ discarded so no keys are disclosed):
119
126
 
120
127
  ```bash
121
128
  unset NANSEN_WALLET_PASSWORD
122
- nansen wallet export default 2>&1
129
+ if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi
123
130
  ```
124
131
 
125
132
  ### Path D: Password lost entirely
@@ -147,11 +154,12 @@ the keychain password can actually decrypt the wallet:
147
154
  # Unset env var to prove keychain works
148
155
  unset NANSEN_WALLET_PASSWORD
149
156
 
150
- # This MUST succeed — it proves the keychain password decrypts the wallet
151
- nansen wallet export default 2>&1
157
+ # This MUST exit 0 — it proves the keychain password decrypts the wallet.
158
+ # Output is discarded on purpose: the exit code alone is the signal.
159
+ if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi
152
160
  ```
153
161
 
154
- If export shows `Incorrect password`, the wrong password was saved to the
162
+ If the export fails, the wrong password was saved to the
155
163
  keychain. Fix with:
156
164
 
157
165
  ```bash
@@ -182,4 +190,4 @@ wallet operations will require `NANSEN_WALLET_PASSWORD` env var or re-running
182
190
  - **NEVER use `--human` flag** — interactive prompts break agents
183
191
  - If the human authorizes reading `~/.nansen/.env`, read it in the same command
184
192
  (`source ~/.nansen/.env && nansen wallet secure`) — do not echo or log the value
185
- - **ALWAYS verify after migration** with `nansen wallet export default` — `wallet show` does NOT prove the password works (it never loads the password)
193
+ - **ALWAYS verify after migration** with `nansen wallet export default --reveal > /dev/null 2>&1` (branch on the exit code; never let the output print) — `wallet show` does NOT prove the password works (it never loads the password)