nansen-cli 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/README.md +32 -32
  3. package/docs/auth.md +56 -0
  4. package/docs/browser-login.md +101 -7
  5. package/docs/error-codes.md +249 -0
  6. package/package.json +10 -4
  7. package/skills/nansen-agent-guide/SKILL.md +17 -1
  8. package/skills/nansen-alerts-webhook-listener/SKILL.md +1 -1
  9. package/skills/nansen-dca-tracker/SKILL.md +1 -1
  10. package/skills/nansen-defi-positions/SKILL.md +1 -1
  11. package/skills/nansen-exit-signals/SKILL.md +2 -2
  12. package/skills/nansen-fund-tracker/SKILL.md +1 -1
  13. package/skills/nansen-general-search/SKILL.md +1 -1
  14. package/skills/nansen-holder-analysis/SKILL.md +2 -2
  15. package/skills/nansen-limit-orders/SKILL.md +1 -1
  16. package/skills/nansen-mpp-payment/SKILL.md +2 -2
  17. package/skills/nansen-perp-screener/SKILL.md +1 -1
  18. package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
  19. package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
  20. package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
  21. package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
  22. package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
  23. package/skills/nansen-prediction-markets/SKILL.md +1 -1
  24. package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
  25. package/skills/nansen-smart-alerts/SKILL.md +2 -1
  26. package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
  27. package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
  28. package/skills/nansen-smart-money-trend/SKILL.md +1 -1
  29. package/skills/nansen-token-research/SKILL.md +1 -1
  30. package/skills/nansen-token-screener/SKILL.md +1 -1
  31. package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
  32. package/skills/nansen-trading/SKILL.md +1 -1
  33. package/skills/nansen-wallet-batch/SKILL.md +1 -1
  34. package/skills/nansen-wallet-clustering/SKILL.md +1 -1
  35. package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
  36. package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
  37. package/skills/nansen-wallet-manager/SKILL.md +1 -1
  38. package/skills/nansen-wallet-profiler/SKILL.md +1 -1
  39. package/skills/nansen-web-fetcher/SKILL.md +1 -1
  40. package/skills/nansen-web-searcher/SKILL.md +1 -1
  41. package/src/api-endpoints.json +1605 -0
  42. package/src/api.js +202 -97
  43. package/src/auth-credentials.js +1 -0
  44. package/src/auth-state.js +2 -2
  45. package/src/auth-store-native.js +6 -1
  46. package/src/auth-store-worker.js +1 -1
  47. package/src/auth-store.js +9 -4
  48. package/src/bridge.js +19 -10
  49. package/src/cli.js +188 -89
  50. package/src/commands/agent.js +2 -3
  51. package/src/commands/alerts.js +277 -9
  52. package/src/commands/feedback.js +98 -37
  53. package/src/commands/mcp.js +1 -1
  54. package/src/commands/research.js +14 -37
  55. package/src/cost-cache.js +33 -7
  56. package/src/doctor.js +14 -5
  57. package/src/error-codes.js +226 -0
  58. package/src/input-validation.js +551 -0
  59. package/src/limit-order.js +12 -3
  60. package/src/perp.js +2 -1
  61. package/src/privy.js +89 -11
  62. package/src/query-options.js +30 -7
  63. package/src/rpc-urls.js +3 -1
  64. package/src/schema.json +1137 -145
  65. package/src/solana-tx.js +4 -0
  66. package/src/trade-validation.js +167 -8
  67. package/src/trading.js +172 -12
  68. package/src/transfer.js +7 -1
  69. package/src/update-check.js +32 -5
  70. package/src/wallet.js +211 -57
  71. package/src/walletconnect-x402.js +14 -8
