nansen-cli 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/README.md +32 -32
  3. package/docs/auth.md +56 -0
  4. package/docs/browser-login.md +101 -7
  5. package/docs/error-codes.md +249 -0
  6. package/package.json +10 -4
  7. package/skills/nansen-agent-guide/SKILL.md +17 -1
  8. package/skills/nansen-alerts-webhook-listener/SKILL.md +1 -1
  9. package/skills/nansen-dca-tracker/SKILL.md +1 -1
  10. package/skills/nansen-defi-positions/SKILL.md +1 -1
  11. package/skills/nansen-exit-signals/SKILL.md +2 -2
  12. package/skills/nansen-fund-tracker/SKILL.md +1 -1
  13. package/skills/nansen-general-search/SKILL.md +1 -1
  14. package/skills/nansen-holder-analysis/SKILL.md +2 -2
  15. package/skills/nansen-limit-orders/SKILL.md +1 -1
  16. package/skills/nansen-mpp-payment/SKILL.md +2 -2
  17. package/skills/nansen-perp-screener/SKILL.md +1 -1
  18. package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
  19. package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
  20. package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
  21. package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
  22. package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
  23. package/skills/nansen-prediction-markets/SKILL.md +1 -1
  24. package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
  25. package/skills/nansen-smart-alerts/SKILL.md +2 -1
  26. package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
  27. package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
  28. package/skills/nansen-smart-money-trend/SKILL.md +1 -1
  29. package/skills/nansen-token-research/SKILL.md +1 -1
  30. package/skills/nansen-token-screener/SKILL.md +1 -1
  31. package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
  32. package/skills/nansen-trading/SKILL.md +1 -1
  33. package/skills/nansen-wallet-batch/SKILL.md +1 -1
  34. package/skills/nansen-wallet-clustering/SKILL.md +1 -1
  35. package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
  36. package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
  37. package/skills/nansen-wallet-manager/SKILL.md +1 -1
  38. package/skills/nansen-wallet-profiler/SKILL.md +1 -1
  39. package/skills/nansen-web-fetcher/SKILL.md +1 -1
  40. package/skills/nansen-web-searcher/SKILL.md +1 -1
  41. package/src/api-endpoints.json +1605 -0
  42. package/src/api.js +202 -97
  43. package/src/auth-credentials.js +1 -0
  44. package/src/auth-state.js +2 -2
  45. package/src/auth-store-native.js +6 -1
  46. package/src/auth-store-worker.js +1 -1
  47. package/src/auth-store.js +9 -4
  48. package/src/bridge.js +19 -10
  49. package/src/cli.js +188 -89
  50. package/src/commands/agent.js +2 -3
  51. package/src/commands/alerts.js +277 -9
  52. package/src/commands/feedback.js +98 -37
  53. package/src/commands/mcp.js +1 -1
  54. package/src/commands/research.js +14 -37
  55. package/src/cost-cache.js +33 -7
  56. package/src/doctor.js +14 -5
  57. package/src/error-codes.js +226 -0
  58. package/src/input-validation.js +551 -0
  59. package/src/limit-order.js +12 -3
  60. package/src/perp.js +2 -1
  61. package/src/privy.js +89 -11
  62. package/src/query-options.js +30 -7
  63. package/src/rpc-urls.js +3 -1
  64. package/src/schema.json +1137 -145
  65. package/src/solana-tx.js +4 -0
  66. package/src/trade-validation.js +167 -8
  67. package/src/trading.js +172 -12
  68. package/src/transfer.js +7 -1
  69. package/src/update-check.js +32 -5
  70. package/src/wallet.js +211 -57
  71. package/src/walletconnect-x402.js +14 -8
