nansen-cli 1.33.0 → 1.34.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.34.0
+
+### Minor Changes
+
+- [#459](https://github.com/nansen-ai/nansen-cli/pull/459) [`37e6725`](https://github.com/nansen-ai/nansen-cli/commit/37e6725aeeb3b83eb29c4650908b8dbb522ed316) Thanks [@dependabot](https://github.com/apps/dependabot)! - Drop support for Node.js 18 (EOL since April 2025). The minimum supported version is now Node.js 20, matching our test toolchain (vitest 4.x requires Node 20+).
+
+- [#460](https://github.com/nansen-ai/nansen-cli/pull/460) [`aac4bbe`](https://github.com/nansen-ai/nansen-cli/commit/aac4bbe18312edb48c91df60ab555f9c1d8334ce) Thanks [@gulshngill](https://github.com/gulshngill)! - Add trader_type, sectors_filter, sm_label_filter, and trader_label_filter filters to `nansen research perp screener` (ECINT-6680).
+
+  New CLI options:
+
+  - `--trader-type <type>` — filter by trader type: all, sm, whale, public_figure, high_winrate_hl_perps_trader
+  - `--sectors-filter <sectors>` — comma-separated sector:subcategory pairs, e.g. "Crypto:AI,TradFi:Stocks"
+  - `--sm-label-filter <labels>` — comma-separated Nansen SM labels (applies when trader-type is all or sm)
+  - `--trader-label-filter <labels>` — comma-separated HL perps trader labels (applies when trader-type is all or sm)
+
 ## 1.33.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",
@@ -59,7 +59,7 @@
   },
   "homepage": "https://github.com/nansen-ai/nansen-cli#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.1",

package/skills/nansen-perp-screener/SKILL.md

@@ -30,3 +30,62 @@ nansen research perp leaderboard --days 7 --limit 20
 nansen research smart-money perp-trades --limit 20
 # → token_symbol, side, action (Open/Close), value_usd, price_usd, trader_address_label
 ```
+
+## New Filters (ECINT-6680)
+
+### `--trader-type`
+Filter by trader type. Accepted values: `all` (default), `sm`, `whale`, `public_figure`, `high_winrate_hl_perps_trader`.
+
+```bash
+# Show only whale traders
+nansen research perp screener --trader-type whale --limit 10
+
+# Show only smart money traders
+nansen research perp screener --trader-type sm --limit 20
+
+# Show high win-rate HL perps traders
+nansen research perp screener --trader-type high_winrate_hl_perps_trader --limit 20
+```
+
+### `--sm-label-filter`
+Comma-separated Nansen SM labels to filter by. Only applies when `--trader-type` is `all` or `sm`.
+
+```bash
+# Filter to a specific SM label
+nansen research perp screener --trader-type sm --sm-label-filter "30D Smart Trader"
+
+# Multiple labels
+nansen research perp screener --sm-label-filter "30D Smart Trader,Smart LP"
+```
+
+### `--trader-label-filter`
+Comma-separated HL perps trader labels to filter by. Only applies when `--trader-type` is `all` or `sm`.
+
+```bash
+# Filter to HL Perps Whale label
+nansen research perp screener --trader-label-filter "HL Perps Whale"
+```
+
+### `--sectors-filter`
+Comma-separated `category:subcategory` pairs to filter coins by sector.
+
+```bash
+# Filter to AI and DeFi crypto sectors
+nansen research perp screener --sectors-filter "Crypto:AI,Crypto:DeFi" --trader-type whale
+
+# Combine with trader type and limit
+nansen research perp screener --sectors-filter "Crypto:AI,Crypto:DeFi" --trader-type whale --limit 10 --sort volume:desc
+```
+
+## Combined Examples
+
+```bash
+# Whale traders in AI crypto, sorted by volume
+nansen research perp screener --trader-type whale --sectors-filter "Crypto:AI" --sort volume:desc --limit 10
+
+# Smart money with specific label, last 7 days
+nansen research perp screener --trader-type sm --sm-label-filter "30D Smart Trader" --days 7 --limit 20
+
+# All traders in TradFi stocks sector
+nansen research perp screener --sectors-filter "TradFi:Stocks" --sort open_interest:desc --limit 20
+```

package/src/api.js

@@ -1187,13 +1187,18 @@ export class NansenAPI {
   // ============= Perp Endpoints =============
 
   async perpScreener(params = {}) {
-    const { filters = {}, orderBy, pagination, days = 30 } = params;
-    return this.request('/api/v1/perp-screener', {
+    const { filters = {}, orderBy, pagination, days = 30, traderType, sectorsFilter, smLabelFilter, traderLabelFilter } = params;
+    const body = {
       date: buildDateRange(days),
       filters,
       order_by: orderBy,
       pagination
-    });
+    };
+    if (traderType !== undefined) body.filters.trader_type = traderType;
+    if (sectorsFilter !== undefined) body.filters.sectors_filter = sectorsFilter;
+    if (smLabelFilter !== undefined) body.filters.sm_label_filter = smLabelFilter;
+    if (traderLabelFilter !== undefined) body.filters.trader_label_filter = traderLabelFilter;
+    return this.request('/api/v1/perp-screener', body);
   }
 
   async perpLeaderboard(params = {}) {

package/src/cli.js

@@ -1367,7 +1367,19 @@ export function buildCommands(deps = {}) {
       const days = options.days ? parseInt(options.days) : 30;
 
       const handlers = {
-        'screener': () => apiInstance.perpScreener({ filters, orderBy, pagination, days }),
+        'screener': () => {
+          const traderType = options['trader-type'];
+          const sectorsFilter = options['sectors-filter']
+            ? options['sectors-filter'].split(',').map(s => s.trim()).filter(Boolean)
+            : undefined;
+          const smLabelFilter = options['sm-label-filter']
+            ? options['sm-label-filter'].split(',').map(s => s.trim()).filter(Boolean)
+            : undefined;
+          const traderLabelFilter = options['trader-label-filter']
+            ? options['trader-label-filter'].split(',').map(s => s.trim()).filter(Boolean)
+            : undefined;
+          return apiInstance.perpScreener({ filters, orderBy, pagination, days, traderType, sectorsFilter, smLabelFilter, traderLabelFilter });
+        },
         'leaderboard': () => {
           const withLabels = resolveBooleanOption(options, flags, 'premium-labels');
           return apiInstance.perpLeaderboard({ filters, orderBy, pagination, days, withLabels });

package/src/schema.json

@@ -522,7 +522,11 @@
               "options": {
                 "market-cap": {
                   "description": "Filter by market cap group",
-                  "enum": ["lowcap", "midcap", "largecap"]
+                  "enum": [
+                    "lowcap",
+                    "midcap",
+                    "largecap"
+                  ]
                 },
                 "limit": {
                   "default": 25
@@ -555,6 +559,25 @@
               "options": {
                 "days": {
                   "default": 30
+                },
+                "trader-type": {
+                  "description": "Filter by trader type. One of: all, sm, whale, public_figure, high_winrate_hl_perps_trader. Defaults to all.",
+                  "enum": [
+                    "all",
+                    "sm",
+                    "whale",
+                    "public_figure",
+                    "high_winrate_hl_perps_trader"
+                  ]
+                },
+                "sectors-filter": {
+                  "description": "Comma-separated sector:subcategory pairs to filter by, e.g. \"Crypto:AI,TradFi:Stocks\"."
+                },
+                "sm-label-filter": {
+                  "description": "Comma-separated Nansen SM labels to filter by, e.g. \"30D Smart Trader\". Only applies when trader-type is all or sm."
+                },
+                "trader-label-filter": {
+                  "description": "Comma-separated HL perps trader labels to filter by, e.g. \"HL Perps Whale\". Only applies when trader-type is all or sm."
                 }
               }
             },
@@ -616,8 +639,12 @@
               "endpoint": "/api/v1/prediction-market/market-screener",
               "description": "Get Prediction Market Screener",
               "options": {
-                "query": { "default": "" },
-                "sort-by": { "description": "Deprecated: use --sort field:dir instead" },
+                "query": {
+                  "default": ""
+                },
+                "sort-by": {
+                  "description": "Deprecated: use --sort field:dir instead"
+                },
                 "tags": {},
                 "min-liquidity": {},
                 "max-liquidity": {},
@@ -638,8 +665,12 @@
               "endpoint": "/api/v1/prediction-market/event-screener",
               "description": "Get Prediction Market Event Screener",
               "options": {
-                "query": { "default": "" },
-                "sort-by": { "description": "Deprecated: use --sort field:dir instead" },
+                "query": {
+                  "default": ""
+                },
+                "sort-by": {
+                  "description": "Deprecated: use --sort field:dir instead"
+                },
                 "tags": {},
                 "min-liquidity": {},
                 "max-liquidity": {},
@@ -717,104 +748,218 @@
           "endpoint": "/api/v1beta1/tgm/historical-dex-trades",
           "description": "Historical DEX trades for a token at a point in time",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" },
-            "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "from-date": {
+              "required": true,
+              "description": "Start of date range (YYYY-MM-DD)"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End of date range (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-pnl-leaderboard": {
           "endpoint": "/api/v1beta1/tgm/historical-pnl-leaderboard",
           "description": "Historical PnL leaderboard for a token",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" },
-            "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "from-date": {
+              "required": true,
+              "description": "Start of date range (YYYY-MM-DD)"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End of date range (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-token-flow-summary": {
           "endpoint": "/api/v1beta1/tgm/historical-token-flow-summary",
           "description": "Historical token flow summary (no pagination)",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" },
-            "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "from-date": {
+              "required": true,
+              "description": "Start of date range (YYYY-MM-DD)"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End of date range (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-token-quant-scores": {
           "endpoint": "/api/v1beta1/tgm/historical-token-quant-scores",
           "description": "Historical token quantitative scores at a snapshot date",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-top-holders": {
           "endpoint": "/api/v1beta1/tgm/historical-top-holders",
           "description": "Historical top holders of a token at a snapshot date",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-who-bought-sold": {
           "endpoint": "/api/v1beta1/tgm/historical-who-bought-sold",
           "description": "Historical buyers/sellers of a token",
           "options": {
-            "token-address": { "required": true, "description": "Token address" },
-            "from-date": { "required": true, "description": "Start of date range (YYYY-MM-DD)" },
-            "to-date": { "required": true, "description": "End of date range (YYYY-MM-DD)" },
-            "buy-or-sell": { "default": "BUY", "description": "BUY or SELL" },
-            "chain": { "default": "solana", "description": "Chain" }
+            "token-address": {
+              "required": true,
+              "description": "Token address"
+            },
+            "from-date": {
+              "required": true,
+              "description": "Start of date range (YYYY-MM-DD)"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End of date range (YYYY-MM-DD)"
+            },
+            "buy-or-sell": {
+              "default": "BUY",
+              "description": "BUY or SELL"
+            },
+            "chain": {
+              "default": "solana",
+              "description": "Chain"
+            }
           }
         },
         "historical-smart-money-balances": {
           "endpoint": "/api/v1beta1/smart-money/historical-token-balances",
           "description": "Historical smart money token balances at a snapshot date (no order_by)",
           "options": {
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chains": { "default": "solana", "description": "Comma-separated chains" }
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chains": {
+              "default": "solana",
+              "description": "Comma-separated chains"
+            }
           }
         },
         "historical-token-screener": {
           "endpoint": "/api/v1beta1/token-screener/historical",
           "description": "Historical token screener over a trailing window",
           "options": {
-            "timeframe-days": { "required": true, "type": "number", "description": "Trailing window size in days" },
-            "to-date": { "required": true, "description": "End date for the window (YYYY-MM-DD)" },
-            "chains": { "default": "solana", "description": "Comma-separated chains" }
+            "timeframe-days": {
+              "required": true,
+              "type": "number",
+              "description": "Trailing window size in days"
+            },
+            "to-date": {
+              "required": true,
+              "description": "End date for the window (YYYY-MM-DD)"
+            },
+            "chains": {
+              "default": "solana",
+              "description": "Comma-separated chains"
+            }
           }
         },
         "historical-wallet-balances": {
           "endpoint": "/api/v1beta1/profiler/address/historical-token-balances",
           "description": "Historical token balances for a wallet at a snapshot date",
           "options": {
-            "address": { "required": true, "description": "Wallet address" },
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chain": { "default": "ethereum", "description": "Chain" }
+            "address": {
+              "required": true,
+              "description": "Wallet address"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "ethereum",
+              "description": "Chain"
+            }
           }
         },
         "historical-tx-lookup": {
           "endpoint": "/api/v1beta1/profiler/historical-transaction-lookup",
           "description": "Lookup a historical transaction by hash",
           "options": {
-            "transaction-hash": { "required": true, "description": "Transaction hash (0x-prefixed, 66 chars)" },
-            "as-of-date": { "required": true, "description": "Reference date for label and pricing resolution (YYYY-MM-DD)" },
-            "block-timestamp": { "description": "Block timestamp (YYYY-MM-DD HH:MM:SS) — skips slow hash-resolution step if provided" },
-            "chain": { "default": "ethereum", "description": "Chain (ethereum, bnb, base)" }
+            "transaction-hash": {
+              "required": true,
+              "description": "Transaction hash (0x-prefixed, 66 chars)"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Reference date for label and pricing resolution (YYYY-MM-DD)"
+            },
+            "block-timestamp": {
+              "description": "Block timestamp (YYYY-MM-DD HH:MM:SS) \u2014 skips slow hash-resolution step if provided"
+            },
+            "chain": {
+              "default": "ethereum",
+              "description": "Chain (ethereum, bnb, base)"
+            }
           }
         },
         "historical-wallet-transactions": {
           "endpoint": "/api/v1beta1/profiler/address/historical-transactions",
           "description": "Historical transactions for a wallet at a snapshot date",
           "options": {
-            "address": { "required": true, "description": "Wallet address" },
-            "as-of-date": { "required": true, "description": "Snapshot date (YYYY-MM-DD)" },
-            "chain": { "default": "ethereum", "description": "Chain" }
+            "address": {
+              "required": true,
+              "description": "Wallet address"
+            },
+            "as-of-date": {
+              "required": true,
+              "description": "Snapshot date (YYYY-MM-DD)"
+            },
+            "chain": {
+              "default": "ethereum",
+              "description": "Chain"
+            }
           }
         }
       }
@@ -971,7 +1116,7 @@
             },
             "to-chain": {
               "type": "string",
-              "description": "Destination blockchain for cross-chain swap (solana or base). Omit for same-chain. At least one side must be USDC or a native token (ETH, SOL). Non-native to non-native is not supported — swap to USDC first, then bridge. Bridge providers (Li.Fi or Relay) are selected automatically based on best price. Sub-dollar swaps are supported via Relay."
+              "description": "Destination blockchain for cross-chain swap (solana or base). Omit for same-chain. At least one side must be USDC or a native token (ETH, SOL). Non-native to non-native is not supported \u2014 swap to USDC first, then bridge. Bridge providers (Li.Fi or Relay) are selected automatically based on best price. Sub-dollar swaps are supported via Relay."
             },
             "from": {
               "type": "string",
@@ -1047,7 +1192,7 @@
             },
             "aggregator": {
               "type": "string",
-              "description": "lifi or relay. Overrides auto-detection — use when polling from a different machine or after the 30-day local record TTL has expired."
+              "description": "lifi or relay. Overrides auto-detection \u2014 use when polling from a different machine or after the 30-day local record TTL has expired."
             }
           }
         },
@@ -1101,7 +1246,9 @@
                   "description": "Wallet name (or \"walletconnect\"/\"wc\")"
                 }
               },
-              "chains": ["solana"],
+              "chains": [
+                "solana"
+              ],
               "prerequisites": [
                 "A Solana wallet must be configured. Run: nansen wallet create"
               ]
@@ -1141,7 +1288,9 @@
                   "description": "Wallet name (or \"walletconnect\"/\"wc\")"
                 }
               },
-              "chains": ["solana"]
+              "chains": [
+                "solana"
+              ]
             },
             "cancel": {
               "description": "Cancel an open limit order",
@@ -1156,7 +1305,9 @@
                   "description": "Wallet name (or \"walletconnect\"/\"wc\")"
                 }
               },
-              "chains": ["solana"]
+              "chains": [
+                "solana"
+              ]
             },
             "update": {
               "description": "Update trigger price or slippage on an existing order",
@@ -1179,7 +1330,9 @@
                   "description": "Wallet name (or \"walletconnect\"/\"wc\")"
                 }
               },
-              "chains": ["solana"]
+              "chains": [
+                "solana"
+              ]
             }
           }
         }