@@ -0,0 +1,249 @@
1
+ <!-- Generated from src/error-codes.js by scripts/generate-error-codes-doc.js. Do not edit by hand; run: npm run error-codes:generate -->
2
+
3
+ # Error codes
4
+
5
+ Every failure exits with a non-zero status and prints one JSON envelope on stdout (with `--table` or `--format csv`, the same fields as text or CSV):
6
+
7
+ ```json
8
+ {
9
+ "success": false,
10
+ "error": "Option '--timefrme' is not recognized by nansen research token info. Command-specific options: --chain, --token, --timeframe. Common options also apply; see: nansen schema.",
11
+ "code": "INVALID_PARAMS",
12
+ "status": null,
13
+ "details": {
14
+ "param": "--timefrme",
15
+ "errors": [
16
+ { "field": "--timefrme", "message": "Option '--timefrme' is not recognized by nansen research token info. Command-specific options: --chain, --token, --timeframe. Common options also apply; see: nansen schema.", "code": "unknown_field" }
17
+ ]
18
+ }
19
+ }
20
+ ```
21
+
22
+ - `error` is the message. It is not repeated inside `details`.
23
+ - `code` is one of the codes below. Branch on it, not on the message.
24
+ - `status` is the HTTP status for an API error and `null` for a local error.
25
+ - `requestId` is present when the API returned one. Quote it to support.
26
+ - `details` carries the API's error body (for example `code`, `param`, `errors`, `doc_url`) or, for a local check, `param` and `errors`.
27
+ - `details.errors[]` lists each bad field or option as `{ field, message, code }`. For an API error, `field` is the request field (for example `body.chain`); for a local check, it is the option (for example `--chain`).
28
+
29
+ One exception: in an interactive terminal without `--pretty`, `--table`, `--format` or `--stream`, a local usage error (`MISSING_PARAM` or `MISSING_ARGS`) prints only its message. The exit status is still non-zero. Piped output always gets the envelope.
30
+
31
+ A connection failure is `NETWORK_ERROR` and never `UNAUTHORIZED`: the CLI could not reach the API, so it did not check the credential. Fix the connection; do not replace the API key.
32
+
33
+ ## Codes
34
+
35
+ ### Input and validation
36
+
37
+ | Code | Meaning | Retry |
38
+ | --- | --- | --- |
39
+ | `INVALID_PARAMS` | An option or request field has an invalid value, or the command does not accept it. `details.errors[]` names each field. | No |
40
+ | `MISSING_PARAM` | A required option or request field is missing. `details.errors[]` names each field. | No |
41
+ | `MISSING_ARGS` | A trade or wallet command is missing required arguments; the message shows the usage. | No |
42
+ | `INVALID_INPUT` | A trade, bridge, perp or wallet argument failed local validation. | No |
43
+ | `INVALID_ADDRESS` | An address does not match the format of the selected chain. | No |
44
+ | `INVALID_TOKEN` | A token address or symbol is not valid for the selected chain. | No |
45
+ | `INVALID_CHAIN` | The chain is not known or not supported (legacy; supported-chain errors now use INVALID_PARAMS with the field named). | No |
46
+ | `INVALID_AMOUNT` | An amount is zero, negative or not a whole number of base units. | No |
47
+ | `INVALID_SLIPPAGE` | The slippage value is outside the allowed range. | No |
48
+ | `INVALID_AGGREGATOR` | The --aggregator value is not one of the supported aggregators. | No |
49
+ | `INVALID_QUOTE_INDEX` | The --quote-index does not select a quote in the saved quote. | No |
50
+ | `UNSUPPORTED_FILTER` | The API does not support this filter for the token or chain. Do not retry. | No |
51
+ | `QUERY_TOO_LARGE` | The query would return too much data. Narrow it; retrying does not help. | No |
52
+ | `PAYLOAD_TOO_LARGE` | The request body is larger than the API accepts (HTTP 413). | No |
53
+ | `UNKNOWN_COMMAND` | The command or subcommand does not exist. The message suggests the closest match and `details.available` lists the valid ones. | No |
54
+ | `COMMAND_UNAVAILABLE` | The command was removed or is not available in this version. | No |
55
+ | `GASLESS_REMOVED` | The removed --gasless flag was passed to trade execute. | No |
56
+
57
+ ### Authentication and access
58
+
59
+ | Code | Meaning | Retry |
60
+ | --- | --- | --- |
61
+ | `UNAUTHORIZED` | The API rejected the credential (HTTP 401): the API key is missing, invalid or revoked. Not a connection problem. | No |
62
+ | `INVALID_API_KEY` | login could not verify the API key because the API rejected it. | No |
63
+ | `API_KEY_REQUIRED` | No API key was provided where one is required. | No |
64
+ | `VERIFICATION_FAILED` | login could not verify the API key for a reason other than a rejected key (network, rate limit, outage). The key may be valid. | No |
65
+ | `FORBIDDEN` | The credential is valid but has no permission for this endpoint (HTTP 403). | No |
66
+ | `GEO_BLOCKED` | The endpoint is not available in the caller's region (HTTP 451). | No |
67
+ | `NOT_A_TTY` | An interactive step (prompt or browser login) needs a terminal, but stdin or stdout is not one. | No |
68
+ | `MIXED_CREDENTIALS` | A browser-session request was combined with an API key or payment signature. | No |
69
+
70
+ ### Credits, plans and rate limits
71
+
72
+ | Code | Meaning | Retry |
73
+ | --- | --- | --- |
74
+ | `CREDITS_EXHAUSTED` | The account has no API credits left. Retrying does not help. | No |
75
+ | `PLAN_UPGRADE_REQUIRED` | The account plan does not include this endpoint. | No |
76
+ | `PAYMENT_REQUIRED` | The request needs an x402 payment and no payment could be made (HTTP 402). | No |
77
+ | `PAYMENT_AMBIGUOUS` | An x402 payment was sent but its outcome is unknown. Do not retry with another payment. | No |
78
+ | `RATE_LIMITED` | Too many requests (HTTP 429). Wait `details.retryAfterMs` before retrying. | Yes |
79
+
80
+ ### API, network and server
81
+
82
+ | Code | Meaning | Retry |
83
+ | --- | --- | --- |
84
+ | `NETWORK_ERROR` | The CLI could not reach the API (DNS, TLS, proxy, firewall or offline). The credential was not checked; do not replace the API key. | Yes |
85
+ | `TIMEOUT` | The request or query timed out. | Yes |
86
+ | `SERVER_ERROR` | The API failed with an internal error (HTTP 5xx). Quote `requestId` to support. | Yes |
87
+ | `SERVICE_UNAVAILABLE` | The API or an upstream service is temporarily unavailable (HTTP 503). | Yes |
88
+ | `NOT_FOUND` | The resource or endpoint was not found (HTTP 404). | No |
89
+ | `TOKEN_NOT_FOUND` | The token was not found (HTTP 404). | No |
90
+ | `ADDRESS_NOT_FOUND` | The address has no data (HTTP 404). | No |
91
+ | `METHOD_NOT_ALLOWED` | The HTTP method is not allowed for this endpoint (HTTP 405). | No |
92
+ | `CONFLICT` | The request conflicts with the current state of the resource (HTTP 409). | No |
93
+ | `NON_JSON_RESPONSE` | A trading or limit-order service answered with a body that is not JSON. | Yes |
94
+ | `LIMIT_ORDER_NETWORK_ERROR` | The CLI could not reach the limit-order service. | Yes |
95
+
96
+ ### Browser login and saved sessions
97
+
98
+ | Code | Meaning | Retry |
99
+ | --- | --- | --- |
100
+ | `AUTH_BUNDLE_TOO_LARGE` | The issued session is larger than secure storage allows. The previous credential is unchanged. | No |
101
+ | `AUTH_BUSY` | Another authentication operation is running. Retry after it finishes. | Yes |
102
+ | `AUTH_CANCELLED` | The authentication operation was cancelled. | No |
103
+ | `AUTH_CLEANUP_REQUIRED` | Old login journals need cleanup. Unlock the credential store and run nansen logout. | No |
104
+ | `AUTH_CONNECT_UNAVAILABLE` | The CLI could not connect to the authentication service. | Yes |
105
+ | `AUTH_HOME_UNAVAILABLE` | No absolute home directory was found. Set HOME or USERPROFILE. | No |
106
+ | `AUTH_JOURNAL_INVALID` | A login recovery journal is corrupt. | No |
107
+ | `AUTH_LOCK_UNAVAILABLE` | Native file locking is not available on this platform, so saved authentication cannot be written. | No |
108
+ | `AUTH_NETWORK_ERROR` | A network error occurred during browser login. | Yes |
109
+ | `AUTH_ORIGIN_MISMATCH` | The saved session or simulation endpoint does not match the selected API origin. | No |
110
+ | `AUTH_ORIGIN_UNSUPPORTED` | Browser sessions need the Nansen production or staging API origin. | No |
111
+ | `AUTH_SELECTION_CHANGED` | The saved credential changed while the command ran. Retry the command. | Yes |
112
+ | `AUTH_STATE_INVALID` | The saved authentication state is invalid. | No |
113
+ | `AUTH_STORE_UNAVAILABLE` | The OS credential store is unavailable or locked. | No |
114
+ | `AUTH_TIMEOUT` | An authentication operation timed out. | Yes |
115
+ | `BROWSER_SESSION_SETUP_REQUIRED` | The session issuer configuration is not compatible with this CLI. | No |
116
+ | `INVALID_BROWSER_SESSION` | The API rejected the new browser session. Run nansen login again. | No |
117
+ | `PAIRING_CANCELLED` | Browser login was cancelled before approval. | No |
118
+ | `PAIRING_DENIED` | Browser login was denied in the browser. | No |
119
+ | `PAIRING_EXPIRED` | The browser login code expired before approval. | No |
120
+ | `PAIRING_FAILED` | Browser login failed. | No |
121
+ | `SESSION_CLOCK_SKEW` | The session is not valid yet because the local clock is behind. Synchronize system time. | No |
122
+ | `SESSION_EXPIRED` | The browser access token expired and could not be renewed. Run nansen login. | No |
123
+ | `SESSION_REFRESH_PROTOCOL_ERROR` | The issuer rejected the session refresh request format. | No |
124
+ | `SESSION_REFRESH_REJECTED` | The saved session cannot be renewed. Run nansen login. | No |
125
+ | `SESSION_REFRESH_RETRYABLE` | Session renewal was refused before rotation. Retry later. | Yes |
126
+ | `SESSION_REFRESH_RETRY_EXHAUSTED` | Session renewal failed repeatedly. Run nansen login. | No |
127
+ | `SESSION_RENEWAL_STORAGE_ERROR` | The renewed session could not be stored. Retry the command. | Yes |
128
+ | `SESSION_RENEWAL_UNCERTAIN` | The outcome of session renewal is unknown. Run nansen login. | No |
129
+ | `SESSION_VERIFICATION_FAILED` | The CLI could not verify the account of a new browser session. | No |
130
+
131
+ ### Wallets and passwords
132
+
133
+ | Code | Meaning | Retry |
134
+ | --- | --- | --- |
135
+ | `NO_WALLET` | No wallet (or WalletConnect session) is available for this chain. | No |
136
+ | `INVALID_WALLET` | The wallet cannot sign for this chain or action. | No |
137
+ | `PASSWORD_REQUIRED` | The wallet is encrypted and no password was found. `details` lists how to provide one. | No |
138
+ | `INCORRECT_PASSWORD` | The wallet password is wrong. | No |
139
+ | `NO_PASSWORD_FOUND` | No wallet password was found in any password store. | No |
140
+ | `KEYCHAIN_UNAVAILABLE` | The OS keychain is not available for the wallet password. | No |
141
+ | `CREATE_FAILED` | The wallet could not be created. | No |
142
+ | `DEFAULT_FAILED` | The default wallet could not be changed. | No |
143
+ | `DELETE_FAILED` | The wallet could not be deleted. | No |
144
+ | `EXPORT_FAILED` | The wallet could not be exported. | No |
145
+ | `SHOW_FAILED` | The wallet could not be shown. | No |
146
+ | `SEND_FAILED` | A native transfer failed. | No |
147
+ | `PRIVY_ERROR` | The Privy wallet service returned an error. | No |
148
+
149
+ ### Trading, quotes and simulation
150
+
151
+ | Code | Meaning | Retry |
152
+ | --- | --- | --- |
153
+ | `NO_QUOTES` | No aggregator returned a quote. | No |
154
+ | `ALL_QUOTES_FAILED` | Every quote failed to execute. | No |
155
+ | `QUOTE_ERROR` | The quote service returned an error. | No |
156
+ | `EXECUTE_ERROR` | Trade execution failed. | No |
157
+ | `MISSING_QUOTE_ID` | trade execute needs a --quote id. | No |
158
+ | `AGGREGATOR_NOT_AVAILABLE` | The requested aggregator has no quote in the saved quote. | No |
159
+ | `MAX_INPUT_EXCEEDED` | The quote would spend more than the allowed maximum input. | No |
160
+ | `NO_TRANSACTION` | No quote contains transaction data. | No |
161
+ | `INVALID_EXECUTION_ROUTE` | The quote has an execution route the CLI does not support. | No |
162
+ | `INSUFFICIENT_BALANCE` | The wallet balance is too low for the trade. | No |
163
+ | `INSUFFICIENT_GAS` | The wallet has too little native token for gas. | No |
164
+ | `WALLET_MISMATCH` | The quote was built for a different wallet. | No |
165
+ | `AMOUNT_MISMATCH` | The quote or bridge amount differs from the requested amount. | No |
166
+ | `INVALID_SIGNED_TX` | The signed transaction is not valid. | No |
167
+ | `BROADCAST_FAILED` | The transaction could not be broadcast. | No |
168
+ | `TX_REVERTED` | The transaction reverted or failed on chain. | No |
169
+ | `TXHASH_MISMATCH` | The RPC returned a different transaction hash than the one signed. | No |
170
+ | `RECEIPT_TIMEOUT` | The transaction was not confirmed in time and may still land. Check the transaction before retrying. | No |
171
+ | `OUTCOME_VERIFICATION_FAILED` | The CLI could not verify the trade outcome. | No |
172
+ | `SWAP_OUTCOME_MISMATCH` | The simulated swap outcome does not match the quote; nothing was signed. | No |
173
+ | `LIMIT_ORDER_DESTINATION_MISMATCH` | The limit order sends funds to an unexpected destination; nothing was signed. | No |
174
+ | `LIMIT_ORDER_OUTCOME_MISMATCH` | The simulated limit-order deposit does not match the order; nothing was signed. | No |
175
+ | `SIMULATION_FAILED` | Pre-broadcast simulation failed; nothing was signed. | No |
176
+ | `SIMULATION_ACCESS_DENIED` | The account cannot use hosted simulation. | No |
177
+ | `SIM_REVERTED` | The transaction reverts in simulation. | No |
178
+ | `SIM_RPC_ERROR` | The simulation RPC returned an error. | No |
179
+ | `SIM_RESULT_UNPARSEABLE` | The simulation result could not be parsed. | No |
180
+ | `NO_SIM_RPC` | No simulation RPC is configured for the chain. | No |
181
+ | `NOT_SIM_CAPABLE` | The RPC does not support simulation. | No |
182
+ | `RPC_UNCONFIGURED` | No RPC URL is configured for the chain. | No |
183
+ | `RPC_HTTP_ERROR` | The RPC answered with an HTTP or JSON-RPC error. | No |
184
+ | `RPC_JSON_ERROR` | The RPC answered with a body that is not JSON. | No |
185
+ | `RPC_NETWORK_ERROR` | The CLI could not reach the RPC. | Yes |
186
+ | `CONFIRMATION_DECLINED` | The confirmation prompt was declined; nothing was signed. | No |
187
+ | `CONFIRMATION_UNAVAILABLE` | Confirmation is required but no terminal is available. Pass --yes to confirm. | No |
188
+
189
+ ### Bridge
190
+
191
+ | Code | Meaning | Retry |
192
+ | --- | --- | --- |
193
+ | `BRIDGE_FAILED` | The bridge transfer failed. | No |
194
+ | `BRIDGE_NOT_FOUND` | No bridge request was found for the id. | No |
195
+ | `BRIDGE_STATUS_ERROR` | The bridge status could not be read. | Yes |
196
+ | `BRIDGE_TIMEOUT` | The bridge transfer did not finish in time. Check nansen bridge status. | No |
197
+ | `QUOTE_STATE_UNSAFE` | The bridge execution could not be recorded safely. Check nansen bridge status before requesting a new quote. | No |
198
+ | `SIGNER_MISMATCH` | The bridge quote expects a different signer. | No |
199
+ | `UNEXPECTED_ACTION` | The bridge quote contains an action the CLI does not expect. | No |
200
+ | `UNEXPECTED_NETWORK` | The bridge quote uses an unexpected network. | No |
201
+ | `PARTIAL_FILL` | The bridge transfer was only partly filled. | No |
202
+ | `HL_ACTION_REJECTED` | Hyperliquid rejected the action. | No |
203
+
204
+ ### Perpetuals (Hyperliquid)
205
+
206
+ | Code | Meaning | Retry |
207
+ | --- | --- | --- |
208
+ | `BUILDER_FEE_TOO_HIGH` | The builder fee is above the allowed ceiling. | No |
209
+ | `BUILDER_FEE_UNAVAILABLE` | The builder fee could not be read or approved. | No |
210
+ | `META_UNAVAILABLE` | Hyperliquid asset metadata is not available. | Yes |
211
+ | `SANCTIONED` | The address failed sanctions screening. | No |
212
+ | `SCREENING_UNAVAILABLE` | Sanctions screening is not available, so the action was refused. | Yes |
213
+ | `UNSUPPORTED_NETWORK` | The network is not supported for this perp action. | No |
214
+ | `ZERO_PRICE` | The order price rounds to zero. | No |
215
+ | `ZERO_SIZE` | The order size rounds to zero. | No |
216
+
217
+ ### Local files, config and tooling
218
+
219
+ | Code | Meaning | Retry |
220
+ | --- | --- | --- |
221
+ | `FILE_EXISTS` | The output path already exists; the CLI does not overwrite it. | No |
222
+ | `FILE_WRITE_FAILED` | The output file could not be written. | No |
223
+ | `LOCAL_FILE_UNSAFE` | A local file has unsafe permissions or type. | No |
224
+ | `INVALID_CONFIG` | A configuration file could not be read or parsed. | No |
225
+ | `MCP_VERIFY_FAILED` | nansen mcp verify could not connect to the MCP server with the configured settings. | No |
226
+ | `UNSUPPORTED_PLATFORM` | The MCP client is not available on this operating system. | No |
227
+
228
+ ### Generic
229
+
230
+ | Code | Meaning | Retry |
231
+ | --- | --- | --- |
232
+ | `COMMAND_ERROR` | A command failed without a more specific code. | No |
233
+ | `UNKNOWN` | An unexpected error with no code. Report it with the message. | No |
234
+
235
+ ## Field codes
236
+
237
+ `details.errors[].code` uses the API's field-level codes ([API error handling](https://docs.nansen.ai/getting-started/error-handling)). The CLI uses the same codes for its own checks, so one bad field reads the same from the CLI, the REST API and the MCP server.
238
+
239
+ | Field code | Meaning |
240
+ | --- | --- |
241
+ | `missing_field` | A required field or option is missing. |
242
+ | `unknown_field` | The field or option is not recognized. The message suggests the closest valid name. |
243
+ | `invalid_field_value` | The value is not valid for the field (wrong type, not an allowed value, or a chain the command does not support). |
244
+ | `invalid_address_format` | The address does not match the chain's format. |
245
+ | `invalid_date_format` | The date is not a valid YYYY-MM-DD date. |
246
+ | `invalid_date_range` | The date range is not allowed. |
247
+ | `mutually_exclusive_fields` | Two fields that cannot be combined were both given. |
248
+ | `value_out_of_range` | The value is outside the allowed range. |
249
+ | `too_many_items` | The list has more items than allowed. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nansen-cli",
3
- "version": "2.3.0",
3
+ "version": "2.4.0",
4
4
  "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
