nansen-cli 2.3.0 → 2.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +112 -0
- package/README.md +61 -38
- package/docs/auth.md +56 -0
- package/docs/browser-login.md +101 -7
- package/docs/error-codes.md +251 -0
- package/package.json +10 -4
- package/skills/nansen-agent-guide/SKILL.md +20 -4
- package/skills/nansen-alerts-webhook-listener/SKILL.md +17 -14
- package/skills/nansen-dca-tracker/SKILL.md +1 -1
- package/skills/nansen-defi-positions/SKILL.md +1 -1
- package/skills/nansen-exit-signals/SKILL.md +2 -2
- package/skills/nansen-fund-tracker/SKILL.md +1 -1
- package/skills/nansen-general-search/SKILL.md +1 -1
- package/skills/nansen-holder-analysis/SKILL.md +2 -2
- package/skills/nansen-limit-orders/SKILL.md +9 -1
- package/skills/nansen-mpp-payment/SKILL.md +2 -2
- package/skills/nansen-perp-screener/SKILL.md +1 -1
- package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
- package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
- package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
- package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
- package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
- package/skills/nansen-prediction-markets/SKILL.md +1 -1
- package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
- package/skills/nansen-smart-alerts/SKILL.md +5 -2
- package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
- package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
- package/skills/nansen-smart-money-trend/SKILL.md +1 -1
- package/skills/nansen-token-research/SKILL.md +1 -1
- package/skills/nansen-token-screener/SKILL.md +1 -1
- package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
- package/skills/nansen-trading/SKILL.md +23 -2
- package/skills/nansen-wallet-batch/SKILL.md +1 -1
- package/skills/nansen-wallet-clustering/SKILL.md +1 -1
- package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
- package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
- package/skills/nansen-wallet-manager/SKILL.md +11 -5
- package/skills/nansen-wallet-profiler/SKILL.md +1 -1
- package/skills/nansen-web-fetcher/SKILL.md +1 -1
- package/skills/nansen-web-searcher/SKILL.md +1 -1
- package/src/api-endpoints.json +1605 -0
- package/src/api.js +282 -124
- package/src/auth-credentials.js +1 -0
- package/src/auth-key-input.js +57 -9
- package/src/auth-state.js +2 -2
- package/src/auth-store-native.js +6 -1
- package/src/auth-store-worker.js +1 -1
- package/src/auth-store.js +9 -4
- package/src/auto-paginate.js +25 -7
- package/src/bridge.js +19 -10
- package/src/cache-inspect.js +16 -6
- package/src/cli.js +272 -114
- package/src/commands/agent.js +2 -3
- package/src/commands/alerts.js +365 -18
- package/src/commands/completion.js +4 -1
- package/src/commands/feedback.js +98 -37
- package/src/commands/mcp.js +1 -1
- package/src/commands/research.js +14 -37
- package/src/cost-cache.js +33 -7
- package/src/doctor.js +14 -5
- package/src/ens.js +14 -5
- package/src/error-codes.js +228 -0
- package/src/execute-guard.js +8 -3
- package/src/input-validation.js +555 -0
- package/src/limit-order.js +127 -54
- package/src/perp.js +358 -35
- package/src/privy.js +90 -15
- package/src/query-options.js +47 -8
- package/src/response-cache-files.js +65 -0
- package/src/response-meta.js +8 -2
- package/src/rpc-urls.js +3 -1
- package/src/schema.json +1254 -156
- package/src/solana-tx.js +4 -0
- package/src/telemetry-flags.js +75 -0
- package/src/trade-validation.js +167 -8
- package/src/trading.js +243 -20
- package/src/transfer.js +79 -12
- package/src/update-check.js +32 -5
- package/src/wallet.js +246 -69
- package/src/walletconnect-x402.js +27 -9
package/src/query-options.js
CHANGED
|
@@ -7,28 +7,58 @@
|
|
|
7
7
|
*/
|
|
8
8
|
|
|
9
9
|
import { NansenError, CommandError, ErrorCode } from './api.js';
|
|
10
|
+
import { normalizeFilterAddresses } from './input-validation.js';
|
|
10
11
|
|
|
12
|
+
/**
|
|
13
|
+
* The request `pagination` object for --page/--limit, or undefined when
|
|
14
|
+
* neither is given. Both must be positive whole numbers: --page 0 used to be
|
|
15
|
+
* clamped to 1 silently (API-1081).
|
|
16
|
+
*/
|
|
11
17
|
export function buildPagination(options) {
|
|
12
18
|
if (options.limit === undefined && options.page === undefined) return undefined;
|
|
13
|
-
const
|
|
14
|
-
if (
|
|
15
|
-
|
|
19
|
+
const pagination = { page: 1 };
|
|
20
|
+
if (options.page !== undefined) {
|
|
21
|
+
const page = Number(options.page);
|
|
22
|
+
if (typeof options.page === 'boolean' || String(options.page).trim() === '' || !Number.isSafeInteger(page) || page < 1) {
|
|
23
|
+
throw new NansenError('--page must be a positive integer', ErrorCode.INVALID_PARAMS);
|
|
24
|
+
}
|
|
25
|
+
pagination.page = page;
|
|
26
|
+
}
|
|
27
|
+
if (options.limit !== undefined) {
|
|
28
|
+
const perPage = Number(options.limit);
|
|
29
|
+
if (typeof options.limit === 'boolean' || String(options.limit).trim() === '' || !Number.isSafeInteger(perPage) || perPage < 1) {
|
|
30
|
+
throw new NansenError('--limit must be a positive integer', ErrorCode.INVALID_PARAMS);
|
|
31
|
+
}
|
|
32
|
+
pagination.per_page = perPage;
|
|
16
33
|
}
|
|
17
|
-
return
|
|
18
|
-
page: Math.max(1, parseInt(options.page, 10) || 1),
|
|
19
|
-
per_page: perPage,
|
|
20
|
-
};
|
|
34
|
+
return pagination;
|
|
21
35
|
}
|
|
22
36
|
|
|
23
37
|
// Parse simple sort syntax: "field:direction" or "field" (defaults to DESC)
|
|
24
38
|
export function parseSort(sortOption, orderByOption) {
|
|
25
39
|
// If --order-by is provided, use it (full JSON control)
|
|
26
|
-
if (orderByOption)
|
|
40
|
+
if (orderByOption) {
|
|
41
|
+
const isEntry = e => e !== null && typeof e === 'object' && !Array.isArray(e)
|
|
42
|
+
&& typeof e.field === 'string' && e.field.trim() !== '';
|
|
43
|
+
if (!Array.isArray(orderByOption) || !orderByOption.every(isEntry)) {
|
|
44
|
+
throw new NansenError(
|
|
45
|
+
`--order-by must be a JSON array of {"field", "direction"} objects, e.g. --order-by '[{"field":"value_usd","direction":"DESC"}]'`,
|
|
46
|
+
ErrorCode.INVALID_PARAMS,
|
|
47
|
+
);
|
|
48
|
+
}
|
|
49
|
+
return orderByOption;
|
|
50
|
+
}
|
|
27
51
|
if (!sortOption) return undefined;
|
|
28
52
|
if (typeof sortOption !== 'string') {
|
|
29
53
|
throw new NansenError('--sort must be "field" or "field:direction"', ErrorCode.INVALID_PARAMS);
|
|
30
54
|
}
|
|
31
55
|
const parts = sortOption.split(':');
|
|
56
|
+
if (parts.length > 2) {
|
|
57
|
+
throw new NansenError(
|
|
58
|
+
`--sort must be "field" or "field:direction", got "${sortOption}" (e.g. --sort ${parts[0].trim()}:desc)`,
|
|
59
|
+
ErrorCode.INVALID_PARAMS,
|
|
60
|
+
);
|
|
61
|
+
}
|
|
32
62
|
const field = parts[0].trim();
|
|
33
63
|
const rawDirection = (parts[1] || '').trim();
|
|
34
64
|
const direction = (rawDirection || 'desc').toUpperCase();
|
|
@@ -85,6 +115,15 @@ export function parseObjectOption(val, name) {
|
|
|
85
115
|
return val;
|
|
86
116
|
}
|
|
87
117
|
|
|
118
|
+
/**
|
|
119
|
+
* `--filters '<json>'` as a plain object with every EVM address lowercased.
|
|
120
|
+
* The API stores EVM addresses lowercase, so a checksummed address matched no
|
|
121
|
+
* rows and the command returned an empty success (API-1081).
|
|
122
|
+
*/
|
|
123
|
+
export function parseFiltersOption(val) {
|
|
124
|
+
return normalizeFilterAddresses(parseObjectOption(val, 'filters'));
|
|
125
|
+
}
|
|
126
|
+
|
|
88
127
|
/** Reject explicit blank strings before a handler selects an omitted-option default. */
|
|
89
128
|
export function rejectBlankOption(value, name, example) {
|
|
90
129
|
if (typeof value === 'string' && value.trim() === '') {
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* File-level housekeeping for the response cache directory (~/.nansen/cache),
|
|
3
|
+
* shared by api.js (which writes entries) and cache-inspect.js (which clears
|
|
4
|
+
* them). Imports nothing from either so both can use it without a cycle.
|
|
5
|
+
*
|
|
6
|
+
* Names in the directory:
|
|
7
|
+
* <sha256>.json a cache entry
|
|
8
|
+
* <sha256>.json.<pid>.<uuid>.tmp a write in progress; renamed onto the
|
|
9
|
+
* entry when it completes, so a leftover one
|
|
10
|
+
* means the writing process was killed
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import fs from 'fs';
|
|
14
|
+
import path from 'path';
|
|
15
|
+
|
|
16
|
+
export const RESPONSE_ENTRY = /^[0-9a-f]{64}\.json$/;
|
|
17
|
+
export const RESPONSE_TEMP = /^[0-9a-f]{64}\.json\.\d+\.[0-9a-f-]{36}\.tmp$/;
|
|
18
|
+
|
|
19
|
+
// A write holds its temp file for milliseconds. Anything this old was left by
|
|
20
|
+
// a process that died before the rename.
|
|
21
|
+
export const STALE_TEMP_MS = 10 * 60 * 1000;
|
|
22
|
+
|
|
23
|
+
// Entries are never read back after their TTL (default 300s, set per call with
|
|
24
|
+
// --cache-ttl) and a read does not delete them, so without a sweep, requests
|
|
25
|
+
// that are never repeated leave files behind forever. The sweep after a cache
|
|
26
|
+
// write removes entries older than this, or older than the longest TTL the
|
|
27
|
+
// writing process has read with, whichever is longer.
|
|
28
|
+
export const ENTRY_MAX_AGE_MS = 24 * 60 * 60 * 1000;
|
|
29
|
+
|
|
30
|
+
/** A temp file left behind by a write that never completed. */
|
|
31
|
+
export function isStaleTemp(name, stat, now = Date.now()) {
|
|
32
|
+
return RESPONSE_TEMP.test(name) && now - stat.mtimeMs > STALE_TEMP_MS;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Remove stale temp files and entries older than `retentionMs` (default
|
|
37
|
+
* ENTRY_MAX_AGE_MS) from `dir`.
|
|
38
|
+
* Only regular files whose names match the two shapes above are touched; a
|
|
39
|
+
* symlinked or missing directory and symlinked entries are left alone.
|
|
40
|
+
* Returns how many files were removed.
|
|
41
|
+
*
|
|
42
|
+
* Another process may rename a fresh entry onto a path between the lstat and
|
|
43
|
+
* the unlink. That costs it one cache miss, never wrong data.
|
|
44
|
+
*/
|
|
45
|
+
export function pruneResponseCacheDir(dir, now = Date.now(), retentionMs = ENTRY_MAX_AGE_MS) {
|
|
46
|
+
const dirStat = fs.lstatSync(dir, { throwIfNoEntry: false });
|
|
47
|
+
if (!dirStat || !dirStat.isDirectory()) return 0;
|
|
48
|
+
let removed = 0;
|
|
49
|
+
for (const name of fs.readdirSync(dir)) {
|
|
50
|
+
const isEntry = RESPONSE_ENTRY.test(name);
|
|
51
|
+
if (!isEntry && !RESPONSE_TEMP.test(name)) continue;
|
|
52
|
+
const file = path.join(dir, name);
|
|
53
|
+
const stat = fs.lstatSync(file, { throwIfNoEntry: false });
|
|
54
|
+
if (!stat || !stat.isFile()) continue;
|
|
55
|
+
const stale = isEntry ? now - stat.mtimeMs > retentionMs : isStaleTemp(name, stat, now);
|
|
56
|
+
if (!stale) continue;
|
|
57
|
+
try {
|
|
58
|
+
fs.unlinkSync(file);
|
|
59
|
+
removed += 1;
|
|
60
|
+
} catch (error) {
|
|
61
|
+
if (error?.code !== 'ENOENT') throw error;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
return removed;
|
|
65
|
+
}
|
package/src/response-meta.js
CHANGED
|
@@ -66,6 +66,7 @@ export function readResponseMeta(response) {
|
|
|
66
66
|
const planNotice = stringHeader(response, PLAN_NOTICE);
|
|
67
67
|
const apiKeyNotice = stringHeader(response, API_KEY_NOTICE);
|
|
68
68
|
const requestId = stringHeader(response, REQUEST_ID);
|
|
69
|
+
const warning = stringHeader(response, 'warning');
|
|
69
70
|
|
|
70
71
|
const meta = {};
|
|
71
72
|
if (requestId !== null) {
|
|
@@ -83,8 +84,9 @@ export function readResponseMeta(response) {
|
|
|
83
84
|
// drain — not a wall-clock timestamp.
|
|
84
85
|
meta.rateLimit = { limit, remaining: rateRemaining, resetSeconds };
|
|
85
86
|
}
|
|
86
|
-
if (upgradeHint !== null || planNotice !== null || apiKeyNotice !== null) {
|
|
87
|
+
if (upgradeHint !== null || planNotice !== null || apiKeyNotice !== null || warning !== null) {
|
|
87
88
|
meta.notices = {
|
|
89
|
+
...(warning !== null && { warning }),
|
|
88
90
|
...(upgradeHint !== null && { upgradeHint }),
|
|
89
91
|
...(planNotice !== null && { planNotice }),
|
|
90
92
|
...(apiKeyNotice !== null && { apiKeyNotice }),
|
|
@@ -102,11 +104,13 @@ export function readResponseMeta(response) {
|
|
|
102
104
|
export function aggregatePaginatedResponseMeta(pages) {
|
|
103
105
|
if (!Array.isArray(pages) || pages.length === 0) return null;
|
|
104
106
|
|
|
107
|
+
const warning = [...new Set(pages.map(page => page.meta?.notices?.warning).filter(Boolean))].join(', ');
|
|
105
108
|
const livePages = pages.filter(page => !page.cached);
|
|
106
109
|
const metas = livePages.map(page => page.meta);
|
|
107
110
|
const present = metas.filter(Boolean);
|
|
108
111
|
if (livePages.length === 0) {
|
|
109
112
|
return {
|
|
113
|
+
...(warning && { notices: { warning } }),
|
|
110
114
|
credits: { used: 0, remaining: null, cost: 0 },
|
|
111
115
|
pagination: { pagesFetched: pages.length, livePages: 0, cachedPages: pages.length },
|
|
112
116
|
};
|
|
@@ -134,6 +138,7 @@ export function aggregatePaginatedResponseMeta(pages) {
|
|
|
134
138
|
|
|
135
139
|
const notices = {};
|
|
136
140
|
for (const meta of present) Object.assign(notices, meta.notices || {});
|
|
141
|
+
if (warning) notices.warning = warning;
|
|
137
142
|
if (Object.keys(notices).length > 0) result.notices = notices;
|
|
138
143
|
|
|
139
144
|
result.pagination = {
|
|
@@ -147,12 +152,13 @@ export function aggregatePaginatedResponseMeta(pages) {
|
|
|
147
152
|
/**
|
|
148
153
|
* Yield notice strings for any server-set advisory headers.
|
|
149
154
|
* Each yields a `⚠️ <message>` line for stderr.
|
|
150
|
-
* Order:
|
|
155
|
+
* Order: API warning → apiKeyNotice → upgradeHint → planNotice.
|
|
151
156
|
*/
|
|
152
157
|
export function noticeWarnings(meta) {
|
|
153
158
|
const notices = meta?.notices;
|
|
154
159
|
if (!notices) return [];
|
|
155
160
|
const out = [];
|
|
161
|
+
if (notices.warning) out.push(`⚠️ ${notices.warning}`);
|
|
156
162
|
if (notices.apiKeyNotice) out.push(`⚠️ ${notices.apiKeyNotice}`);
|
|
157
163
|
if (notices.upgradeHint) out.push(`ℹ️ ${notices.upgradeHint}`);
|
|
158
164
|
if (notices.planNotice) out.push(`ℹ️ ${notices.planNotice}`);
|
package/src/rpc-urls.js
CHANGED
|
@@ -37,7 +37,9 @@
|
|
|
37
37
|
* working while new code uses the standardised NANSEN_BASE_RPC name.
|
|
38
38
|
*/
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
// eth.public-rpc.com started requiring an API key (HTTP 403), which broke every
|
|
41
|
+
// `wallet send --chain ethereum|evm` that had no NANSEN_EVM_RPC override.
|
|
42
|
+
const DEFAULT_EVM_RPC = 'https://ethereum-rpc.publicnode.com';
|
|
41
43
|
const DEFAULT_BASE_RPC = 'https://mainnet.base.org';
|
|
42
44
|
const DEFAULT_BSC_RPC = 'https://bsc-dataseed.binance.org';
|
|
43
45
|
const DEFAULT_XLAYER_RPC = 'https://rpc.xlayer.tech';
|