nansen-cli 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 1.11.0
+
+### Minor Changes
+
+- [#186](https://github.com/nansen-ai/nansen-cli/pull/186) [`feecc50`](https://github.com/nansen-ai/nansen-cli/commit/feecc5080254b55aaef0addb646279d52a468063) Thanks [@TimNooren](https://github.com/TimNooren)! - Trade commands output to stdout instead of stderr; wallet send prints human-readable text instead of JSON
+
+### Patch Changes
+
+- [#166](https://github.com/nansen-ai/nansen-cli/pull/166) [`c1034db`](https://github.com/nansen-ai/nansen-cli/commit/c1034dbb4bf2fc173f377cbc0adbbbe3e67873aa) Thanks [@0xlaveen](https://github.com/0xlaveen)! - fix: pass --page parameter correctly in smart-money, profiler, token, perp, and points commands
+
+- [#137](https://github.com/nansen-ai/nansen-cli/pull/137) [`1214767`](https://github.com/nansen-ai/nansen-cli/commit/12147675aadfd0bd97627cb2f41f1dcc5205b0d7) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Add missing sort/filters options to profiler schema and fix pnl sort/filters forwarding
+
+## 1.10.1
+
+### Patch Changes
+
+- [#133](https://github.com/nansen-ai/nansen-cli/pull/133) [`4cbeb65`](https://github.com/nansen-ai/nansen-cli/commit/4cbeb6510c286660f611117d2d8b0508f2340e31) Thanks [@0xlaveen](https://github.com/0xlaveen)! - fix: correct profiler pagination parameter from `recordsPerPage` to `per_page`; remove unsupported pagination from pnl-summary; add --limit to labels, historical-balances, counterparties schema
+
+- [#164](https://github.com/nansen-ai/nansen-cli/pull/164) [`ec6ab78`](https://github.com/nansen-ai/nansen-cli/commit/ec6ab78d604a177c3459833091531de3fc07add1) Thanks [@DMagowan](https://github.com/DMagowan)! - fix: correct `--date` option marked as `required: true` when it is optional
+
+  The schema incorrectly marked `--date` as `required: true` for three commands:
+
+  - `research token flows`
+  - `research token who-bought-sold`
+  - `research profiler transactions`
+
+  All three use `parseDateOption` with a `days` fallback, so `--date` is optional — omitting it defaults to a rolling window based on `--days`. An agent following the schema strictly would unnecessarily refuse to run these commands without a date.
+
+- [#162](https://github.com/nansen-ai/nansen-cli/pull/162) [`4dbe181`](https://github.com/nansen-ai/nansen-cli/commit/4dbe181d3b4973881bcb7fb445cf6559819006b6) Thanks [@DMagowan](https://github.com/DMagowan)! - fix: surface wallet prerequisite in `trade quote` help text and schema
+
+  `nansen trade quote` requires a configured wallet (the trading API builds a transaction specific to the sender address), but this was not communicated until the command failed. Adds a PREREQUISITE section to the usage text and a `prerequisites` field to the schema so agents can discover this requirement before running the command.
+
+- [#165](https://github.com/nansen-ai/nansen-cli/pull/165) [`92f37ea`](https://github.com/nansen-ai/nansen-cli/commit/92f37eaa8655ae1a39b9200aafaf4771a0859229) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Fix trading docs and config to reflect actual supported chains (Base and Solana only)
+
 ## 1.10.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/nansen-cli.svg)](https://www.npmjs.com/package/nansen-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Built by agents, for agents.** Command-line interface for the [Nansen API](https://docs.nansen.ai) with structured JSON output.
+> **Built by agents, for agents.** Command-line interface for the [Nansen API](https://docs.nansen.ai), designed for AI agents.
 
 ## Installation
 
@@ -32,7 +32,7 @@ nansen schema [command] [--pretty]    # full command reference (no API key neede
 
 **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `search`, `perp`, `points`
 
-**Trade:** `quote`, `execute` — DEX swaps via LiFi/Jupiter.
+**Trade:** `quote`, `execute` — DEX swaps on Solana and Base.
 
 **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local keypairs (EVM + Solana).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "src/*.js",
+    "src/*.json",
     "CHANGELOG.md"
   ],
   "scripts": {
@@ -60,4 +61,4 @@
     "globals": "^17.4.0",
     "vitest": "^4.0.18"
   }
-}
+}

package/src/api.js

@@ -62,7 +62,7 @@ export class NansenError extends Error {
     this.name = 'NansenError';
     this.code = code;
     this.status = status;
-    this.data = data;
+    this.details = data;
   }
 
   toJSON() {
@@ -70,7 +70,7 @@ export class NansenError extends Error {
       error: this.message,
       code: this.code,
       status: this.status,
-      details: this.data,
+      details: this.details,
     };
   }
 }
@@ -646,11 +646,12 @@ export class NansenAPI {
   }
 
   async smartMoneyPerpTrades(params = {}) {
-    const { filters = {}, orderBy, pagination } = params;
+    const { filters = {}, orderBy, pagination, onlyNewPositions } = params;
     return this.request('/api/v1/smart-money/perp-trades', {
       filters,
       order_by: orderBy,
-      pagination
+      pagination,
+      only_new_positions: onlyNewPositions
     });
   }
 
@@ -703,7 +704,7 @@ export class NansenAPI {
   }
 
   async addressLabels(params = {}) {
-    const { address, chain = 'ethereum', pagination = { page: 1, recordsPerPage: 100 } } = params;
+    const { address, chain = 'ethereum', pagination = { page: 1, per_page: 100 } } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -732,7 +733,7 @@ export class NansenAPI {
   }
 
   async addressPnl(params = {}) {
-    const { address, chain = 'ethereum', date, days = 30, pagination } = params;
+    const { address, chain = 'ethereum', date, days = 30, filters = {}, orderBy, pagination } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -742,6 +743,8 @@ export class NansenAPI {
       address,
       chain,
       date: dateRange,
+      filters,
+      order_by: orderBy,
       pagination
     });
   }
@@ -814,7 +817,9 @@ export class NansenAPI {
   }
 
   async addressPnlSummary(params = {}) {
-    const { address, chain = 'ethereum', orderBy, pagination, days = 30 } = params;
+    // Note: pnl-summary endpoint is non-paginated (returns aggregate stats, not a list).
+    // Pagination param intentionally omitted from this request.
+    const { address, chain = 'ethereum', orderBy, days = 30 } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -823,8 +828,7 @@ export class NansenAPI {
       address,
       chain,
       date: buildDateRange(days),
-      order_by: orderBy,
-      pagination
+      order_by: orderBy
     });
   }
 

package/src/cli.js

@@ -17,159 +17,22 @@ const { version: VERSION } = require('../package.json');
 
 // ============= Schema Definition =============
 
-export const SCHEMA = {
-  version: VERSION,
-  commands: {
-    'research': {
-      description: 'Research and analytics commands',
-      subcommands: {
-        'smart-money': {
-          description: 'Smart Money analytics - track sophisticated market participants',
-          subcommands: {
-            'netflow': {
-              description: 'Net capital flows (inflows vs outflows)',
-              options: {
-                chain: { type: 'string', default: 'solana', description: 'Blockchain to query' },
-                chains: { type: 'array', description: 'Multiple chains as JSON array' },
-                limit: { type: 'number', description: 'Number of results' },
-                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: ['token_address', 'token_symbol', 'token_name', 'chain', 'inflow_usd', 'outflow_usd', 'net_flow_usd']
-            },
-            'dex-trades': {
-              description: 'Real-time DEX trading activity',
-              options: { chain: { type: 'string', default: 'solana' }, chains: { type: 'array' }, limit: { type: 'number' }, labels: { type: 'string|array' }, sort: { type: 'string' }, filters: { type: 'object' } },
-              returns: ['chain', 'block_timestamp', 'transaction_hash', 'trader_address', 'trader_address_label', 'token_bought_address', 'token_sold_address', 'token_bought_amount', 'token_sold_amount', 'token_bought_symbol', 'token_sold_symbol', 'trade_value_usd']
-            },
-            'perp-trades': {
-              description: 'Perpetual trading on Hyperliquid',
-              options: { limit: { type: 'number' }, sort: { type: 'string' }, filters: { type: 'object' } },
-              returns: ['trader_address', 'trader_address_label', 'token_symbol', 'side', 'action', 'token_amount', 'price_usd', 'value_usd', 'type', 'block_timestamp', 'transaction_hash']
-            },
-            'holdings': {
-              description: 'Aggregated token balances',
-              options: { chain: { type: 'string', default: 'solana' }, chains: { type: 'array' }, limit: { type: 'number' }, labels: { type: 'string|array' } },
-              returns: ['chain', 'token_address', 'token_symbol', 'token_sectors', 'value_usd', 'balance_24h_percent_change', 'holders_count', 'share_of_holdings_percent', 'token_age_days', 'market_cap_usd']
-            },
-            'dcas': {
-              description: 'DCA strategies on Jupiter',
-              options: { limit: { type: 'number' }, filters: { type: 'object' } },
-              returns: ['dca_created_at', 'dca_updated_at', 'trader_address', 'trader_address_label', 'dca_vault_address', 'input_token_address', 'output_token_address', 'deposit_token_amount', 'token_spent_amount', 'output_token_redeemed_amount', 'dca_status', 'input_token_symbol', 'output_token_symbol', 'deposit_value_usd']
-            },
-            'historical-holdings': {
-              description: 'Historical holdings over time',
-              options: { chain: { type: 'string', default: 'solana' }, chains: { type: 'array' }, days: { type: 'number', default: 30 }, limit: { type: 'number' } },
-              returns: ['date', 'token_address', 'token_symbol', 'balance', 'balance_usd']
-            }
-          }
-        },
-        'profiler': {
-          description: 'Wallet profiling - detailed information about any blockchain address',
-          subcommands: {
-            'balance': { description: 'Current token holdings', options: { address: { type: 'string', required: true, description: 'Wallet address to query' }, chain: { type: 'string', default: 'ethereum' }, entity: { type: 'string', description: 'Entity name instead of address' } }, returns: ['chain', 'address', 'token_address', 'token_symbol', 'token_name', 'token_amount', 'price_usd', 'value_usd'] },
-            'labels': { description: 'Behavioral and entity labels', options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' } }, returns: ['label', 'label_type', 'label_subtype'] },
-            'transactions': { description: 'Transaction history', options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, date: { type: 'string', required: true, description: 'Date or date range' }, limit: { type: 'number' }, days: { type: 'number', default: 30 } }, returns: ['chain', 'method', 'tokens_sent', 'tokens_received', 'volume_usd', 'block_timestamp', 'transaction_hash'] },
-            'pnl': { description: 'PnL and trade performance', options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, date: { type: 'string', description: 'Date or date range' }, days: { type: 'number', default: 30 }, limit: { type: 'number' } }, returns: ['token_address', 'token_symbol', 'realized_pnl_usd', 'unrealized_pnl_usd', 'total_pnl_usd'] },
-            'search': { description: 'Search for entities by name', options: { query: { type: 'string', required: true, description: 'Search query' }, limit: { type: 'number' } }, returns: ['entity_name'] },
-            'historical-balances': { description: 'Historical balances over time', options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, days: { type: 'number', default: 30 } }, returns: ['date', 'token_address', 'token_symbol', 'balance', 'balance_usd'] },
-            'related-wallets': { description: 'Find wallets related to an address', options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, limit: { type: 'number' } }, returns: ['address', 'address_label', 'relation', 'transaction_hash', 'block_timestamp', 'order', 'chain'] },
-            'counterparties': { description: 'Top counterparties by volume', options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, days: { type: 'number', default: 30 } }, returns: ['counterparty_address', 'counterparty_address_label', 'interaction_count', 'total_volume_usd', 'volume_in_usd', 'volume_out_usd', 'tokens_info'] },
-            'pnl-summary': { description: 'Summarized PnL metrics', options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, days: { type: 'number', default: 30 } }, returns: ['top5_tokens', 'traded_token_count', 'traded_times', 'realized_pnl_usd', 'realized_pnl_percent', 'win_rate'] },
-            'perp-positions': { description: 'Current perpetual positions', options: { address: { type: 'string', required: true }, limit: { type: 'number' } }, returns: ['symbol', 'side', 'size', 'entry_price', 'mark_price', 'unrealized_pnl', 'leverage'] },
-            'perp-trades': { description: 'Perpetual trading history', options: { address: { type: 'string', required: true }, days: { type: 'number', default: 30 }, limit: { type: 'number' } }, returns: ['symbol', 'side', 'size', 'price', 'value_usd', 'pnl_usd', 'timestamp'] },
-            'batch': { description: 'Batch profile multiple addresses', options: { addresses: { type: 'string', description: 'Comma-separated addresses' }, file: { type: 'string', description: 'File with one address per line' }, chain: { type: 'string', default: 'ethereum' }, include: { type: 'string', default: 'labels,balance', description: 'Comma-separated: labels,balance,pnl' }, delay: { type: 'number', default: 1000, description: 'Delay between requests in ms' } }, returns: ['address', 'chain', 'labels', 'balance', 'pnl', 'error'] },
-            'trace': { description: 'Multi-hop counterparty trace (BFS)', options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, depth: { type: 'number', default: 2, description: 'Max hops (1-5)' }, width: { type: 'number', default: 10, description: 'Top N counterparties per hop' }, days: { type: 'number', default: 30 }, delay: { type: 'number', default: 1000, description: 'Delay between requests in ms' } }, returns: ['root', 'chain', 'depth', 'nodes', 'edges', 'stats'] },
-            'compare': { description: 'Compare two wallets (shared counterparties, tokens)', options: { addresses: { type: 'string', required: true, description: 'Two comma-separated addresses' }, chain: { type: 'string', default: 'ethereum' }, days: { type: 'number', default: 30 } }, returns: ['addresses', 'chain', 'shared_counterparties', 'shared_tokens', 'balances'] }
-          }
-        },
-        'token': {
-          description: 'Token God Mode - deep analytics for any token',
-          subcommands: {
-            'indicators': { description: 'Risk and reward indicators for a token (Nansen Score)', options: { token: { type: 'string', required: true, description: 'Token address' }, chain: { type: 'string', default: 'ethereum' } }, returns: ['token_info[market_cap_usd, market_cap_group, is_stablecoin]', 'risk_indicators[indicator_type, score, signal, signal_percentile, last_trigger_on]', 'reward_indicators[indicator_type, score, signal, signal_percentile, last_trigger_on]'] },
-            'ohlcv': { description: 'OHLCV candle data for a token', options: { token: { type: 'string', required: true, description: 'Token address' }, chain: { type: 'string', default: 'solana' }, timeframe: { type: 'string', default: '1h', enum: ['1m', '5m', '15m', '30m', '1h', '2h', '4h', '1d', '1w', '1M'], description: 'Candle timeframe (e.g., 1h, 4h, 1d)' } }, returns: ['timestamp', 'open', 'high', 'low', 'close', 'volume'] },
-            'info': { description: 'Get detailed information for a specific token', options: { token: { type: 'string', required: true, description: 'Token address' }, chain: { type: 'string', default: 'solana' }, timeframe: { type: 'string', default: '1d', enum: ['5m', '1h', '6h', '12h', '1d', '7d'] } }, returns: ['token_address', 'token_symbol', 'token_name', 'chain', 'price_usd', 'volume_usd', 'market_cap', 'holder_count', 'liquidity_usd'] },
-            'screener': { description: 'Discover and filter tokens', options: { chain: { type: 'string', default: 'solana' }, chains: { type: 'array' }, timeframe: { type: 'string', default: '24h', enum: ['5m', '10m', '1h', '6h', '24h', '7d', '30d'] }, 'smart-money': { type: 'boolean', description: 'Filter for Smart Money only' }, search: { type: 'string', description: 'Filter results by token symbol or name (client-side)' }, limit: { type: 'number' }, sort: { type: 'string' } }, returns: ['token_address', 'token_symbol', 'token_name', 'chain', 'price_usd', 'volume_usd', 'market_cap', 'holder_count', 'smart_money_holders'] },
-            'holders': { description: 'Token holder analysis', options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, 'smart-money': { type: 'boolean' }, limit: { type: 'number' } }, returns: ['address', 'address_label', 'token_amount', 'total_outflow', 'total_inflow', 'balance_change_24h', 'balance_change_7d', 'balance_change_30d', 'ownership_percentage', 'value_usd'] },
-            'flows': { description: 'Token flow metrics', options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, date: { type: 'string', required: true, description: 'Date or date range' }, days: { type: 'number', default: 30 }, limit: { type: 'number' } }, returns: ['date', 'price_usd', 'token_amount', 'value_usd', 'holders_count', 'total_inflows_count', 'total_outflows_count'] },
-            'dex-trades': { description: 'DEX trading activity', options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, 'smart-money': { type: 'boolean' }, days: { type: 'number', default: 30 }, limit: { type: 'number' } }, returns: ['tx_hash', 'wallet_address', 'side', 'amount', 'price_usd', 'value_usd', 'timestamp'] },
-            'pnl': { description: 'PnL leaderboard', options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, days: { type: 'number', default: 30 }, limit: { type: 'number' }, sort: { type: 'string' } }, returns: ['wallet_address', 'realized_pnl_usd', 'unrealized_pnl_usd', 'total_pnl_usd', 'labels'] },
-            'who-bought-sold': { description: 'Recent buyers and sellers', options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, date: { type: 'string', required: true, description: 'Date or date range' }, days: { type: 'number', default: 30 }, limit: { type: 'number' } }, returns: ['address', 'address_label', 'bought_token_volume', 'sold_token_volume', 'token_trade_volume', 'bought_volume_usd', 'sold_volume_usd', 'trade_volume_usd'] },
-            'flow-intelligence': { description: 'Detailed flow intelligence by label', options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, days: { type: 'number', default: 30 } }, returns: ['public_figure_net_flow_usd', 'public_figure_wallet_count', 'top_pnl_net_flow_usd', 'top_pnl_wallet_count', 'whale_net_flow_usd', 'whale_wallet_count', 'smart_trader_net_flow_usd', 'smart_trader_wallet_count', 'exchange_net_flow_usd', 'exchange_wallet_count', 'fresh_wallets_net_flow_usd', 'fresh_wallets_wallet_count'] },
-            'transfers': { description: 'Token transfer history', options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, days: { type: 'number', default: 30 }, limit: { type: 'number' }, from: { type: 'string', description: 'Filter by sender address' }, to: { type: 'string', description: 'Filter by recipient address' }, enrich: { type: 'boolean', description: 'Enrich addresses with Nansen labels' } }, returns: ['tx_hash', 'from', 'to', 'amount', 'value_usd', 'timestamp'] },
-            'jup-dca': { description: 'Jupiter DCA orders for token', options: { token: { type: 'string', required: true }, limit: { type: 'number' } }, returns: ['wallet_address', 'input_token', 'output_token', 'total_input', 'executed', 'remaining'] },
-            'perp-trades': { description: 'Perp trades by token symbol', options: { symbol: { type: 'string', required: true, description: 'Token symbol (e.g., BTC, ETH)' }, days: { type: 'number', default: 30 }, limit: { type: 'number' } }, returns: ['wallet_address', 'side', 'size', 'price', 'value_usd', 'pnl_usd', 'timestamp'] },
-            'perp-positions': { description: 'Open perp positions by token symbol', options: { symbol: { type: 'string', required: true }, limit: { type: 'number' } }, returns: ['wallet_address', 'side', 'size', 'entry_price', 'mark_price', 'unrealized_pnl', 'leverage'] },
-            'perp-pnl-leaderboard': { description: 'Perp PnL leaderboard by token', options: { symbol: { type: 'string', required: true }, days: { type: 'number', default: 30 }, limit: { type: 'number' } }, returns: ['wallet_address', 'realized_pnl', 'unrealized_pnl', 'total_pnl', 'trade_count'] }
-          }
-        },
-        'search': {
-          description: 'Search for tokens and entities across Nansen',
-          options: {
-            query: { type: 'string', required: true, description: 'Search query (token name, symbol, address, or entity)' },
-            type: { type: 'string', default: 'any', enum: ['token', 'entity', 'any'], description: 'Result type filter' },
-            chain: { type: 'string', description: 'Filter by chain (e.g., ethereum, solana)' },
-            limit: { type: 'number', default: 25, description: 'Max results (1-50)' }
-          },
-          returns: ['tokens[name, symbol, chain, address, price, volume_24h, market_cap, rank]', 'entities[name, tags, rank]', 'total_results']
-        },
-        'perp': {
-          description: 'Perpetual futures analytics',
-          subcommands: {
-            'screener': { description: 'Screen perpetual futures contracts', options: { days: { type: 'number', default: 30 }, limit: { type: 'number' }, sort: { type: 'string' }, filters: { type: 'object' } }, returns: ['token_symbol', 'volume_usd', 'open_interest', 'funding_rate', 'price_change_24h'] },
-            'leaderboard': { description: 'Perpetual futures PnL leaderboard', options: { days: { type: 'number', default: 30 }, limit: { type: 'number' }, sort: { type: 'string' }, filters: { type: 'object' } }, returns: ['address', 'address_label', 'realized_pnl', 'unrealized_pnl', 'total_pnl', 'trade_count', 'win_rate'] }
-          }
-        },
-        'portfolio': {
-          description: 'Portfolio analytics',
-          subcommands: {
-            'defi': { description: 'DeFi holdings across protocols', options: { wallet: { type: 'string', required: true, description: 'Wallet address' } }, returns: ['protocol', 'chain', 'position_type', 'token_symbol', 'balance', 'balance_usd'] }
-          }
-        },
-        'points': {
-          description: 'Nansen Points analytics',
-          subcommands: {
-            'leaderboard': { description: 'Points leaderboard', options: { tier: { type: 'string', description: 'Filter by tier' }, limit: { type: 'number' } }, returns: ['rank', 'address', 'address_label', 'points', 'tier'] }
-          }
-        }
-      }
-    },
-    'trade': {
-      description: 'DEX trading commands',
-      subcommands: {
-        'quote': {
-          description: 'Get a DEX swap quote (chain, tokens, amount)',
-          options: {
-            chain: { type: 'string', default: 'ethereum', description: 'Blockchain' },
-            from: { type: 'string', required: true, description: 'Token to sell (address or symbol)' },
-            to: { type: 'string', required: true, description: 'Token to buy (address or symbol)' },
-            amount: { type: 'string', required: true, description: 'Amount to swap' },
-            wallet: { type: 'string', description: 'Wallet name, or "walletconnect"/"wc" for WalletConnect (EVM only)' }
-          }
-        },
-        'execute': {
-          description: 'Sign and broadcast a quoted trade',
-          options: {
-            chain: { type: 'string', default: 'ethereum', description: 'Blockchain' },
-            wallet: { type: 'string', description: 'Wallet name, or "walletconnect"/"wc" for WalletConnect (EVM only)' }
-          }
-        }
-      }
-    }
-  },
-  globalOptions: {
-    pretty: { type: 'boolean', description: 'Format JSON output for readability' },
-    table: { type: 'boolean', description: 'Format output as human-readable table' },
-    fields: { type: 'string', description: 'Comma-separated list of fields to include in output' },
-    'no-retry': { type: 'boolean', description: 'Disable automatic retry on rate limits/errors' },
-    retries: { type: 'number', default: 3, description: 'Max retry attempts' },
-    format: { type: 'string', enum: ['json', 'csv'], description: 'Output format (default: json)' },
-    'x402-payment-signature': { type: 'string', description: 'Pre-signed x402 payment signature header' }
-  },
-  chains: ['ethereum', 'solana', 'base', 'bnb', 'arbitrum', 'polygon', 'optimism', 'avalanche', 'linea', 'scroll', 'mantle', 'ronin', 'sei', 'plasma', 'sonic', 'monad', 'hyperevm', 'iotaevm'],
-  smartMoneyLabels: ['Fund', 'Smart Trader', '30D Smart Trader', '90D Smart Trader', '180D Smart Trader', 'Smart HL Perps Trader']
-};
+const schemaDefinition = require('./schema.json');
+
+// SCHEMA is the static definition with version injected at runtime.
+// The schema.json file is the source of truth for command metadata (returns, options, etc.)
+// and should be updated whenever the API changes — do not edit returns arrays here.
+export const SCHEMA = { version: VERSION, ...schemaDefinition };
+
+// ============= Pagination =============
+
+export function buildPagination(options) {
+  if (!options.limit && !options.page) return undefined;
+  return {
+    page: Math.max(1, parseInt(options.page, 10) || 1),
+    per_page: options.limit,
+  };
+}
 
 // ============= Field Filtering =============
 