@@ -14,7 +14,9 @@
14
14
  "skills/**",
15
15
  "scripts/postinstall.js",
16
16
  "CHANGELOG.md",
17
- "docs/browser-login.md"
17
+ "docs/auth.md",
18
+ "docs/browser-login.md",
19
+ "docs/error-codes.md"
18
20
  ],
19
21
  "scripts": {
20
22
  "postinstall": "node scripts/postinstall.js",
@@ -32,6 +34,10 @@
32
34
  "mcp:check": "node scripts/generate-mcp-docs.js --check",
33
35
  "mcp:check-pin": "node scripts/check-mcp-remote-pin.js",
34
36
  "mcp:check-consumers": "node scripts/check-mcp-consumers.js",
37
+ "error-codes:generate": "node scripts/generate-error-codes-doc.js",
38
+ "error-codes:check": "node scripts/generate-error-codes-doc.js --check",
39
+ "endpoints:sync": "node scripts/sync-api-endpoints.js",
40
+ "endpoints:check": "node scripts/sync-api-endpoints.js --check",
35
41
  "lint:fix": "eslint . --fix",
36
42
  "changeset": "changeset",
37
43
  "changeset:version": "changeset version && npm install --package-lock-only",
@@ -70,11 +76,11 @@
70
76
  "@changesets/changelog-github": "^0.5.1",
71
77
  "@changesets/cli": "^2.29.4",
72
78
  "@eslint/js": "^10.0.1",
73
- "@vitest/coverage-v8": "^4.0.18",
79
+ "@vitest/coverage-v8": "^4.1.12",
74
80
  "clawhub": "^0.9.0",
75
81
  "eslint": "^10.0.2",
76
82
  "globals": "^17.4.0",
77
- "vitest": "^4.0.18"
83
+ "vitest": "^4.1.12"
78
84
  },
