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.
- package/CHANGELOG.md +112 -0
- package/README.md +61 -38
- package/docs/auth.md +56 -0
- package/docs/browser-login.md +101 -7
- package/docs/error-codes.md +251 -0
- package/package.json +10 -4
- package/skills/nansen-agent-guide/SKILL.md +20 -4
- package/skills/nansen-alerts-webhook-listener/SKILL.md +17 -14
- package/skills/nansen-dca-tracker/SKILL.md +1 -1
- package/skills/nansen-defi-positions/SKILL.md +1 -1
- package/skills/nansen-exit-signals/SKILL.md +2 -2
- package/skills/nansen-fund-tracker/SKILL.md +1 -1
- package/skills/nansen-general-search/SKILL.md +1 -1
- package/skills/nansen-holder-analysis/SKILL.md +2 -2
- package/skills/nansen-limit-orders/SKILL.md +9 -1
- package/skills/nansen-mpp-payment/SKILL.md +2 -2
- package/skills/nansen-perp-screener/SKILL.md +1 -1
- package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
- package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
- package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
- package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
- package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
- package/skills/nansen-prediction-markets/SKILL.md +1 -1
- package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
- package/skills/nansen-smart-alerts/SKILL.md +5 -2
- package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
- package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
- package/skills/nansen-smart-money-trend/SKILL.md +1 -1
- package/skills/nansen-token-research/SKILL.md +1 -1
- package/skills/nansen-token-screener/SKILL.md +1 -1
- package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
- package/skills/nansen-trading/SKILL.md +23 -2
- package/skills/nansen-wallet-batch/SKILL.md +1 -1
- package/skills/nansen-wallet-clustering/SKILL.md +1 -1
- package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
- package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
- package/skills/nansen-wallet-manager/SKILL.md +11 -5
- package/skills/nansen-wallet-profiler/SKILL.md +1 -1
- package/skills/nansen-web-fetcher/SKILL.md +1 -1
- package/skills/nansen-web-searcher/SKILL.md +1 -1
- package/src/api-endpoints.json +1605 -0
- package/src/api.js +282 -124
- package/src/auth-credentials.js +1 -0
- package/src/auth-key-input.js +57 -9
- package/src/auth-state.js +2 -2
- package/src/auth-store-native.js +6 -1
- package/src/auth-store-worker.js +1 -1
- package/src/auth-store.js +9 -4
- package/src/auto-paginate.js +25 -7
- package/src/bridge.js +19 -10
- package/src/cache-inspect.js +16 -6
- package/src/cli.js +272 -114
- package/src/commands/agent.js +2 -3
- package/src/commands/alerts.js +365 -18
- package/src/commands/completion.js +4 -1
- package/src/commands/feedback.js +98 -37
- package/src/commands/mcp.js +1 -1
- package/src/commands/research.js +14 -37
- package/src/cost-cache.js +33 -7
- package/src/doctor.js +14 -5
- package/src/ens.js +14 -5
- package/src/error-codes.js +228 -0
- package/src/execute-guard.js +8 -3
- package/src/input-validation.js +555 -0
- package/src/limit-order.js +127 -54
- package/src/perp.js +358 -35
- package/src/privy.js +90 -15
- package/src/query-options.js +47 -8
- package/src/response-cache-files.js +65 -0
- package/src/response-meta.js +8 -2
- package/src/rpc-urls.js +3 -1
- package/src/schema.json +1254 -156
- package/src/solana-tx.js +4 -0
- package/src/telemetry-flags.js +75 -0
- package/src/trade-validation.js +167 -8
- package/src/trading.js +243 -20
- package/src/transfer.js +79 -12
- package/src/update-check.js +32 -5
- package/src/wallet.js +246 -69
- 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
|
+
"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/
|
|
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.
|
|
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.
|
|
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
|
|
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,
|
|
40
|
+
nansen agent "..." --expert # deeper analysis, 400 credits
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
Cost:
|
|
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 --
|
|
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
|
|
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 "
|
|
91
|
+
(umask 077 && node -e "process.stdout.write(require('crypto').randomBytes(32).toString('hex'))" > nansen-webhook-secret.txt)
|
|
90
92
|
```
|
|
91
93
|
|
|
92
|
-
|
|
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=
|
|
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
|
|
291
|
-
2. The commands to start the server and tunnel (
|
|
292
|
-
3. The exact `nansen alerts create` or `nansen alerts update` command they should run, with
|
|
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=
|
|
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
|
|
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
|
|
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 **
|
|
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=
|
|
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=
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|