nansen-cli 1.3.0 → 1.3.2

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in the repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/CLAUDE.md

@@ -136,12 +136,14 @@ Structured error codes for programmatic handling:
 |------|-------------|
 | `UNAUTHORIZED` | Invalid or missing API key (401) |
 | `FORBIDDEN` | Valid key but insufficient permissions (403) |
+| `CREDITS_EXHAUSTED` | Insufficient API credits (403) — do not retry |
 | `RATE_LIMITED` | Too many requests (429) |
 | `INVALID_ADDRESS` | Address format validation failed |
 | `INVALID_TOKEN` | Token address validation failed |
 | `INVALID_CHAIN` | Unsupported or invalid chain |
 | `INVALID_PARAMS` | Generic parameter validation error |
 | `MISSING_PARAM` | Required parameter not provided |
+| `UNSUPPORTED_FILTER` | Filter not supported for this token/chain (400) |
 | `NOT_FOUND` | Resource not found (404) |
 | `TOKEN_NOT_FOUND` | Token doesn't exist |
 | `ADDRESS_NOT_FOUND` | Address has no data |
@@ -176,6 +178,15 @@ Structured error codes for programmatic handling:
 - **Beta endpoints** (`/api/beta/...`) may have different pagination
 - **EVM vs Solana addresses** — validation auto-detects based on chain param
 
+## Changesets
+
+Every PR that changes user-facing behavior must include a changeset:
+```bash
+npx changeset
+```
+Choose `patch` for bug fixes, `minor` for new features, `major` for breaking changes.
+CI will not publish without a changeset.
+
 ## PR Checklist
 
 - [ ] Tests pass (`npm test`)

package/README.md

