nansen-cli 1.12.0 → 1.13.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.13.1
+
+### Patch Changes
+
+- [#225](https://github.com/nansen-ai/nansen-cli/pull/225) [`051e4a3`](https://github.com/nansen-ai/nansen-cli/commit/051e4a353641d000facd2133810c059981b9ac7f) Thanks [@TimNooren](https://github.com/TimNooren)! - Remove "recommended, lower fees" label from Base network in wallet create output
+
+## 1.13.0
+
+### Minor Changes
+
+- [#107](https://github.com/nansen-ai/nansen-cli/pull/107) [`5877c06`](https://github.com/nansen-ai/nansen-cli/commit/5877c06061c1d32998fa3ce011c16f4352fc22dc) Thanks [@marius-reed](https://github.com/marius-reed)! - Add 11 prediction market (Polymarket) endpoints under `nansen research pm`. Includes OHLCV, orderbook, top holders, trades, screeners, PnL, position detail, and categories. Supports `--market-id`, `--address`, `--sort-by`, `--query`, `--status` flags with pagination, sorting, and table output.
+
 ## 1.12.0
 
 ### Minor Changes

package/README.md

@@ -30,7 +30,7 @@ nansen wallet <subcommand> [options]
 nansen schema [command] [--pretty]    # full command reference (no API key needed)
 ```
 
-**Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `search`, `perp`, `points`
+**Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`, `points`
 
 **Trade:** `quote`, `execute` — DEX swaps on Solana and Base.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -24,7 +24,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "changeset": "changeset",
-    "changeset:version": "changeset version",
+    "changeset:version": "changeset version && npm install --package-lock-only",
     "changeset:publish": "changeset publish"
   },
   "keywords": [

package/src/api.js

@@ -6,6 +6,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { EVM_CHAINS } from './chain-ids.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -255,12 +256,6 @@ const ADDRESS_PATTERNS = {
   bitcoin: /^(1|3|bc1)[a-zA-HJ-NP-Z0-9]{25,62}$/,
 };
 
-const EVM_CHAINS = [
-  'ethereum', 'arbitrum', 'base', 'bnb', 'polygon', 'optimism',
-  'avalanche', 'linea', 'scroll', 'mantle', 'ronin',
-  'sei', 'plasma', 'sonic', 'monad', 'hyperevm', 'iotaevm'
-];
-
 /**
  * Validate address format for a given chain
  * @param {string} address - The address to validate
@@ -1103,6 +1098,113 @@ export class NansenAPI {
     });
   }
 
+  // ============= Prediction Market Endpoints =============
+
+  async pmOhlcv(params = {}) {
+    const { marketId, sort, pagination } = params;
+    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    return this.request('/api/v1/prediction-market/ohlcv', {
+      market_id: marketId,
+      sort,
+      pagination
+    });
+  }
+
+  async pmOrderbook(params = {}) {
+    const { marketId, pagination } = params;
+    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    return this.request('/api/v1/prediction-market/orderbook', {
+      market_id: marketId,
+      pagination
+    });
+  }
+
+  async pmTopHolders(params = {}) {
+    const { marketId, sort, pagination } = params;
+    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    return this.request('/api/v1/prediction-market/top-holders', {
+      market_id: marketId,
+      sort,
+      pagination
+    });
+  }
+
+  async pmTradesByMarket(params = {}) {
+    const { marketId, pagination } = params;
+    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    return this.request('/api/v1/prediction-market/trades-by-market', {
+      market_id: marketId,
+      pagination
+    });
+  }
+
+  async pmTradesByAddress(params = {}) {
+    const { address, pagination } = params;
+    // Polymarket runs exclusively on Polygon
+    const validation = validateAddress(address, 'polygon');
+    if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    return this.request('/api/v1/prediction-market/trades-by-address', {
+      address,
+      pagination
+    });
+  }
+
+  async pmMarketScreener(params = {}) {
+    const { sortBy = 'volume_24hr', query = '', status = '', pagination } = params;
+    return this.request('/api/v1/prediction-market/market-screener', {
+      sort_by: sortBy,
+      query,
+      status,
+      pagination
+    });
+  }
+
+  async pmEventScreener(params = {}) {
+    const { sortBy = 'volume_24hr', query = '', status = '', pagination } = params;
+    return this.request('/api/v1/prediction-market/event-screener', {
+      sort_by: sortBy,
+      query,
+      status,
+      pagination
+    });
+  }
+
+  async pmPnlByMarket(params = {}) {
+    const { marketId, pagination } = params;
+    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    return this.request('/api/v1/prediction-market/pnl-by-market', {
+      market_id: marketId,
+      pagination
+    });
+  }
+
+  async pmPnlByAddress(params = {}) {
+    const { address, pagination } = params;
+    // Polymarket runs exclusively on Polygon
+    const validation = validateAddress(address, 'polygon');
+    if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    return this.request('/api/v1/prediction-market/pnl-by-address', {
+      address,
+      pagination
+    });
+  }
+
+  async pmPositionDetail(params = {}) {
+    const { marketId, pagination } = params;
+    if (!marketId) throw new NansenError('market_id is required', ErrorCode.MISSING_PARAM);
+    return this.request('/api/v1/prediction-market/position-detail', {
+      market_id: marketId,
+      pagination
+    });
+  }
+
+  async pmCategories(params = {}) {
+    const { pagination } = params;
+    return this.request('/api/v1/prediction-market/categories', {
+      pagination
+    });
+  }
+
   // ============= Points Endpoints =============
 
   async pointsLeaderboard(params = {}) {

package/src/chain-ids.js

@@ -17,3 +17,14 @@ export const EVM_CHAIN_IDS = {
   zksync: 324,
   mantle: 5000,
 };
+
+/**
+ * All EVM chain names recognised by this CLI.
+ * Used for address-format validation (0x...) and ENS resolution gating.
+ * Import from here instead of defining an inline list per file.
+ */
+export const EVM_CHAINS = [
+  'ethereum', 'arbitrum', 'base', 'bnb', 'polygon', 'optimism',
+  'avalanche', 'linea', 'scroll', 'zksync', 'mantle', 'ronin',
+  'sei', 'plasma', 'sonic', 'unichain', 'monad', 'hyperevm', 'iotaevm',
+];

package/src/cli.js

@@ -55,15 +55,26 @@ export function filterFields(data, fields) {
     const filtered = {};
     for (const key of Object.keys(obj)) {
       if (fieldSet.has(key)) {
+        // Explicitly requested — include as-is
         filtered[key] = obj[key];
       } else if (typeof obj[key] === 'object' && obj[key] !== null) {
-        // Recurse into nested objects/arrays
-        const nested = filterObject(obj[key]);
-        // Only include if it has content
-        if (nested !== null && nested !== undefined) {
-          if (Array.isArray(nested) && nested.length > 0) {
-            filtered[key] = nested;
-          } else if (!Array.isArray(nested) && Object.keys(nested).length > 0) {
+        if (Array.isArray(obj[key])) {
+          // Only recurse into arrays whose elements are plain objects.
+          // Primitive arrays (e.g. tags: ["a","b"]) are dropped unless the
+          // key was explicitly requested (handled above).
+          const hasObjectElements = obj[key].length > 0 &&
+            typeof obj[key][0] === 'object' && obj[key][0] !== null;
+          if (hasObjectElements) {
+            const nested = obj[key].map(item => filterObject(item))
+              .filter(item => Object.keys(item).length > 0);
+            if (nested.length > 0) {
+              filtered[key] = nested;
+            }
+          }
+        } else {
+          // Plain object — always recurse in case it wraps requested fields
+          const nested = filterObject(obj[key]);
+          if (nested !== null && nested !== undefined && Object.keys(nested).length > 0) {
             filtered[key] = nested;
           }
         }
@@ -1217,12 +1228,48 @@ export function buildCommands(deps = {}) {
         return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
       }
 
+      return handlers[subcommand]();
+    },
+
+    'prediction-market': async (args, apiInstance, flags, options) => {
+      const subcommand = args[0] || 'help';
+      const marketId = options['market-id'];
+      const address = options.address;
+      const sortBy = options['sort-by'];
+      const query = options.query;
+      const status = options.status;
+      const sort = parseSort(options.sort);
+      const pagination = buildPagination(options);
+
+      const handlers = {
+        'ohlcv': () => apiInstance.pmOhlcv({ marketId, sort, pagination }),
+        'orderbook': () => apiInstance.pmOrderbook({ marketId, pagination }),
+        'top-holders': () => apiInstance.pmTopHolders({ marketId, sort, pagination }),
+        'trades-by-market': () => apiInstance.pmTradesByMarket({ marketId, pagination }),
+        'trades-by-address': () => apiInstance.pmTradesByAddress({ address, pagination }),
+        'market-screener': () => apiInstance.pmMarketScreener({ sortBy, query, status, pagination }),
+        'event-screener': () => apiInstance.pmEventScreener({ sortBy, query, status, pagination }),
+        'pnl-by-market': () => apiInstance.pmPnlByMarket({ marketId, pagination }),
+        'pnl-by-address': () => apiInstance.pmPnlByAddress({ address, pagination }),
+        'position-detail': () => apiInstance.pmPositionDetail({ marketId, pagination }),
+        'categories': () => apiInstance.pmCategories({ pagination }),
+        'help': () => ({
+          commands: ['ohlcv', 'orderbook', 'top-holders', 'trades-by-market', 'trades-by-address', 'market-screener', 'event-screener', 'pnl-by-market', 'pnl-by-address', 'position-detail', 'categories'],
+          description: 'Polymarket prediction market analytics',
+          example: 'nansen research pm market-screener --sort-by volume_24hr --limit 20'
+        })
+      };
+
+      if (!handlers[subcommand]) {
+        throw new NansenError(`Unknown subcommand: ${subcommand}. Available: ${Object.keys(handlers).filter(k => k !== 'help').join(', ')}`, ErrorCode.UNKNOWN);
+      }
+
       return handlers[subcommand]();
     }
   };
 
   // 'research' delegates to the category handlers defined above
-  const RESEARCH_CATEGORIES = new Set(['smart-money', 'profiler', 'token', 'search', 'perp', 'portfolio', 'points']);
+  const RESEARCH_CATEGORIES = new Set(['smart-money', 'profiler', 'token', 'search', 'perp', 'portfolio', 'points', 'prediction-market']);
 
   cmds['research'] = async (args, apiInstance, flags, options) => {
     const rawCategory = args[0];
@@ -1298,11 +1345,12 @@ export const RESEARCH_CATEGORY_ALIASES = {
   'tgm': 'token',
   'sm': 'smart-money',
   'prof': 'profiler',
-  'port': 'portfolio'
+  'port': 'portfolio',
+  'pm': 'prediction-market'
 };
 
 // Generate help text for a specific subcommand using SCHEMA
-export function generateSubcommandHelp(command, subcommand) {
+export function generateSubcommandHelp(command, subcommand, prefix = null) {
   const cmdSchema = SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command];
   if (!cmdSchema) return null;
 
@@ -1329,8 +1377,8 @@ export function generateSubcommandHelp(command, subcommand) {
 
   const exampleValues = { address: '0x...', token: '0x...', query: '"term"', symbol: 'BTC', date: '2024-01-01' };
   const chain = subSchema.options?.chain?.default || 'solana';
-  const prefix = DEPRECATED_TO_RESEARCH.has(command) ? `research ${command}` : command;
-  let example = `nansen ${prefix} ${subcommand}`;
+  const cmdPrefix = prefix || (DEPRECATED_TO_RESEARCH.has(command) ? `research ${command}` : command);
+  let example = `nansen ${cmdPrefix} ${subcommand}`;
   if (subSchema.options) {
     for (const [name, opt] of Object.entries(subSchema.options)) {
       if (opt.required) example += ` --${name} ${exampleValues[name] || '<val>'}`;
@@ -1398,7 +1446,7 @@ export async function runCLI(rawArgs, deps = {}) {
         const category = RESEARCH_CATEGORY_ALIASES[subcommand] || subcommand;
         const deepSub = subArgs[1];
         if (deepSub) {
-          const subHelp = generateSubcommandHelp(category, deepSub);
+          const subHelp = generateSubcommandHelp(category, deepSub, `research ${subcommand}`);
           if (subHelp) {
             output(subHelp);
             notify();

package/src/ens.js

@@ -6,15 +6,10 @@
 
 import https from 'https';
 import { keccak256 } from './crypto.js';
+import { EVM_CHAINS } from './chain-ids.js';
 
 const ENS_PATTERN = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?\.eth$/;
 
-const EVM_CHAINS = [
-  'ethereum', 'base', 'optimism', 'arbitrum', 'polygon', 'bnb',
-  'avalanche', 'fantom', 'gnosis', 'linea', 'scroll', 'zksync',
-  'blast', 'mantle', 'ronin', 'sei', 'plasma', 'sonic', 'unichain', 'monad', 'hyperevm', 'iotaevm'
-];
-
 /**
  * Check if a string looks like an ENS name
  */

package/src/schema.json

@@ -33,10 +33,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -74,10 +70,6 @@
                 },
                 "filters": {
                   "type": "object"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -118,10 +110,6 @@
                 },
                 "filters": {
                   "type": "object"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -153,18 +141,6 @@
                 },
                 "labels": {
                   "type": "string|array"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., value_usd:desc)"
-                },
-                "filters": {
-                  "type": "object",
-                  "description": "Additional filters as JSON"
                 }
               },
               "returns": [
@@ -186,20 +162,8 @@
                 "limit": {
                   "type": "number"
                 },
-                "labels": {
-                  "type": "string|array",
-                  "description": "Smart Money label filter"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., deposit_value_usd:desc)"
-                },
                 "filters": {
                   "type": "object"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -236,22 +200,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "labels": {
-                  "type": "string|array",
-                  "description": "Smart Money label filter"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., value_usd:desc)"
-                },
-                "filters": {
-                  "type": "object",
-                  "description": "Additional filters as JSON"
                 }
               },
               "returns": [
@@ -342,18 +290,6 @@
                 "days": {
                   "type": "number",
                   "default": 30
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., block_timestamp:desc)"
-                },
-                "filters": {
-                  "type": "object",
-                  "description": "Additional filters as JSON"
                 }
               },
               "returns": [
@@ -388,18 +324,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., pnl_usd_realised:desc)"
-                },
-                "filters": {
-                  "type": "object",
-                  "description": "Additional filters as JSON"
                 }
               },
               "returns": [
@@ -434,10 +358,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -461,18 +381,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., value_usd:desc)"
-                },
-                "filters": {
-                  "type": "object",
-                  "description": "Additional filters as JSON"
                 }
               },
               "returns": [
@@ -497,14 +405,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., order:desc)"
                 }
               },
               "returns": [
@@ -534,18 +434,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., total_volume_usd:desc)"
-                },
-                "filters": {
-                  "type": "object",
-                  "description": "Additional filters as JSON"
                 }
               },
               "returns": [
@@ -593,18 +481,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., position_value_usd:desc)"
-                },
-                "filters": {
-                  "type": "object",
-                  "description": "Additional filters as JSON"
                 }
               },
               "returns": [
@@ -635,18 +511,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
-                },
-                "sort": {
-                  "type": "string",
-                  "description": "Sort field:direction (e.g., value_usd:desc)"
-                },
-                "filters": {
-                  "type": "object",
-                  "description": "Additional filters as JSON"
                 }
               },
               "returns": [
@@ -910,10 +774,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -959,10 +819,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1008,10 +864,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1052,10 +904,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1099,10 +947,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1155,10 +999,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1246,10 +1086,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1281,10 +1117,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1327,10 +1159,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1364,10 +1192,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1406,10 +1230,6 @@
                 "filters": {
                   "type": "object",
                   "description": "Additional filters as JSON"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1460,10 +1280,6 @@
               "type": "number",
               "default": 25,
               "description": "Max results (1-50)"
-            },
-            "page": {
-              "type": "number",
-              "description": "Page number for paginated results (default: 1)"
             }
           },
           "returns": [
@@ -1490,10 +1306,6 @@
                 },
                 "filters": {
                   "type": "object"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1524,10 +1336,6 @@
                 },
                 "filters": {
                   "type": "object"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1564,6 +1372,389 @@
             }
           }
         },
