nansen-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# Nansen CLI
+
+[![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-138%20passing-brightgreen.svg)]()
+
+Command-line interface for the [Nansen API](https://docs.nansen.ai). Designed for AI agents with structured JSON output.
+
+## Installation
+
+```bash
+# Install globally via npm
+npm install -g nansen-cli
+
+# Or run directly with npx
+npx nansen-cli help
+
+# Or clone and install locally
+git clone https://github.com/nansen-ai/nansen-cli.git
+cd nansen-cli
+npm install
+npm link
+```
+
+## Configuration
+
+**Option 1: Interactive login (recommended)**
+```bash
+nansen login
+# Enter your API key when prompted
+# ✓ Saved to ~/.nansen/config.json
+```
+
+**Option 2: Environment variable**
+```bash
+export NANSEN_API_KEY=your-api-key
+```
+
+Get your API key at [app.nansen.ai/api](https://app.nansen.ai/api).
+
+## Quick Start
+
+```bash
+# Get trending tokens on Solana
+nansen token screener --chain solana --timeframe 24h --pretty
+
+# Check Smart Money activity
+nansen smart-money netflow --chain solana --pretty
+
+# Profile a wallet
+nansen profiler balance --address 0x28c6c06298d514db089934071355e5743bf21d60 --chain ethereum --pretty
+
+# Search for an entity
+nansen profiler search --query "Vitalik Buterin" --pretty
+```
+
+## Commands
+
+### `smart-money` - Smart Money Analytics
+
+Track trading and holding activity of sophisticated market participants.
+
+| Subcommand | Description |
+|------------|-------------|
+| `netflow` | Net capital flows (inflows vs outflows) |
+| `dex-trades` | Real-time DEX trading activity |
+| `perp-trades` | Perpetual trading on Hyperliquid |
+| `holdings` | Aggregated token balances |
+| `dcas` | DCA strategies on Jupiter |
+| `historical-holdings` | Historical holdings over time |
+
+**Smart Money Labels:**
+- `Fund` - Institutional investment funds
+- `Smart Trader` - Historically profitable traders
+- `30D Smart Trader` - Top performers (30-day window)
+- `90D Smart Trader` - Top performers (90-day window)
+- `180D Smart Trader` - Top performers (180-day window)
+- `Smart HL Perps Trader` - Profitable Hyperliquid traders
+
+### `profiler` - Wallet Profiling
+
+Detailed information about any blockchain address.
+
+| Subcommand | Description |
+|------------|-------------|
+| `balance` | Current token holdings |
+| `labels` | Behavioral and entity labels |
+| `transactions` | Transaction history |
+| `pnl` | PnL and trade performance |
+| `search` | Search for entities by name |
+| `historical-balances` | Historical balances over time |
+| `related-wallets` | Find wallets related to an address |
+| `counterparties` | Top counterparties by volume |
+| `pnl-summary` | Summarized PnL metrics |
+| `perp-positions` | Current perpetual positions |
+| `perp-trades` | Perpetual trading history |
+
+### `token` - Token God Mode
+
+Deep analytics for any token.
+
+| Subcommand | Description |
+|------------|-------------|
+| `screener` | Discover and filter tokens |
+| `holders` | Token holder analysis |
+| `flows` | Token flow metrics |
+| `dex-trades` | DEX trading activity |
+| `pnl` | PnL leaderboard |
+| `who-bought-sold` | Recent buyers and sellers |
+| `flow-intelligence` | Detailed flow intelligence by label |
+| `transfers` | Token transfer history |
+| `jup-dca` | Jupiter DCA orders for token |
+| `perp-trades` | Perp trades by token symbol |
+| `perp-positions` | Open perp positions by token symbol |
+| `perp-pnl-leaderboard` | Perp PnL leaderboard by token |
+
+### `portfolio` - Portfolio Analytics
+
+| Subcommand | Description |
+|------------|-------------|
+| `defi` | DeFi holdings across protocols |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--pretty` | Format JSON output for readability |
+| `--chain <chain>` | Blockchain to query |
+| `--chains <json>` | Multiple chains as JSON array |
+| `--limit <n>` | Number of results |
+| `--days <n>` | Date range in days (default: 30) |
+| `--symbol <sym>` | Token symbol for perp endpoints (e.g., BTC, ETH) |
+| `--filters <json>` | Filter criteria as JSON |
+| `--order-by <json>` | Sort order as JSON array |
+| `--labels <label>` | Smart Money label filter |
+| `--smart-money` | Filter for Smart Money only |
+| `--timeframe <tf>` | Time window (5m, 10m, 1h, 6h, 24h, 7d, 30d) |
+
+## Supported Chains
+
+`ethereum`, `solana`, `base`, `bnb`, `arbitrum`, `polygon`, `optimism`, `avalanche`, `linea`, `scroll`, `zksync`, `mantle`, `ronin`, `sei`, `plasma`, `sonic`, `unichain`, `monad`, `hyperevm`, `iotaevm`
+
+## AI Agent Integration
+
+The CLI is designed for AI agents and automation:
+
+- **Structured Output**: All responses are JSON with consistent schema
+- **Error Handling**: Errors include status codes and actionable details
+- **Composable**: Commands can be chained with shell pipes
+- **Discoverable**: `help` commands at every level
+
+```json
+// Success response
+{
+  "success": true,
+  "data": {
+    "results": [...],
+    "pagination": {...}
+  }
+}
+
+// Error response
+{
+  "success": false,
+  "error": "API error message",
+  "status": 401,
+  "details": {...}
+}
+```
+
+## Examples
+
+```bash
+# Get Smart Money DEX trades from Funds only
+nansen smart-money dex-trades --chain ethereum --labels Fund
+
+# Get token holders with Smart Money filter
+nansen token holders --token So11111111111111111111111111111111111111112 --chain solana --smart-money
+
+# Get historical holdings for the past 7 days
+nansen smart-money historical-holdings --chain solana --days 7
+
+# Get BTC perpetual positions on Hyperliquid
+nansen token perp-positions --symbol BTC --pretty
+
+# Get top PnL traders for a token
+nansen token pnl --token JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN --chain solana --days 30
+```
+
+## Development
+
+```bash
+# Run tests (mocked, no API key needed)
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run against live API
+NANSEN_API_KEY=your-key npm run test:live
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+
+## API Coverage
+
+| Category | Endpoints | Coverage |
+|----------|-----------|----------|
+| Smart Money | 6 | 100% |
+| Profiler | 11 | 100% |
+| Token God Mode | 12 | 100% |
+| Portfolio | 1 | 100% |
+| **Total** | **30** | **100%** |
+
+## License
+
+[MIT](LICENSE) © [Nansen](https://nansen.ai)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "nansen-cli",
+  "version": "1.0.0",
+  "description": "Command-line interface for Nansen API - designed for AI agents",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "nansen": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:live": "NANSEN_LIVE_TEST=1 vitest run"
+  },
+  "keywords": [
+    "nansen",
+    "crypto",
+    "blockchain",
+    "api",
+    "cli",
+    "ai-agent",
+    "smart-money",
+    "onchain",
+    "defi",
+    "solana",
+    "ethereum"
+  ],
+  "author": "Nansen <dev@nansen.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nansen-ai/nansen-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nansen-ai/nansen-cli/issues"
+  },
+  "homepage": "https://github.com/nansen-ai/nansen-cli#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "vitest": "^4.0.18"
+  }
+}