79
85
  "dependencies": {
80
86
  "@ethereumjs/rlp": "^10.1.1",
@@ -15,7 +15,7 @@ allowed-tools: Bash(nansen:*)
15
15
  ---
16
16
  ## Authentication
17
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).
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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
19
 
20
20
 
21
21
 
@@ -78,6 +78,22 @@ the current account's saved feedback preference with
78
78
  subject to the host's controls. If off, unset or unavailable, show the proposed
79
79
  report and ask the user. If they decline or you cannot ask, do not send.
80
80
 
81
+ A report is a JSON object. `category` and `description` are required.
82
+ `category` must be one of `bug`, `data_quality`, `documentation`,
83
+ `missing_capability`, `usability` or `other`. A feature request or product
84
+ gap is `missing_capability`; do not invent categories. `description` says
85
+ what happened and what was needed, in up to 2,000 characters. You may add
86
+ `endpoint`, `tool`, `goal`, `expected_behavior`, `observed_behavior`,
87
+ `workaround`, `request_ids` (up to 10 of your own request IDs) and `client`
88
+ (`{"name": ..., "version": ...}`). Any other field, such as `title`,
89
+ `summary` or `component`, gets a 422. With a generated ID, that 422 also
90
+ erases the saved report and you need `--new`. Write plain sentences without
91
+ Markdown or code formatting. `nansen feedback submit --help` lists the limits.
92
+
93
+ ```json
94
+ {"category": "missing_capability", "description": "There is no command to list my past feedback receipts.", "goal": "Check the status of reports I sent earlier."}
95
+ ```
96
+
81
97
  If the preference read fails, ask first. An explicit user request or approval
