nansen-cli 2.3.0 → 2.5.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 (80) hide show
  1. package/CHANGELOG.md +112 -0
  2. package/README.md +61 -38
  3. package/docs/auth.md +56 -0
  4. package/docs/browser-login.md +101 -7
  5. package/docs/error-codes.md +251 -0
  6. package/package.json +10 -4
  7. package/skills/nansen-agent-guide/SKILL.md +20 -4
  8. package/skills/nansen-alerts-webhook-listener/SKILL.md +17 -14
  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 +9 -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 +5 -2
  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 +23 -2
  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 +11 -5
  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 +282 -124
  43. package/src/auth-credentials.js +1 -0
  44. package/src/auth-key-input.js +57 -9
  45. package/src/auth-state.js +2 -2
  46. package/src/auth-store-native.js +6 -1
  47. package/src/auth-store-worker.js +1 -1
  48. package/src/auth-store.js +9 -4
  49. package/src/auto-paginate.js +25 -7
  50. package/src/bridge.js +19 -10
  51. package/src/cache-inspect.js +16 -6
  52. package/src/cli.js +272 -114
  53. package/src/commands/agent.js +2 -3
  54. package/src/commands/alerts.js +365 -18
  55. package/src/commands/completion.js +4 -1
  56. package/src/commands/feedback.js +98 -37
  57. package/src/commands/mcp.js +1 -1
  58. package/src/commands/research.js +14 -37
  59. package/src/cost-cache.js +33 -7
  60. package/src/doctor.js +14 -5
  61. package/src/ens.js +14 -5
  62. package/src/error-codes.js +228 -0
  63. package/src/execute-guard.js +8 -3
  64. package/src/input-validation.js +555 -0
  65. package/src/limit-order.js +127 -54
  66. package/src/perp.js +358 -35
  67. package/src/privy.js +90 -15
  68. package/src/query-options.js +47 -8
  69. package/src/response-cache-files.js +65 -0
  70. package/src/response-meta.js +8 -2
  71. package/src/rpc-urls.js +3 -1
  72. package/src/schema.json +1254 -156
  73. package/src/solana-tx.js +4 -0
  74. package/src/telemetry-flags.js +75 -0
  75. package/src/trade-validation.js +167 -8
  76. package/src/trading.js +243 -20
  77. package/src/transfer.js +79 -12
  78. package/src/update-check.js +32 -5
  79. package/src/wallet.js +246 -69
  80. package/src/walletconnect-x402.js +27 -9
