nansen-cli 1.44.2 → 1.45.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 +68 -0
- package/README.md +4 -1
- package/package.json +1 -1
- package/skills/nansen-wallet-clustering/REFERENCE.md +14 -2
- package/skills/nansen-wallet-clustering/SKILL.md +5 -0
- package/skills/nansen-wallet-profiler/SKILL.md +12 -0
- package/src/api.js +168 -11
- package/src/cli.js +286 -96
- package/src/commands/agent.js +65 -37
- package/src/commands/alerts.js +67 -53
- package/src/commands/mcp.js +6 -0
- package/src/commands/research.js +9 -2
- package/src/cost-cache.js +9 -1
- package/src/limit-order.js +10 -0
- package/src/query-options.js +30 -1
- package/src/schema.json +103 -35
- package/src/trade-validation.js +39 -5
- package/src/trading.js +33 -2
- package/src/update-check.js +9 -3
- package/src/wallet.js +4 -0
- package/src/walletconnect-x402.js +28 -38
- package/src/x402-svm.js +53 -12
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,73 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.45.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#624](https://github.com/nansen-ai/nansen-cli/pull/624) [`8bd2f00`](https://github.com/nansen-ai/nansen-cli/commit/8bd2f0057fce09d1fce8c91dd5d2128c3c9ce25d) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `nansen research profiler counterparties-batch` — top counterparties for up to 10 wallets in a single request. Takes `--addresses "0xabc,0xdef"` (comma-separated or a JSON array) or `--file`, validates the 10-address and 90-day limits client-side, and returns rows tagged with the `wallet_address` they belong to (results are not aggregated across wallets). `--chain` defaults to `all`, which auto-detects the ecosystem; one ecosystem per request, as EVM and Solana addresses cannot be mixed.
|
|
8
|
+
|
|
9
|
+
### Patch Changes
|
|
10
|
+
|
|
11
|
+
- [#643](https://github.com/nansen-ai/nansen-cli/pull/643) [`b459772`](https://github.com/nansen-ai/nansen-cli/commit/b4597722c26b95dbd4eedb5b93f8a5dd9042be10) Thanks [@Codier](https://github.com/Codier)! - Ignore failed and malformed OpenAPI responses when refreshing the credit-cost cache. A non-2xx response that still returned JSON replaced the cached cost map with an empty one and stamped it fresh, so credit estimates went missing for up to 24 hours and the next refresh was suppressed.
|
|
12
|
+
|
|
13
|
+
- [#634](https://github.com/nansen-ai/nansen-cli/pull/634) [`a5a3b27`](https://github.com/nansen-ai/nansen-cli/commit/a5a3b27d9f8fe58ba87a37bec24c2cc627d64fda) Thanks [@Bruce039](https://github.com/Bruce039)! - Avoid caching failed or malformed update-check responses as fresh results, so transient registry errors are retried instead of suppressing checks for 24 hours.
|
|
14
|
+
|
|
15
|
+
- [#637](https://github.com/nansen-ai/nansen-cli/pull/637) [`a0f889d`](https://github.com/nansen-ai/nansen-cli/commit/a0f889d02b9b5bcb729ba82a7ad150a2dadc31c9) Thanks [@gulshngill](https://github.com/gulshngill)! - Fix the `--chain` allowlist on `nansen research profiler counterparties-batch`. It was built from the CLI's internal EVM chain list, which disagreed with the endpoint in both directions: `scroll` and `ronin` were accepted and always 422'd upstream, while every non-EVM chain the profiler serves (`bitcoin`, `tron`, `sui`, `ton`, `near`, `injective`, `mantra`, `robinhood`, `arc`, `starknet`) was rejected client-side. The allowlist is now the endpoint's own `ProfilerChain` enum, and `--chain bsc` is accepted and sent as `bnb`. Addresses on a chain whose format the CLI cannot check are still required to be address-shaped, so a newline `--file` cannot post arbitrary lines as wallet addresses; TON accepts both friendly and raw (`0:`/`-1:` plus 64 hex) addresses.
|
|
16
|
+
|
|
17
|
+
- [#645](https://github.com/nansen-ai/nansen-cli/pull/645) [`dda318e`](https://github.com/nansen-ai/nansen-cli/commit/dda318e72812fc567d3abd1c0e8282aa3c367133) Thanks [@gulshngill](https://github.com/gulshngill)! - Declare the `DELETE /api/v1/smart-alert/{alertId}` route the `alerts delete` command already calls in `src/schema.json`. This was the last route in the parity checker's schema-drift list; the sibling routes (list/create/update/toggle/account/web/agent) were declared in #549.
|
|
18
|
+
|
|
19
|
+
- [#640](https://github.com/nansen-ai/nansen-cli/pull/640) [`60961cf`](https://github.com/nansen-ai/nansen-cli/commit/60961cf9bcb828bc85caccb7b55c09b664e46aac) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Fix `parseArgs` treating an explicit empty-string option value (`--flag ""`) as a boolean flag and leaking the `""` into positional arguments. `nansen web fetch <url> --question ""` now reports the blank-question error instead of `Invalid URL: ""`.
|
|
20
|
+
|
|
21
|
+
Register `--all`, `--max`, `--gasless`, `--auto-slippage`, and `--unsafe-no-password` as valueless flags. They are read only as booleans, so a following token such as `nansen perp meta --all` plus an asset name was parsed as their value and the switch went dead.
|
|
22
|
+
|
|
23
|
+
Reject a blank `nansen mcp verify --url ""` instead of falling back to the default Nansen endpoint, which reported the default URL as verified when the caller passed an unset shell variable.
|
|
24
|
+
|
|
25
|
+
Reject a blank `--slippage` or `--max-auto-slippage` on `nansen trade quote`. An empty string became `0` in the range check, satisfied the rule that `--swap-mode exactOut --auto-slippage` needs an explicit cap, and was then dropped when the request was built, so the ERC-20 approval was scoped by a cap that never reached the server.
|
|
26
|
+
|
|
27
|
+
Reject a blank `nansen web fetch --url ""` instead of dropping it and fetching only the positional URLs.
|
|
28
|
+
|
|
29
|
+
- [#644](https://github.com/nansen-ai/nansen-cli/pull/644) [`14bbd9b`](https://github.com/nansen-ai/nansen-cli/commit/14bbd9b273a570953d02900acb21aeed81ac1bfe) Thanks [@hulk-linus](https://github.com/apps/hulk-linus)! - Reject explicitly blank quote options, execute and limit-order wallet selectors, limit-order expiry and list options, wallet creation names and send options, and research chain/timeframe, days, buy-or-sell, and profiler batch/trace tuning options with an actionable error instead of selecting defaults. Preserve numeric zero slippage caps in programmatic quote requests.
|
|
30
|
+
|
|
31
|
+
- [#542](https://github.com/nansen-ai/nansen-cli/pull/542) [`055488a`](https://github.com/nansen-ai/nansen-cli/commit/055488a1b9a9a85994b12af0245e3a9139b8238f) Thanks [@gulshngill](https://github.com/gulshngill)! - Stop calling the removed points leaderboard API route. Both `points leaderboard` and `research points leaderboard` now return a structured unavailable error and exit with a failure status, without suggesting the other unavailable command as a replacement.
|
|
32
|
+
|
|
33
|
+
- [#549](https://github.com/nansen-ai/nansen-cli/pull/549) [`28714c6`](https://github.com/nansen-ai/nansen-cli/commit/28714c6a2f89fbd8965e84916e9f185883b3cd27) Thanks [@gulshngill](https://github.com/gulshngill)! - Declare the API routes `alerts`, `account`, `web` and `agent` already call in `src/schema.json`. The schema is what shell completions, `--help` and docs tooling read, so eight routes the code requests were invisible to them (and to the API/MCP/CLI parity check).
|
|
34
|
+
|
|
35
|
+
- [#647](https://github.com/nansen-ai/nansen-cli/pull/647) [`2b84502`](https://github.com/nansen-ai/nansen-cli/commit/2b8450254515a2e0aa1b3e973332a2362a85f8ea) Thanks [@kome12](https://github.com/kome12)! - Reject invalid profiler trace width values instead of returning an empty-looking trace.
|
|
36
|
+
|
|
37
|
+
- [#642](https://github.com/nansen-ai/nansen-cli/pull/642) [`b6c928f`](https://github.com/nansen-ai/nansen-cli/commit/b6c928fc458a216aff3ac1f4961f8aaf4a02eceb) Thanks [@kome12](https://github.com/kome12)! - Validate `nansen alerts` string/array options (`--chains`, `--token`/`--exclude-token`, `--subject`/`--counterparty`/`--caller`/`--contract` and their `--exclude-*` variants, `--events`, `--signature-hash`, `--token-sector`/`--exclude-token-sector`, and `alerts list --token-address`/`--chain`) so JSON primitives (e.g. `--chains true`) produce actionable `INVALID_PARAMS` errors instead of a raw `TypeError` crash or being silently dropped/passed through into the alert payload.
|
|
38
|
+
|
|
39
|
+
- [#630](https://github.com/nansen-ai/nansen-cli/pull/630) [`7cb8bb2`](https://github.com/nansen-ai/nansen-cli/commit/7cb8bb2ecd4cd2e1a302b43de73ef2b015dc42d6) Thanks [@kriss39](https://github.com/kriss39)! - Validate supported analytics `--days` values as non-negative integers with a representable date range instead of truncating malformed inputs or forwarding `NaN`.
|
|
40
|
+
|
|
41
|
+
- [#639](https://github.com/nansen-ai/nansen-cli/pull/639) [`17e4f64`](https://github.com/nansen-ai/nansen-cli/commit/17e4f648412057c0012cd5ea464be10363be893e) Thanks [@kome12](https://github.com/kome12)! - Validate more CLI string options (`profiler batch --include`, `perp screener --sectors-filter`/`--sm-label-filter`/`--trader-label-filter`, `prediction-market market-screener`/`event-screener --tags`, and `--fields`) so JSON primitives produce actionable `INVALID_PARAMS` errors instead of raw `.split()`/`.trim()` TypeErrors.
|
|
42
|
+
|
|
43
|
+
- [#632](https://github.com/nansen-ai/nansen-cli/pull/632) [`d9c7e6e`](https://github.com/nansen-ai/nansen-cli/commit/d9c7e6e6ea9615ee9534cafc960d54a2dadc0160) Thanks [@Bruce039](https://github.com/Bruce039)! - Reject malformed or valueless `--date` inputs instead of silently falling back to the rolling `--days` range.
|
|
44
|
+
|
|
45
|
+
- [#631](https://github.com/nansen-ai/nansen-cli/pull/631) [`17cbed5`](https://github.com/nansen-ai/nansen-cli/commit/17cbed5e8a286ebebaefe893ee6a0198188ff379) Thanks [@Bruce039](https://github.com/Bruce039)! - Reject malformed and non-finite prediction-market screener numeric filters before they can be serialized as `null` or silently ignored.
|
|
46
|
+
|
|
47
|
+
- [#629](https://github.com/nansen-ai/nansen-cli/pull/629) [`b802bca`](https://github.com/nansen-ai/nansen-cli/commit/b802bca7ad5352ba03226fdbc64e97a3f4496d03) Thanks [@kriss39](https://github.com/kriss39)! - Reject malformed, fractional, non-finite, repeated, or valueless `profiler trace --depth` inputs while preserving the existing 1-5 clamping behavior for valid integers.
|
|
48
|
+
|
|
49
|
+
- [#633](https://github.com/nansen-ai/nansen-cli/pull/633) [`901f63e`](https://github.com/nansen-ai/nansen-cli/commit/901f63e522cdbbf773f055d928a415f99d02bf94) Thanks [@Bruce039](https://github.com/Bruce039)! - Validate web `--query` and `--question` option types so JSON primitives produce actionable CLI errors instead of raw `.trim()` TypeErrors.
|
|
50
|
+
|
|
51
|
+
## 1.44.3
|
|
52
|
+
|
|
53
|
+
### Patch Changes
|
|
54
|
+
|
|
55
|
+
- [#621](https://github.com/nansen-ai/nansen-cli/pull/621) [`6ece0a1`](https://github.com/nansen-ai/nansen-cli/commit/6ece0a14290444472f0784115e678e73deb3981f) Thanks [@kome12](https://github.com/kome12)! - Validate alerts list pagination flags before fetching alerts.
|
|
56
|
+
|
|
57
|
+
- [#620](https://github.com/nansen-ai/nansen-cli/pull/620) [`bf8f40f`](https://github.com/nansen-ai/nansen-cli/commit/bf8f40f840495d7a92d95d105d131b5406a10e22) Thanks [@Radovenchyk](https://github.com/Radovenchyk)! - Fix `nansen agent` throwing a raw `AbortError` instead of a `NansenError(TIMEOUT)` when the request timeout fires while reading the SSE response body (as opposed to during the initial connection). Both streaming and `--json` output modes now report a consistent timeout error regardless of which phase of the request the abort happened in.
|
|
58
|
+
|
|
59
|
+
- [#618](https://github.com/nansen-ai/nansen-cli/pull/618) [`1e08a15`](https://github.com/nansen-ai/nansen-cli/commit/1e08a150295b44768ce954b9628de10e291924f4) Thanks [@Radovenchyk](https://github.com/Radovenchyk)! - Fix `consumeSSEStream` silently dropping the final SSE event when the stream closes without a trailing blank line (e.g. a `finish` event carrying `conversation_id`, or a trailing `delta` chunk).
|
|
60
|
+
|
|
61
|
+
- [#623](https://github.com/nansen-ai/nansen-cli/pull/623) [`9ae1dc2`](https://github.com/nansen-ai/nansen-cli/commit/9ae1dc2d871b04fae749c7126f970258bf58f41e) Thanks [@kome12](https://github.com/kome12)! - Improve Solana raw-instruction bridge error handling for RPC failures and malformed instruction data.
|
|
62
|
+
|
|
63
|
+
- [#622](https://github.com/nansen-ai/nansen-cli/pull/622) [`d86aae9`](https://github.com/nansen-ai/nansen-cli/commit/d86aae9e8d45d0427fbc0d51363529b5873d8dd0) Thanks [@kome12](https://github.com/kome12)! - Tolerate small refunded native input amounts during bridge outcome verification.
|
|
64
|
+
|
|
65
|
+
- [#617](https://github.com/nansen-ai/nansen-cli/pull/617) [`d048c0f`](https://github.com/nansen-ai/nansen-cli/commit/d048c0f3bb4e5ded6c42324ec7d3e32b58bfd4ee) Thanks [@teyrebaz33](https://github.com/teyrebaz33)! - Fix x402 auto-payment via WalletConnect signing a payment authorization from any connected EVM account instead of verifying the WalletConnect session is actually approved for the payment's chain.
|
|
66
|
+
|
|
67
|
+
`handleX402Payment` resolved its signer with its own `checkWalletConnection()` helper and took `wallet.accounts[0]?.address` with no chain filtering at all -- the same defect class fixed in `getWalletConnectAddress` for `nansen transfer`/`nansen trade execute` (see the WalletConnect chain-scoped signing fix), just left unguarded here because this path never reused that helper. Because EVM addresses are identical across chains, a WalletConnect session approved only for, say, Base could be silently used to authorize an x402 payment on BNB Smart Chain or X Layer -- the other two EVM networks Nansen's x402 payments support.
|
|
68
|
+
|
|
69
|
+
`handleX402Payment` now resolves its signer via `getWalletConnectAddress('evm', chainId)`, scoped to the exact chain of the selected payment requirement, and refuses to pay with a clear error when no WalletConnect session is approved for that chain. The now-unused, duplicate `checkWalletConnection` helper was removed.
|
|
70
|
+
|
|
3
71
|
## 1.44.2
|
|
4
72
|
|
|
5
73
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -55,7 +55,9 @@ nansen completion <bash|zsh|fish> # shell completions (no API key needed)
|
|
|
55
55
|
nansen schema [command] [--pretty] # full command reference (no API key needed)
|
|
56
56
|
```
|
|
57
57
|
|
|
58
|
-
**Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp
|
|
58
|
+
**Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`
|
|
59
|
+
|
|
60
|
+
The points leaderboard API has been removed. `nansen research points leaderboard` and the legacy command `nansen points leaderboard` return `success: false` with code `COMMAND_UNAVAILABLE` and exit status `1`, without making an API request.
|
|
59
61
|
|
|
60
62
|
**Direct research subcommands:**
|
|
61
63
|
- `nansen research chain-rank [--timeframe-days 7|30|365] [--chain-type all|evm]` — rank chains by growth metrics
|
|
@@ -335,6 +337,7 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
|
|
|
335
337
|
| `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
|
|
336
338
|
| `UNSUPPORTED_FILTER` | Remove the filter and retry. |
|
|
337
339
|
| `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
|
|
340
|
+
| `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
|
|
338
341
|
|
|
339
342
|
**Error metadata.** When the API reports them, `details` carries:
|
|
340
343
|
|
package/package.json
CHANGED
|
@@ -28,7 +28,19 @@ On confirm, re-run steps 1-2 on it. Reserve step 3 (counterparties) for the seed
|
|
|
28
28
|
|
|
29
29
|
## L2 Coverage
|
|
30
30
|
|
|
31
|
-
When step 3 returns sparse results on a mainnet EVM address, extend to L2s
|
|
31
|
+
When step 3 returns sparse results on a mainnet EVM address, extend to L2s. `--chain all`
|
|
32
|
+
detects each address's chain and covers the EVM chains in a single call, and takes up to
|
|
33
|
+
10 addresses at once (every row carries the wallet_address it belongs to):
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
nansen research profiler counterparties-batch --addresses "$ADDR" --chain all --days 90 --limit 50
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Rows come back as contiguous per-wallet blocks ordered by wallet address, so with several
|
|
40
|
+
addresses a small page holds one wallet only — raise `--limit` and page with `--page N`.
|
|
41
|
+
|
|
42
|
+
`counterparties-batch` is capped at 90 days. For a wider window, fall back to the
|
|
43
|
+
per-chain loop:
|
|
32
44
|
|
|
33
45
|
```bash
|
|
34
46
|
for CHAIN in base arbitrum optimism polygon; do
|
|
@@ -39,5 +51,5 @@ done
|
|
|
39
51
|
## Cost Warnings
|
|
40
52
|
|
|
41
53
|
- `trace` is credit-heavy; keep `--width 3` or lower
|
|
42
|
-
- L2
|
|
54
|
+
- The per-chain L2 loop above costs 4 API calls per address; `counterparties-batch --chain all` is 1
|
|
43
55
|
- Historical balances reveal past holdings on drained wallets — useful fingerprint
|
|
@@ -30,6 +30,11 @@ nansen research profiler labels --address $ADDR --chain $CHAIN
|
|
|
30
30
|
nansen research profiler related-wallets --address $ADDR --chain $CHAIN
|
|
31
31
|
# 3. Counterparties (paginate with --page N; widen with --days 365 if empty)
|
|
32
32
|
nansen research profiler counterparties --address $ADDR --chain $CHAIN --days 90
|
|
33
|
+
# 3b. Once a cluster is confirmed: counterparties for up to 10 of its wallets in one call
|
|
34
|
+
# (max --days 90; one ecosystem per request — EVM and Solana cannot be mixed). Rows are
|
|
35
|
+
# contiguous per-wallet blocks ordered by wallet address: raise --limit and page with
|
|
36
|
+
# --page N to reach later wallets.
|
|
37
|
+
nansen research profiler counterparties-batch --addresses "addr1,addr2" --chain $CHAIN --days 90 --limit 50
|
|
33
38
|
# 4. Batch profile cluster
|
|
34
39
|
nansen research profiler batch --addresses "addr1,addr2" --chain $CHAIN --include labels,balance,pnl
|
|
35
40
|
# 5. Compare pairs → shared_counterparties, shared_tokens, balances
|
|
@@ -49,6 +49,17 @@ nansen research profiler historical-balances --address <addr> --chain solana --d
|
|
|
49
49
|
```bash
|
|
50
50
|
nansen research profiler related-wallets --address <addr> --chain ethereum
|
|
51
51
|
nansen research profiler counterparties --address <addr> --chain ethereum --days 30
|
|
52
|
+
|
|
53
|
+
# Counterparties for up to 10 wallets in one call (max --days 90).
|
|
54
|
+
# Results are not aggregated — every row carries the wallet_address it belongs to.
|
|
55
|
+
# One ecosystem per request: EVM and Solana addresses cannot be mixed; `all` auto-detects it.
|
|
56
|
+
# --chain also takes any single chain the profiler serves, EVM or not: arbitrum, arc,
|
|
57
|
+
# avalanche, base, bitcoin, bnb (`bsc` is accepted too), ethereum, hyperevm, injective,
|
|
58
|
+
# iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, sei,
|
|
59
|
+
# solana, sonic, starknet, sui, ton, tron.
|
|
60
|
+
# Rows come back as contiguous per-wallet blocks ordered by wallet address, so a small page
|
|
61
|
+
# holds one wallet only — raise --limit and page with --page N to reach later wallets.
|
|
62
|
+
nansen research profiler counterparties-batch --addresses "0xabc,0xdef" --days 30 --limit 50
|
|
52
63
|
```
|
|
53
64
|
|
|
54
65
|
## Perps (no --chain)
|
|
@@ -81,6 +92,7 @@ nansen research profiler compare --addresses "0xabc,0xdef" --chain ethereum
|
|
|
81
92
|
| `--chain` | Required except for perps and search |
|
|
82
93
|
| `--days` | Lookback period (default 30) |
|
|
83
94
|
| `--limit` | Number of results |
|
|
95
|
+
| `--addresses` | Comma-separated wallets for `batch`, `compare`, `counterparties-batch` |
|
|
84
96
|
| `--include` | Batch fields: `labels,balance,pnl` |
|
|
85
97
|
| `--depth` | Trace depth 1-5 (default 2) |
|
|
86
98
|
| `--width` | Trace width — keep low to save credits |
|
package/src/api.js
CHANGED
|
@@ -386,6 +386,80 @@ const ADDRESS_PATTERNS = {
|
|
|
386
386
|
bitcoin: /^(1|3|bc1)[a-zA-HJ-NP-Z0-9]{25,62}$/,
|
|
387
387
|
};
|
|
388
388
|
|
|
389
|
+
// Server-side limits on the batch counterparties endpoint. Checked client-side so
|
|
390
|
+
// an over-limit request fails with an actionable message instead of a 422.
|
|
391
|
+
export const COUNTERPARTIES_BATCH_MAX_ADDRESSES = 10;
|
|
392
|
+
export const COUNTERPARTIES_BATCH_MAX_DAYS = 90;
|
|
393
|
+
|
|
394
|
+
/**
|
|
395
|
+
* Chains the batch counterparties endpoint accepts: the upstream `ProfilerChain`
|
|
396
|
+
* enum from https://api.nansen.ai/openapi.json, which is what the request model
|
|
397
|
+
* validates `chain` against. Anything outside it is a 422.
|
|
398
|
+
*
|
|
399
|
+
* Deliberately NOT derived from EVM_CHAINS. That list is this CLI's own
|
|
400
|
+
* address-format/ENS set and disagrees with the endpoint in both directions: it
|
|
401
|
+
* carries `scroll` and `ronin`, which the endpoint rejects, and omits every
|
|
402
|
+
* non-EVM chain the endpoint does serve (bitcoin, tron, sui, ton, near, ...).
|
|
403
|
+
* Mirrors ADDRESS_COUNTERPARTIES_BATCH_CHAINS on the MCP side (nansen-ra#3550),
|
|
404
|
+
* which additionally drops `arc` and `starknet`; the spec enum is the contract
|
|
405
|
+
* here, so they stay in.
|
|
406
|
+
*/
|
|
407
|
+
export const COUNTERPARTIES_BATCH_CHAINS = [
|
|
408
|
+
'all', 'arbitrum', 'arc', 'avalanche', 'base', 'bitcoin', 'bnb', 'ethereum',
|
|
409
|
+
'hyperevm', 'injective', 'iotaevm', 'linea', 'mantle', 'mantra', 'monad',
|
|
410
|
+
'near', 'optimism', 'plasma', 'polygon', 'robinhood', 'sei', 'solana',
|
|
411
|
+
'sonic', 'starknet', 'sui', 'ton', 'tron',
|
|
412
|
+
];
|
|
413
|
+
|
|
414
|
+
/**
|
|
415
|
+
* A token that is at least shaped like an address: 3-128 chars, no whitespace,
|
|
416
|
+
* alphanumerics plus the separators bech32/NEAR/TON addresses use.
|
|
417
|
+
*
|
|
418
|
+
* COUNTERPARTIES_BATCH_CHAINS admits chains whose address format validateAddress
|
|
419
|
+
* has no pattern for (arc, injective, mantra, near, robinhood, starknet, sui,
|
|
420
|
+
* ton, tron), where it falls through to its permissive "any non-empty string"
|
|
421
|
+
* branch. Accepting those chains must not turn a newline `--file` into a way to
|
|
422
|
+
* post arbitrary lines as `wallet_addresses`, so this is the floor; the API does
|
|
423
|
+
* the real per-chain check. Every valid EVM, Solana and Bitcoin address already
|
|
424
|
+
* satisfies it, so it never fires on a chain that was strictly validated.
|
|
425
|
+
*/
|
|
426
|
+
const ADDRESS_SHAPED = /^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/;
|
|
427
|
+
|
|
428
|
+
/**
|
|
429
|
+
* TON's raw address form: a workchain id, ":", then 64 hex characters —
|
|
430
|
+
* `0:` for the basechain, `-1:` for the masterchain. Both the ":" and the
|
|
431
|
+
* leading "-" fail ADDRESS_SHAPED, so raw TON addresses were rejected with a
|
|
432
|
+
* misleading error even though the endpoint serves them. Matched exactly here
|
|
433
|
+
* rather than by adding ":" to ADDRESS_SHAPED, which would put a separator no
|
|
434
|
+
* other supported chain uses back into the floor for every chain. Friendly
|
|
435
|
+
* (base64url) TON addresses already clear ADDRESS_SHAPED.
|
|
436
|
+
*/
|
|
437
|
+
const TON_RAW_ADDRESS = /^-?\d{1,10}:[0-9a-fA-F]{64}$/;
|
|
438
|
+
|
|
439
|
+
/** Whether an address clears the shape floor for `chain`. */
|
|
440
|
+
function isAddressShaped(address, chain) {
|
|
441
|
+
if (ADDRESS_SHAPED.test(address)) return true;
|
|
442
|
+
return chain === 'ton' && TON_RAW_ADDRESS.test(address);
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
/**
|
|
446
|
+
* Resolve a caller-supplied chain to the spelling the batch endpoint accepts,
|
|
447
|
+
* or throw. `bsc` is the common spelling and the one the API echoes back in
|
|
448
|
+
* responses, but the request enum only knows `bnb` — normalise rather than
|
|
449
|
+
* reject, matching the MCP tool.
|
|
450
|
+
*/
|
|
451
|
+
function resolveCounterpartiesBatchChain(chain) {
|
|
452
|
+
const lowered = String(chain ?? '').trim().toLowerCase();
|
|
453
|
+
const resolved = lowered === 'bsc' ? 'bnb' : lowered;
|
|
454
|
+
if (!COUNTERPARTIES_BATCH_CHAINS.includes(resolved)) {
|
|
455
|
+
throw new NansenError(
|
|
456
|
+
`Unsupported chain "${chain}" for batch counterparties. Supported chains: ${COUNTERPARTIES_BATCH_CHAINS.join(', ')}.`,
|
|
457
|
+
ErrorCode.INVALID_PARAMS
|
|
458
|
+
);
|
|
459
|
+
}
|
|
460
|
+
return resolved;
|
|
461
|
+
}
|
|
462
|
+
|
|
389
463
|
/**
|
|
390
464
|
* Validate address format for a given chain
|
|
391
465
|
* @param {string} address - The address to validate
|
|
@@ -442,7 +516,7 @@ export function validateTokenAddress(tokenAddress, chain = 'solana') {
|
|
|
442
516
|
*/
|
|
443
517
|
function requireValidAddress(address, chain) {
|
|
444
518
|
const v = validateAddress(address, chain);
|
|
445
|
-
if (!v.valid) throw new NansenError(v.error
|
|
519
|
+
if (!v.valid) throw new NansenError(`Invalid address "${address}" for chain "${chain}": ${v.error}`, v.code);
|
|
446
520
|
}
|
|
447
521
|
|
|
448
522
|
/**
|
|
@@ -453,6 +527,20 @@ function requireValidToken(tokenAddress, chain) {
|
|
|
453
527
|
if (!v.valid) throw new NansenError(v.error, v.code);
|
|
454
528
|
}
|
|
455
529
|
|
|
530
|
+
/**
|
|
531
|
+
* Which ecosystem chain 'all' would route this address to, or throw if neither.
|
|
532
|
+
* validateAddress's unknown-chain branch accepts any non-empty string for 'all',
|
|
533
|
+
* so classify against the concrete formats instead.
|
|
534
|
+
*/
|
|
535
|
+
function classifyAutoDetectedAddress(address) {
|
|
536
|
+
if (validateAddress(address, 'ethereum').valid) return 'EVM';
|
|
537
|
+
if (validateAddress(address, 'solana').valid) return 'Solana';
|
|
538
|
+
throw new NansenError(
|
|
539
|
+
`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).`,
|
|
540
|
+
ErrorCode.INVALID_ADDRESS
|
|
541
|
+
);
|
|
542
|
+
}
|
|
543
|
+
|
|
456
544
|
export function loadConfig() {
|
|
457
545
|
// Base config from files, then env vars override individual fields
|
|
458
546
|
let config = null;
|
|
@@ -1228,6 +1316,85 @@ export class NansenAPI {
|
|
|
1228
1316
|
});
|
|
1229
1317
|
}
|
|
1230
1318
|
|
|
1319
|
+
/**
|
|
1320
|
+
* Batch counterparties for up to 10 distinct wallets in one request.
|
|
1321
|
+
* Results are not aggregated: every row carries the `wallet_address` it belongs to.
|
|
1322
|
+
* Defaults to chain 'all' (the ecosystem is auto-detected), matching the CLI.
|
|
1323
|
+
*/
|
|
1324
|
+
async addressCounterpartiesBatch(params = {}) {
|
|
1325
|
+
const { addresses, chain = 'all', filters = {}, orderBy, pagination, days = 30, sourceInput } = params;
|
|
1326
|
+
const resolvedChain = resolveCounterpartiesBatchChain(chain);
|
|
1327
|
+
const list = Array.isArray(addresses) ? addresses : (addresses ? [addresses] : []);
|
|
1328
|
+
// Dedupe on the normalised form, because the server lowercases EVM addresses
|
|
1329
|
+
// before deduping: a checksum-cased repeat must not count twice against the
|
|
1330
|
+
// address limit. Solana (and other case-sensitive) addresses normalise to
|
|
1331
|
+
// themselves. Chain 'all' auto-detects per address, so normalise EVM casing
|
|
1332
|
+
// there too.
|
|
1333
|
+
const normalizeChain = resolvedChain === 'all' ? 'ethereum' : resolvedChain;
|
|
1334
|
+
const walletAddresses = [...new Set(
|
|
1335
|
+
list.map(a => normalizeAddress(String(a).trim(), normalizeChain)).filter(Boolean)
|
|
1336
|
+
)];
|
|
1337
|
+
|
|
1338
|
+
if (walletAddresses.length === 0) {
|
|
1339
|
+
throw new NansenError(
|
|
1340
|
+
'At least one wallet address is required. Pass --addresses "0xabc,0xdef" or --file <path>',
|
|
1341
|
+
ErrorCode.MISSING_PARAM
|
|
1342
|
+
);
|
|
1343
|
+
}
|
|
1344
|
+
if (walletAddresses.length > COUNTERPARTIES_BATCH_MAX_ADDRESSES) {
|
|
1345
|
+
throw new NansenError(
|
|
1346
|
+
`Batch counterparties accepts at most ${COUNTERPARTIES_BATCH_MAX_ADDRESSES} distinct addresses per request, got ${walletAddresses.length}. Split them across several requests.`,
|
|
1347
|
+
ErrorCode.INVALID_PARAMS
|
|
1348
|
+
);
|
|
1349
|
+
}
|
|
1350
|
+
if (!Number.isFinite(days) || days < 1) {
|
|
1351
|
+
throw new NansenError('--days must be a positive number', ErrorCode.INVALID_PARAMS);
|
|
1352
|
+
}
|
|
1353
|
+
if (days > COUNTERPARTIES_BATCH_MAX_DAYS) {
|
|
1354
|
+
throw new NansenError(
|
|
1355
|
+
`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.`,
|
|
1356
|
+
ErrorCode.INVALID_PARAMS
|
|
1357
|
+
);
|
|
1358
|
+
}
|
|
1359
|
+
if (resolvedChain === 'all') {
|
|
1360
|
+
// 'all' routes each address to its own ecosystem, but one request cannot
|
|
1361
|
+
// span both — the server rejects a mixed batch, so fail before sending it.
|
|
1362
|
+
const ecosystems = new Set(walletAddresses.map(classifyAutoDetectedAddress));
|
|
1363
|
+
if (ecosystems.size > 1) {
|
|
1364
|
+
throw new NansenError(
|
|
1365
|
+
"A batch cannot mix EVM and Solana addresses. Query each ecosystem separately; chain='all' auto-detects either ecosystem.",
|
|
1366
|
+
ErrorCode.INVALID_PARAMS
|
|
1367
|
+
);
|
|
1368
|
+
}
|
|
1369
|
+
} else {
|
|
1370
|
+
for (const walletAddress of walletAddresses) {
|
|
1371
|
+
// Strict where this CLI knows the format (EVM, Solana, Bitcoin); a
|
|
1372
|
+
// no-op elsewhere, where the shape floor is all there is.
|
|
1373
|
+
requireValidAddress(walletAddress, resolvedChain);
|
|
1374
|
+
if (!isAddressShaped(walletAddress, resolvedChain)) {
|
|
1375
|
+
const shape = 'an address-shaped token (3-128 characters, letters, digits, ".", "-" or "_")'
|
|
1376
|
+
+ (resolvedChain === 'ton'
|
|
1377
|
+
? ', or a raw TON address (workchain, ":" and 64 hex characters, e.g. "0:" or "-1:")'
|
|
1378
|
+
: '');
|
|
1379
|
+
throw new NansenError(
|
|
1380
|
+
`Invalid address "${walletAddress}" for chain "${resolvedChain}": expected ${shape}. This CLI cannot check ${resolvedChain} address formats, so the API validates the rest.`,
|
|
1381
|
+
ErrorCode.INVALID_ADDRESS
|
|
1382
|
+
);
|
|
1383
|
+
}
|
|
1384
|
+
}
|
|
1385
|
+
}
|
|
1386
|
+
|
|
1387
|
+
return this.request('/api/v1/profiler/address/counterparties/batch', {
|
|
1388
|
+
wallet_addresses: walletAddresses,
|
|
1389
|
+
chain: resolvedChain,
|
|
1390
|
+
date: buildDateRange(days),
|
|
1391
|
+
source_input: sourceInput,
|
|
1392
|
+
filters,
|
|
1393
|
+
order_by: orderBy,
|
|
1394
|
+
pagination
|
|
1395
|
+
});
|
|
1396
|
+
}
|
|
1397
|
+
|
|
1231
1398
|
async addressPnlSummary(params = {}) {
|
|
1232
1399
|
// Note: pnl-summary endpoint is non-paginated (returns aggregate stats, not a list).
|
|
1233
1400
|
// Pagination param intentionally omitted from this request.
|
|
@@ -1679,16 +1846,6 @@ export class NansenAPI {
|
|
|
1679
1846
|
});
|
|
1680
1847
|
}
|
|
1681
1848
|
|
|
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
1849
|
// ============= Portfolio Endpoints =============
|
|
1693
1850
|
|
|
1694
1851
|
async portfolioDefiHoldings(params = {}) {
|