82
98
  permits that report; it does not change the saved preference. Never enable the
83
99
  preference automatically or add approval fields to the report. Direct users to
@@ -16,7 +16,7 @@ allowed-tools: Bash(nansen:*), Bash(node:*), Bash(npx:*), Bash(ngrok:*), Write
16
16
  ---
17
17
  ## Authentication
18
18
 
19
- Nansen account API calls accept a selected `nansen:api` browser session or conventional API key with the same permissions. `NANSEN_API_KEY` takes precedence; optional `primaryEnv` preserves configured-key injection. Run `nansen auth status` for offline selection. Cached access expiry alone permits automatic renewal during an authorized task. Stop on anonymous selection, invalid state, blocked/uncertain renewal or actual auth failure; never drop a credential or fall back to anonymous x402 payment. Browser login does not grant wallet signing, privileged service identity or a persistent MCP integration key. Preserve all confirmation, signing, sanctions and geographic checks below. Browser 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
20
20
 
21
21
 
22
22
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -15,7 +15,7 @@ allowed-tools: Bash(nansen:*)
15
15
  ---
16
16
  ## Authentication
17
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).
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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
19
 
20
20
 
21
21
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -35,7 +35,7 @@ nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
35
35
  # → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets (negative = selling)
36
36
 
37
37
  nansen research token who-bought-sold --token $TOKEN --chain $CHAIN --limit 20