@@ -0,0 +1,251 @@
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
+ | `NOT_A_PIPE` | An option that reads a secret from stdin (`--api-key-stdin`, `--webhook-secret-stdin`) was used with a terminal on stdin. Pipe the value or redirect a file. | No |
42
+ | `MISSING_ARGS` | A trade or wallet command is missing required arguments; the message shows the usage. | No |
43
+ | `INVALID_INPUT` | A trade, bridge, perp or wallet argument failed local validation. | No |
44
+ | `INVALID_ADDRESS` | An address does not match the format of the selected chain. | No |
45
+ | `INVALID_TOKEN` | A token address or symbol is not valid for the selected chain. | No |
46
+ | `INVALID_CHAIN` | The chain is not known or not supported (legacy; supported-chain errors now use INVALID_PARAMS with the field named). | No |
47
+ | `INVALID_AMOUNT` | An amount is zero, negative or not a whole number of base units. | No |
48
+ | `INVALID_SLIPPAGE` | The slippage value is outside the allowed range. | No |
49
+ | `INVALID_AGGREGATOR` | The --aggregator value is not one of the supported aggregators. | No |
50
+ | `INVALID_QUOTE_INDEX` | The --quote-index does not select a quote in the saved quote. | No |
51
+ | `UNSUPPORTED_FILTER` | The API does not support this filter for the token or chain. Do not retry. | No |
52
+ | `QUERY_TOO_LARGE` | The query would return too much data. Narrow it; retrying does not help. | No |
53
+ | `PAYLOAD_TOO_LARGE` | The request body is larger than the API accepts (HTTP 413). | No |
54
+ | `UNKNOWN_COMMAND` | The command or subcommand does not exist. The message suggests the closest match and `details.available` lists the valid ones. | No |
55
+ | `COMMAND_UNAVAILABLE` | The command was removed or is not available in this version. | No |
56
+ | `GASLESS_REMOVED` | The removed --gasless flag was passed to trade execute. | No |
57
+
58
+ ### Authentication and access
59
+
60
+ | Code | Meaning | Retry |
61
+ | --- | --- | --- |
62
+ | `UNAUTHORIZED` | The API rejected the credential (HTTP 401): the API key is missing, invalid or revoked. Not a connection problem. | No |
63
+ | `INVALID_API_KEY` | login could not verify the API key because the API rejected it. | No |
64
+ | `API_KEY_REQUIRED` | No API key was provided where one is required. | No |
65
+ | `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 |
66
+ | `FORBIDDEN` | The credential is valid but has no permission for this endpoint (HTTP 403). | No |
67
+ | `GEO_BLOCKED` | The endpoint is not available in the caller's region (HTTP 451). | No |
68
+ | `NOT_A_TTY` | An interactive step (prompt or browser login) needs a terminal, but stdin or stdout is not one. | No |
69
+ | `MIXED_CREDENTIALS` | A browser-session request was combined with an API key or payment signature. | No |
70
+
71
+ ### Credits, plans and rate limits
72
+
73
+ | Code | Meaning | Retry |
74
+ | --- | --- | --- |
75
+ | `CREDITS_EXHAUSTED` | The account has no API credits left. Retrying does not help. | No |
76
+ | `PLAN_UPGRADE_REQUIRED` | The account plan does not include this endpoint. | No |
77
+ | `PAYMENT_REQUIRED` | The request needs an x402 payment and no payment could be made (HTTP 402). | No |
78
+ | `PAYMENT_AMBIGUOUS` | An x402 payment was sent but its outcome is unknown. Do not retry with another payment. | No |
79
+ | `RATE_LIMITED` | Too many requests (HTTP 429). Wait `details.retryAfterMs` before retrying. | Yes |
80
+
81
+ ### API, network and server
82
+
83
+ | Code | Meaning | Retry |
84
+ | --- | --- | --- |
85
+ | `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 |
86
+ | `TIMEOUT` | The request or query timed out. | Yes |
87
+ | `SERVER_ERROR` | The API failed with an internal error (HTTP 5xx). Quote `requestId` to support. | Yes |
88
+ | `SERVICE_UNAVAILABLE` | The API or an upstream service is temporarily unavailable (HTTP 503). | Yes |
89
+ | `NOT_FOUND` | The resource or endpoint was not found (HTTP 404). | No |
90
+ | `TOKEN_NOT_FOUND` | The token was not found (HTTP 404). | No |
91
+ | `ADDRESS_NOT_FOUND` | The address has no data (HTTP 404). | No |
92
+ | `METHOD_NOT_ALLOWED` | The HTTP method is not allowed for this endpoint (HTTP 405). | No |
93
+ | `CONFLICT` | The request conflicts with the current state of the resource (HTTP 409). | No |
94
+ | `NON_JSON_RESPONSE` | A trading or limit-order service answered with a body that is not JSON. | Yes |
95
+ | `LIMIT_ORDER_NETWORK_ERROR` | The CLI could not reach the limit-order service. | Yes |
96
+
97
+ ### Browser login and saved sessions
98
+
99
+ | Code | Meaning | Retry |
100
+ | --- | --- | --- |
101
+ | `AUTH_BUNDLE_TOO_LARGE` | The issued session is larger than secure storage allows. The previous credential is unchanged. | No |
102
+ | `AUTH_BUSY` | Another authentication operation is running. Retry after it finishes. | Yes |
103
+ | `AUTH_CANCELLED` | The authentication operation was cancelled. | No |
104
+ | `AUTH_CLEANUP_REQUIRED` | Old login journals need cleanup. Unlock the credential store and run nansen logout. | No |
105
+ | `AUTH_CONNECT_UNAVAILABLE` | The CLI could not connect to the authentication service. | Yes |
106
+ | `AUTH_HOME_UNAVAILABLE` | No absolute home directory was found. Set HOME or USERPROFILE. | No |
107
+ | `AUTH_JOURNAL_INVALID` | A login recovery journal is corrupt. | No |
108
+ | `AUTH_LOCK_UNAVAILABLE` | Native file locking is not available on this platform, so saved authentication cannot be written. | No |
109
+ | `AUTH_NETWORK_ERROR` | A network error occurred during browser login. | Yes |
110
+ | `AUTH_ORIGIN_MISMATCH` | The saved session or simulation endpoint does not match the selected API origin. | No |
111
+ | `AUTH_ORIGIN_UNSUPPORTED` | Browser sessions need the Nansen production or staging API origin. | No |
112
+ | `AUTH_SELECTION_CHANGED` | The saved credential changed while the command ran. Retry the command. | Yes |
113
+ | `AUTH_STATE_INVALID` | The saved authentication state is invalid. | No |
114
+ | `AUTH_STORE_UNAVAILABLE` | The OS credential store is unavailable or locked. | No |
115
+ | `AUTH_TIMEOUT` | An authentication operation timed out. | Yes |
116
+ | `BROWSER_SESSION_SETUP_REQUIRED` | The session issuer configuration is not compatible with this CLI. | No |
117
+ | `INVALID_BROWSER_SESSION` | The API rejected the new browser session. Run nansen login again. | No |
118
+ | `PAIRING_CANCELLED` | Browser login was cancelled before approval. | No |
119
+ | `PAIRING_DENIED` | Browser login was denied in the browser. | No |
120
+ | `PAIRING_EXPIRED` | The browser login code expired before approval. | No |
121
+ | `PAIRING_FAILED` | Browser login failed. | No |
122
+ | `SESSION_CLOCK_SKEW` | The session is not valid yet because the local clock is behind. Synchronize system time. | No |
123
+ | `SESSION_EXPIRED` | The browser access token expired and could not be renewed. Run nansen login. | No |
124
+ | `SESSION_REFRESH_PROTOCOL_ERROR` | The issuer rejected the session refresh request format. | No |
125
+ | `SESSION_REFRESH_REJECTED` | The saved session cannot be renewed. Run nansen login. | No |
126
+ | `SESSION_REFRESH_RETRYABLE` | Session renewal was refused before rotation. Retry later. | Yes |
127
+ | `SESSION_REFRESH_RETRY_EXHAUSTED` | Session renewal failed repeatedly. Run nansen login. | No |
128
+ | `SESSION_RENEWAL_STORAGE_ERROR` | The renewed session could not be stored. Retry the command. | Yes |
129
+ | `SESSION_RENEWAL_UNCERTAIN` | The outcome of session renewal is unknown. Run nansen login. | No |
130
+ | `SESSION_VERIFICATION_FAILED` | The CLI could not verify the account of a new browser session. | No |
131
+
132
+ ### Wallets and passwords
133
+
134
+ | Code | Meaning | Retry |
135
+ | --- | --- | --- |
136
+ | `NO_WALLET` | No wallet (or WalletConnect session) is available for this chain. | No |
137
+ | `INVALID_WALLET` | The wallet cannot sign for this chain or action. | No |
138
+ | `PASSWORD_REQUIRED` | The wallet is encrypted and no password was found. `details` lists how to provide one. | No |
139
+ | `INCORRECT_PASSWORD` | The wallet password is wrong. | No |
140
+ | `NO_PASSWORD_FOUND` | No wallet password was found in any password store. | No |
141
+ | `KEYCHAIN_UNAVAILABLE` | The OS keychain is not available for the wallet password. | No |
142
+ | `CREATE_FAILED` | The wallet could not be created. | No |
143
+ | `DEFAULT_FAILED` | The default wallet could not be changed. | No |
144
+ | `DELETE_FAILED` | The wallet could not be deleted. | No |
145
+ | `EXPORT_FAILED` | The wallet could not be exported. | No |
146
+ | `SHOW_FAILED` | The wallet could not be shown. | No |
147
+ | `SEND_FAILED` | A native transfer failed. | No |
148
+ | `PRIVY_ERROR` | The Privy wallet service returned an error. | No |
149
+
150
+ ### Trading, quotes and simulation
151
+
152
+ | Code | Meaning | Retry |
153
+ | --- | --- | --- |
154
+ | `NO_QUOTES` | No aggregator returned a quote. | No |
155
+ | `ALL_QUOTES_FAILED` | Every quote failed to execute. | No |
156
+ | `QUOTE_ERROR` | The quote service returned an error. | No |
157
+ | `EXECUTE_ERROR` | Trade execution failed. | No |
158
+ | `MISSING_QUOTE_ID` | trade execute needs a --quote id. | No |
159
+ | `AGGREGATOR_NOT_AVAILABLE` | The requested aggregator has no quote in the saved quote. | No |
160
+ | `MAX_INPUT_EXCEEDED` | The quote would spend more than the allowed maximum input. | No |
161
+ | `NO_TRANSACTION` | No quote contains transaction data. | No |
162
+ | `INVALID_EXECUTION_ROUTE` | The quote has an execution route the CLI does not support. | No |
163
+ | `INSUFFICIENT_BALANCE` | The wallet balance is too low for the trade. | No |
164
+ | `INSUFFICIENT_GAS` | The wallet has too little native token for gas. | No |
165
+ | `WALLET_MISMATCH` | The quote was built for a different wallet. | No |
166
+ | `AMOUNT_MISMATCH` | The quote or bridge amount differs from the requested amount. | No |
167
+ | `INVALID_SIGNED_TX` | The signed transaction is not valid. | No |
168
+ | `BROADCAST_FAILED` | The transaction could not be broadcast. | No |
169
+ | `TX_REVERTED` | The transaction reverted or failed on chain. | No |
170
+ | `TXHASH_MISMATCH` | The RPC returned a different transaction hash than the one signed. | No |
171
+ | `RECEIPT_TIMEOUT` | The transaction was not confirmed in time and may still land. Check the transaction before retrying. | No |
172
+ | `OUTCOME_VERIFICATION_FAILED` | The CLI could not verify the trade outcome. | No |
173
+ | `SWAP_OUTCOME_MISMATCH` | The simulated swap outcome does not match the quote; nothing was signed. | No |
174
+ | `LIMIT_ORDER_DESTINATION_MISMATCH` | The limit order sends funds to an unexpected destination; nothing was signed. | No |
175
+ | `LIMIT_ORDER_OUTCOME_MISMATCH` | The simulated limit-order deposit does not match the order; nothing was signed. | No |
176
+ | `SIMULATION_FAILED` | Pre-broadcast simulation failed; nothing was signed. | No |
177
+ | `SIMULATION_ACCESS_DENIED` | The account cannot use hosted simulation. | No |
178
+ | `SIM_REVERTED` | The transaction reverts in simulation. | No |
179
+ | `SIM_RPC_ERROR` | The simulation RPC returned an error. | No |
180
+ | `SIM_RESULT_UNPARSEABLE` | The simulation result could not be parsed. | No |
181
+ | `NO_SIM_RPC` | No simulation RPC is configured for the chain. | No |
182
+ | `NOT_SIM_CAPABLE` | The RPC does not support simulation. | No |
183
+ | `RPC_UNCONFIGURED` | No RPC URL is configured for the chain. | No |
184
+ | `RPC_HTTP_ERROR` | The RPC answered with an HTTP or JSON-RPC error. | No |
185
+ | `RPC_JSON_ERROR` | The RPC answered with a body that is not JSON. | No |
186
+ | `RPC_NETWORK_ERROR` | The CLI could not reach the RPC. | Yes |
187
+ | `CONFIRMATION_DECLINED` | The confirmation prompt was declined; nothing was signed. | No |
188
+ | `CONFIRMATION_UNAVAILABLE` | Confirmation is required but no terminal is available. Pass --yes to confirm. | No |
189
+
190
+ ### Bridge
191
+
192
+ | Code | Meaning | Retry |
193
+ | --- | --- | --- |
194
+ | `BRIDGE_FAILED` | The bridge transfer failed. | No |
195
+ | `BRIDGE_NOT_FOUND` | No bridge request was found for the id. | No |
196
+ | `BRIDGE_STATUS_ERROR` | The bridge status could not be read. | Yes |
197
+ | `BRIDGE_TIMEOUT` | The bridge transfer did not finish in time. Check nansen bridge status. | No |
198
+ | `QUOTE_STATE_UNSAFE` | The bridge execution could not be recorded safely. Check nansen bridge status before requesting a new quote. | No |
199
+ | `SIGNER_MISMATCH` | The bridge quote expects a different signer. | No |
200
+ | `UNEXPECTED_ACTION` | The bridge quote contains an action the CLI does not expect. | No |
201
+ | `UNEXPECTED_NETWORK` | The bridge quote uses an unexpected network. | No |
202
+ | `PARTIAL_FILL` | The bridge transfer was only partly filled. | No |
203
+ | `HL_ACTION_REJECTED` | Hyperliquid rejected the action. | No |
204
+
205
+ ### Perpetuals (Hyperliquid)
206
+
207
+ | Code | Meaning | Retry |
208
+ | --- | --- | --- |
209
+ | `BUILDER_FEE_TOO_HIGH` | The builder fee is above the allowed ceiling. | No |
210
+ | `BUILDER_FEE_UNAVAILABLE` | The builder fee could not be read or approved. | No |
211
+ | `META_UNAVAILABLE` | Hyperliquid asset metadata is not available. | Yes |
212
+ | `NO_OPEN_POSITION` | perp close --dry-run found no open position in that coin, so a real close would be rejected. The positions data can lag a fill that just happened, so retry after a few seconds if the position was opened moments ago. | Yes |
213
+ | `SANCTIONED` | The address failed sanctions screening. | No |
214
+ | `SCREENING_UNAVAILABLE` | Sanctions screening is not available, so the action was refused. | Yes |
215
+ | `UNSUPPORTED_NETWORK` | The network is not supported for this perp action. | No |
216
+ | `ZERO_PRICE` | The order price rounds to zero. | No |
217
+ | `ZERO_SIZE` | The order size rounds to zero. | No |
218
+
219
+ ### Local files, config and tooling
220
+
221
+ | Code | Meaning | Retry |
222
+ | --- | --- | --- |
223
+ | `FILE_EXISTS` | The output path already exists; the CLI does not overwrite it. | No |
224
+ | `FILE_WRITE_FAILED` | The output file could not be written. | No |
225
+ | `LOCAL_FILE_UNSAFE` | A local file has unsafe permissions or type. | No |
226
+ | `INVALID_CONFIG` | A configuration file could not be read or parsed. | No |
227
+ | `MCP_VERIFY_FAILED` | nansen mcp verify could not connect to the MCP server with the configured settings. | No |
228
+ | `UNSUPPORTED_PLATFORM` | The MCP client is not available on this operating system. | No |
229
+
230
+ ### Generic
231
+
232
+ | Code | Meaning | Retry |
233
+ | --- | --- | --- |
234
+ | `COMMAND_ERROR` | A command failed without a more specific code. | No |
235
+ | `UNKNOWN` | An unexpected error with no code. Report it with the message. | No |
236
+
237
+ ## Field codes
238
+
239
+ `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.
240
+
241
+ | Field code | Meaning |
242
+ | --- | --- |
243
+ | `missing_field` | A required field or option is missing. |
244
+ | `unknown_field` | The field or option is not recognized. The message suggests the closest valid name. |
245
+ | `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). |
246
+ | `invalid_address_format` | The address does not match the chain's format. |
247
+ | `invalid_date_format` | The date is not a valid YYYY-MM-DD date. |
248
+ | `invalid_date_range` | The date range is not allowed. |
249
+ | `mutually_exclusive_fields` | Two fields that cannot be combined were both given. |
250
+ | `value_out_of_range` | The value is outside the allowed range. |
251
+ | `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.5.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
 
@@ -37,10 +37,10 @@ Public agent fast/expert and direct API commands accept the selected nansen:api
37
37
  ```bash