@@ -460,13 +323,17 @@ export function formatOutput(data, { pretty = false, table = false, csv = false
 
 // Format error data (returns object, does not exit)
 export function formatError(error) {
-  return {
+  const details = error.details ?? error.data ?? null;
+  const result = {
     success: false,
     error: error.message,
     code: error.code || 'UNKNOWN',
     status: error.status || null,
-    details: error.data || null
   };
+  if (details != null && !(typeof details === 'object' && !Array.isArray(details) && Object.keys(details).length === 0)) {
+    result.details = details;
+  }
+  return result;
 }
 
 /**
@@ -753,7 +620,7 @@ export async function compareWallets(api, params = {}) {
 
 export const BANNER = '';
 
-export const HELP = `Nansen CLI v${VERSION} — structured JSON output for AI agents.
+export const HELP = `Nansen CLI v${VERSION} — designed for AI agents.
 
 USAGE: nansen <command> [subcommand] [options]
 
@@ -1002,7 +869,7 @@ export function buildCommands(deps = {}) {
       const chains = options.chains || [chain];
       const filters = options.filters || {};
       const orderBy = parseSort(options.sort, options['order-by']);
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
 
       // Add smart money label filter if specified
       if (options.labels) {
@@ -1016,7 +883,7 @@ export function buildCommands(deps = {}) {
       const handlers = {
         'netflow': () => apiInstance.smartMoneyNetflow({ chains, filters, orderBy, pagination }),
         'dex-trades': () => apiInstance.smartMoneyDexTrades({ chains, filters, orderBy, pagination }),
-        'perp-trades': () => apiInstance.smartMoneyPerpTrades({ filters, orderBy, pagination }),
+        'perp-trades': () => apiInstance.smartMoneyPerpTrades({ filters, orderBy, pagination, onlyNewPositions: options['only-new-positions'] ?? flags['only-new-positions'] }),
         'holdings': () => apiInstance.smartMoneyHoldings({ chains, filters, orderBy, pagination }),
         'dcas': () => apiInstance.smartMoneyDcas({ filters, orderBy, pagination }),
         'historical-holdings': () => apiInstance.smartMoneyHistoricalHoldings({ chains, filters, orderBy, pagination, days }),
@@ -1053,7 +920,7 @@ export function buildCommands(deps = {}) {
       }
       const filters = options.filters || {};
       const orderBy = parseSort(options.sort, options['order-by']);
-      const pagination = options.limit ? { page: 1, recordsPerPage: options.limit } : undefined;
+      const pagination = buildPagination(options);
       const days = options.days ? parseInt(options.days) : 30;
 
       const handlers = {
@@ -1065,7 +932,7 @@ export function buildCommands(deps = {}) {
         },
         'pnl': () => {
           const date = parseDateOption(options.date, days);
-          return apiInstance.addressPnl({ address, chain, date, days, pagination });
+          return apiInstance.addressPnl({ address, chain, date, days, filters, orderBy, pagination });
         },
         'search': () => apiInstance.entitySearch({ query: options.query }),
         'historical-balances': () => apiInstance.addressHistoricalBalances({ address, chain, filters, orderBy, pagination, days }),
@@ -1139,7 +1006,7 @@ export function buildCommands(deps = {}) {
       const timeframe = options.timeframe || '24h';
       const filters = options.filters || {};
       const orderBy = parseSort(options.sort, options['order-by']);
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
       const days = options.days ? parseInt(options.days) : 30;
 
       // Convenience filter for smart money only
@@ -1245,7 +1112,7 @@ export function buildCommands(deps = {}) {
       const subcommand = args[0] || 'help';
       const filters = options.filters || {};
       const orderBy = parseSort(options.sort, options['order-by']);
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
       const days = options.days ? parseInt(options.days) : 30;
 
       const handlers = {
@@ -1277,7 +1144,7 @@ export function buildCommands(deps = {}) {
     'points': async (args, apiInstance, flags, options) => {
       const subcommand = args[0] || 'help';
       const tier = options.tier;
-      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const pagination = buildPagination(options);
 
       const handlers = {
         'leaderboard': () => apiInstance.pointsLeaderboard({ tier, pagination }),
@@ -1342,7 +1209,7 @@ WALLET:
                     Defaults to the default local wallet if omitted.
 
 SYMBOLS:
-  Common tokens resolve automatically: SOL, ETH, BNB, USDC, USDT, WETH, WBNB
+  Common tokens resolve automatically: SOL, ETH, USDC, USDT, WETH
   Raw addresses are also accepted.`);
       return;
     }

package/src/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 /**
  * Nansen CLI - Command-line interface for Nansen API
- * Designed for AI agents with structured JSON output
- * 
+ * Designed for AI agents.
+ *
  * Usage: nansen <command> [options]
- * 
- * All output is JSON for easy parsing by AI agents.
+ *
+ * Research commands return JSON; operational commands print human-readable text.
  * Use --pretty for human-readable formatting.
  * 
  * Core logic lives in cli.js for testability.