@@ -2,8 +2,8 @@
 
 [![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)
-[![Tests](https://img.shields.io/badge/tests-323%20passing-brightgreen.svg)]()
-[![Coverage](https://img.shields.io/badge/coverage-80%25-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-325%20passing-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-83%25-brightgreen.svg)]()
 
 > **Built by agents, for agents.** We prioritize the best possible AI agent experience.
 

package/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: nansen-cli
+description: Query the Nansen API for onchain analytics - Smart Money flows, wallet profiling, token analysis, and DeFi portfolio data. Use when analyzing crypto wallets, tracking smart money activity, or researching tokens.
+license: MIT
+metadata:
+  author: nansen-ai
+  version: "1.3.0"
+compatibility: Requires Node.js 18+. Needs NANSEN_API_KEY environment variable or run `nansen login`.
+---
+
+# Nansen CLI
+
+Command-line interface for the [Nansen API](https://docs.nansen.ai) - onchain analytics for crypto investors and AI agents.
+
+## Setup
+
+```bash
+# Install globally
+npm install -g nansen-cli
+
+# Authenticate (interactive)
+nansen login
+
+# Or set environment variable
+export NANSEN_API_KEY=your-api-key
+```
+
+Get your API key at [app.nansen.ai/api](https://app.nansen.ai/api).
+
+## Commands
+
+### Smart Money
+Track sophisticated market participants:
+```bash
+nansen smart-money netflow --chain solana --pretty
+nansen smart-money dex-trades --chain solana --labels "Smart Trader"
+nansen smart-money holdings --chain solana
+```
+
+### Wallet Profiler
+Analyze any wallet:
+```bash
+nansen profiler balance --address 0x123... --chain ethereum
+nansen profiler labels --address 0x123... --chain ethereum
+nansen profiler pnl --address 0x123... --chain ethereum
+nansen profiler search --query "Vitalik"
+```
+
+### Token God Mode
+Deep token analytics:
+```bash
+nansen token screener --chain solana --timeframe 24h
+nansen token holders --token <address> --chain solana --smart-money
+nansen token flows --token <address> --chain solana
+nansen token pnl --token <address> --chain solana
+```
+
+### Portfolio
+DeFi holdings analysis:
+```bash
+nansen portfolio defi --wallet 0x123...
+```
+
+## Output Formats
+
+- **Default**: JSON (for AI agents)
+- `--pretty`: Formatted JSON
+- `--table`: Human-readable table
+- `--stream`: NDJSON (one record per line)
+- `--fields`: Filter specific fields
+
+## Key Options
+
+| Option | Description |
+|--------|-------------|
+| `--chain` | Blockchain (solana, ethereum, base, etc.) |
+| `--chains` | Multiple chains as JSON array |
+| `--limit` | Number of results |
+| `--days` | Date range in days |
+| `--sort` | Sort field (e.g., `value_usd:desc`) |
+| `--smart-money` | Filter for Smart Money only |
+
+## Supported Chains
+
+ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, zksync, mantle, ronin, sei, sonic, monad, hyperevm
+
+## Smart Money Labels
+
+Fund, Smart Trader, 30D Smart Trader, 90D Smart Trader, 180D Smart Trader, Smart HL Perps Trader
+
+## Schema Introspection
+
+Get the full API schema for programmatic use:
+```bash
+nansen schema --pretty
+nansen schema smart-money --pretty
+```
+
+## Known Endpoint Issues
+
+### Chain/Token-Specific Limitations
+- `token holders --smart-money` — Fails with `UNSUPPORTED_FILTER` for tokens without smart money tracking (e.g., WCT on Optimism). Not all tokens have smart money data. Do not retry.
+- `token flow-intelligence` — May return all-zero flows for tokens without significant smart money activity. This is normal, not an error.
+
+### Credit Management
+- `profiler labels` and `profiler balance` consume credits. Budget ~20 calls per session.
+- `Insufficient credits` (403, code `CREDITS_EXHAUSTED`) is a hard stop — no retry will help.
+- Check your Nansen dashboard for credit balance: [app.nansen.ai](https://app.nansen.ai).
+- Run balance checks in batches of 3-4 to avoid burning credits on rate-limit retries.
+
+### Error Codes to Watch
+| Code | Meaning | Action |
+|------|---------|--------|
+| `UNSUPPORTED_FILTER` | Filter not available for this token/chain | Remove the filter and retry, or skip this token |
+| `CREDITS_EXHAUSTED` | API credits depleted | Stop all API calls. Check dashboard. |
+| `RATE_LIMITED` | Too many requests (429) | Wait and retry (automatic with default retry) |
+
+## Examples
+
+```bash
+# Find trending Solana tokens with Smart Money activity
+nansen token screener --chain solana --timeframe 24h --smart-money --pretty
+
+# Check who's accumulating a specific token
+nansen token holders --token So11111111111111111111111111111111111111112 --chain solana --smart-money --limit 20 --pretty
+
+# Profile a whale wallet
+nansen profiler balance --address Gu29tjXrVr9v5n42sX1DNrMiF3BwbrTm379szgB9qXjc --chain solana --pretty
+
+# Track Smart Money flows into memecoins
+nansen smart-money netflow --chain solana --labels "Smart Trader" --pretty
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -12,7 +12,10 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:live": "NANSEN_LIVE_TEST=1 vitest run"
+    "test:live": "NANSEN_LIVE_TEST=1 vitest run",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish"
   },
   "keywords": [
     "nansen",
@@ -31,16 +34,18 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nansen-ai/nansen-cli.git"
+    "url": "git+https://github.com/askeluv/nansen-cli.git"
   },
   "bugs": {
-    "url": "https://github.com/nansen-ai/nansen-cli/issues"
+    "url": "https://github.com/askeluv/nansen-cli/issues"
   },
-  "homepage": "https://github.com/nansen-ai/nansen-cli#readme",
+  "homepage": "https://github.com/askeluv/nansen-cli#readme",
   "engines": {
     "node": ">=18.0.0"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.5.1",
+    "@changesets/cli": "^2.29.4",
     "@vitest/coverage-v8": "^4.0.18",
     "vitest": "^4.0.18"
   }

package/src/api.js

@@ -18,6 +18,7 @@ export const ErrorCode = {
   // Authentication & Authorization
   UNAUTHORIZED: 'UNAUTHORIZED',           // 401 - Invalid or missing API key
   FORBIDDEN: 'FORBIDDEN',                 // 403 - Valid key but insufficient permissions
+  CREDITS_EXHAUSTED: 'CREDITS_EXHAUSTED', // 403 - Insufficient API credits
   
   // Rate Limiting
   RATE_LIMITED: 'RATE_LIMITED',           // 429 - Too many requests
@@ -28,6 +29,7 @@ export const ErrorCode = {
   INVALID_CHAIN: 'INVALID_CHAIN',         // Unsupported or invalid chain
   INVALID_PARAMS: 'INVALID_PARAMS',       // Generic parameter validation error
   MISSING_PARAM: 'MISSING_PARAM',         // Required parameter not provided
+  UNSUPPORTED_FILTER: 'UNSUPPORTED_FILTER', // Filter not supported for this token/chain
   
   // Resource Errors
   NOT_FOUND: 'NOT_FOUND',                 // 404 - Resource not found
@@ -77,6 +79,8 @@ function statusToErrorCode(status, data = {}) {
   
   switch (status) {
     case 400:
+    case 422:
+      if (messageLower.includes('field') && messageLower.includes('not recognized')) return ErrorCode.UNSUPPORTED_FILTER;
       if (messageLower.includes('address')) return ErrorCode.INVALID_ADDRESS;
       if (messageLower.includes('token')) return ErrorCode.INVALID_TOKEN;
       if (messageLower.includes('chain')) return ErrorCode.INVALID_CHAIN;
@@ -84,6 +88,7 @@ function statusToErrorCode(status, data = {}) {
     case 401:
       return ErrorCode.UNAUTHORIZED;
     case 403:
+      if (messageLower.includes('credit') || messageLower.includes('insufficient')) return ErrorCode.CREDITS_EXHAUSTED;
       return ErrorCode.FORBIDDEN;
     case 404:
       if (messageLower.includes('token')) return ErrorCode.TOKEN_NOT_FOUND;
@@ -245,8 +250,8 @@ const ADDRESS_PATTERNS = {
 
 const EVM_CHAINS = [
   'ethereum', 'arbitrum', 'base', 'bnb', 'polygon', 'optimism',
-  'avalanche', 'linea', 'scroll', 'zksync', 'mantle', 'ronin',
-  'sei', 'plasma', 'sonic', 'unichain', 'monad', 'hyperevm', 'iotaevm'
+  'avalanche', 'linea', 'scroll', 'mantle', 'ronin',
+  'sei', 'plasma', 'sonic', 'monad', 'hyperevm', 'iotaevm'
 ];
 
 /**
@@ -334,7 +339,7 @@ const DEFAULT_RETRY_OPTIONS = {
 /**
  * Sleep for a given number of milliseconds
  */
-function sleep(ms) {
+export function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
@@ -392,6 +397,15 @@ export class NansenAPI {
     };
   }
 
+  static cleanBody(body) {
+    return Object.fromEntries(
+      Object.entries(body).filter(([_, v]) =>
+        v !== undefined && v !== null &&
+        !(typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0)
+      )
+    );
+  }
+
   async request(endpoint, body = {}, options = {}) {
     const url = `${this.baseUrl}${endpoint}`;
     const { maxRetries, baseDelayMs, maxDelayMs, retryOnStatus } = this.retryOptions;
@@ -420,7 +434,7 @@ export class NansenAPI {
             'apikey': this.apiKey,
             ...options.headers
           },
-          body: JSON.stringify(body)
+          body: JSON.stringify(NansenAPI.cleanBody(body))
         });
       } catch (err) {
         // Network-level errors - retry these too
@@ -461,10 +475,17 @@ export class NansenAPI {
       }
 
       if (!response.ok) {
-        const message = data.message || data.error || `API error: ${response.status}`;
+        let message = data.message || data.error || `API error: ${response.status}`;
         const code = statusToErrorCode(response.status, data);
         const retryAfterMs = parseRetryAfter(response.headers.get('retry-after'));
-        
+
+        // Enhance messages for specific error codes
+        if (code === ErrorCode.UNSUPPORTED_FILTER) {
+          message = message.replace(/\.+$/, '') + '. This filter is not supported for this token/chain combination. Do not retry.';
+        } else if (code === ErrorCode.CREDITS_EXHAUSTED) {
+          message = message.replace(/\.+$/, '') + '. No retry will help. Check your Nansen dashboard for credit balance.';
+        }
+
         lastError = new NansenError(message, code, response.status, {
           ...data,
           attempt: attempt + 1,
@@ -592,14 +613,20 @@ export class NansenAPI {
   }
 
   async addressTransactions(params = {}) {
-    const { address, chain = 'ethereum', filters = {}, orderBy, pagination } = params;
+    const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30, date } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
+    const dateRange = date || (() => {
+      const to = new Date().toISOString().split('T')[0];
+      const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+      return { from, to };
+    })();
     return this.request('/api/v1/profiler/address/transactions', {
       address,
       chain,
+      date: dateRange,
       filters,
       order_by: orderBy,
       pagination
@@ -619,10 +646,9 @@ export class NansenAPI {
   }
 
   async entitySearch(params = {}) {
-    const { query, pagination } = params;
-    return this.request('/api/beta/profiler/entity-name-search', {
-      parameters: { query },
-      pagination
+    const { query } = params;
+    return this.request('/api/v1/search/entity-name', {
+      search_query: query
     });
   }
 
@@ -645,7 +671,7 @@ export class NansenAPI {
   }
 
   async addressRelatedWallets(params = {}) {
-    const { address, chain = 'ethereum', filters = {}, orderBy, pagination } = params;
+    const { address, chain = 'ethereum', orderBy, pagination } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -653,7 +679,6 @@ export class NansenAPI {
     return this.request('/api/v1/profiler/address/related-wallets', {
       address,
       chain,
-      filters,
       order_by: orderBy,
       pagination
     });
@@ -678,7 +703,7 @@ export class NansenAPI {
   }
 
   async addressPnlSummary(params = {}) {
-    const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
+    const { address, chain = 'ethereum', orderBy, pagination, days = 30 } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -689,20 +714,19 @@ export class NansenAPI {
       address,
       chain,
       date: { from, to },
-      filters,
       order_by: orderBy,
       pagination
     });
   }
 
   async addressPerpPositions(params = {}) {
-    const { address, filters = {}, orderBy, pagination } = params;
+    const { address, filters = {}, orderBy } = params;
     // Perp positions work with HL addresses (not validated)
+    // Note: This endpoint does NOT support pagination parameter
     return this.request('/api/v1/profiler/perp-positions', {
       address,
       filters,
-      order_by: orderBy,
-      pagination
+      order_by: orderBy
     });
   }
 
@@ -749,14 +773,20 @@ export class NansenAPI {
   }
 
   async tokenFlows(params = {}) {
-    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination } = params;
+    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30, date } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
+    const dateRange = date || (() => {
+      const to = new Date().toISOString().split('T')[0];
+      const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+      return { from, to };
+    })();
     return this.request('/api/v1/tgm/flows', {
       token_address: tokenAddress,
       chain,
+      date: dateRange,
       filters,
       order_by: orderBy,
       pagination
@@ -807,14 +837,20 @@ export class NansenAPI {
   }
 
   async tokenWhoBoughtSold(params = {}) {
-    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination } = params;
+    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30, date } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
+    const dateRange = date || (() => {
+      const to = new Date().toISOString().split('T')[0];
+      const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+      return { from, to };
+    })();
     return this.request('/api/v1/tgm/who-bought-sold', {
       token_address: tokenAddress,
       chain,
+      date: dateRange,
       filters,
       order_by: orderBy,
       pagination
@@ -822,17 +858,14 @@ export class NansenAPI {
   }
 
   async tokenFlowIntelligence(params = {}) {
-    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination } = params;
+    const { tokenAddress, chain = 'solana' } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
     return this.request('/api/v1/tgm/flow-intelligence', {
       token_address: tokenAddress,
-      chain,
-      filters,
-      order_by: orderBy,
-      pagination
+      chain
     });
   }
 

package/src/cli.js

@@ -3,13 +3,19 @@
  * Extracted from index.js for coverage
  */
 
-import { NansenAPI, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir } from './api.js';
+import { NansenAPI, NansenError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, sleep } from './api.js';
+import fs from 'fs';
+import { getUpdateNotification, scheduleUpdateCheck } from './update-check.js';
+import { createRequire } from 'module';
 import * as readline from 'readline';
 
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require('../package.json');
+
 // ============= Schema Definition =============
 
 export const SCHEMA = {
-  version: '1.1.0',
+  version: VERSION,
   commands: {
     'smart-money': {
       description: 'Smart Money analytics - track sophisticated market participants',
@@ -36,22 +42,22 @@ export const SCHEMA = {
             sort: { type: 'string' },
             filters: { type: 'object' }
           },
-          returns: ['tx_hash', 'wallet_address', 'token_address', 'token_symbol', 'side', 'amount', 'value_usd', 'timestamp']
+          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: ['wallet_address', 'symbol', 'side', 'size', 'price', 'value_usd', 'pnl_usd', 'timestamp']
+          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: ['token_address', 'token_symbol', 'chain', 'balance', 'balance_usd', 'holder_count']
+          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: ['wallet_address', 'input_token', 'output_token', 'total_input', 'total_output', 'avg_price']
+          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',
@@ -70,7 +76,7 @@ export const SCHEMA = {
             chain: { type: 'string', default: 'ethereum' },
             entity: { type: 'string', description: 'Entity name instead of address' }
           },
-          returns: ['token_address', 'token_symbol', 'token_name', 'balance', 'balance_usd', 'price_usd']
+          returns: ['chain', 'address', 'token_address', 'token_symbol', 'token_name', 'token_amount', 'price_usd', 'value_usd']
         },
         'labels': {
           description: 'Behavioral and entity labels',
@@ -79,8 +85,8 @@ export const SCHEMA = {
         },
         'transactions': {
           description: 'Transaction history',
-          options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, limit: { type: 'number' }, days: { type: 'number', default: 30 } },
-          returns: ['tx_hash', 'block_number', 'timestamp', 'from', 'to', 'value', 'value_usd', 'method']
+          options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, date: { type: 'string', required: true, description: 'Date or date range (YYYY-MM-DD or {"from":"YYYY-MM-DD","to":"YYYY-MM-DD"})' }, 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',
@@ -90,7 +96,7 @@ export const SCHEMA = {
         'search': {
           description: 'Search for entities by name',
           options: { query: { type: 'string', required: true, description: 'Search query' }, limit: { type: 'number' } },
-          returns: ['entity_name', 'address', 'chain', 'labels']
+          returns: ['entity_name']
         },
         'historical-balances': {
           description: 'Historical balances over time',
@@ -100,17 +106,17 @@ export const SCHEMA = {
         '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', 'relationship', 'transaction_count', 'volume_usd']
+          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_label', 'transaction_count', 'volume_usd']
+          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: ['total_realized_pnl', 'total_unrealized_pnl', 'win_rate', 'total_trades']
+          returns: ['top5_tokens', 'traded_token_count', 'traded_times', 'realized_pnl_usd', 'realized_pnl_percent', 'win_rate']
         },
         'perp-positions': {
           description: 'Current perpetual positions',
@@ -121,6 +127,38 @@ export const SCHEMA = {
           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']
         }
       }
     },
@@ -142,12 +180,12 @@ export const SCHEMA = {
         'holders': {
           description: 'Token holder analysis',
           options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, 'smart-money': { type: 'boolean' }, limit: { type: 'number' } },
-          returns: ['wallet_address', 'balance', 'balance_usd', 'pct_supply', 'labels']
+          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' }, limit: { type: 'number' } },
-          returns: ['label', 'inflow', 'outflow', 'net_flow', 'wallet_count']
+          options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, date: { type: 'string', required: true, description: 'Date or date range (YYYY-MM-DD or {"from":"YYYY-MM-DD","to":"YYYY-MM-DD"})' }, 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',
@@ -161,17 +199,17 @@ export const SCHEMA = {
         },
         'who-bought-sold': {
           description: 'Recent buyers and sellers',
-          options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, limit: { type: 'number' } },
-          returns: ['wallet_address', 'side', 'amount', 'value_usd', 'timestamp', 'labels']
+          options: { token: { type: 'string', required: true }, chain: { type: 'string', default: 'solana' }, date: { type: 'string', required: true, description: 'Date or date range (YYYY-MM-DD or {"from":"YYYY-MM-DD","to":"YYYY-MM-DD"})' }, 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' }, limit: { type: 'number' } },
-          returns: ['label', 'inflow_usd', 'outflow_usd', 'net_flow_usd', 'unique_wallets']
+          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' } },
+          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': {
@@ -212,9 +250,10 @@ export const SCHEMA = {
     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' }
+    retries: { type: 'number', default: 3, description: 'Max retry attempts' },
+    format: { type: 'string', enum: ['json', 'csv'], description: 'Output format (default: json)' }
   },
-  chains: ['ethereum', 'solana', 'base', 'bnb', 'arbitrum', 'polygon', 'optimism', 'avalanche', 'linea', 'scroll', 'zksync', 'mantle', 'ronin', 'sei', 'plasma', 'sonic', 'unichain', 'monad', 'hyperevm', 'iotaevm'],
+  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']
 };
 
@@ -278,7 +317,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream') {
+      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich') {
         result.flags[key] = true;
       } else if (next && !next.startsWith('-')) {
         // Try to parse as JSON first
@@ -384,9 +423,53 @@ export function formatTable(data) {
   return lines.join('\n');
 }
 
+/**
+ * Format data as CSV with header row
+ */
+export function formatCsv(data) {
+  // Extract array of records from various response shapes
+  let records = [];
+  if (Array.isArray(data)) {
+    records = data;
+  } else if (data?.data && Array.isArray(data.data)) {
+    records = data.data;
+  } else if (data?.results && Array.isArray(data.results)) {
+    records = data.results;
+  } else if (data?.data?.results && Array.isArray(data.data.results)) {
+    records = data.data.results;
+  } else if (typeof data === 'object' && data !== null) {
+    records = [data];
+  }
+
+  if (records.length === 0) return '';
+
+  const columns = [...new Set(records.flatMap(r => Object.keys(r)))];
+
+  const escape = (val) => {
+    if (val === null || val === undefined) return '';
+    const s = typeof val === 'object' ? JSON.stringify(val) : String(val);
+    if (s.includes(',') || s.includes('"') || s.includes('\n')) {
+      return '"' + s.replace(/"/g, '""') + '"';
+    }
+    return s;
+  };
+
+  const lines = [columns.join(',')];
+  for (const record of records) {
+    lines.push(columns.map(col => escape(record[col])).join(','));
+  }
+  return lines.join('\n');
+}
+
 // Format output data (returns string, does not print)
-export function formatOutput(data, { pretty = false, table = false } = {}) {
-  if (table) {
+export function formatOutput(data, { pretty = false, table = false, csv = false } = {}) {
+  if (csv) {
+    if (data.success === false) {
+      return { type: 'error', text: `Error: ${data.error}` };
+    }
+    const csvData = data.data || data;
+    return { type: 'csv', text: formatCsv(csvData) };
+  } else if (table) {
     if (data.success === false) {
       return { type: 'error', text: `Error: ${data.error}` };
     } else {
@@ -439,6 +522,32 @@ export function formatStream(data) {
   return records.map(record => JSON.stringify(record)).join('\n');
 }
 
+/**
+ * Parse --date option into {from, to} object.
+ * Accepts: "YYYY-MM-DD" (single date → from=date, to=date),
+ *          '{"from":"YYYY-MM-DD","to":"YYYY-MM-DD"}' (JSON object),
+ *          or already-parsed object {from, to}.
+ * Falls back to days-based range if no date provided.
+ */
+export function parseDateOption(dateOption, days = 30) {
+  if (dateOption) {
+    if (typeof dateOption === 'object' && dateOption.from) {
+      return dateOption;
+    }
+    if (typeof dateOption === 'string') {
+      // Simple date string: use as both from and to
+      const dateMatch = dateOption.match(/^\d{4}-\d{2}-\d{2}$/);
+      if (dateMatch) {
+        return { from: dateOption, to: dateOption };
+      }
+    }
+  }
+  // Default: use days-based range
+  const to = new Date().toISOString().split('T')[0];
+  const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+  return { from, to };
+}
+
 // Parse simple sort syntax: "field:direction" or "field" (defaults to DESC)
 export function parseSort(sortOption, orderByOption) {
   // If --order-by is provided, use it (full JSON control)
@@ -455,6 +564,202 @@ export function parseSort(sortOption, orderByOption) {
   return [{ field, direction }];
 }
 
+// Enrich transfers with Nansen labels for from/to addresses
+async function enrichTransfers(result, apiInstance, chain) {
+  const transfers = result?.data?.results || result?.transfers || result?.data || [];
+  if (!Array.isArray(transfers) || transfers.length === 0) return result;
+
+  // Collect unique addresses (cap at 50)
+  const addrs = new Set();
+  for (const t of transfers) {
+    if (t.from) addrs.add(t.from);
+    if (t.to) addrs.add(t.to);
+    if (addrs.size >= 50) break;
+  }
+
+  // Batch lookup labels
+  const labelMap = {};
+  for (const addr of addrs) {
+    try {
+      const labelsResult = await apiInstance.addressLabels({ address: addr, chain });
+      labelMap[addr] = labelsResult?.labels || labelsResult?.data?.results || [];
+    } catch {
+      labelMap[addr] = [];
+    }
+  }
+
+  // Merge labels into transfers
+  for (const t of transfers) {
+    if (t.from && labelMap[t.from]) t.from_labels = labelMap[t.from];
+    if (t.to && labelMap[t.to]) t.to_labels = labelMap[t.to];
+  }
+
+  return result;
+}
+
+// ============= Composite Functions =============
+
+export async function batchProfile(api, params = {}) {
+  const { addresses = [], chain = 'ethereum', include = ['labels', 'balance'], delayMs = 1000 } = params;
+  const results = [];
+  for (let i = 0; i < addresses.length; i++) {
+    const address = addresses[i].trim();
+    const entry = { address, chain };
+    const validation = validateAddress(address, chain);
+    if (!validation.valid) {
+      entry.error = validation.error;
+      results.push(entry);
+      if (i < addresses.length - 1) await sleep(delayMs);
+      continue;
+    }
+    try {
+      if (include.includes('labels')) {
+        entry.labels = await api.addressLabels({ address, chain });
+      }
+      if (include.includes('balance')) {
+        entry.balance = await api.addressBalance({ address, chain });
+      }
+      if (include.includes('pnl')) {
+        entry.pnl = await api.addressPnl({ address, chain });
+      }
+    } catch (err) {
+      entry.error = err.message;
+    }
+    results.push(entry);
+    if (i < addresses.length - 1) await sleep(delayMs);
+  }
+  return { results, total: addresses.length, completed: results.filter(r => !r.error).length };
+}
+
+export async function traceCounterparties(api, params = {}) {
+  const { address, chain = 'ethereum', depth = 2, width = 10, days = 30, delayMs = 1000 } = params;
+  if (!address) {
+    throw new NansenError('address is required for trace', ErrorCode.MISSING_PARAM);
+  }
+  const validation = validateAddress(address, chain);
+  if (!validation.valid) {
+    throw new NansenError(validation.error, ErrorCode.INVALID_ADDRESS);
+  }
+  const clampedDepth = Math.max(1, Math.min(depth, 5));
+  const visited = new Set();
+  const nodes = [];
+  const edges = [];
+  const queue = [{ addr: address, hop: 0 }];
+  visited.add(address);
+  nodes.push(address);
+
+  while (queue.length > 0) {
+    const { addr, hop } = queue.shift();
+    if (hop >= clampedDepth) continue;
+
+    try {
+      const result = await api.addressCounterparties({
+        address: addr, chain, days,
+        pagination: { page: 1, per_page: width },
+      });
+
+      const counterparties = result?.data?.results || result?.counterparties || result?.data || [];
+      const items = Array.isArray(counterparties) ? counterparties.slice(0, width) : [];
+
+      for (const cp of items) {
+        const cpAddr = cp.counterparty_address || cp.address || cp.counterparty;
+        if (!cpAddr) continue;
+
+        edges.push({
+          from: addr, to: cpAddr,
+          volume_usd: cp.volume_usd || cp.total_volume_usd || 0,
+          tx_count: cp.transaction_count || cp.tx_count || 0,
+          hop: hop + 1,
+        });
+
+        if (!visited.has(cpAddr)) {
+          visited.add(cpAddr);
+          nodes.push(cpAddr);
+          queue.push({ addr: cpAddr, hop: hop + 1 });
+        }
+      }
+    } catch (err) {
+      // Skip addresses that fail (404, etc) but continue the traversal
+    }
+
+    if (queue.length > 0) await sleep(delayMs);
+  }
+
+  return {
+    root: address, chain, depth: clampedDepth,
+    nodes, edges,
+    stats: { nodes_visited: nodes.length, edges_found: edges.length, max_depth_reached: Math.max(0, ...edges.map(e => e.hop)) },
+  };
+}
+
+export async function compareWallets(api, params = {}) {
+  const { addresses = [], chain = 'ethereum', days = 30, delayMs = 1000 } = params;
+  if (addresses.length !== 2) {
+    throw new NansenError('Exactly 2 addresses are required for comparison', ErrorCode.INVALID_PARAMS);
+  }
+  const [addr1, addr2] = addresses;
+  for (const addr of [addr1, addr2]) {
+    const validation = validateAddress(addr, chain);
+    if (!validation.valid) {
+      throw new NansenError(validation.error, ErrorCode.INVALID_ADDRESS);
+    }
+  }
+
+  // Fetch counterparties and balances for both addresses
+  const [cp1, cp2] = await Promise.all([
+    api.addressCounterparties({ address: addr1, chain, days }).catch(() => null),
+    api.addressCounterparties({ address: addr2, chain, days }).catch(() => null),
+  ]);
+  await sleep(delayMs);
+  const [bal1, bal2] = await Promise.all([
+    api.addressBalance({ address: addr1, chain }).catch(() => null),
+    api.addressBalance({ address: addr2, chain }).catch(() => null),
+  ]);
+
+  // Extract counterparty addresses
+  const extractCps = (result) => {
+    const list = result?.data?.results || result?.counterparties || result?.data || [];
+    return Array.isArray(list) ? list : [];
+  };
+  const cps1 = extractCps(cp1);
+  const cps2 = extractCps(cp2);
+  const cpAddrs1 = new Set(cps1.map(c => c.counterparty_address || c.address || c.counterparty).filter(Boolean));
+  const cpAddrs2 = new Set(cps2.map(c => c.counterparty_address || c.address || c.counterparty).filter(Boolean));
+  const sharedCpAddrs = [...cpAddrs1].filter(a => cpAddrs2.has(a));
+
+  // Extract token holdings
+  const extractTokens = (result) => {
+    const list = result?.data?.results || result?.balances || result?.data || [];
+    return Array.isArray(list) ? list : [];
+  };
+  const tokens1 = extractTokens(bal1);
+  const tokens2 = extractTokens(bal2);
+  const tokenSyms1 = new Set(tokens1.map(t => t.token_symbol).filter(Boolean));
+  const tokenSyms2 = new Set(tokens2.map(t => t.token_symbol).filter(Boolean));
+  const sharedTokens = [...tokenSyms1].filter(s => tokenSyms2.has(s));
+
+  return {
+    addresses: [addr1, addr2], chain,
+    shared_counterparties: sharedCpAddrs,
+    shared_tokens: sharedTokens,
+    balances: [
+      { address: addr1, total_usd: tokens1.reduce((sum, t) => sum + (t.balance_usd || 0), 0) },
+      { address: addr2, total_usd: tokens2.reduce((sum, t) => sum + (t.balance_usd || 0), 0) },
+    ],
+  };
+}
+
+// ASCII Art Banner
+export const BANNER = `
+ ███╗   ██╗ █████╗ ███╗   ██╗███████╗███████╗███╗   ██╗
+ ████╗  ██║██╔══██╗████╗  ██║██╔════╝██╔════╝████╗  ██║
+ ██╔██╗ ██║███████║██╔██╗ ██║███████╗█████╗  ██╔██╗ ██║
+ ██║╚██╗██║██╔══██║██║╚██╗██║╚════██║██╔══╝  ██║╚██╗██║
+ ██║ ╚████║██║  ██║██║ ╚████║███████║███████╗██║ ╚████║
+ ╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝╚═╝  ╚═══╝
+                   Surface The Signal
+`;
+
 // Help text
 export const HELP = `
 Nansen CLI - Command-line interface for Nansen API
@@ -469,7 +774,7 @@ COMMANDS:
   schema         Output JSON schema for all commands (for agent introspection)
   cache          Cache management (clear)
   smart-money    Smart Money analytics (netflow, dex-trades, holdings, dcas, historical-holdings)
-  profiler       Wallet profiling (balance, labels, transactions, pnl, perp-positions, perp-trades)
+  profiler       Wallet profiling (balance, labels, pnl, batch, trace, compare, counterparties)
   token          Token God Mode (screener, holders, flows, trades, pnl, perp-trades, perp-positions)
   portfolio      Portfolio analytics (defi-holdings)
   help           Show this help message
@@ -492,6 +797,7 @@ GLOBAL OPTIONS:
   --no-cache     Disable cache for this request
   --cache-ttl <s> Cache TTL in seconds (default: 300)
   --stream       Output as JSON lines (NDJSON) for incremental processing
+  --format csv   Output as CSV with header row
 
 EXAMPLES:
   # Get Smart Money netflow on Solana
@@ -510,7 +816,7 @@ EXAMPLES:
   nansen profiler search --query "Vitalik"
 
   # Get token holders with filters
-  nansen token holders --token 0x123... --filters '{"only_smart_money":true}'
+  nansen token holders --token 0x123... --smart-money
 
 SMART MONEY LABELS:
   Fund, Smart Trader, 30D Smart Trader, 90D Smart Trader, 
@@ -518,8 +824,8 @@ SMART MONEY LABELS:
 
 SUPPORTED CHAINS:
   ethereum, solana, base, bnb, arbitrum, polygon, optimism,
-  avalanche, linea, scroll, zksync, mantle, ronin, sei,
-  plasma, sonic, unichain, monad, hyperevm, iotaevm
+  avalanche, linea, scroll, mantle, ronin, sei,
+  plasma, sonic, monad, hyperevm, iotaevm
 
 For more info: https://docs.nansen.ai
 `;
@@ -733,17 +1039,57 @@ export function buildCommands(deps = {}) {
       const handlers = {
         'balance': () => apiInstance.addressBalance({ address, entityName, chain, filters, orderBy }),
         'labels': () => apiInstance.addressLabels({ address, chain, pagination }),
-        'transactions': () => apiInstance.addressTransactions({ address, chain, filters, orderBy, pagination }),
+        'transactions': () => {
+          const date = parseDateOption(options.date, days);
+          return apiInstance.addressTransactions({ address, chain, filters, orderBy, pagination, days, date });
+        },
         'pnl': () => apiInstance.addressPnl({ address, chain }),
-        'search': () => apiInstance.entitySearch({ query: options.query, pagination }),
+        'search': () => apiInstance.entitySearch({ query: options.query }),
         'historical-balances': () => apiInstance.addressHistoricalBalances({ address, chain, filters, orderBy, pagination, days }),
-        'related-wallets': () => apiInstance.addressRelatedWallets({ address, chain, filters, orderBy, pagination }),
+        'related-wallets': () => apiInstance.addressRelatedWallets({ address, chain, orderBy, pagination }),
         'counterparties': () => apiInstance.addressCounterparties({ address, chain, filters, orderBy, pagination, days }),
-        'pnl-summary': () => apiInstance.addressPnlSummary({ address, chain, filters, orderBy, pagination, days }),
+        'pnl-summary': () => apiInstance.addressPnlSummary({ address, chain, orderBy, pagination, days }),
         'perp-positions': () => apiInstance.addressPerpPositions({ address, filters, orderBy, pagination }),
         'perp-trades': () => apiInstance.addressPerpTrades({ address, filters, orderBy, pagination, days }),
+        'batch': () => {
+          let addresses = [];
+          if (options.addresses) {
+            addresses = options.addresses.split(',').map(a => a.trim()).filter(Boolean);
+          } else if (options.file) {
+            const content = fs.readFileSync(options.file, 'utf8');
+            try {
+              const parsed = JSON.parse(content);
+              if (!Array.isArray(parsed)) {
+                throw new NansenError('File must contain a JSON array of address strings or one address per line', ErrorCode.INVALID_PARAMS);
+              }
+              if (!parsed.every(item => typeof item === 'string')) {
+                throw new NansenError('File must contain a JSON array of address strings or one address per line', ErrorCode.INVALID_PARAMS);
+              }
+              addresses = parsed.map(a => a.trim()).filter(Boolean);
+            } catch (e) {
+              if (e instanceof NansenError) throw e;
+              addresses = content.split('\n').map(a => a.trim()).filter(Boolean);
+            }
+          }
+          if (addresses.length > 100) {
+            throw new NansenError('Batch is limited to 100 addresses', ErrorCode.INVALID_PARAMS);
+          }
+          const include = options.include ? options.include.split(',').map(s => s.trim()) : ['labels', 'balance'];
+          const delayMs = options.delay ? parseInt(options.delay) : 1000;
+          return batchProfile(apiInstance, { addresses, chain, include, delayMs });
+        },
+        'trace': () => {
+          const depth = options.depth ? Math.max(1, Math.min(parseInt(options.depth), 5)) : 2;
+          const width = options.width ? parseInt(options.width) : 10;
+          const delayMs = options.delay ? parseInt(options.delay) : 1000;
+          return traceCounterparties(apiInstance, { address, chain, depth, width, days, delayMs });
+        },
+        'compare': () => {
+          const addrs = (options.addresses || '').split(',').map(a => a.trim()).filter(Boolean);
+          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'],
+          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'
         })
@@ -771,18 +1117,30 @@ export function buildCommands(deps = {}) {
       // Convenience filter for smart money only
       const onlySmartMoney = options['smart-money'] || flags['smart-money'] || false;
       if (onlySmartMoney) {
-        filters.only_smart_money = true;
+        filters.include_smart_money_labels = filters.include_smart_money_labels || 
+          ['Fund', 'Smart Trader', '30D Smart Trader', '90D Smart Trader', '180D Smart Trader'];
       }
 
       const handlers = {
         'screener': () => apiInstance.tokenScreener({ chains, timeframe, filters, orderBy, pagination }),
-        'holders': () => apiInstance.tokenHolders({ tokenAddress, chain, filters, orderBy, pagination }),
-        'flows': () => apiInstance.tokenFlows({ tokenAddress, chain, filters, orderBy, pagination }),
+        'holders': () => apiInstance.tokenHolders({ tokenAddress, chain, labelType: onlySmartMoney ? 'smart_money' : 'all_holders', filters, orderBy, pagination }),
+        'flows': () => {
+          const date = parseDateOption(options.date, days);
+          return apiInstance.tokenFlows({ tokenAddress, chain, filters, orderBy, pagination, days, date });
+        },
         'dex-trades': () => apiInstance.tokenDexTrades({ tokenAddress, chain, onlySmartMoney, filters, orderBy, pagination, days }),
         'pnl': () => apiInstance.tokenPnlLeaderboard({ tokenAddress, chain, filters, orderBy, pagination, days }),
-        'who-bought-sold': () => apiInstance.tokenWhoBoughtSold({ tokenAddress, chain, filters, orderBy, pagination }),
-        'flow-intelligence': () => apiInstance.tokenFlowIntelligence({ tokenAddress, chain, filters, orderBy, pagination }),
-        'transfers': () => apiInstance.tokenTransfers({ tokenAddress, chain, filters, orderBy, pagination, days }),
+        'who-bought-sold': () => {
+          const date = parseDateOption(options.date, days);
+          return apiInstance.tokenWhoBoughtSold({ tokenAddress, chain, filters, orderBy, pagination, days, date });
+        },
+        'flow-intelligence': () => apiInstance.tokenFlowIntelligence({ tokenAddress, chain, days }),
+        'transfers': () => {
+          // Inject --from/--to into filters
+          if (options.from) filters.from_address = options.from;
+          if (options.to) filters.to_address = options.to;
+          return apiInstance.tokenTransfers({ tokenAddress, chain, filters, orderBy, pagination, days });
+        },
         'jup-dca': () => apiInstance.tokenJupDca({ tokenAddress, filters, orderBy, pagination }),
         'perp-trades': () => apiInstance.tokenPerpTrades({ tokenSymbol, filters, orderBy, pagination, days }),
         'perp-positions': () => apiInstance.tokenPerpPositions({ tokenSymbol, filters, orderBy, pagination }),
@@ -798,7 +1156,14 @@ export function buildCommands(deps = {}) {
         return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
       }
 
-      return handlers[subcommand]();
+      let result = await handlers[subcommand]();
+
+      // Enrich transfers with Nansen labels for from/to addresses
+      if (subcommand === 'transfers' && (options.enrich || flags.enrich)) {
+        result = await enrichTransfers(result, apiInstance, chain);
+      }
+
+      return result;
     },
 
     'portfolio': async (args, apiInstance, flags, options) => {
@@ -838,17 +1203,29 @@ export async function runCLI(rawArgs, deps = {}) {
   } = deps;
 
   const { _: positional, flags, options } = parseArgs(rawArgs);
-  
+
   const command = positional[0] || 'help';
   const subArgs = positional.slice(1);
   const pretty = flags.pretty || flags.p;
   const table = flags.table || flags.t;
   const stream = flags.stream || flags.s;
+  const csv = options.format === 'csv';
+
+  // Update check (read cached result + schedule background refresh)
+  const updateNotification = getUpdateNotification(VERSION);
+  scheduleUpdateCheck();
+  const notify = () => { if (updateNotification) errorOutput(updateNotification); };
 
   const commands = { ...buildCommands(deps), ...commandOverrides };
 
+  if (flags.version || flags.v) {
+    output(VERSION);
+    return { type: 'version', data: VERSION };
+  }
+
   if (command === 'help' || flags.help || flags.h) {
-    output(HELP);
+    output(BANNER + HELP);
+    notify();
     return { type: 'help' };
   }
 
@@ -859,6 +1236,7 @@ export async function runCLI(rawArgs, deps = {}) {
     };
     const formatted = formatOutput(errorData, { pretty, table });
     output(formatted.text);
+    notify();
     exit(1);
     return { type: 'error', data: errorData };
   }
@@ -871,9 +1249,11 @@ export async function runCLI(rawArgs, deps = {}) {
     if (command === 'schema' && result) {
       const formatted = formatOutput(result, { pretty, table: false });
       output(formatted.text);
+      notify();
       return { type: 'schema', data: result };
     }
-    
+
+    notify();
     return { type: 'no-auth', command };
   }
 
@@ -905,17 +1285,20 @@ export async function runCLI(rawArgs, deps = {}) {
       if (streamOutput) {
         output(streamOutput);
       }
+      notify();
       return { type: 'stream', data: result };
     }
-    
+
     const successData = { success: true, data: result };
-    const formatted = formatOutput(successData, { pretty, table });
+    const formatted = formatOutput(successData, { pretty, table, csv });
     output(formatted.text);
-    return { type: 'success', data: result };
+    notify();
+    return { type: csv ? 'csv' : 'success', data: result };
   } catch (error) {
     const errorData = formatError(error);
-    const formatted = formatOutput(errorData, { pretty, table });
+    const formatted = formatOutput(errorData, { pretty, table, csv });
     errorOutput(formatted.text);
+    notify();
     exit(1);
     return { type: 'error', data: errorData };
   }

package/src/update-check.js

@@ -0,0 +1,95 @@
+/**
+ * Update check — lightweight, non-blocking, zero-dependency.
+ *
+ * getUpdateNotification(currentVersion) — reads cached result, returns string or null
+ * scheduleUpdateCheck()                — spawns detached background fetch if cache is stale
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '', '.nansen');
+const CACHE_FILE = path.join(CONFIG_DIR, 'update-check.json');
+const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
+const PACKAGE_NAME = 'nansen-cli';
+
+/**
+ * Compare two semver strings. Returns true if latest > current.
+ */
+function isNewer(latest, current) {
+  const parse = v => v.replace(/^v/, '').split('.').map(Number);
+  const [lM, lm, lp] = parse(latest);
+  const [cM, cm, cp] = parse(current);
+  if (lM !== cM) return lM > cM;
+  if (lm !== cm) return lm > cm;
+  return lp > cp;
+}
+
+/**
+ * Read the cached check result and return a notification string (or null).
+ */
+export function getUpdateNotification(currentVersion) {
+  try {
+    if (process.env.NO_UPDATE_NOTIFIER || process.env.CI) return null;
+    if (!fs.existsSync(CACHE_FILE)) return null;
+
+    const raw = fs.readFileSync(CACHE_FILE, 'utf8');
+    const { latest } = JSON.parse(raw);
+    if (!latest) return null;
+
+    if (isNewer(latest, currentVersion)) {
+      return `Update available: ${currentVersion} → ${latest}  (npm i -g ${PACKAGE_NAME})`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * If the cache is missing or stale, spawn a detached background process to refresh it.
+ */
+export function scheduleUpdateCheck() {
+  try {
+    if (process.env.NO_UPDATE_NOTIFIER || process.env.CI) return;
+
+    // Check staleness
+    if (fs.existsSync(CACHE_FILE)) {
+      const { checkedAt } = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+      if (checkedAt && Date.now() - checkedAt < STALE_MS) return;
+    }
+
+    // Inline script executed by the detached child
+    const script = `
+      const https = require('https');
+      const fs = require('fs');
+      const path = require('path');
+      const dir = ${JSON.stringify(CONFIG_DIR)};
+      const file = ${JSON.stringify(CACHE_FILE)};
+      const req = https.get('https://registry.npmjs.org/${PACKAGE_NAME}/latest', { timeout: 5000 }, (res) => {
+        let body = '';
+        res.on('data', c => body += c);
+        res.on('end', () => {
+          try {
+            const { version } = JSON.parse(body);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { mode: 0o700, recursive: true });
+            fs.writeFileSync(file, JSON.stringify({ latest: version, checkedAt: Date.now() }));
+          } catch {}
+        });
+      });
+      req.on('error', () => {});
+      req.setTimeout(5000, () => req.destroy());
+    `;
+
+    const child = spawn(process.execPath, ['-e', script], {
+      detached: true,
+      stdio: 'ignore'
+    });
+    child.unref();
+  } catch {
+    // silent
+  }
+}