38
38
  nansen agent "What are top smart money tokens on Solana today and why?"
39
39
  nansen agent "Analyse wallet 0x123... -- is this a smart trader?"
40
- nansen agent "..." --expert # deeper analysis, 750 credits
40
+ nansen agent "..." --expert # deeper analysis, 400 credits
41
41
  ```
42
42
 
43
- Cost: 200 credits (fast) / 750 credits (expert)
43
+ Cost: 100 credits (fast) / 400 credits (expert)
44
44
 
45
45
  ## Use direct CLI commands when
46
46
 
@@ -58,7 +58,7 @@ Cost: 5-50 credits per call
58
58
 
59
59
  ## Anti-patterns
60
60
 
61
- - Don't use `nansen agent` for simple data fetches -- 40x more expensive
61
+ - Don't use `nansen agent` for simple data fetches -- it costs more than a direct call and returns prose, not data
62
62
  - Don't use raw CLI for open-ended analysis -- returns data, not interpretation
63
63
  - Don't chain 3+ agent calls -- get raw data via CLI, call agent once for synthesis
64
64
 
@@ -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
 
@@ -85,11 +85,13 @@ If the user prefers localtunnel or can't install ngrok, proceed with localtunnel
85
85
 
86
86
  ### Step 1: Generate a webhook secret
87
87
 
88
+ Write the secret straight to a file that only the user can read, so it never appears in the terminal, the shell history or the transcript:
89
+
88
90
  ```bash