38
- # → address, address_label, bought/sold_volume_usd, trade_volume_usd
38
+ # → address, address_label, bought/sold_volume_usd, trade_volume_usd (total: bought + sold), net_volume_usd
39
39
 
40
40
  nansen research smart-money netflow --chain $CHAIN --limit 10
41
41
  # → token_symbol, net_flow_1h/24h/7d/30d_usd, trader_count
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -38,7 +38,7 @@ nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
38
38
  # → net_flow_usd and wallet_count per label: smart_trader, whale, exchange, fresh_wallets
39
39
 
40
40
  nansen research token who-bought-sold --token $TOKEN --chain $CHAIN --limit 20
41
- # → address, address_label, bought/sold_volume_usd, bought/sold_token_volume, trade_volume_usd
41
+ # → address, address_label, bought/sold_volume_usd, bought/sold_token_volume, trade_volume_usd (total: bought + sold), net_volume_usd
42
42
  ```
43
43
 
44
44
  Red flag: high fresh_wallets flow + low SM holders. Green flag: Fund/Smart Trader labels in top 20.
@@ -15,7 +15,7 @@ allowed-tools: Bash(nansen:*)
15
15
  ---
16
16
  ## Authentication
17
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).
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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
19
 
20
20
 
21
21
 
@@ -46,11 +46,11 @@ tempo wallet whoami
46
46
 
47
47
  ```bash
