nansen-cli 1.3.3 → 1.5.0

package/CLAUDE.md

@@ -178,14 +178,38 @@ 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
+## Publishing (npm)
 
-Every PR that changes user-facing behavior must include a changeset:
-```bash
-npx changeset
+**⚠️ DO NOT manually run `npm version` or `npm publish`. CI handles everything.**
+
+### How it works:
+
+1. **Add a changeset** for user-facing changes:
+   ```bash
+   npx changeset
+   # Or manually create .changeset/<name>.md
+   ```
+
+2. **Push to main** — CI runs tests
+
+3. **CI creates a "Version Packages" PR** — This bumps version + updates CHANGELOG
+
+4. **Merge the Version PR** — CI auto-publishes to npm
+
+### Changeset format:
+```markdown
+---
+"nansen-cli": minor
+---
+
+Description of changes (appears in CHANGELOG)
 ```
-Choose `patch` for bug fixes, `minor` for new features, `major` for breaking changes.
-CI will not publish without a changeset.
+
+Choose: `patch` (bug fixes), `minor` (new features), `major` (breaking changes)
+
+### If you mess up:
+- Accidentally bumped version manually? `git revert` and add a changeset instead
+- CI publish failed? Check GitHub Actions logs, likely needs `NPM_TOKEN` secret refresh
 
 ## PR Checklist
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -34,12 +34,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/askeluv/nansen-cli.git"
+    "url": "git+https://github.com/nansen-ai/nansen-cli.git"
   },
   "bugs": {
-    "url": "https://github.com/askeluv/nansen-cli/issues"
+    "url": "https://github.com/nansen-ai/nansen-cli/issues"
   },
-  "homepage": "https://github.com/askeluv/nansen-cli#readme",
+  "homepage": "https://github.com/nansen-ai/nansen-cli#readme",
   "engines": {
     "node": ">=18.0.0"
   },

package/src/api.js

@@ -19,6 +19,7 @@ export const ErrorCode = {
   UNAUTHORIZED: 'UNAUTHORIZED',           // 401 - Invalid or missing API key
   FORBIDDEN: 'FORBIDDEN',                 // 403 - Valid key but insufficient permissions
   CREDITS_EXHAUSTED: 'CREDITS_EXHAUSTED', // 403 - Insufficient API credits
+  PAYMENT_REQUIRED: 'PAYMENT_REQUIRED',   // 402 - x402 payment required
   
   // Rate Limiting
   RATE_LIMITED: 'RATE_LIMITED',           // 429 - Too many requests
@@ -87,6 +88,8 @@ function statusToErrorCode(status, data = {}) {
       return ErrorCode.INVALID_PARAMS;
     case 401:
       return ErrorCode.UNAUTHORIZED;
+    case 402:
+      return ErrorCode.PAYMENT_REQUIRED;
     case 403:
       if (messageLower.includes('credit') || messageLower.includes('insufficient')) return ErrorCode.CREDITS_EXHAUSTED;
       return ErrorCode.FORBIDDEN;
@@ -484,6 +487,16 @@ export class NansenAPI {
           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.';
+        } else if (code === ErrorCode.PAYMENT_REQUIRED) {
+          message = 'Payment required (x402). This endpoint requires on-chain payment.';
+          const paymentHeader = response.headers.get('payment-required');
+          if (paymentHeader) {
+            try {
+              data.paymentRequirements = JSON.parse(atob(paymentHeader));
+            } catch {
+              data.paymentRequiredRaw = paymentHeader;
+            }
+          }
         }
 
         lastError = new NansenError(message, code, response.status, {
@@ -634,14 +647,23 @@ export class NansenAPI {
   }
 
   async addressPnl(params = {}) {
-    const { address, chain = 'ethereum' } = params;
+    const { address, chain = 'ethereum', date, days = 30, pagination } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
-    return this.request('/api/v1/profiler/address/pnl-and-trade-performance', {
+    // Build date range
+    let dateRange = date;
+    if (!dateRange) {
+      const to = new Date().toISOString().split('T')[0];
+      const from = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+      dateRange = { from, to };
+    }
+    return this.request('/api/v1/profiler/address/pnl', {
       address,
-      chain
+      chain,
+      date: dateRange,
+      pagination
     });
   }
 
@@ -938,6 +960,55 @@ export class NansenAPI {
     });
   }
 
+  async tokenInformation(params = {}) {
+    const { tokenAddress, chain = 'solana', timeframe = '24h' } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    }
+    return this.request('/api/v1/tgm/token-information', {
+      token_address: tokenAddress,
+      chain,
+      timeframe
+    });
+  }
+
+  // ============= Perp Endpoints =============
+
+  async perpScreener(params = {}) {
+    const { 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/perp-screener', {
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  async perpLeaderboard(params = {}) {
+    const { 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/perp-leaderboard', {
+      date: { from, to },
+      filters,
+      order_by: orderBy,
+      pagination
+    });
+  }
+
+  // ============= Points Endpoints =============
+
+  async pointsLeaderboard(params = {}) {
+    const { tier, pagination } = params;
+    return this.request('/api/v1/points/leaderboard', {
+      tier,
+      pagination
+    });
+  }
+
   // ============= Portfolio Endpoints =============
 
   async portfolioDefiHoldings(params = {}) {

package/src/cli.js

@@ -90,7 +90,7 @@ export const SCHEMA = {
         },
         'pnl': {
           description: 'PnL and trade performance',
-          options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' } },
+          options: { address: { type: 'string', required: true }, chain: { type: 'string', default: 'ethereum' }, date: { type: 'string', 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: ['token_address', 'token_symbol', 'realized_pnl_usd', 'unrealized_pnl_usd', 'total_pnl_usd']
         },
         'search': {
@@ -165,6 +165,15 @@ export const SCHEMA = {
     'token': {
       description: 'Token God Mode - deep analytics for any token',
       subcommands: {
+        'info': {
+          description: 'Get detailed information for a specific token',
+          options: {
+            token: { type: 'string', required: true, description: 'Token address' },
+            chain: { type: 'string', default: 'solana' },
+            timeframe: { type: 'string', default: '24h', enum: ['5m', '10m', '1h', '6h', '24h', '7d', '30d'] }
+          },
+          returns: ['token_address', 'token_symbol', 'token_name', 'chain', 'price_usd', 'volume_usd', 'market_cap', 'holder_count', 'liquidity_usd']
+        },
         'screener': {
           description: 'Discover and filter tokens',
           options: {
@@ -172,6 +181,7 @@ export const SCHEMA = {
             chains: { type: 'array' },
             timeframe: { type: 'string', default: '24h', enum: ['5m', '10m', '1h', '6h', '24h', '7d', '30d'] },
             'smart-money': { type: 'boolean', description: 'Filter for Smart Money only' },
+            search: { type: 'string', description: 'Filter results by token symbol or name (client-side)' },
             limit: { type: 'number' },
             sort: { type: 'string' }
           },
@@ -243,6 +253,44 @@ export const SCHEMA = {
           returns: ['protocol', 'chain', 'position_type', 'token_symbol', 'balance', 'balance_usd']
         }
       }
+    },
+    'perp': {
+      description: 'Perpetual futures analytics',
+      subcommands: {
+        'screener': {
+          description: 'Screen perpetual futures contracts',
+          options: {
+            days: { type: 'number', default: 30 },
+            limit: { type: 'number' },
+            sort: { type: 'string' },
+            filters: { type: 'object' }
+          },
+          returns: ['token_symbol', 'volume_usd', 'open_interest', 'funding_rate', 'price_change_24h']
+        },
+        'leaderboard': {
+          description: 'Perpetual futures PnL leaderboard',
+          options: {
+            days: { type: 'number', default: 30 },
+            limit: { type: 'number' },
+            sort: { type: 'string' },
+            filters: { type: 'object' }
+          },
+          returns: ['address', 'address_label', 'realized_pnl', 'unrealized_pnl', 'total_pnl', 'trade_count', 'win_rate']
+        }
+      }
+    },
+    'points': {
+      description: 'Nansen Points analytics',
+      subcommands: {
+        'leaderboard': {
+          description: 'Points leaderboard',
+          options: {
+            tier: { type: 'string', description: 'Filter by tier' },
+            limit: { type: 'number' }
+          },
+          returns: ['rank', 'address', 'address_label', 'points', 'tier']
+        }
+      }
     }
   },
   globalOptions: {
@@ -773,10 +821,16 @@ COMMANDS:
   logout         Remove saved API key
   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, pnl, batch, trace, compare, counterparties)
-  token          Token God Mode (screener, holders, flows, trades, pnl, perp-trades, perp-positions)
-  portfolio      Portfolio analytics (defi-holdings)
+  smart-money    Smart Money analytics (netflow, dex-trades, perp-trades, holdings, dcas, historical-holdings)
+  profiler       Wallet profiling (balance, labels, transactions, pnl, pnl-summary, search,
+                   historical-balances, related-wallets, counterparties, perp-positions, perp-trades,
+                   batch, trace, compare)
+  token          Token God Mode (info, screener, holders, flows, dex-trades, pnl, who-bought-sold,
+                   flow-intelligence, transfers, jup-dca, perp-trades, perp-positions,
+                   perp-pnl-leaderboard)
+  portfolio      Portfolio analytics (defi)
+  perp           Perpetual futures analytics (screener, leaderboard)
+  points         Nansen Points analytics (leaderboard)
   help           Show this help message
 
 GLOBAL OPTIONS:
@@ -1043,7 +1097,10 @@ export function buildCommands(deps = {}) {
           const date = parseDateOption(options.date, days);
           return apiInstance.addressTransactions({ address, chain, filters, orderBy, pagination, days, date });
         },
-        'pnl': () => apiInstance.addressPnl({ address, chain }),
+        'pnl': () => {
+          const date = parseDateOption(options.date, days);
+          return apiInstance.addressPnl({ address, chain, date, days, pagination });
+        },
         'search': () => apiInstance.entitySearch({ query: options.query }),
         'historical-balances': () => apiInstance.addressHistoricalBalances({ address, chain, filters, orderBy, pagination, days }),
         'related-wallets': () => apiInstance.addressRelatedWallets({ address, chain, orderBy, pagination }),
@@ -1122,7 +1179,31 @@ export function buildCommands(deps = {}) {
       }
 
       const handlers = {
-        'screener': () => apiInstance.tokenScreener({ chains, timeframe, filters, orderBy, pagination }),
+        'info': () => apiInstance.tokenInformation({ tokenAddress, chain, timeframe }),
+        'screener': async () => {
+          const search = options.search;
+          // When searching, fetch more results to filter from (API has no server-side search)
+          const searchPagination = search 
+            ? { page: 1, per_page: Math.max(500, pagination?.per_page || 0) }
+            : pagination;
+          const result = await apiInstance.tokenScreener({ chains, timeframe, filters, orderBy, pagination: searchPagination });
+          if (search) {
+            const q = search.toLowerCase();
+            const requestedLimit = pagination?.per_page || 100;
+            const filterArr = (arr) => arr.filter(t => 
+              (t.token_symbol && t.token_symbol.toLowerCase().includes(q)) ||
+              (t.token_name && t.token_name.toLowerCase().includes(q)) ||
+              (t.token_address && t.token_address.toLowerCase() === q)
+            ).slice(0, requestedLimit);
+            // Handle nested response shapes: {data: [...]} or {data: {data: [...]}}
+            if (Array.isArray(result?.data)) {
+              return { ...result, data: filterArr(result.data) };
+            } else if (result?.data?.data && Array.isArray(result.data.data)) {
+              return { ...result, data: { ...result.data, data: filterArr(result.data.data) } };
+            }
+          }
+          return result;
+        },
         'holders': () => apiInstance.tokenHolders({ tokenAddress, chain, labelType: onlySmartMoney ? 'smart_money' : 'all_holders', filters, orderBy, pagination }),
         'flows': () => {
           const date = parseDateOption(options.date, days);
@@ -1146,7 +1227,7 @@ export function buildCommands(deps = {}) {
         'perp-positions': () => apiInstance.tokenPerpPositions({ tokenSymbol, filters, orderBy, pagination }),
         'perp-pnl-leaderboard': () => apiInstance.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'],
+          commands: ['info', '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'
         })
@@ -1184,6 +1265,51 @@ export function buildCommands(deps = {}) {
         return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
       }
 
+      return handlers[subcommand]();
+    },
+
+    'perp': async (args, apiInstance, flags, options) => {
+      const subcommand = args[0] || 'help';
+      const filters = options.filters || {};
+      const orderBy = parseSort(options.sort, options['order-by']);
+      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+      const days = options.days ? parseInt(options.days) : 30;
+
+      const handlers = {
+        'screener': () => apiInstance.perpScreener({ filters, orderBy, pagination, days }),
+        'leaderboard': () => apiInstance.perpLeaderboard({ filters, orderBy, pagination, days }),
+        'help': () => ({
+          commands: ['screener', 'leaderboard'],
+          description: 'Perpetual futures analytics endpoints',
+          example: 'nansen perp screener --days 7 --limit 20'
+        })
+      };
+
+      if (!handlers[subcommand]) {
+        return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
+      }
+
+      return handlers[subcommand]();
+    },
+
+    'points': async (args, apiInstance, flags, options) => {
+      const subcommand = args[0] || 'help';
+      const tier = options.tier;
+      const pagination = options.limit ? { page: 1, per_page: options.limit } : undefined;
+
+      const handlers = {
+        'leaderboard': () => apiInstance.pointsLeaderboard({ tier, pagination }),
+        'help': () => ({
+          commands: ['leaderboard'],
+          description: 'Nansen Points analytics endpoints',
+          example: 'nansen points leaderboard --limit 100'
+        })
+      };
+
+      if (!handlers[subcommand]) {
+        return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
+      }
+
       return handlers[subcommand]();
     }
   };
@@ -1192,6 +1318,120 @@ export function buildCommands(deps = {}) {
 // Commands that don't require API authentication
 export const NO_AUTH_COMMANDS = ['login', 'logout', 'help', 'schema', 'cache'];
 
+// Command aliases for convenience
+export const COMMAND_ALIASES = {
+  'tgm': 'token',           // Token God Mode
+  'sm': 'smart-money',      // Smart Money
+  'prof': 'profiler',       // Profiler
+  'port': 'portfolio'       // Portfolio
+};
+
+// Generate help text for a specific subcommand using SCHEMA
+export function generateSubcommandHelp(command, subcommand) {
+  const cmdSchema = SCHEMA.commands[command];
+  if (!cmdSchema) return null;
+  
+  const subSchema = cmdSchema.subcommands?.[subcommand];
+  if (!subSchema) return null;
+
+  const lines = [];
+  lines.push(`\n${command} ${subcommand} - ${subSchema.description || 'No description'}\n`);
+  
+  // Usage
+  const requiredOpts = [];
+  const optionalOpts = [];
+  
+  if (subSchema.options) {
+    for (const [name, opt] of Object.entries(subSchema.options)) {
+      if (opt.required) {
+        requiredOpts.push(name);
+      } else {
+        optionalOpts.push(name);
+      }
+    }
+  }
+  
+  let usage = `USAGE:\n  nansen ${command} ${subcommand}`;
+  if (requiredOpts.length) {
+    usage += ' ' + requiredOpts.map(o => `--${o} <value>`).join(' ');
+  }
+  if (optionalOpts.length) {
+    usage += ' [options]';
+  }
+  lines.push(usage);
+  
+  // Required options
+  if (requiredOpts.length) {
+    lines.push('\nREQUIRED:');
+    for (const name of requiredOpts) {
+      const opt = subSchema.options[name];
+      const desc = opt.description || `${opt.type}`;
+      lines.push(`  --${name.padEnd(16)} ${desc}`);
+    }
+  }
+  
+  // Optional options
+  if (optionalOpts.length) {
+    lines.push('\nOPTIONS:');
+    for (const name of optionalOpts) {
+      const opt = subSchema.options[name];
+      const defaultStr = opt.default !== undefined ? ` (default: ${opt.default})` : '';
+      const desc = (opt.description || opt.type) + defaultStr;
+      lines.push(`  --${name.padEnd(16)} ${desc}`);
+    }
+  }
+  
+  // Return fields
+  if (subSchema.returns && subSchema.returns.length) {
+    lines.push('\nRETURNS:');
+    lines.push(`  ${subSchema.returns.join(', ')}`);
+  }
+  
+  // Examples
+  lines.push('\nEXAMPLES:');
+  const chain = subSchema.options?.chain?.default || 'solana';
+  
+  // Example values for common required options
+  const exampleValues = {
+    address: '0x123...',
+    token: '0x123...',
+    query: '"search term"',
+    symbol: 'BTC',
+    date: '2024-01-01'
+  };
+  
+  // Build example based on required options
+  let example = `  nansen ${command} ${subcommand}`;
+  for (const name of requiredOpts) {
+    const value = exampleValues[name] || '<value>';
+    example += ` --${name} ${value}`;
+  }
+  if (subSchema.options?.chain && !requiredOpts.includes('chain')) {
+    example += ` --chain ${chain}`;
+  }
+  example += ' --pretty';
+  lines.push(example);
+  
+  // Add a filtered example if filters are supported
+  if (subSchema.options?.filters || subSchema.options?.labels) {
+    let filterExample = `  nansen ${command} ${subcommand}`;
+    for (const name of requiredOpts) {
+      const value = exampleValues[name] || '<value>';
+      filterExample += ` --${name} ${value}`;
+    }
+    if (subSchema.options?.chain && !requiredOpts.includes('chain')) {
+      filterExample += ` --chain ${chain}`;
+    }
+    if (subSchema.options?.labels) {
+      filterExample += ' --labels "Smart Trader"';
+    }
+    filterExample += ' --limit 10 --table';
+    lines.push(filterExample);
+  }
+  
+  return lines.join('\n');
+}
+
 // Run CLI with given args (returns result, allows custom output/exit handlers)
 export async function runCLI(rawArgs, deps = {}) {
   const {
@@ -1204,8 +1444,11 @@ export async function runCLI(rawArgs, deps = {}) {
 
   const { _: positional, flags, options } = parseArgs(rawArgs);
 
-  const command = positional[0] || 'help';
+  // Resolve command aliases
+  const rawCommand = positional[0] || 'help';
+  const command = COMMAND_ALIASES[rawCommand] || rawCommand;
   const subArgs = positional.slice(1);
+  const subcommand = subArgs[0];
   const pretty = flags.pretty || flags.p;
   const table = flags.table || flags.t;
   const stream = flags.stream || flags.s;
@@ -1224,6 +1467,32 @@ export async function runCLI(rawArgs, deps = {}) {
   }
 
   if (command === 'help' || flags.help || flags.h) {
+    // Check for subcommand-specific help: nansen <command> <subcommand> --help
+    if (flags.help || flags.h) {
+      // First try subcommand help
+      if (command && subcommand) {
+        const subHelp = generateSubcommandHelp(command, subcommand);
+        if (subHelp) {
+          output(subHelp);
+          notify();
+          return { type: 'subcommand-help', command, subcommand };
+        }
+      }
+      // Then try command-level help (list subcommands)
+      if (command && SCHEMA.commands[command]) {
+        const cmdSchema = SCHEMA.commands[command];
+        const lines = [`\n${command} - ${cmdSchema.description}\n`];
+        lines.push('SUBCOMMANDS:');
+        for (const [sub, subSchema] of Object.entries(cmdSchema.subcommands || {})) {
+          lines.push(`  ${sub.padEnd(20)} ${subSchema.description || ''}`);
+        }
+        lines.push(`\nFor detailed help: nansen ${command} <subcommand> --help`);
+        output(lines.join('\n'));
+        notify();
+        return { type: 'command-help', command };
+      }
+    }
+    // Fallback to main help
     output(BANNER + HELP);
     notify();
     return { type: 'help' };