@@ -0,0 +1,226 @@
1
+ /**
2
+ * Nansen CLI - The one list of error codes.
3
+ *
4
+ * Every failure the CLI reports carries one of these codes in the `code` field
5
+ * of the error envelope ({ success: false, error, code, status, details }).
6
+ * Agents branch on `code`, so a code must never appear in the source without
7
+ * an entry here: src/__tests__/error-code-registry.test.js scans the source and
8
+ * fails on an unregistered code, and docs/error-codes.md is generated from this
9
+ * table (`npm run error-codes:generate`; `npm test` fails when it is stale).
10
+ *
11
+ * Field-level validation errors also carry `details.errors[]` entries
12
+ * ({ field, message, code }) whose `code` uses the API's snake_case set
13
+ * (FIELD_ERROR_CODES below), so the CLI, the REST API and the MCP server
14
+ * describe one bad field the same way.
15
+ */
16
+
17
+ /** Group order and headings for the generated documentation. */
18
+ export const ERROR_CODE_GROUPS = {
19
+ input: 'Input and validation',
20
+ auth: 'Authentication and access',
21
+ quota: 'Credits, plans and rate limits',
22
+ api: 'API, network and server',
23
+ session: 'Browser login and saved sessions',
24
+ wallet: 'Wallets and passwords',
25
+ trade: 'Trading, quotes and simulation',
26
+ bridge: 'Bridge',
27
+ perp: 'Perpetuals (Hyperliquid)',
28
+ local: 'Local files, config and tooling',
29
+ generic: 'Generic',
30
+ };
31
+
32
+ /**
33
+ * code -> { group, description }. `retry` is set where retrying the same
34
+ * request can succeed without changing it.
35
+ */
36
+ export const ERROR_CODES = {
37
+ // ── Input and validation ──
38
+ INVALID_PARAMS: { group: 'input', description: 'An option or request field has an invalid value, or the command does not accept it. `details.errors[]` names each field.' },
39
+ MISSING_PARAM: { group: 'input', description: 'A required option or request field is missing. `details.errors[]` names each field.' },
40
+ MISSING_ARGS: { group: 'input', description: 'A trade or wallet command is missing required arguments; the message shows the usage.' },
41
+ INVALID_INPUT: { group: 'input', description: 'A trade, bridge, perp or wallet argument failed local validation.' },
42
+ INVALID_ADDRESS: { group: 'input', description: 'An address does not match the format of the selected chain.' },
43
+ INVALID_TOKEN: { group: 'input', description: 'A token address or symbol is not valid for the selected chain.' },
44
+ INVALID_CHAIN: { group: 'input', description: 'The chain is not known or not supported (legacy; supported-chain errors now use INVALID_PARAMS with the field named).' },
45
+ INVALID_AMOUNT: { group: 'input', description: 'An amount is zero, negative or not a whole number of base units.' },
46
+ INVALID_SLIPPAGE: { group: 'input', description: 'The slippage value is outside the allowed range.' },
47
+ INVALID_AGGREGATOR: { group: 'input', description: 'The --aggregator value is not one of the supported aggregators.' },
48
+ INVALID_QUOTE_INDEX: { group: 'input', description: 'The --quote-index does not select a quote in the saved quote.' },
49
+ UNSUPPORTED_FILTER: { group: 'input', description: 'The API does not support this filter for the token or chain. Do not retry.' },
50
+ QUERY_TOO_LARGE: { group: 'input', description: 'The query would return too much data. Narrow it; retrying does not help.' },
51
+ PAYLOAD_TOO_LARGE: { group: 'input', description: 'The request body is larger than the API accepts (HTTP 413).' },
52
+ UNKNOWN_COMMAND: { group: 'input', description: 'The command or subcommand does not exist. The message suggests the closest match and `details.available` lists the valid ones.' },
53
+ COMMAND_UNAVAILABLE: { group: 'input', description: 'The command was removed or is not available in this version.' },
54
+ GASLESS_REMOVED: { group: 'input', description: 'The removed --gasless flag was passed to trade execute.' },
55
+
56
+ // ── Authentication and access ──
57
+ UNAUTHORIZED: { group: 'auth', description: 'The API rejected the credential (HTTP 401): the API key is missing, invalid or revoked. Not a connection problem.' },
58
+ INVALID_API_KEY: { group: 'auth', description: 'login could not verify the API key because the API rejected it.' },
59
+ API_KEY_REQUIRED: { group: 'auth', description: 'No API key was provided where one is required.' },
60
+ VERIFICATION_FAILED: { group: 'auth', description: 'login could not verify the API key for a reason other than a rejected key (network, rate limit, outage). The key may be valid.' },
61
+ FORBIDDEN: { group: 'auth', description: 'The credential is valid but has no permission for this endpoint (HTTP 403).' },
62
+ GEO_BLOCKED: { group: 'auth', description: 'The endpoint is not available in the caller\'s region (HTTP 451).' },
63
+ NOT_A_TTY: { group: 'auth', description: 'An interactive step (prompt or browser login) needs a terminal, but stdin or stdout is not one.' },
64
+ MIXED_CREDENTIALS: { group: 'auth', description: 'A browser-session request was combined with an API key or payment signature.' },
65
+
66
+ // ── Credits, plans and rate limits ──
67
+ CREDITS_EXHAUSTED: { group: 'quota', description: 'The account has no API credits left. Retrying does not help.' },
68
+ PLAN_UPGRADE_REQUIRED: { group: 'quota', description: 'The account plan does not include this endpoint.' },
69
+ PAYMENT_REQUIRED: { group: 'quota', description: 'The request needs an x402 payment and no payment could be made (HTTP 402).' },
70
+ PAYMENT_AMBIGUOUS: { group: 'quota', description: 'An x402 payment was sent but its outcome is unknown. Do not retry with another payment.' },
71
+ RATE_LIMITED: { group: 'quota', description: 'Too many requests (HTTP 429). Wait `details.retryAfterMs` before retrying.', retry: true },
72
+
73
+ // ── API, network and server ──
74
+ NETWORK_ERROR: { group: 'api', description: 'The CLI could not reach the API (DNS, TLS, proxy, firewall or offline). The credential was not checked; do not replace the API key.', retry: true },
75
+ TIMEOUT: { group: 'api', description: 'The request or query timed out.', retry: true },
76
+ SERVER_ERROR: { group: 'api', description: 'The API failed with an internal error (HTTP 5xx). Quote `requestId` to support.', retry: true },
77
+ SERVICE_UNAVAILABLE: { group: 'api', description: 'The API or an upstream service is temporarily unavailable (HTTP 503).', retry: true },
78
+ NOT_FOUND: { group: 'api', description: 'The resource or endpoint was not found (HTTP 404).' },
79
+ TOKEN_NOT_FOUND: { group: 'api', description: 'The token was not found (HTTP 404).' },
80
+ ADDRESS_NOT_FOUND: { group: 'api', description: 'The address has no data (HTTP 404).' },
81
+ METHOD_NOT_ALLOWED: { group: 'api', description: 'The HTTP method is not allowed for this endpoint (HTTP 405).' },
82
+ CONFLICT: { group: 'api', description: 'The request conflicts with the current state of the resource (HTTP 409).' },
83
+ NON_JSON_RESPONSE: { group: 'api', description: 'A trading or limit-order service answered with a body that is not JSON.', retry: true },
84
+ LIMIT_ORDER_NETWORK_ERROR: { group: 'api', description: 'The CLI could not reach the limit-order service.', retry: true },
85
+
86
+ // ── Browser login and saved sessions ──
87
+ AUTH_BUNDLE_TOO_LARGE: { group: 'session', description: 'The issued session is larger than secure storage allows. The previous credential is unchanged.' },
88
+ AUTH_BUSY: { group: 'session', description: 'Another authentication operation is running. Retry after it finishes.', retry: true },
89
+ AUTH_CANCELLED: { group: 'session', description: 'The authentication operation was cancelled.' },
90
+ AUTH_CLEANUP_REQUIRED: { group: 'session', description: 'Old login journals need cleanup. Unlock the credential store and run nansen logout.' },
91
+ AUTH_CONNECT_UNAVAILABLE: { group: 'session', description: 'The CLI could not connect to the authentication service.', retry: true },
92
+ AUTH_HOME_UNAVAILABLE: { group: 'session', description: 'No absolute home directory was found. Set HOME or USERPROFILE.' },
93
+ AUTH_JOURNAL_INVALID: { group: 'session', description: 'A login recovery journal is corrupt.' },
94
+ AUTH_LOCK_UNAVAILABLE: { group: 'session', description: 'Native file locking is not available on this platform, so saved authentication cannot be written.' },
95
+ AUTH_NETWORK_ERROR: { group: 'session', description: 'A network error occurred during browser login.', retry: true },
96
+ AUTH_ORIGIN_MISMATCH: { group: 'session', description: 'The saved session or simulation endpoint does not match the selected API origin.' },
97
+ AUTH_ORIGIN_UNSUPPORTED: { group: 'session', description: 'Browser sessions need the Nansen production or staging API origin.' },
98
+ AUTH_SELECTION_CHANGED: { group: 'session', description: 'The saved credential changed while the command ran. Retry the command.', retry: true },
99
+ AUTH_STATE_INVALID: { group: 'session', description: 'The saved authentication state is invalid.' },
100
+ AUTH_STORE_UNAVAILABLE: { group: 'session', description: 'The OS credential store is unavailable or locked.' },
101
+ AUTH_TIMEOUT: { group: 'session', description: 'An authentication operation timed out.', retry: true },
102
+ BROWSER_SESSION_SETUP_REQUIRED: { group: 'session', description: 'The session issuer configuration is not compatible with this CLI.' },
103
+ INVALID_BROWSER_SESSION: { group: 'session', description: 'The API rejected the new browser session. Run nansen login again.' },
104
+ PAIRING_CANCELLED: { group: 'session', description: 'Browser login was cancelled before approval.' },
105
+ PAIRING_DENIED: { group: 'session', description: 'Browser login was denied in the browser.' },
106
+ PAIRING_EXPIRED: { group: 'session', description: 'The browser login code expired before approval.' },
107
+ PAIRING_FAILED: { group: 'session', description: 'Browser login failed.' },
108
+ SESSION_CLOCK_SKEW: { group: 'session', description: 'The session is not valid yet because the local clock is behind. Synchronize system time.' },
109
+ SESSION_EXPIRED: { group: 'session', description: 'The browser access token expired and could not be renewed. Run nansen login.' },
110
+ SESSION_REFRESH_PROTOCOL_ERROR: { group: 'session', description: 'The issuer rejected the session refresh request format.' },
111
+ SESSION_REFRESH_REJECTED: { group: 'session', description: 'The saved session cannot be renewed. Run nansen login.' },
112
+ SESSION_REFRESH_RETRYABLE: { group: 'session', description: 'Session renewal was refused before rotation. Retry later.', retry: true },
113
+ SESSION_REFRESH_RETRY_EXHAUSTED: { group: 'session', description: 'Session renewal failed repeatedly. Run nansen login.' },
114
+ SESSION_RENEWAL_STORAGE_ERROR: { group: 'session', description: 'The renewed session could not be stored. Retry the command.', retry: true },
115
+ SESSION_RENEWAL_UNCERTAIN: { group: 'session', description: 'The outcome of session renewal is unknown. Run nansen login.' },
116
+ SESSION_VERIFICATION_FAILED: { group: 'session', description: 'The CLI could not verify the account of a new browser session.' },
117
+
118
+ // ── Wallets and passwords ──
119
+ NO_WALLET: { group: 'wallet', description: 'No wallet (or WalletConnect session) is available for this chain.' },
120
+ INVALID_WALLET: { group: 'wallet', description: 'The wallet cannot sign for this chain or action.' },
121
+ PASSWORD_REQUIRED: { group: 'wallet', description: 'The wallet is encrypted and no password was found. `details` lists how to provide one.' },
122
+ INCORRECT_PASSWORD: { group: 'wallet', description: 'The wallet password is wrong.' },
123
+ NO_PASSWORD_FOUND: { group: 'wallet', description: 'No wallet password was found in any password store.' },
124
+ KEYCHAIN_UNAVAILABLE: { group: 'wallet', description: 'The OS keychain is not available for the wallet password.' },
125
+ CREATE_FAILED: { group: 'wallet', description: 'The wallet could not be created.' },
126
+ DEFAULT_FAILED: { group: 'wallet', description: 'The default wallet could not be changed.' },
127
+ DELETE_FAILED: { group: 'wallet', description: 'The wallet could not be deleted.' },
128
+ EXPORT_FAILED: { group: 'wallet', description: 'The wallet could not be exported.' },
129
+ SHOW_FAILED: { group: 'wallet', description: 'The wallet could not be shown.' },
130
+ SEND_FAILED: { group: 'wallet', description: 'A native transfer failed.' },
131
+ PRIVY_ERROR: { group: 'wallet', description: 'The Privy wallet service returned an error.' },
132
+
133
+ // ── Trading, quotes and simulation ──
134
+ NO_QUOTES: { group: 'trade', description: 'No aggregator returned a quote.' },
135
+ ALL_QUOTES_FAILED: { group: 'trade', description: 'Every quote failed to execute.' },
136
+ QUOTE_ERROR: { group: 'trade', description: 'The quote service returned an error.' },
137
+ EXECUTE_ERROR: { group: 'trade', description: 'Trade execution failed.' },
138
+ MISSING_QUOTE_ID: { group: 'trade', description: 'trade execute needs a --quote id.' },
139
+ AGGREGATOR_NOT_AVAILABLE: { group: 'trade', description: 'The requested aggregator has no quote in the saved quote.' },
140
+ MAX_INPUT_EXCEEDED: { group: 'trade', description: 'The quote would spend more than the allowed maximum input.' },
141
+ NO_TRANSACTION: { group: 'trade', description: 'No quote contains transaction data.' },
142
+ INVALID_EXECUTION_ROUTE: { group: 'trade', description: 'The quote has an execution route the CLI does not support.' },
143
+ INSUFFICIENT_BALANCE: { group: 'trade', description: 'The wallet balance is too low for the trade.' },
144
+ INSUFFICIENT_GAS: { group: 'trade', description: 'The wallet has too little native token for gas.' },
145
+ WALLET_MISMATCH: { group: 'trade', description: 'The quote was built for a different wallet.' },
146
+ AMOUNT_MISMATCH: { group: 'trade', description: 'The quote or bridge amount differs from the requested amount.' },
147
+ INVALID_SIGNED_TX: { group: 'trade', description: 'The signed transaction is not valid.' },
148
+ BROADCAST_FAILED: { group: 'trade', description: 'The transaction could not be broadcast.' },
149
+ TX_REVERTED: { group: 'trade', description: 'The transaction reverted or failed on chain.' },
150
+ TXHASH_MISMATCH: { group: 'trade', description: 'The RPC returned a different transaction hash than the one signed.' },
151
+ RECEIPT_TIMEOUT: { group: 'trade', description: 'The transaction was not confirmed in time and may still land. Check the transaction before retrying.' },
152
+ OUTCOME_VERIFICATION_FAILED: { group: 'trade', description: 'The CLI could not verify the trade outcome.' },
153
+ SWAP_OUTCOME_MISMATCH: { group: 'trade', description: 'The simulated swap outcome does not match the quote; nothing was signed.' },
154
+ LIMIT_ORDER_DESTINATION_MISMATCH: { group: 'trade', description: 'The limit order sends funds to an unexpected destination; nothing was signed.' },
155
+ LIMIT_ORDER_OUTCOME_MISMATCH: { group: 'trade', description: 'The simulated limit-order deposit does not match the order; nothing was signed.' },
156
+ SIMULATION_FAILED: { group: 'trade', description: 'Pre-broadcast simulation failed; nothing was signed.' },
157
+ SIMULATION_ACCESS_DENIED: { group: 'trade', description: 'The account cannot use hosted simulation.' },
158
+ SIM_REVERTED: { group: 'trade', description: 'The transaction reverts in simulation.' },
159
+ SIM_RPC_ERROR: { group: 'trade', description: 'The simulation RPC returned an error.' },
160
+ SIM_RESULT_UNPARSEABLE: { group: 'trade', description: 'The simulation result could not be parsed.' },
161
+ NO_SIM_RPC: { group: 'trade', description: 'No simulation RPC is configured for the chain.' },
162
+ NOT_SIM_CAPABLE: { group: 'trade', description: 'The RPC does not support simulation.' },
163
+ RPC_UNCONFIGURED: { group: 'trade', description: 'No RPC URL is configured for the chain.' },
164
+ RPC_HTTP_ERROR: { group: 'trade', description: 'The RPC answered with an HTTP or JSON-RPC error.' },
165
+ RPC_JSON_ERROR: { group: 'trade', description: 'The RPC answered with a body that is not JSON.' },
166
+ RPC_NETWORK_ERROR: { group: 'trade', description: 'The CLI could not reach the RPC.', retry: true },
167
+ CONFIRMATION_DECLINED: { group: 'trade', description: 'The confirmation prompt was declined; nothing was signed.' },
168
+ CONFIRMATION_UNAVAILABLE: { group: 'trade', description: 'Confirmation is required but no terminal is available. Pass --yes to confirm.' },
169
+
170
+ // ── Bridge ──
171
+ BRIDGE_FAILED: { group: 'bridge', description: 'The bridge transfer failed.' },
172
+ BRIDGE_NOT_FOUND: { group: 'bridge', description: 'No bridge request was found for the id.' },
173
+ BRIDGE_STATUS_ERROR: { group: 'bridge', description: 'The bridge status could not be read.', retry: true },
174
+ BRIDGE_TIMEOUT: { group: 'bridge', description: 'The bridge transfer did not finish in time. Check nansen bridge status.' },
175
+ QUOTE_STATE_UNSAFE: { group: 'bridge', description: 'The bridge execution could not be recorded safely. Check nansen bridge status before requesting a new quote.' },
176
+ SIGNER_MISMATCH: { group: 'bridge', description: 'The bridge quote expects a different signer.' },
177
+ UNEXPECTED_ACTION: { group: 'bridge', description: 'The bridge quote contains an action the CLI does not expect.' },
178
+ UNEXPECTED_NETWORK: { group: 'bridge', description: 'The bridge quote uses an unexpected network.' },
179
+ PARTIAL_FILL: { group: 'bridge', description: 'The bridge transfer was only partly filled.' },
180
+ HL_ACTION_REJECTED: { group: 'bridge', description: 'Hyperliquid rejected the action.' },
181
+
182
+ // ── Perpetuals ──
183
+ BUILDER_FEE_TOO_HIGH: { group: 'perp', description: 'The builder fee is above the allowed ceiling.' },
184
+ BUILDER_FEE_UNAVAILABLE: { group: 'perp', description: 'The builder fee could not be read or approved.' },
185
+ META_UNAVAILABLE: { group: 'perp', description: 'Hyperliquid asset metadata is not available.', retry: true },
186
+ SANCTIONED: { group: 'perp', description: 'The address failed sanctions screening.' },
187
+ SCREENING_UNAVAILABLE: { group: 'perp', description: 'Sanctions screening is not available, so the action was refused.', retry: true },
188
+ UNSUPPORTED_NETWORK: { group: 'perp', description: 'The network is not supported for this perp action.' },
189
+ ZERO_PRICE: { group: 'perp', description: 'The order price rounds to zero.' },
190
+ ZERO_SIZE: { group: 'perp', description: 'The order size rounds to zero.' },
191
+
192
+ // ── Local files, config and tooling ──
193
+ FILE_EXISTS: { group: 'local', description: 'The output path already exists; the CLI does not overwrite it.' },
194
+ FILE_WRITE_FAILED: { group: 'local', description: 'The output file could not be written.' },
195
+ LOCAL_FILE_UNSAFE: { group: 'local', description: 'A local file has unsafe permissions or type.' },
196
+ INVALID_CONFIG: { group: 'local', description: 'A configuration file could not be read or parsed.' },
197
+ MCP_VERIFY_FAILED: { group: 'local', description: 'nansen mcp verify could not connect to the MCP server with the configured settings.' },
198
+ UNSUPPORTED_PLATFORM: { group: 'local', description: 'The MCP client is not available on this operating system.' },
199
+
200
+ // ── Generic ──
201
+ COMMAND_ERROR: { group: 'generic', description: 'A command failed without a more specific code.' },
202
+ UNKNOWN: { group: 'generic', description: 'An unexpected error with no code. Report it with the message.' },
203
+ };
204
+
205
+ /**
206
+ * Codes that `details.errors[].code` can carry. They are the API's own
207
+ * field-level codes (https://docs.nansen.ai/getting-started/error-handling),
208
+ * reused for the CLI's local checks so one bad field reads the same on every
209
+ * surface.
210
+ */
211
+ export const FIELD_ERROR_CODES = {
212
+ missing_field: 'A required field or option is missing.',
213
+ unknown_field: 'The field or option is not recognized. The message suggests the closest valid name.',
214
+ 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).',
215
+ invalid_address_format: 'The address does not match the chain\'s format.',
216
+ invalid_date_format: 'The date is not a valid YYYY-MM-DD date.',
217
+ invalid_date_range: 'The date range is not allowed.',
218
+ mutually_exclusive_fields: 'Two fields that cannot be combined were both given.',
219
+ value_out_of_range: 'The value is outside the allowed range.',
220
+ too_many_items: 'The list has more items than allowed.',
221
+ };
222
+
223
+ /** Code name -> code string, for `ErrorCode.X` references. */
224
+ export const ErrorCode = Object.freeze(
225
+ Object.fromEntries(Object.keys(ERROR_CODES).map(code => [code, code])),
226
+ );