package/src/api.js

@@ -0,0 +1,593 @@
+/**
+ * Nansen API Client
+ * Handles all HTTP communication with the Nansen API
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ============= Config Paths =============
+
+const CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '', '.nansen');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+/**
+ * Get the config directory path
+ */
+export function getConfigDir() {
+  return CONFIG_DIR;
+}
+
+/**
+ * Get the config file path
+ */
+export function getConfigFile() {
+  return CONFIG_FILE;
+}
+
+/**
+ * Save config to ~/.nansen/config.json
+ */
+export function saveConfig(config) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { mode: 0o700, recursive: true });
+  }
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Delete config file (logout)
+ */
+export function deleteConfig() {
+  if (fs.existsSync(CONFIG_FILE)) {
+    fs.unlinkSync(CONFIG_FILE);
+    return true;
+  }
+  return false;
+}
+
+// ============= Address Validation =============
+
+const ADDRESS_PATTERNS = {
+  // EVM chains: 0x followed by 40 hex chars
+  evm: /^0x[a-fA-F0-9]{40}$/,
+  // Solana: Base58, 32-44 chars (no 0, O, I, l)
+  solana: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/,
+  // Bitcoin: Various formats
+  bitcoin: /^(1|3|bc1)[a-zA-HJ-NP-Z0-9]{25,62}$/,
+};
+
+const EVM_CHAINS = [
+  'ethereum', 'arbitrum', 'base', 'bnb', 'polygon', 'optimism',
+  'avalanche', 'linea', 'scroll', 'zksync', 'mantle', 'ronin',
+  'sei', 'plasma', 'sonic', 'unichain', 'monad', 'hyperevm', 'iotaevm'
+];
+
+/**
+ * Validate address format for a given chain
+ * @param {string} address - The address to validate
+ * @param {string} chain - The blockchain (ethereum, solana, etc.)
+ * @returns {{valid: boolean, error?: string}}
+ */
+export function validateAddress(address, chain = 'ethereum') {
+  if (!address || typeof address !== 'string') {
+    return { valid: false, error: 'Address is required' };
+  }
+
+  const trimmed = address.trim();
+  
+  if (EVM_CHAINS.includes(chain)) {
+    if (!ADDRESS_PATTERNS.evm.test(trimmed)) {
+      return { valid: false, error: `Invalid EVM address format. Expected 0x followed by 40 hex characters.` };
+    }
+  } else if (chain === 'solana') {
+    if (!ADDRESS_PATTERNS.solana.test(trimmed)) {
+      return { valid: false, error: `Invalid Solana address format. Expected Base58 string (32-44 chars).` };
+    }
+  } else if (chain === 'bitcoin') {
+    if (!ADDRESS_PATTERNS.bitcoin.test(trimmed)) {
+      return { valid: false, error: `Invalid Bitcoin address format.` };
+    }
+  }
+  // For unknown chains, allow any non-empty string (API will validate)
+  
+  return { valid: true };
+}
+
+/**
+ * Validate token address (same rules as wallet address)
+ */
+export function validateTokenAddress(tokenAddress, chain = 'solana') {
+  return validateAddress(tokenAddress, chain);
+}
+
+function loadConfig() {
+  // Priority: 1. Environment variables, 2. ~/.nansen/config.json, 3. Local config.json
+  
+  // Check environment variables first (highest priority)
+  if (process.env.NANSEN_API_KEY) {
+    return {
+      apiKey: process.env.NANSEN_API_KEY,
+      baseUrl: process.env.NANSEN_BASE_URL || 'https://api.nansen.ai'
+    };
+  }
+  
+  // Check ~/.nansen/config.json (from `nansen login`)
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    } catch (e) {
+      // Ignore parse errors, continue to next option
+    }
+  }
+  
+  // Check local config.json (for development)
+  const localConfig = path.join(__dirname, '..', 'config.json');
+  if (fs.existsSync(localConfig)) {
+    return JSON.parse(fs.readFileSync(localConfig, 'utf8'));
+  }
+  
+  // No config found
+  return {
+    apiKey: null,
+    baseUrl: 'https://api.nansen.ai'
+  };
+}
+
+const config = loadConfig();
+
+export class NansenAPI {
+  constructor(apiKey = config.apiKey, baseUrl = config.baseUrl) {
+    if (!apiKey) {
+      throw new Error('API key required. Run `nansen login` or set NANSEN_API_KEY environment variable.');
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+
+  async request(endpoint, body = {}, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'apikey': this.apiKey,
+        ...options.headers
+      },
+      body: JSON.stringify(body)
+    });
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      const error = new Error(data.message || data.error || `API error: ${response.status}`);
+      error.status = response.status;
+      error.data = data;
+      throw error;
+    }
+
+    return data;
+  }
+
+  // ============= Smart Money Endpoints =============
+  
+  async smartMoneyNetflow(params = {}) {
+    const { chains = ['solana'], filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1/smart-money/netflow', {
+      chains,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async smartMoneyDexTrades(params = {}) {
+    const { chains = ['solana'], filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1/smart-money/dex-trades', {
+      chains,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async smartMoneyPerpTrades(params = {}) {
+    const { filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1/smart-money/perp-trades', {
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async smartMoneyHoldings(params = {}) {
+    const { chains = ['solana'], filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1/smart-money/holdings', {
+      chains,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async smartMoneyDcas(params = {}) {
+    const { filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1/smart-money/dcas', {
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async smartMoneyHistoricalHoldings(params = {}) {
+    const { chains = ['solana'], filters = {}, orderBy, pagination, days = 30 } = params;
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/smart-money/historical-holdings', {
+      chains,
+      date_range: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  // ============= Profiler Endpoints =============
+
+  async addressBalance(params = {}) {
+    const { address, entityName, chain = 'ethereum', hideSpamToken = true, filters = {}, orderBy } = params;
+    if (address) {
+      const validation = validateAddress(address, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/profiler/address/current-balance', {
+      address,
+      entity_name: entityName,
+      chain,
+      hide_spam_token: hideSpamToken,
+      filters,
+      order_by: orderBy
+    });
+  }
+
+  async addressLabels(params = {}) {
+    const { address, chain = 'ethereum', pagination = { page: 1, recordsPerPage: 100 } } = params;
+    if (address) {
+      const validation = validateAddress(address, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/beta/profiler/address/labels', {
+      parameters: { address, chain },
+      pagination
+    });
+  }
+
+  async addressTransactions(params = {}) {
+    const { address, chain = 'ethereum', filters = {}, orderBy, pagination } = params;
+    if (address) {
+      const validation = validateAddress(address, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/profiler/address/transactions', {
+      address,
+      chain,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async addressPnl(params = {}) {
+    const { address, chain = 'ethereum' } = params;
+    if (address) {
+      const validation = validateAddress(address, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/profiler/address/pnl-and-trade-performance', {
+      address,
+      chain
+    });
+  }
+
+  async entitySearch(params = {}) {
+    const { query, pagination } = params;
+    return this.request('/api/beta/profiler/entity-name-search', {
+      parameters: { query },
+      pagination
+    });
+  }
+
+  async addressHistoricalBalances(params = {}) {
+    const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
+    if (address) {
+      const validation = validateAddress(address, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/profiler/address/historical-balances', {
+      address,
+      chain,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async addressRelatedWallets(params = {}) {
+    const { address, chain = 'ethereum', filters = {}, orderBy, pagination } = params;
+    if (address) {
+      const validation = validateAddress(address, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/profiler/address/related-wallets', {
+      address,
+      chain,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async addressCounterparties(params = {}) {
+    const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
+    if (address) {
+      const validation = validateAddress(address, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/profiler/address/counterparties', {
+      address,
+      chain,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async addressPnlSummary(params = {}) {
+    const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
+    if (address) {
+      const validation = validateAddress(address, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/profiler/address/pnl-summary', {
+      address,
+      chain,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async addressPerpPositions(params = {}) {
+    const { address, filters = {}, orderBy, pagination } = params;
+    // Perp positions work with HL addresses (not validated)
+    return this.request('/api/v1/profiler/perp-positions', {
+      address,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async addressPerpTrades(params = {}) {
+    const { address, filters = {}, orderBy, pagination, days = 30 } = params;
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/profiler/perp-trades', {
+      address,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  // ============= Token God Mode Endpoints =============
+
+  async tokenScreener(params = {}) {
+    const { chains = ['solana'], timeframe = '24h', filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1/token-screener', {
+      chains,
+      timeframe,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenHolders(params = {}) {
+    const { tokenAddress, chain = 'solana', labelType = 'all_holders', filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/tgm/holders', {
+      token_address: tokenAddress,
+      chain,
+      label_type: labelType,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenFlows(params = {}) {
+    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/tgm/flows', {
+      token_address: tokenAddress,
+      chain,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenDexTrades(params = {}) {
+    const { tokenAddress, chain = 'solana', onlySmartMoney = false, filters = {}, orderBy, pagination, days = 7 } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    
+    // Apply smart money filter via filters object
+    if (onlySmartMoney) {
+      filters.include_smart_money_labels = filters.include_smart_money_labels || 
+        ['Fund', 'Smart Trader', '30D Smart Trader', '90D Smart Trader', '180D Smart Trader'];
+    }
+    
+    return this.request('/api/v1/tgm/dex-trades', {
+      token_address: tokenAddress,
+      chain,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenPnlLeaderboard(params = {}) {
+    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30 } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/tgm/pnl-leaderboard', {
+      token_address: tokenAddress,
+      chain,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenWhoBoughtSold(params = {}) {
+    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/tgm/who-bought-sold', {
+      token_address: tokenAddress,
+      chain,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenFlowIntelligence(params = {}) {
+    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/tgm/flow-intelligence', {
+      token_address: tokenAddress,
+      chain,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenTransfers(params = {}) {
+    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 7 } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/tgm/transfers', {
+      token_address: tokenAddress,
+      chain,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenJupDca(params = {}) {
+    const { tokenAddress, filters = {}, orderBy, pagination } = params;
+    // JUP DCA is Solana-only
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, 'solana');
+      if (!validation.valid) throw new Error(validation.error);
+    }
+    return this.request('/api/v1/tgm/jup-dca', {
+      token_address: tokenAddress,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenPerpTrades(params = {}) {
+    const { tokenSymbol, filters = {}, orderBy, pagination, days = 30 } = params;
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/tgm/perp-trades', {
+      token_symbol: tokenSymbol,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenPerpPositions(params = {}) {
+    const { tokenSymbol, filters = {}, orderBy, pagination } = params;
+    return this.request('/api/v1/tgm/perp-positions', {
+      token_symbol: tokenSymbol,
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async tokenPerpPnlLeaderboard(params = {}) {
+    const { tokenSymbol, filters = {}, orderBy, pagination, days = 30 } = params;
+    const to = new Date().toISOString().split('T')[0];
+    const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+    return this.request('/api/v1/tgm/perp-pnl-leaderboard', {
+      token_symbol: tokenSymbol,
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  // ============= Portfolio Endpoints =============
+
+  async portfolioDefiHoldings(params = {}) {
+    const { walletAddress } = params;
+    return this.request('/api/v1/portfolio/defi-holdings', {
+      wallet_address: walletAddress
+    });
+  }
+}
+
+export default NansenAPI;

package/src/index.js

@@ -0,0 +1,404 @@
+#!/usr/bin/env node
+/**
+ * Nansen CLI - Command-line interface for Nansen API
+ * Designed for AI agents with structured JSON output
+ * 
+ * Usage: nansen <command> [options]
+ * 
+ * All output is JSON for easy parsing by AI agents.
+ * Use --pretty for human-readable formatting.
+ */
+
+import { NansenAPI, saveConfig, deleteConfig, getConfigFile } from './api.js';
+import * as readline from 'readline';
+
+// Parse command line arguments
+function parseArgs(args) {
+  const result = { _: [], flags: {}, options: {} };
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      
+      if (key === 'pretty' || key === 'help') {
+        result.flags[key] = true;
+      } else if (next && !next.startsWith('-')) {
+        // Try to parse as JSON first
+        try {
+          result.options[key] = JSON.parse(next);
+        } catch {
+          result.options[key] = next;
+        }
+        i++;
+      } else {
+        result.flags[key] = true;
+      }
+    } else if (arg.startsWith('-')) {
+      result.flags[arg.slice(1)] = true;
+    } else {
+      result._.push(arg);
+    }
+  }
+  
+  return result;
+}
+
+// Output helper
+function output(data, pretty = false) {
+  if (pretty) {
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    console.log(JSON.stringify(data));
+  }
+}
+
+// Error output
+function errorOutput(error, pretty = false) {
+  const errorData = {
+    success: false,
+    error: error.message,
+    status: error.status,
+    details: error.data
+  };
+  output(errorData, pretty);
+  process.exit(1);
+}
+
+// Help text
+const HELP = `
+Nansen CLI - Command-line interface for Nansen API
+Designed for AI agents with structured JSON output.
+
+USAGE:
+  nansen <command> [subcommand] [options]
+
+COMMANDS:
+  login          Save your API key (interactive)
+  logout         Remove saved API key
+  smart-money    Smart Money analytics (netflow, dex-trades, holdings, dcas, historical-holdings)
+  profiler       Wallet profiling (balance, labels, transactions, pnl, perp-positions, perp-trades)
+  token          Token God Mode (screener, holders, flows, trades, pnl, perp-trades, perp-positions)
+  portfolio      Portfolio analytics (defi-holdings)
+  help           Show this help message
+
+GLOBAL OPTIONS:
+  --pretty       Format JSON output for readability
+  --chain        Blockchain to query (ethereum, solana, base, etc.)
+  --chains       Multiple chains as JSON array
+  --limit        Number of results (shorthand for pagination)
+  --filters      JSON object with filters
+  --order-by     JSON array with sort order
+  --days         Date range in days (default: 30 for most endpoints)
+  --symbol       Token symbol (for perp endpoints)
+
+EXAMPLES:
+  # Get Smart Money netflow on Solana
+  nansen smart-money netflow --chain solana
+
+  # Get top tokens by Smart Money activity
+  nansen token screener --chain solana --timeframe 24h --pretty
+
+  # Get wallet balance
+  nansen profiler balance --address 0x123... --chain ethereum
+
+  # Get wallet labels
+  nansen profiler labels --address 0x123... --chain ethereum
+
+  # Search for entity
+  nansen profiler search --query "Vitalik"
+
+  # Get token holders with filters
+  nansen token holders --token 0x123... --filters '{"only_smart_money":true}'
+
+SMART MONEY LABELS:
+  Fund, Smart Trader, 30D Smart Trader, 90D Smart Trader, 
+  180D Smart Trader, Smart HL Perps Trader
+
+SUPPORTED CHAINS:
+  ethereum, solana, base, bnb, arbitrum, polygon, optimism,
+  avalanche, linea, scroll, zksync, mantle, ronin, sei,
+  plasma, sonic, unichain, monad, hyperevm, iotaevm
+
+For more info: https://docs.nansen.ai
+`;
+
+// Command handlers
+// Helper to prompt for input
+async function prompt(question, hidden = false) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  
+  return new Promise((resolve) => {
+    if (hidden && process.stdout.isTTY) {
+      process.stdout.write(question);
+      let input = '';
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.setEncoding('utf8');
+      
+      const onData = (char) => {
+        if (char === '\n' || char === '\r') {
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+          process.stdin.removeListener('data', onData);
+          process.stdout.write('\n');
+          rl.close();
+          resolve(input);
+        } else if (char === '\u0003') {
+          // Ctrl+C
+          process.exit();
+        } else if (char === '\u007F' || char === '\b') {
+          // Backspace
+          if (input.length > 0) {
+            input = input.slice(0, -1);
+            process.stdout.write('\b \b');
+          }
+        } else {
+          input += char;
+          process.stdout.write('*');
+        }
+      };
+      
+      process.stdin.on('data', onData);
+    } else {
+      rl.question(question, (answer) => {
+        rl.close();
+        resolve(answer);
+      });
+    }
+  });
+}
+
+const commands = {
+  'login': async (args, api, flags) => {
+    console.log('Nansen CLI Login\n');
+    console.log('Get your API key at: https://app.nansen.ai/api\n');
+    
+    const apiKey = await prompt('Enter your API key: ', true);
+    
+    if (!apiKey || apiKey.trim().length === 0) {
+      console.log('\n❌ No API key provided');
+      process.exit(1);
+    }
+    
+    // Validate the key with a test request
+    console.log('\nValidating API key...');
+    try {
+      const testApi = new NansenAPI(apiKey.trim());
+      await testApi.tokenScreener({ chains: ['solana'], pagination: { page: 1, per_page: 1 } });
+      
+      // Save the config
+      saveConfig({ 
+        apiKey: apiKey.trim(), 
+        baseUrl: 'https://api.nansen.ai' 
+      });
+      
+      console.log('✓ API key validated');
+      console.log(`✓ Saved to ${getConfigFile()}\n`);
+      console.log('You can now use the Nansen CLI. Try:');
+      console.log('  nansen token screener --chain solana --pretty');
+    } catch (error) {
+      console.log(`\n❌ Invalid API key: ${error.message}`);
+      process.exit(1);
+    }
+  },
+
+  'logout': async (args, api, flags) => {
+    const deleted = deleteConfig();
+    if (deleted) {
+      console.log(`✓ Removed ${getConfigFile()}`);
+    } else {
+      console.log('No saved credentials found');
+    }
+  },
+
+  'help': async (args, api, flags) => {
+    console.log(HELP);
+  },
+
+  'smart-money': async (args, api, flags, options) => {
+    const subcommand = args[0] || 'help';
+    const chain = options.chain || 'solana';
+    const chains = options.chains || [chain];
+    const filters = options.filters || {};
+    const orderBy = options['order-by'];
+    const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+
+    // Add smart money label filter if specified
+    if (options.labels) {
+      filters.include_smart_money_labels = Array.isArray(options.labels) 
+        ? options.labels 
+        : [options.labels];
+    }
+
+    const days = options.days ? parseInt(options.days) : 30;
+
+    const handlers = {
+      'netflow': () => api.smartMoneyNetflow({ chains, filters, orderBy, pagination }),
+      'dex-trades': () => api.smartMoneyDexTrades({ chains, filters, orderBy, pagination }),
+      'perp-trades': () => api.smartMoneyPerpTrades({ filters, orderBy, pagination }),
+      'holdings': () => api.smartMoneyHoldings({ chains, filters, orderBy, pagination }),
+      'dcas': () => api.smartMoneyDcas({ filters, orderBy, pagination }),
+      'historical-holdings': () => api.smartMoneyHistoricalHoldings({ chains, filters, orderBy, pagination, days }),
+      'help': () => ({
+        commands: ['netflow', 'dex-trades', 'perp-trades', 'holdings', 'dcas', 'historical-holdings'],
+        description: 'Smart Money analytics endpoints',
+        example: 'nansen smart-money netflow --chain solana --labels Fund'
+      })
+    };
+
+    if (!handlers[subcommand]) {
+      return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
+    }
+
+    return handlers[subcommand]();
+  },
+
+  'profiler': async (args, api, flags, options) => {
+    const subcommand = args[0] || 'help';
+    const address = options.address;
+    const entityName = options.entity || options['entity-name'];
+    const chain = options.chain || 'ethereum';
+    const filters = options.filters || {};
+    const orderBy = options['order-by'];
+    const pagination = options.limit ? { page: 1, recordsPerPage: options.limit } : undefined;
+    const days = options.days ? parseInt(options.days) : 30;
+
+    const handlers = {
+      'balance': () => api.addressBalance({ address, entityName, chain, filters, orderBy }),
+      'labels': () => api.addressLabels({ address, chain, pagination }),
+      'transactions': () => api.addressTransactions({ address, chain, filters, orderBy, pagination }),
+      'pnl': () => api.addressPnl({ address, chain }),
+      'search': () => api.entitySearch({ query: options.query, pagination }),
+      'historical-balances': () => api.addressHistoricalBalances({ address, chain, filters, orderBy, pagination, days }),
+      'related-wallets': () => api.addressRelatedWallets({ address, chain, filters, orderBy, pagination }),
+      'counterparties': () => api.addressCounterparties({ address, chain, filters, orderBy, pagination, days }),
+      'pnl-summary': () => api.addressPnlSummary({ address, chain, filters, orderBy, pagination, days }),
+      'perp-positions': () => api.addressPerpPositions({ address, filters, orderBy, pagination }),
+      'perp-trades': () => api.addressPerpTrades({ address, filters, orderBy, pagination, days }),
+      'help': () => ({
+        commands: ['balance', 'labels', 'transactions', 'pnl', 'search', 'historical-balances', 'related-wallets', 'counterparties', 'pnl-summary', 'perp-positions', 'perp-trades'],
+        description: 'Wallet profiling endpoints',
+        example: 'nansen profiler balance --address 0x123... --chain ethereum'
+      })
+    };
+
+    if (!handlers[subcommand]) {
+      return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
+    }
+
+    return handlers[subcommand]();
+  },
+
+  'token': async (args, api, flags, options) => {
+    const subcommand = args[0] || 'help';
+    const tokenAddress = options.token || options['token-address'];
+    const tokenSymbol = options.symbol || options['token-symbol'];
+    const chain = options.chain || 'solana';
+    const chains = options.chains || [chain];
+    const timeframe = options.timeframe || '24h';
+    const filters = options.filters || {};
+    const orderBy = options['order-by'];
+    const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+    const days = options.days ? parseInt(options.days) : 30;
+
+    // Convenience filter for smart money only
+    const onlySmartMoney = options['smart-money'] || flags['smart-money'] || false;
+    if (onlySmartMoney) {
+      filters.only_smart_money = true;
+    }
+
+    const handlers = {
+      'screener': () => api.tokenScreener({ chains, timeframe, filters, orderBy, pagination }),
+      'holders': () => api.tokenHolders({ tokenAddress, chain, filters, orderBy, pagination }),
+      'flows': () => api.tokenFlows({ tokenAddress, chain, filters, orderBy, pagination }),
+      'dex-trades': () => api.tokenDexTrades({ tokenAddress, chain, onlySmartMoney, filters, orderBy, pagination, days }),
+      'pnl': () => api.tokenPnlLeaderboard({ tokenAddress, chain, filters, orderBy, pagination, days }),
+      'who-bought-sold': () => api.tokenWhoBoughtSold({ tokenAddress, chain, filters, orderBy, pagination }),
+      'flow-intelligence': () => api.tokenFlowIntelligence({ tokenAddress, chain, filters, orderBy, pagination }),
+      'transfers': () => api.tokenTransfers({ tokenAddress, chain, filters, orderBy, pagination, days }),
+      'jup-dca': () => api.tokenJupDca({ tokenAddress, filters, orderBy, pagination }),
+      'perp-trades': () => api.tokenPerpTrades({ tokenSymbol, filters, orderBy, pagination, days }),
+      'perp-positions': () => api.tokenPerpPositions({ tokenSymbol, filters, orderBy, pagination }),
+      'perp-pnl-leaderboard': () => api.tokenPerpPnlLeaderboard({ tokenSymbol, filters, orderBy, pagination, days }),
+      'help': () => ({
+        commands: ['screener', 'holders', 'flows', 'dex-trades', 'pnl', 'who-bought-sold', 'flow-intelligence', 'transfers', 'jup-dca', 'perp-trades', 'perp-positions', 'perp-pnl-leaderboard'],
+        description: 'Token God Mode endpoints',
+        example: 'nansen token screener --chain solana --timeframe 24h --smart-money'
+      })
+    };
+
+    if (!handlers[subcommand]) {
+      return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
+    }
+
+    return handlers[subcommand]();
+  },
+
+  'portfolio': async (args, api, flags, options) => {
+    const subcommand = args[0] || 'help';
+    const walletAddress = options.wallet || options.address;
+
+    const handlers = {
+      'defi': () => api.portfolioDefiHoldings({ walletAddress }),
+      'defi-holdings': () => api.portfolioDefiHoldings({ walletAddress }),
+      'help': () => ({
+        commands: ['defi', 'defi-holdings'],
+        description: 'Portfolio analytics endpoints',
+        example: 'nansen portfolio defi --wallet 0x123...'
+      })
+    };
+
+    if (!handlers[subcommand]) {
+      return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
+    }
+
+    return handlers[subcommand]();
+  }
+};
+
+// Main entry point
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const { _: positional, flags, options } = parseArgs(rawArgs);
+  
+  const command = positional[0] || 'help';
+  const subArgs = positional.slice(1);
+  const pretty = flags.pretty || flags.p;
+
+  if (command === 'help' || flags.help || flags.h) {
+    console.log(HELP);
+    return;
+  }
+
+  if (!commands[command]) {
+    output({ 
+      error: `Unknown command: ${command}`,
+      available: Object.keys(commands)
+    }, pretty);
+    process.exit(1);
+  }
+
+  // Commands that don't require API authentication
+  const noAuthCommands = ['login', 'logout', 'help'];
+  
+  if (noAuthCommands.includes(command)) {
+    await commands[command](subArgs, null, flags, options);
+    return;
+  }
+
+  try {
+    const api = new NansenAPI();
+    const result = await commands[command](subArgs, api, flags, options);
+    output({ success: true, data: result }, pretty);
+  } catch (error) {
+    errorOutput(error, pretty);
+  }
+}
+
+main();