89
- node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
91
+ (umask 077 && node -e "process.stdout.write(require('crypto').randomBytes(32).toString('hex'))" > nansen-webhook-secret.txt)
90
92
  ```
91
93
 
92
- Store the output — you need it for both the server and the alert configuration. **Never log or echo the secret after this point.**
94
+ The server and the alert both read it from this file (`WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)"` for the server, `--webhook-secret-stdin < nansen-webhook-secret.txt` for `nansen alerts`). **Never log, echo or paste the secret.**
93
95
 
94
96
  ### Step 2: Write the webhook receiver script
95
97
 
@@ -257,7 +259,7 @@ server.listen(PORT, '127.0.0.1', () => {
257
259
  Start the server:
258
260
 
259
261
  ```bash
260
- WEBHOOK_SECRET='<secret>' node nansen-webhook-server.mjs
262
+ WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs
261
263
  ```
262
264
 
263
265
  Then start a public tunnel so Nansen's servers can reach it.
@@ -287,9 +289,9 @@ Prints a URL like `https://xxx.loca.lt`. The webhook URL is `https://xxx.loca.lt
287
289
  **Do NOT create or modify any alerts.** Instead, print a clear summary for the user explaining what was set up and what they need to do next.
288
290
 
289
291
  The summary MUST include:
290
- 1. Confirmation of what was created (the server script path and the generated secret)
291
- 2. The commands to start the server and tunnel (with the actual secret filled in)
292
- 3. The exact `nansen alerts create` or `nansen alerts update` command they should run, with the `--webhook` and `--webhook-secret` flags filled in with the tunnel URL and secret — but leave the alert-specific flags (`--name`, `--type`, `--chains`, etc.) as placeholders for the user to fill in
292
+ 1. Confirmation of what was created (the server script path and the secret file path; never the secret itself)
293
+ 2. The commands to start the server and tunnel (reading the secret from the file)
294
+ 3. The exact `nansen alerts create` or `nansen alerts update` command they should run, with `--webhook` filled in with the tunnel URL and `--webhook-secret-stdin < nansen-webhook-secret.txt` for the secret (do not put the secret on the command line with `--webhook-secret`; it lands in shell history and the process list) — but leave the alert-specific flags (`--name`, `--type`, `--chains`, etc.) as placeholders for the user to fill in
293
295
  4. A reminder that the server and tunnel must be running before the alert is created (Nansen validates the webhook endpoint on creation)
294
296
  5. A note that tunnel URLs are ephemeral and will change on restart
295
297
 
@@ -299,12 +301,13 @@ Example summary format:
299
301
  ## Webhook listener ready
300
302
 
301
303
  **Server script:** ./nansen-webhook-server.mjs
304
+ **Secret file:** ./nansen-webhook-secret.txt (readable only by you)
302
305
  **Port:** 9477
303
306
 
304
307
  ### To start receiving alerts:
305
308
 
306
309
  1. Start the server (keep this terminal open):
307
- WEBHOOK_SECRET='<actual-secret>' node nansen-webhook-server.mjs
310
+ WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs
308
311
 
309
312
  2. In a new terminal, start the tunnel:
310
313
  ngrok http 9477 # recommended
@@ -316,13 +319,13 @@ Example summary format:
316
319
  --type <sm-token-flows|common-token-transfer|smart-contract-call> \
317
320
  --chains <chains> \
318
321
  --webhook 'https://<your-tunnel-url>/webhook' \
319
- --webhook-secret '<actual-secret>' \
320
- [type-specific flags...]
322
+ --webhook-secret-stdin \
323
+ [type-specific flags...] < nansen-webhook-secret.txt
321
324
 
322
325
  Or add the webhook to an existing alert:
323
326
  nansen alerts update <alert-id> \
324
327
  --webhook 'https://<your-tunnel-url>/webhook' \
325
- --webhook-secret '<actual-secret>'
328
+ --webhook-secret-stdin < nansen-webhook-secret.txt
326
329
 
327
330
  Note: The tunnel URL changes each time you restart. Update the alert
328
331
  webhook URL if you restart the tunnel.
@@ -343,11 +346,11 @@ See `nansen alerts create --help` for full flag reference per alert type.
343
346
 
344
347
  | Symptom | Fix |
345
348
  |---|---|
346
- | "Invalid signature" on every request | Ensure the **exact same secret** is in `WEBHOOK_SECRET` and `--webhook-secret` |
349
+ | "Invalid signature" on every request | Ensure the server and the alert read the **same secret** (the same `nansen-webhook-secret.txt`). Re-run `nansen alerts update <id> --webhook '<url>/webhook' --webhook-secret-stdin < nansen-webhook-secret.txt` after changing it |
347
350
  | "Failed to send welcome message" on alert create | Start the server and tunnel **before** creating the alert |
348
351
  | No alerts arriving | Check `nansen alerts list --table` — is the alert enabled? Is the webhook URL correct (includes `/webhook`)? |
349
352
  | Tunnel URL expired / tunnel died | Restart the tunnel, get the new URL, then `nansen alerts update <id> --webhook '<new-url>/webhook'`. If this keeps happening, switch from localtunnel to ngrok. |
350
- | Port already in use | Set a different port: `PORT=9478 WEBHOOK_SECRET='...' node nansen-webhook-server.mjs` and update the tunnel accordingly |
353
+ | Port already in use | Set a different port: `PORT=9478 WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" node nansen-webhook-server.mjs` and update the tunnel accordingly |
351
354
 
352
355
  ## OpenClaw Integration
353
356
 
@@ -365,7 +368,7 @@ If the user is running OpenClaw locally on the same machine, the webhook server
365
368
  ### Start command (with OpenClaw forwarding)
366
369
 
367
370
  ```bash
368
- WEBHOOK_SECRET='<secret>' \
371
+ WEBHOOK_SECRET="$(cat nansen-webhook-secret.txt)" \
369
372
  OPENCLAW_GATEWAY_URL='http://localhost:3000' \
370
373
  OPENCLAW_AUTH_TOKEN='<token>' \
371
374
  node nansen-webhook-server.mjs
@@ -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
 
@@ -117,6 +117,14 @@ nansen trade limit-order cancel --order <orderId>
117
117
  Cancelling submits a withdrawal transaction; surface the tx signature from the
118
118
  CLI output so the user can verify on Solscan.
119
119
 
120
+ ### Preview and confirm
121
+
122
+ `create` and `cancel` accept `--dry-run` (print the plan and exit 0; no API
123
+ request, no signature, nothing submitted) and `--yes`/`-y` (skip the
124
+ confirmation prompt, same as `NANSEN_YES=1`). The prompt only appears in an
125
+ interactive terminal; agents and CI run unprompted. Use `--dry-run` to show the
126
+ user what will be created or cancelled before running it for real.
127
+
120
128
  ### Update
121
129
 
122
130
  ```bash
@@ -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