nansen-cli 1.44.3 → 1.46.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +112 -0
- package/README.md +33 -5
- package/package.json +1 -1
- package/skills/nansen-trading/SKILL.md +20 -1
- package/skills/nansen-wallet-clustering/REFERENCE.md +14 -2
- package/skills/nansen-wallet-clustering/SKILL.md +5 -0
- package/skills/nansen-wallet-keychain-migration/SKILL.md +18 -13
- package/skills/nansen-wallet-manager/SKILL.md +15 -1
- package/skills/nansen-wallet-profiler/SKILL.md +12 -0
- package/src/api.js +283 -34
- package/src/bridge.js +187 -68
- package/src/chain-ids.js +1 -2
- package/src/cli.js +597 -187
- package/src/commands/agent.js +5 -2
- package/src/commands/alerts.js +53 -43
- package/src/commands/mcp.js +8 -2
- package/src/commands/research.js +12 -3
- package/src/cost-cache.js +9 -1
- package/src/ens.js +3 -1
- package/src/execute-guard.js +116 -0
- package/src/limit-order.js +19 -1
- package/src/perp.js +20 -9
- package/src/query-options.js +65 -4
- package/src/response-meta.js +1 -1
- package/src/schema.json +226 -56
- package/src/trading.js +564 -18
- package/src/transfer.js +22 -3
- package/src/update-check.js +9 -3
- package/src/wallet.js +137 -3
- package/src/walletconnect-trading.js +5 -3
- package/src/walletconnect-x402.js +9 -5
package/src/api.js
CHANGED
|
@@ -8,7 +8,7 @@ import path from 'path';
|
|
|
8
8
|
import { fileURLToPath } from 'url';
|
|
9
9
|
import { EVM_CHAINS } from './chain-ids.js';
|
|
10
10
|
import { getAnonymousId, TELEMETRY_DISABLED } from './telemetry.js';
|
|
11
|
-
import { readResponseMeta } from './response-meta.js';
|
|
11
|
+
import { readResponseMeta, stringHeader } from './response-meta.js';
|
|
12
12
|
|
|
13
13
|
/**
|
|
14
14
|
* Key for the credit/rate-limit metadata attached to a successful response.
|
|
@@ -50,6 +50,8 @@ export const ErrorCode = {
|
|
|
50
50
|
UNAUTHORIZED: 'UNAUTHORIZED', // 401 - Invalid or missing API key
|
|
51
51
|
FORBIDDEN: 'FORBIDDEN', // 403 - Valid key but insufficient permissions
|
|
52
52
|
CREDITS_EXHAUSTED: 'CREDITS_EXHAUSTED', // 403 - Insufficient API credits
|
|
53
|
+
PLAN_UPGRADE_REQUIRED: 'PLAN_UPGRADE_REQUIRED', // 403 - Feature needs a higher subscription plan
|
|
54
|
+
GEO_BLOCKED: 'GEO_BLOCKED', // 451 - Not available in the caller's region
|
|
53
55
|
PAYMENT_REQUIRED: 'PAYMENT_REQUIRED', // 402 - x402 payment required
|
|
54
56
|
|
|
55
57
|
// Rate Limiting
|
|
@@ -62,11 +64,15 @@ export const ErrorCode = {
|
|
|
62
64
|
INVALID_PARAMS: 'INVALID_PARAMS', // Generic parameter validation error
|
|
63
65
|
MISSING_PARAM: 'MISSING_PARAM', // Required parameter not provided
|
|
64
66
|
UNSUPPORTED_FILTER: 'UNSUPPORTED_FILTER', // Filter not supported for this token/chain
|
|
67
|
+
QUERY_TOO_LARGE: 'QUERY_TOO_LARGE', // Query would return too much data - narrow it; retrying will not help
|
|
68
|
+
PAYLOAD_TOO_LARGE: 'PAYLOAD_TOO_LARGE', // 413 - Request body exceeds the size limit
|
|
65
69
|
|
|
66
70
|
// Resource Errors
|
|
67
71
|
NOT_FOUND: 'NOT_FOUND', // 404 - Resource not found
|
|
68
72
|
TOKEN_NOT_FOUND: 'TOKEN_NOT_FOUND', // Token doesn't exist
|
|
69
73
|
ADDRESS_NOT_FOUND: 'ADDRESS_NOT_FOUND', // Address has no data
|
|
74
|
+
METHOD_NOT_ALLOWED: 'METHOD_NOT_ALLOWED', // 405 - HTTP method not allowed for this endpoint
|
|
75
|
+
CONFLICT: 'CONFLICT', // 409 - Request conflicts with the current state
|
|
70
76
|
|
|
71
77
|
// Server Errors
|
|
72
78
|
SERVER_ERROR: 'SERVER_ERROR', // 500+ - Nansen API internal error
|
|
@@ -96,8 +102,8 @@ export const ErrorCode = {
|
|
|
96
102
|
* parse (e.g. PASSWORD_REQUIRED, API_KEY_REQUIRED).
|
|
97
103
|
*/
|
|
98
104
|
export class CommandError extends Error {
|
|
99
|
-
constructor(message, code = 'COMMAND_ERROR', data = null) {
|
|
100
|
-
super(message);
|
|
105
|
+
constructor(message, code = 'COMMAND_ERROR', data = null, options = undefined) {
|
|
106
|
+
super(message, options); // options.cause keeps the originating error attached
|
|
101
107
|
this.name = 'CommandError';
|
|
102
108
|
this.code = code;
|
|
103
109
|
this.data = data;
|
|
@@ -127,16 +133,46 @@ export class NansenError extends Error {
|
|
|
127
133
|
}
|
|
128
134
|
|
|
129
135
|
/**
|
|
130
|
-
* Stable snake_case codes the
|
|
136
|
+
* Stable snake_case codes the API sends in error bodies, mapped to the
|
|
131
137
|
* ErrorCode values downstream consumers already key on.
|
|
138
|
+
*
|
|
139
|
+
* Every code documented at
|
|
140
|
+
* https://docs.nansen.ai/getting-started/error-handling has an entry here, so
|
|
141
|
+
* friendly messages and agent-facing hints engage for each of them. A code
|
|
142
|
+
* missing from this map passes through statusToErrorCode verbatim; keep the
|
|
143
|
+
* table in step with that page when the API adds a code.
|
|
132
144
|
*/
|
|
133
|
-
const SERVER_CODE_MAP = {
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
145
|
+
export const SERVER_CODE_MAP = {
|
|
146
|
+
// Request validation (400 / 422)
|
|
147
|
+
missing_field: ErrorCode.MISSING_PARAM,
|
|
148
|
+
unknown_field: ErrorCode.INVALID_PARAMS,
|
|
149
|
+
invalid_field_value: ErrorCode.INVALID_PARAMS,
|
|
150
|
+
invalid_address_format: ErrorCode.INVALID_ADDRESS,
|
|
151
|
+
invalid_date_format: ErrorCode.INVALID_PARAMS,
|
|
152
|
+
invalid_date_range: ErrorCode.INVALID_PARAMS,
|
|
153
|
+
mutually_exclusive_fields: ErrorCode.INVALID_PARAMS,
|
|
154
|
+
value_out_of_range: ErrorCode.INVALID_PARAMS,
|
|
155
|
+
too_many_items: ErrorCode.INVALID_PARAMS,
|
|
156
|
+
// Authentication, authorization, quota
|
|
157
|
+
unauthenticated: ErrorCode.UNAUTHORIZED,
|
|
138
158
|
forbidden: ErrorCode.FORBIDDEN,
|
|
159
|
+
geo_blocked: ErrorCode.GEO_BLOCKED,
|
|
160
|
+
plan_upgrade_required: ErrorCode.PLAN_UPGRADE_REQUIRED,
|
|
161
|
+
insufficient_credits: ErrorCode.CREDITS_EXHAUSTED,
|
|
162
|
+
rate_limit_exceeded: ErrorCode.RATE_LIMITED,
|
|
163
|
+
// Resource and request shape
|
|
139
164
|
not_found: ErrorCode.NOT_FOUND,
|
|
165
|
+
method_not_allowed: ErrorCode.METHOD_NOT_ALLOWED,
|
|
166
|
+
conflict: ErrorCode.CONFLICT,
|
|
167
|
+
payload_too_large: ErrorCode.PAYLOAD_TOO_LARGE,
|
|
168
|
+
// Server side
|
|
169
|
+
query_timeout: ErrorCode.TIMEOUT,
|
|
170
|
+
query_too_large: ErrorCode.QUERY_TOO_LARGE,
|
|
171
|
+
upstream_unavailable: ErrorCode.SERVICE_UNAVAILABLE,
|
|
172
|
+
internal_error: ErrorCode.SERVER_ERROR,
|
|
173
|
+
// Aliases from earlier error-body shapes, kept so older responses still map.
|
|
174
|
+
unauthorized: ErrorCode.UNAUTHORIZED,
|
|
175
|
+
payment_required: ErrorCode.PAYMENT_REQUIRED,
|
|
140
176
|
unsupported_filter: ErrorCode.UNSUPPORTED_FILTER,
|
|
141
177
|
validation_error: ErrorCode.INVALID_PARAMS,
|
|
142
178
|
invalid_params: ErrorCode.INVALID_PARAMS,
|
|
@@ -183,8 +219,18 @@ export function statusToErrorCode(status, data = {}) {
|
|
|
183
219
|
if (messageLower.includes('token')) return ErrorCode.TOKEN_NOT_FOUND;
|
|
184
220
|
if (messageLower.includes('address') || messageLower.includes('wallet')) return ErrorCode.ADDRESS_NOT_FOUND;
|
|
185
221
|
return ErrorCode.NOT_FOUND;
|
|
222
|
+
case 405:
|
|
223
|
+
return ErrorCode.METHOD_NOT_ALLOWED;
|
|
224
|
+
case 408:
|
|
225
|
+
return ErrorCode.TIMEOUT;
|
|
226
|
+
case 409:
|
|
227
|
+
return ErrorCode.CONFLICT;
|
|
228
|
+
case 413:
|
|
229
|
+
return ErrorCode.PAYLOAD_TOO_LARGE;
|
|
186
230
|
case 429:
|
|
187
231
|
return ErrorCode.RATE_LIMITED;
|
|
232
|
+
case 451:
|
|
233
|
+
return ErrorCode.GEO_BLOCKED;
|
|
188
234
|
case 500:
|
|
189
235
|
case 502:
|
|
190
236
|
return ErrorCode.SERVER_ERROR;
|
|
@@ -386,6 +432,79 @@ const ADDRESS_PATTERNS = {
|
|
|
386
432
|
bitcoin: /^(1|3|bc1)[a-zA-HJ-NP-Z0-9]{25,62}$/,
|
|
387
433
|
};
|
|
388
434
|
|
|
435
|
+
// Server-side limits on the batch counterparties endpoint. Checked client-side so
|
|
436
|
+
// an over-limit request fails with an actionable message instead of a 422.
|
|
437
|
+
export const COUNTERPARTIES_BATCH_MAX_ADDRESSES = 10;
|
|
438
|
+
export const COUNTERPARTIES_BATCH_MAX_DAYS = 90;
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* Chains the batch counterparties endpoint accepts: the upstream `ProfilerChain`
|
|
442
|
+
* enum from https://api.nansen.ai/openapi.json, which is what the request model
|
|
443
|
+
* validates `chain` against. Anything outside it is a 422.
|
|
444
|
+
*
|
|
445
|
+
* Deliberately NOT derived from EVM_CHAINS. That list is this CLI's own
|
|
446
|
+
* address-format/ENS set and omits every non-EVM chain the endpoint does serve
|
|
447
|
+
* (bitcoin, tron, sui, ton, near, ...).
|
|
448
|
+
* Mirrors ADDRESS_COUNTERPARTIES_BATCH_CHAINS on the MCP side (nansen-ra#3550),
|
|
449
|
+
* which additionally drops `arc` and `starknet`; the spec enum is the contract
|
|
450
|
+
* here, so they stay in.
|
|
451
|
+
*/
|
|
452
|
+
export const COUNTERPARTIES_BATCH_CHAINS = [
|
|
453
|
+
'all', 'arbitrum', 'arc', 'avalanche', 'base', 'bitcoin', 'bnb', 'ethereum',
|
|
454
|
+
'hyperevm', 'injective', 'iotaevm', 'linea', 'mantle', 'mantra', 'monad',
|
|
455
|
+
'near', 'optimism', 'plasma', 'polygon', 'robinhood', 'sei', 'solana',
|
|
456
|
+
'sonic', 'starknet', 'sui', 'ton', 'tron',
|
|
457
|
+
];
|
|
458
|
+
|
|
459
|
+
/**
|
|
460
|
+
* A token that is at least shaped like an address: 3-128 chars, no whitespace,
|
|
461
|
+
* alphanumerics plus the separators bech32/NEAR/TON addresses use.
|
|
462
|
+
*
|
|
463
|
+
* COUNTERPARTIES_BATCH_CHAINS admits chains whose address format validateAddress
|
|
464
|
+
* has no pattern for (arc, injective, mantra, near, robinhood, starknet, sui,
|
|
465
|
+
* ton, tron), where it falls through to its permissive "any non-empty string"
|
|
466
|
+
* branch. Accepting those chains must not turn a newline `--file` into a way to
|
|
467
|
+
* post arbitrary lines as `wallet_addresses`, so this is the floor; the API does
|
|
468
|
+
* the real per-chain check. Every valid EVM, Solana and Bitcoin address already
|
|
469
|
+
* satisfies it, so it never fires on a chain that was strictly validated.
|
|
470
|
+
*/
|
|
471
|
+
const ADDRESS_SHAPED = /^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/;
|
|
472
|
+
|
|
473
|
+
/**
|
|
474
|
+
* TON's raw address form: a workchain id, ":", then 64 hex characters —
|
|
475
|
+
* `0:` for the basechain, `-1:` for the masterchain. Both the ":" and the
|
|
476
|
+
* leading "-" fail ADDRESS_SHAPED, so raw TON addresses were rejected with a
|
|
477
|
+
* misleading error even though the endpoint serves them. Matched exactly here
|
|
478
|
+
* rather than by adding ":" to ADDRESS_SHAPED, which would put a separator no
|
|
479
|
+
* other supported chain uses back into the floor for every chain. Friendly
|
|
480
|
+
* (base64url) TON addresses already clear ADDRESS_SHAPED.
|
|
481
|
+
*/
|
|
482
|
+
const TON_RAW_ADDRESS = /^-?\d{1,10}:[0-9a-fA-F]{64}$/;
|
|
483
|
+
|
|
484
|
+
/** Whether an address clears the shape floor for `chain`. */
|
|
485
|
+
function isAddressShaped(address, chain) {
|
|
486
|
+
if (ADDRESS_SHAPED.test(address)) return true;
|
|
487
|
+
return chain === 'ton' && TON_RAW_ADDRESS.test(address);
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
/**
|
|
491
|
+
* Resolve a caller-supplied chain to the spelling the batch endpoint accepts,
|
|
492
|
+
* or throw. `bsc` is the common spelling and the one the API echoes back in
|
|
493
|
+
* responses, but the request enum only knows `bnb` — normalise rather than
|
|
494
|
+
* reject, matching the MCP tool.
|
|
495
|
+
*/
|
|
496
|
+
function resolveCounterpartiesBatchChain(chain) {
|
|
497
|
+
const lowered = String(chain ?? '').trim().toLowerCase();
|
|
498
|
+
const resolved = lowered === 'bsc' ? 'bnb' : lowered;
|
|
499
|
+
if (!COUNTERPARTIES_BATCH_CHAINS.includes(resolved)) {
|
|
500
|
+
throw new NansenError(
|
|
501
|
+
`Unsupported chain "${chain}" for batch counterparties. Supported chains: ${COUNTERPARTIES_BATCH_CHAINS.join(', ')}.`,
|
|
502
|
+
ErrorCode.INVALID_PARAMS
|
|
503
|
+
);
|
|
504
|
+
}
|
|
505
|
+
return resolved;
|
|
506
|
+
}
|
|
507
|
+
|
|
389
508
|
/**
|
|
390
509
|
* Validate address format for a given chain
|
|
391
510
|
* @param {string} address - The address to validate
|
|
@@ -442,7 +561,7 @@ export function validateTokenAddress(tokenAddress, chain = 'solana') {
|
|
|
442
561
|
*/
|
|
443
562
|
function requireValidAddress(address, chain) {
|
|
444
563
|
const v = validateAddress(address, chain);
|
|
445
|
-
if (!v.valid) throw new NansenError(v.error
|
|
564
|
+
if (!v.valid) throw new NansenError(`Invalid address "${address}" for chain "${chain}": ${v.error}`, v.code);
|
|
446
565
|
}
|
|
447
566
|
|
|
448
567
|
/**
|
|
@@ -453,6 +572,20 @@ function requireValidToken(tokenAddress, chain) {
|
|
|
453
572
|
if (!v.valid) throw new NansenError(v.error, v.code);
|
|
454
573
|
}
|
|
455
574
|
|
|
575
|
+
/**
|
|
576
|
+
* Which ecosystem chain 'all' would route this address to, or throw if neither.
|
|
577
|
+
* validateAddress's unknown-chain branch accepts any non-empty string for 'all',
|
|
578
|
+
* so classify against the concrete formats instead.
|
|
579
|
+
*/
|
|
580
|
+
function classifyAutoDetectedAddress(address) {
|
|
581
|
+
if (validateAddress(address, 'ethereum').valid) return 'EVM';
|
|
582
|
+
if (validateAddress(address, 'solana').valid) return 'Solana';
|
|
583
|
+
throw new NansenError(
|
|
584
|
+
`Invalid address format: "${address}". With chain "all" every address must be a valid EVM address (0x followed by 40 hex characters) or Solana address (Base58, 32-44 chars).`,
|
|
585
|
+
ErrorCode.INVALID_ADDRESS
|
|
586
|
+
);
|
|
587
|
+
}
|
|
588
|
+
|
|
456
589
|
export function loadConfig() {
|
|
457
590
|
// Base config from files, then env vars override individual fields
|
|
458
591
|
let config = null;
|
|
@@ -498,9 +631,35 @@ const DEFAULT_RETRY_OPTIONS = {
|
|
|
498
631
|
maxRetries: 3,
|
|
499
632
|
baseDelayMs: 1000,
|
|
500
633
|
maxDelayMs: 30000,
|
|
634
|
+
// Longest server Retry-After we are willing to wait out. A longer one is not
|
|
635
|
+
// retried at all: retrying earlier than the server asked only burns the
|
|
636
|
+
// remaining attempts on more 429s.
|
|
637
|
+
maxRetryAfterMs: 120000,
|
|
501
638
|
retryOnStatus: [429, 500, 502, 503, 504],
|
|
502
639
|
};
|
|
503
640
|
|
|
641
|
+
/**
|
|
642
|
+
* Read a response body once. A fetch body can only be consumed once, and
|
|
643
|
+
* response.json() consumes it even when parsing fails, so a body the server
|
|
644
|
+
* declares as non-JSON (gateway HTML, plain text) is read as text first. It
|
|
645
|
+
* is still parsed as JSON when it turns out to be JSON; otherwise the thrown
|
|
646
|
+
* error carries the text so the caller can report it.
|
|
647
|
+
*/
|
|
648
|
+
async function readBody(response) {
|
|
649
|
+
const contentType = stringHeader(response, 'content-type');
|
|
650
|
+
if (contentType && !/json/i.test(contentType)) {
|
|
651
|
+
const rawBody = await response.text();
|
|
652
|
+
try {
|
|
653
|
+
return JSON.parse(rawBody);
|
|
654
|
+
} catch (_err) {
|
|
655
|
+
const error = new Error('Response body is not JSON');
|
|
656
|
+
error.rawBody = rawBody;
|
|
657
|
+
throw error;
|
|
658
|
+
}
|
|
659
|
+
}
|
|
660
|
+
return response.json();
|
|
661
|
+
}
|
|
662
|
+
|
|
504
663
|
/**
|
|
505
664
|
* Sleep for a given number of milliseconds
|
|
506
665
|
*/
|
|
@@ -512,10 +671,12 @@ export function sleep(ms) {
|
|
|
512
671
|
* Calculate delay with exponential backoff and jitter
|
|
513
672
|
*/
|
|
514
673
|
function calculateBackoff(attempt, baseDelayMs, maxDelayMs, retryAfterMs = null) {
|
|
515
|
-
// If server specifies retry-after,
|
|
516
|
-
|
|
674
|
+
// If server specifies retry-after, wait at least that long (plus some jitter).
|
|
675
|
+
// maxDelayMs only bounds the local exponential backoff; the caller decides
|
|
676
|
+
// whether a Retry-After is too long to wait for at all.
|
|
677
|
+
if (retryAfterMs !== null && retryAfterMs !== undefined) {
|
|
517
678
|
const jitter = Math.random() * 1000;
|
|
518
|
-
return
|
|
679
|
+
return retryAfterMs + jitter;
|
|
519
680
|
}
|
|
520
681
|
|
|
521
682
|
// Exponential backoff: base * 2^attempt + random jitter
|
|
@@ -707,7 +868,7 @@ export class NansenAPI {
|
|
|
707
868
|
async request(endpoint, body = {}, options = {}) {
|
|
708
869
|
this.lastEndpoint = endpoint;
|
|
709
870
|
const url = `${this.baseUrl}${endpoint}`;
|
|
710
|
-
const { maxRetries, baseDelayMs, maxDelayMs, retryOnStatus } = this.retryOptions;
|
|
871
|
+
const { maxRetries, baseDelayMs, maxDelayMs, maxRetryAfterMs, retryOnStatus } = this.retryOptions;
|
|
711
872
|
const shouldRetry = options.retry !== false; // Allow disabling retry per-request
|
|
712
873
|
|
|
713
874
|
// Check cache first (if enabled and not bypassed)
|
|
@@ -774,24 +935,31 @@ export class NansenAPI {
|
|
|
774
935
|
|
|
775
936
|
let data;
|
|
776
937
|
try {
|
|
777
|
-
data = await response
|
|
778
|
-
} catch (
|
|
938
|
+
data = await readBody(response);
|
|
939
|
+
} catch (err) {
|
|
779
940
|
// Non-JSON response (rare, usually server errors)
|
|
780
941
|
const meta = readResponseMeta(response);
|
|
781
942
|
this.lastResponseMeta = meta;
|
|
943
|
+
// readBody already holds the text when the server declared a non-JSON
|
|
944
|
+
// body; otherwise try to read it now (null once json() consumed it).
|
|
945
|
+
const rawBody = err?.rawBody ?? await response.text().catch(() => null);
|
|
946
|
+
const retryAfterMs = parseRetryAfter(stringHeader(response, 'retry-after'));
|
|
782
947
|
const error = new NansenError(
|
|
783
948
|
`Invalid response from API (status ${response.status})`,
|
|
784
|
-
response.status
|
|
949
|
+
statusToErrorCode(response.status, {}),
|
|
785
950
|
response.status,
|
|
786
951
|
{
|
|
787
|
-
body:
|
|
952
|
+
body: rawBody,
|
|
788
953
|
attempt: attempt + 1,
|
|
954
|
+
retryAfterMs,
|
|
789
955
|
...(meta?.requestId && { requestId: meta.requestId })
|
|
790
956
|
}
|
|
791
957
|
);
|
|
792
958
|
|
|
793
|
-
|
|
794
|
-
|
|
959
|
+
// Same retry policy as a JSON error body: a rate limiter or gateway
|
|
960
|
+
// that answers in plain text or HTML is still a 429/5xx.
|
|
961
|
+
if (shouldRetry && attempt < maxRetries && retryOnStatus.includes(response.status)) {
|
|
962
|
+
const delayMs = calculateBackoff(attempt, baseDelayMs, maxDelayMs, retryAfterMs);
|
|
795
963
|
await sleep(delayMs);
|
|
796
964
|
lastError = error;
|
|
797
965
|
continue;
|
|
@@ -942,9 +1110,18 @@ export class NansenAPI {
|
|
|
942
1110
|
...(meta?.rateLimit && { rateLimit: meta.rateLimit })
|
|
943
1111
|
});
|
|
944
1112
|
|
|
945
|
-
// Retry on specific status codes
|
|
946
|
-
|
|
947
|
-
|
|
1113
|
+
// Retry on specific status codes. A 429 Retry-After is binding: retrying
|
|
1114
|
+
// earlier only burns attempts on more 429s, so wait it out in full or,
|
|
1115
|
+
// if it is longer than we are willing to block, give up right away (the
|
|
1116
|
+
// error already carries retryAfterMs so the caller can come back later).
|
|
1117
|
+
// A Retry-After on a 5xx is only advisory and keeps the old maxDelayMs cap.
|
|
1118
|
+
const isRateLimit = response.status === 429;
|
|
1119
|
+
if (shouldRetry && attempt < maxRetries && retryOnStatus.includes(response.status)
|
|
1120
|
+
&& !(isRateLimit && retryAfterMs !== null && retryAfterMs > maxRetryAfterMs)) {
|
|
1121
|
+
const serverDelayMs = retryAfterMs === null || isRateLimit
|
|
1122
|
+
? retryAfterMs
|
|
1123
|
+
: Math.min(retryAfterMs, maxDelayMs);
|
|
1124
|
+
const delayMs = calculateBackoff(attempt, baseDelayMs, maxDelayMs, serverDelayMs);
|
|
948
1125
|
await sleep(delayMs);
|
|
949
1126
|
continue;
|
|
950
1127
|
}
|
|
@@ -1228,6 +1405,85 @@ export class NansenAPI {
|
|
|
1228
1405
|
});
|
|
1229
1406
|
}
|
|
1230
1407
|
|
|
1408
|
+
/**
|
|
1409
|
+
* Batch counterparties for up to 10 distinct wallets in one request.
|
|
1410
|
+
* Results are not aggregated: every row carries the `wallet_address` it belongs to.
|
|
1411
|
+
* Defaults to chain 'all' (the ecosystem is auto-detected), matching the CLI.
|
|
1412
|
+
*/
|
|
1413
|
+
async addressCounterpartiesBatch(params = {}) {
|
|
1414
|
+
const { addresses, chain = 'all', filters = {}, orderBy, pagination, days = 30, sourceInput } = params;
|
|
1415
|
+
const resolvedChain = resolveCounterpartiesBatchChain(chain);
|
|
1416
|
+
const list = Array.isArray(addresses) ? addresses : (addresses ? [addresses] : []);
|
|
1417
|
+
// Dedupe on the normalised form, because the server lowercases EVM addresses
|
|
1418
|
+
// before deduping: a checksum-cased repeat must not count twice against the
|
|
1419
|
+
// address limit. Solana (and other case-sensitive) addresses normalise to
|
|
1420
|
+
// themselves. Chain 'all' auto-detects per address, so normalise EVM casing
|
|
1421
|
+
// there too.
|
|
1422
|
+
const normalizeChain = resolvedChain === 'all' ? 'ethereum' : resolvedChain;
|
|
1423
|
+
const walletAddresses = [...new Set(
|
|
1424
|
+
list.map(a => normalizeAddress(String(a).trim(), normalizeChain)).filter(Boolean)
|
|
1425
|
+
)];
|
|
1426
|
+
|
|
1427
|
+
if (walletAddresses.length === 0) {
|
|
1428
|
+
throw new NansenError(
|
|
1429
|
+
'At least one wallet address is required. Pass --addresses "0xabc,0xdef" or --file <path>',
|
|
1430
|
+
ErrorCode.MISSING_PARAM
|
|
1431
|
+
);
|
|
1432
|
+
}
|
|
1433
|
+
if (walletAddresses.length > COUNTERPARTIES_BATCH_MAX_ADDRESSES) {
|
|
1434
|
+
throw new NansenError(
|
|
1435
|
+
`Batch counterparties accepts at most ${COUNTERPARTIES_BATCH_MAX_ADDRESSES} distinct addresses per request, got ${walletAddresses.length}. Split them across several requests.`,
|
|
1436
|
+
ErrorCode.INVALID_PARAMS
|
|
1437
|
+
);
|
|
1438
|
+
}
|
|
1439
|
+
if (!Number.isFinite(days) || days < 1) {
|
|
1440
|
+
throw new NansenError('--days must be a positive number', ErrorCode.INVALID_PARAMS);
|
|
1441
|
+
}
|
|
1442
|
+
if (days > COUNTERPARTIES_BATCH_MAX_DAYS) {
|
|
1443
|
+
throw new NansenError(
|
|
1444
|
+
`Batch counterparties is capped at ${COUNTERPARTIES_BATCH_MAX_DAYS} days, got ${days}. Split the window into several requests, or use the single-wallet counterparties command instead.`,
|
|
1445
|
+
ErrorCode.INVALID_PARAMS
|
|
1446
|
+
);
|
|
1447
|
+
}
|
|
1448
|
+
if (resolvedChain === 'all') {
|
|
1449
|
+
// 'all' routes each address to its own ecosystem, but one request cannot
|
|
1450
|
+
// span both — the server rejects a mixed batch, so fail before sending it.
|
|
1451
|
+
const ecosystems = new Set(walletAddresses.map(classifyAutoDetectedAddress));
|
|
1452
|
+
if (ecosystems.size > 1) {
|
|
1453
|
+
throw new NansenError(
|
|
1454
|
+
"A batch cannot mix EVM and Solana addresses. Query each ecosystem separately; chain='all' auto-detects either ecosystem.",
|
|
1455
|
+
ErrorCode.INVALID_PARAMS
|
|
1456
|
+
);
|
|
1457
|
+
}
|
|
1458
|
+
} else {
|
|
1459
|
+
for (const walletAddress of walletAddresses) {
|
|
1460
|
+
// Strict where this CLI knows the format (EVM, Solana, Bitcoin); a
|
|
1461
|
+
// no-op elsewhere, where the shape floor is all there is.
|
|
1462
|
+
requireValidAddress(walletAddress, resolvedChain);
|
|
1463
|
+
if (!isAddressShaped(walletAddress, resolvedChain)) {
|
|
1464
|
+
const shape = 'an address-shaped token (3-128 characters, letters, digits, ".", "-" or "_")'
|
|
1465
|
+
+ (resolvedChain === 'ton'
|
|
1466
|
+
? ', or a raw TON address (workchain, ":" and 64 hex characters, e.g. "0:" or "-1:")'
|
|
1467
|
+
: '');
|
|
1468
|
+
throw new NansenError(
|
|
1469
|
+
`Invalid address "${walletAddress}" for chain "${resolvedChain}": expected ${shape}. This CLI cannot check ${resolvedChain} address formats, so the API validates the rest.`,
|
|
1470
|
+
ErrorCode.INVALID_ADDRESS
|
|
1471
|
+
);
|
|
1472
|
+
}
|
|
1473
|
+
}
|
|
1474
|
+
}
|
|
1475
|
+
|
|
1476
|
+
return this.request('/api/v1/profiler/address/counterparties/batch', {
|
|
1477
|
+
wallet_addresses: walletAddresses,
|
|
1478
|
+
chain: resolvedChain,
|
|
1479
|
+
date: buildDateRange(days),
|
|
1480
|
+
source_input: sourceInput,
|
|
1481
|
+
filters,
|
|
1482
|
+
order_by: orderBy,
|
|
1483
|
+
pagination
|
|
1484
|
+
});
|
|
1485
|
+
}
|
|
1486
|
+
|
|
1231
1487
|
async addressPnlSummary(params = {}) {
|
|
1232
1488
|
// Note: pnl-summary endpoint is non-paginated (returns aggregate stats, not a list).
|
|
1233
1489
|
// Pagination param intentionally omitted from this request.
|
|
@@ -1679,16 +1935,6 @@ export class NansenAPI {
|
|
|
1679
1935
|
});
|
|
1680
1936
|
}
|
|
1681
1937
|
|
|
1682
|
-
// ============= Points Endpoints =============
|
|
1683
|
-
|
|
1684
|
-
async pointsLeaderboard(params = {}) {
|
|
1685
|
-
const { tier, pagination } = params;
|
|
1686
|
-
return this.request('/api/v1/points/leaderboard', {
|
|
1687
|
-
tier,
|
|
1688
|
-
pagination
|
|
1689
|
-
});
|
|
1690
|
-
}
|
|
1691
|
-
|
|
1692
1938
|
// ============= Portfolio Endpoints =============
|
|
1693
1939
|
|
|
1694
1940
|
async portfolioDefiHoldings(params = {}) {
|
|
@@ -1881,7 +2127,10 @@ export class NansenAPI {
|
|
|
1881
2127
|
}
|
|
1882
2128
|
|
|
1883
2129
|
async alertsUpdate(params = {}) {
|
|
1884
|
-
|
|
2130
|
+
// Same hazard as alertsCreate: an update that sets channels makes the
|
|
2131
|
+
// server re-send the channel welcome message, so a lost response after a
|
|
2132
|
+
// committed update must not resend the PATCH through the retry loop.
|
|
2133
|
+
return this.request('/api/v1/smart-alert', params, { method: 'PATCH', cache: false, retry: false });
|
|
1885
2134
|
}
|
|
1886
2135
|
|
|
1887
2136
|
async alertsToggle(params = {}) {
|