nansen-cli 1.11.2 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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
+
+- [#207](https://github.com/nansen-ai/nansen-cli/pull/207) [`73ca500`](https://github.com/nansen-ai/nansen-cli/commit/73ca5009c03ad541673165ca6b50f33ff4cc1673) Thanks [@TimNooren](https://github.com/TimNooren)! - Add --unsafe-no-password flag to wallet create for agent-friendly passwordless wallets.
+
+### Patch Changes
+
+- [#212](https://github.com/nansen-ai/nansen-cli/pull/212) [`726c29d`](https://github.com/nansen-ai/nansen-cli/commit/726c29d2676c8a37772299c6237b44890493dfa5) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Clarify empty input handling in parseAddressList with explicit early return
+
+- [#218](https://github.com/nansen-ai/nansen-cli/pull/218) [`8c4dd71`](https://github.com/nansen-ai/nansen-cli/commit/8c4dd71ce215026e149a6b097540c46622f13d3a) Thanks [@TimNooren](https://github.com/TimNooren)! - fix: `nansen changelog --since <version>` now correctly filters changeset-format entries (## x.y.z) in addition to Keep a Changelog entries (## [x.y.z])
+
+- [#209](https://github.com/nansen-ai/nansen-cli/pull/209) [`a6dc1ed`](https://github.com/nansen-ai/nansen-cli/commit/a6dc1ed9dc40ad3506e7debe09746d463a70c14d) Thanks [@0xlaveen](https://github.com/0xlaveen)! - fix: prevent --help from executing destructive commands (logout, schema, cache)
+
 ## 1.11.2
 
 ### Patch 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.11.2",
+  "version": "1.13.0",
   "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

@@ -582,7 +582,9 @@ export class NansenAPI {
                     // No API key and no payment wallet — guide the user to login rather than
                     // showing a confusing x402 payment dump they can't act on.
                     // TODO: full fix would skip x402 entirely when no apiKey is set — see PR #<this PR number>
-                    message = 'No API key configured. Run: nansen login --api-key <key>. Get your key at https://app.nansen.ai/api';
+                    message = 'No API key configured. Two ways to authenticate:\n' +
+                      '  1. API key: nansen login --api-key <key> (get key at https://app.nansen.ai/api)\n' +
+                      '  2. x402 micropayment: nansen wallet create + fund with USDC (no API key needed)';
                   } else {
                     message = `x402 auto-payment failed: ${x402Err.message}`;
                   }
@@ -1101,6 +1103,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/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;
           }
         }
@@ -439,6 +450,37 @@ async function enrichTransfers(result, apiInstance, chain) {
   return result;
 }
 
+// ============= Address Parsing =============
+
+/**
+ * Parse an --addresses option that may arrive as:
+ *  - a pre-parsed array (arg parser split it)
+ *  - a JSON array string: '["0x…","0x…"]'
+ *  - a comma-separated string: "0x…,0x…"
+ * Non-array JSON values (objects, numbers, booleans) are rejected.
+ */
+export function parseAddressList(raw) {
+  if (Array.isArray(raw)) {
+    return raw.map(a => String(a).trim()).filter(Boolean);
+  }
+  if (!raw) return [];
+
+  const s = String(raw);
+  try {
+    const parsed = JSON.parse(s);
+    if (Array.isArray(parsed)) {
+      return parsed.map(a => String(a).trim()).filter(Boolean);
+    }
+    throw new NansenError(
+      '--addresses must be a comma-separated list or JSON array, got: ' + typeof parsed,
+      ErrorCode.INVALID_PARAMS
+    );
+  } catch (e) {
+    if (e instanceof NansenError) throw e;
+    return s.split(',').map(a => a.trim()).filter(Boolean);
+  }
+}
+
 // ============= Composite Functions =============
 
 export async function batchProfile(api, params = {}) {
@@ -644,7 +686,7 @@ EXAMPLES:
   nansen research profiler balance --address 0x... --chain ethereum
   nansen trade quote --chain base --from ETH --to USDC --amount 1
 
-Research chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
+Research chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, zksync, mantle, ronin, sei, plasma, sonic, unichain, monad, hyperevm, iotaevm
 Trade chains: solana, base
 Labels: Fund, Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader
 
@@ -780,6 +822,10 @@ export function buildCommands(deps = {}) {
     },
 
     'changelog': async (_args, _apiInstance, _flags, _options) => {
+      if (_flags.help || _flags.h) {
+        log('changelog — Show release history\n\nUsage:\n  nansen changelog [--since <version>]\n\nOptions:\n  --since <version>   Show only entries for versions >= this version\n\nExamples:\n  nansen changelog\n  nansen changelog --since 1.10.0');
+        return;
+      }
       const changelogPath = new URL('../CHANGELOG.md', import.meta.url).pathname;
       let content;
       try {
@@ -795,10 +841,10 @@ export function buildCommands(deps = {}) {
         const filtered = [];
         let include = false;
         for (const line of lines) {
-          // Match ## [x.y.z] headers
-          const match = line.match(/^## \[(\d+\.\d+\.\d+)\]/);
+          // Match ## [x.y.z] (Keep a Changelog format) or ## x.y.z (changeset format)
+          const match = line.match(/^## \[(\d+\.\d+\.\d+)\]|^## (\d+\.\d+\.\d+)\b/);
           if (match) {
-            const ver = match[1];
+            const ver = match[1] || match[2];
             // Compare: include versions >= since, stop at versions < since
             if (compareSemver(ver, since) >= 0) {
               include = true;
@@ -945,7 +991,7 @@ export function buildCommands(deps = {}) {
         'batch': () => {
           let addresses = [];
           if (options.addresses) {
-            addresses = options.addresses.split(',').map(a => a.trim()).filter(Boolean);
+            addresses = parseAddressList(options.addresses);
           } else if (options.file) {
             const content = fs.readFileSync(options.file, 'utf8');
             try {
@@ -976,13 +1022,13 @@ export function buildCommands(deps = {}) {
           return traceCounterparties(apiInstance, { address, chain, depth, width, days, delayMs });
         },
         'compare': () => {
-          const addrs = (options.addresses || '').split(',').map(a => a.trim()).filter(Boolean);
+          const addrs = parseAddressList(options.addresses);
           return compareWallets(apiInstance, { addresses: addrs, chain, days });
         },
         'help': () => ({
           commands: ['balance', 'labels', 'transactions', 'pnl', 'search', 'historical-balances', 'related-wallets', 'counterparties', 'pnl-summary', 'perp-positions', 'perp-trades', 'batch', 'trace', 'compare'],
           description: 'Wallet profiling endpoints',
-          example: 'nansen profiler balance --address 0x123... --chain ethereum'
+          example: 'nansen research profiler compare --addresses "0xABC...,0xDEF..." --chain ethereum'
         })
       };
 
@@ -1182,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];
@@ -1263,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;
 
@@ -1294,7 +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';
-  let example = `nansen ${command} ${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>'}`;
@@ -1362,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();
@@ -1408,6 +1492,20 @@ export async function runCLI(rawArgs, deps = {}) {
         return { type: 'command-help', command };
       }
     }
+    // Simple commands (logout, schema, cache) — show help instead of executing
+    // Prevents destructive commands like logout from running when user just wants help
+    if (commands[command]) {
+      const simpleHelp = {
+        'logout': 'nansen logout — Remove saved API key from ~/.nansen/config.json',
+        'schema': 'nansen schema [command] [--pretty] — Show JSON schema for all commands (or a specific command)',
+        'cache':  'nansen cache clear — Clear the API response cache',
+      };
+      if (simpleHelp[command]) {
+        output(simpleHelp[command]);
+        notify();
+        return { type: 'command-help', command };
+      }
+    }
     // Commands with handlers (e.g. quote, execute) show their own usage
     if (command === 'help' || !commands[command]) {
       output(BANNER + HELP);