48
48
  # Smart Money netflow
49
- tempo request POST https://api.nansen.ai/api/v1/smart-money/netflow \
49
+ tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow \
50
50
  --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
51
51
 
52
52
  # TGM holders
53
- tempo request POST https://api.nansen.ai/api/v1/tgm/holders \
53
+ tempo request -X POST https://api.nansen.ai/api/v1/tgm/holders \
54
54
  --json '{"token_address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","chain":"solana"}'
55
55
  ```
56
56
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -20,7 +20,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
20
20
 
21
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
22
 
23
- 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
+ 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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
24
24
 
25
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
26
 
@@ -19,7 +19,7 @@ Browser login requests `nansen:api` for API-key-equivalent account API permissio
19
19
 
20
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
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).
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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
23
23
 
24
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
25
 
@@ -15,7 +15,7 @@ allowed-tools: Bash(nansen:*)
15
15
  ---
16
16
  ## Authentication
17
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).
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 enabled in production within the [documented platform scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).
19
19
 
20
20
 
21
21
 
@@ -138,6 +138,7 @@ nansen alerts create \
138
138
  - Chain aliases: Hyperliquid = `hyperevm`, BSC = `bnb`.
139
139
  - Multiple channels can be combined: `--telegram 123 --slack https://... --webhook https://...`
140
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.
141
+ - Alert output redacts channel credentials (Slack/Discord/webhook URLs and webhook signing secrets), e.g. `https://hooks.slack.com/services/T000/****`. Webhook URLs grant post access to the channel, so keep them out of shared output; pass `--reveal` only when the full value is needed. Never pass a redacted value back to `--slack`/`--discord`/`--webhook`; the CLI rejects it.
141
142
  - `--data '<json>'` merges raw JSON on top of named flags (escape hatch for fields without named flags).
142
143
  - Alert endpoints retain their normal ownership, plan and quota checks for both selected credentials.
143
144
  - Use single quotes for names with `$` or special characters: `--name 'SM >$1M'`