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