+        "prediction-market": {
+          "description": "Polymarket prediction market analytics",
+          "aliases": [
+            "pm"
+          ],
+          "subcommands": {
+            "ohlcv": {
+              "description": "OHLCV candle data for a market",
+              "options": {
+                "market-id": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Market ID"
+                },
+                "sort": {
+                  "type": "string",
+                  "description": "Sort field:direction (e.g., period_start:desc)"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "market_id",
+                "token_id",
+                "side",
+                "outcome_index",
+                "period_start",
+                "open",
+                "high",
+                "low",
+                "close",
+                "volume_usd",
+                "trade_count",
+                "unique_traders"
+              ]
+            },
+            "orderbook": {
+              "description": "Current orderbook levels",
+              "options": {
+                "market-id": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Market ID"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "market_id",
+                "event_id",
+                "outcome",
+                "outcome_index",
+                "asset_id",
+                "side",
+                "price",
+                "size",
+                "cumulative_size",
+                "snapshot_timestamp"
+              ]
+            },
+            "top-holders": {
+              "description": "Top holders for a market",
+              "options": {
+                "market-id": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Market ID"
+                },
+                "sort": {
+                  "type": "string",
+                  "description": "Sort field:direction"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "market_id",
+                "outcome_index",
+                "address",
+                "owner_address",
+                "side",
+                "position_size",
+                "avg_entry_price",
+                "current_price",
+                "unrealized_pnl_usd"
+              ]
+            },
+            "trades-by-market": {
+              "description": "Recent trades for a market",
+              "options": {
+                "market-id": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Market ID"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "timestamp",
+                "seller",
+                "buyer",
+                "taker_action",
+                "side",
+                "outcome_index",
+                "size",
+                "price",
+                "usdc_value",
+                "tx_hash",
+                "market_id"
+              ]
+            },
+            "trades-by-address": {
+              "description": "Trades for a specific address",
+              "options": {
+                "address": {
+                  "type": "string",
+                  "required": true,
+                  "description": "EVM address (Polygon)"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "timestamp",
+                "seller",
+                "buyer",
+                "taker_action",
+                "side",
+                "outcome_index",
+                "size",
+                "price",
+                "usdc_value",
+                "tx_hash",
+                "market_id",
+                "market_question",
+                "event_id",
+                "event_title"
+              ]
+            },
+            "market-screener": {
+              "description": "Screen and discover markets",
+              "options": {
+                "sort-by": {
+                  "type": "string",
+                  "default": "volume_24hr",
+                  "enum": [
+                    "volume_24hr",
+                    "volume",
+                    "volume_1wk",
+                    "volume_1mo",
+                    "liquidity",
+                    "open_interest",
+                    "unique_traders_24h",
+                    "age_hours"
+                  ],
+                  "description": "Sort field"
+                },
+                "query": {
+                  "type": "string",
+                  "description": "Search text"
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "active",
+                    "closed"
+                  ],
+                  "description": "Market status filter (default: active)"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "market_id",
+                "question",
+                "slug",
+                "event_id",
+                "event_title",
+                "active",
+                "closed",
+                "end_date",
+                "neg_risk",
+                "tags",
+                "volume",
+                "volume_24hr",
+                "volume_1wk",
+                "volume_1mo",
+                "volume_change_pct",
+                "liquidity",
+                "open_interest",
+                "best_bid",
+                "best_ask",
+                "last_trade_price",
+                "one_day_price_change",
+                "unique_traders_24h",
+                "created_at",
+                "age_hours"
+              ]
+            },
+            "event-screener": {
+              "description": "Screen and discover events",
+              "options": {
+                "sort-by": {
+                  "type": "string",
+                  "default": "volume_24hr",
+                  "enum": [
+                    "volume_24hr",
+                    "volume",
+                    "volume_1wk",
+                    "volume_1mo",
+                    "liquidity",
+                    "open_interest",
+                    "unique_traders_24h",
+                    "age_hours"
+                  ],
+                  "description": "Sort field"
+                },
+                "query": {
+                  "type": "string",
+                  "description": "Search text"
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "active",
+                    "closed"
+                  ],
+                  "description": "Event status filter (default: active)"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "event_id",
+                "event_title",
+                "tags",
+                "neg_risk",
+                "market_count",
+                "markets",
+                "total_volume",
+                "total_volume_24hr",
+                "total_volume_1wk",
+                "total_volume_1mo",
+                "total_volume_change_pct",
+                "total_liquidity",
+                "total_open_interest",
+                "total_traders_24h",
+                "max_age_hours",
+                "top_market_id",
+                "top_market_question",
+                "top_market_volume_24hr"
+              ]
+            },
+            "pnl-by-market": {
+              "description": "PnL leaderboard for a market",
+              "options": {
+                "market-id": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Market ID"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "address",
+                "owner_address",
+                "side_held",
+                "net_buy_cost_usd",
+                "net_sell_proceeds_usd",
+                "redemption_value_usd",
+                "unrealized_value_usd",
+                "total_pnl_usd",
+                "question",
+                "event_id",
+                "event_title",
+                "market_resolved",
+                "market_id"
+              ]
+            },
+            "pnl-by-address": {
+              "description": "PnL breakdown for an address",
+              "options": {
+                "address": {
+                  "type": "string",
+                  "required": true,
+                  "description": "EVM address (Polygon)"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "address",
+                "market_id",
+                "question",
+                "event_id",
+                "event_title",
+                "side_held",
+                "net_buy_cost_usd",
+                "net_sell_proceeds_usd",
+                "redemption_value_usd",
+                "unrealized_value_usd",
+                "total_pnl_usd",
+                "market_resolved"
+              ]
+            },
+            "position-detail": {
+              "description": "Detailed position data",
+              "options": {
+                "market-id": {
+                  "type": "string",
+                  "required": true,
+                  "description": "Market ID"
+                },
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "address",
+                "owner_address",
+                "outcome",
+                "outcome_index",
+                "token_id",
+                "balance",
+                "buy_cost_usd",
+                "buy_tokens",
+                "sell_proceeds_usd",
+                "sell_tokens",
+                "avg_entry_price",
+                "current_price",
+                "unrealized_value_usd",
+                "redemption_value_usd",
+                "token_pnl_usd",
+                "event_id",
+                "event_title",
+                "market_resolved",
+                "market_id"
+              ]
+            },
+            "categories": {
+              "description": "List market categories",
+              "options": {
+                "limit": {
+                  "type": "number",
+                  "description": "Number of results"
+                }
+              },
+              "returns": [
+                "category",
+                "active_markets",
+                "total_open_interest",
+                "total_volume",
+                "total_volume_24hr",
+                "total_volume_1wk",
+                "total_traders_24h",
+                "top_market_id",
+                "top_market_question",
+                "top_market_volume_24hr"
+              ]
+            }
+          }
+        },
         "points": {
           "description": "Nansen Points analytics",
           "subcommands": {
@@ -1576,10 +1767,6 @@
                 },
                 "limit": {
                   "type": "number"
-                },
-                "page": {
-                  "type": "number",
-                  "description": "Page number for paginated results (default: 1)"
                 }
               },
               "returns": [
@@ -1622,7 +1809,7 @@
             },
             "wallet": {
               "type": "string",
-              "description": "Wallet name (or \"walletconnect\"/\"wc\" for WalletConnect, EVM only). A configured wallet is required \u2014 run `nansen wallet create` if you haven't set one up yet."
+              "description": "Wallet name (or \"walletconnect\"/\"wc\" for WalletConnect, EVM only). A configured wallet is required — run `nansen wallet create` if you haven't set one up yet."
             }
           },
           "prerequisites": [

package/src/wallet.js

@@ -546,7 +546,7 @@ export function buildWalletCommands(deps = {}) {
             if (result.isDefault) log(`  ★ Set as default wallet`);
             log('');
             log('  Fund this wallet to start making API calls or trading:');
-            log(`    Base (recommended, lower fees): send USDC to ${result.evm}`);
+            log(`    Base: send USDC to ${result.evm}`);
             log(`    Solana: send USDC to ${result.solana}`);
             log('');
             if (password === null) {