nansen-cli 1.5.1 → 1.6.0

package/README.md

@@ -123,6 +123,21 @@ Deep analytics for any token.
 |------------|-------------|
 | `defi` | DeFi holdings across protocols |
 
+### `search` - Search
+
+Search for tokens and entities across Nansen.
+
+```bash
+nansen search "uniswap" --pretty
+nansen search "uniswap" --type token --chain ethereum
+```
+
+| Option | Description |
+|--------|-------------|
+| `--type` | Filter by result type: `token`, `entity`, or `any` (default) |
+| `--chain` | Filter by chain |
+| `--limit` | Max results, 1-50 (default: 25) |
+
 ### `schema` - Schema Discovery
 
 Output JSON schema for agent introspection. No API key required.
@@ -258,7 +273,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
 | Profiler | 11 | 100% |
 | Token God Mode | 12 | 100% |
 | Portfolio | 1 | 100% |
-| **Total** | **30** | **100%** |
+| Search | 1 | 100% |
+| **Total** | **31** | **100%** |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",

package/src/api.js

@@ -9,6 +9,10 @@ import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const { version: packageVersion } = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+);
+
 // ============= Error Codes =============
 
 /**
@@ -296,36 +300,35 @@ export function validateTokenAddress(tokenAddress, chain = 'solana') {
 }
 
 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`)
+  // Base config from files, then env vars override individual fields
+  let config = null;
+
+  // ~/.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
+    try { config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch (e) {}
+  }
+
+  // Local config.json (for development)
+  if (!config) {
+    const localConfig = path.join(__dirname, '..', 'config.json');
+    if (fs.existsSync(localConfig)) {
+      config = JSON.parse(fs.readFileSync(localConfig, 'utf8'));
     }
   }
-  
-  // Check local config.json (for development)
-  const localConfig = path.join(__dirname, '..', 'config.json');
-  if (fs.existsSync(localConfig)) {
-    return JSON.parse(fs.readFileSync(localConfig, 'utf8'));
+
+  if (!config) {
+    config = { apiKey: null, baseUrl: 'https://api.nansen.ai' };
   }
-  
-  // No config found
-  return {
-    apiKey: null,
-    baseUrl: 'https://api.nansen.ai'
-  };
+
+  // Env vars override individual fields
+  if (process.env.NANSEN_API_KEY) {
+    config.apiKey = process.env.NANSEN_API_KEY;
+  }
+  if (process.env.NANSEN_BASE_URL) {
+    config.baseUrl = process.env.NANSEN_BASE_URL;
+  }
+
+  return config;
 }
 
 const config = loadConfig();
@@ -388,10 +391,11 @@ export class NansenAPI {
     this.apiKey = apiKey || null;
     this.baseUrl = baseUrl;
     this.retryOptions = { ...DEFAULT_RETRY_OPTIONS, ...options.retry };
-    this.cacheOptions = { 
+    this.cacheOptions = {
       enabled: options.cache?.enabled ?? false,
       ttl: options.cache?.ttl ?? DEFAULT_CACHE_TTL
     };
+    this.defaultHeaders = options.defaultHeaders || {};
   }
 
   static cleanBody(body) {
@@ -428,7 +432,10 @@ export class NansenAPI {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
+            'X-Client-Type': 'nansen-cli',
+            'X-Client-Version': packageVersion,
             ...(this.apiKey ? { 'apikey': this.apiKey } : {}),
+            ...this.defaultHeaders,
             ...options.headers
           },
           body: JSON.stringify(NansenAPI.cleanBody(body))
@@ -482,7 +489,7 @@ export class NansenAPI {
         } 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.';
+          message = 'Payment required (x402). Sign the paymentRequirements below per https://docs.x402.org and pass the result with --x402-payment-signature <value>.';
           const paymentHeader = response.headers.get('payment-required');
           if (paymentHeader) {
             try {
@@ -668,6 +675,20 @@ export class NansenAPI {
     });
   }
 
+  async generalSearch(params = {}) {
+    const { query, resultType = 'any', chain, limit = 25 } = params;
+    if (!query) {
+      throw new NansenError('Search query is required', ErrorCode.MISSING_PARAM);
+    }
+    const body = {
+      search_query: query,
+      result_type: resultType,
+      limit
+    };
+    if (chain) body.chain = chain;
+    return this.request('/api/v1/search/general', body);
+  }
+
   async addressHistoricalBalances(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
     if (address) {
@@ -954,8 +975,20 @@ export class NansenAPI {
     });
   }
 
+  async tokenIndicators(params = {}) {
+    const { tokenAddress, chain = 'ethereum' } = params;
+    if (tokenAddress) {
+      const validation = validateTokenAddress(tokenAddress, chain);
+      if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    }
+    return this.request('/api/v1/tgm/indicators', {
+      token_address: tokenAddress,
+      chain
+    });
+  }
+
   async tokenInformation(params = {}) {
-    const { tokenAddress, chain = 'solana', timeframe = '24h' } = params;
+    const { tokenAddress, chain = 'solana', timeframe = '1d' } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);

package/src/cli.js

@@ -165,12 +165,20 @@ export const SCHEMA = {
     'token': {
       description: 'Token God Mode - deep analytics for any token',
       subcommands: {
+        'indicators': {
+          description: 'Risk and reward indicators for a token (Nansen Score)',
+          options: {
+            token: { type: 'string', required: true, description: 'Token address' },
+            chain: { type: 'string', default: 'ethereum' }
+          },
+          returns: ['token_info[market_cap_usd, market_cap_group, is_stablecoin]', 'risk_indicators[indicator_type, score, signal, signal_percentile, last_trigger_on]', 'reward_indicators[indicator_type, score, signal, signal_percentile, last_trigger_on]']
+        },
         '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'] }
+            timeframe: { type: 'string', default: '1d', enum: ['5m', '1h', '6h', '12h', '1d', '7d'] }
           },
           returns: ['token_address', 'token_symbol', 'token_name', 'chain', 'price_usd', 'volume_usd', 'market_cap', 'holder_count', 'liquidity_usd']
         },
@@ -279,6 +287,16 @@ export const SCHEMA = {
         }
       }
     },
+    'search': {
+      description: 'Search for tokens and entities across Nansen',
+      options: {
+        query: { type: 'string', required: true, description: 'Search query (token name, symbol, address, or entity)' },
+        type: { type: 'string', default: 'any', enum: ['token', 'entity', 'any'], description: 'Result type filter' },
+        chain: { type: 'string', description: 'Filter by chain (e.g., ethereum, solana)' },
+        limit: { type: 'number', default: 25, description: 'Max results (1-50)' }
+      },
+      returns: ['tokens[name, symbol, chain, address, price, volume_24h, market_cap, rank]', 'entities[name, tags, rank]', 'total_results']
+    },
     'points': {
       description: 'Nansen Points analytics',
       subcommands: {
@@ -299,7 +317,8 @@ export const SCHEMA = {
     fields: { type: 'string', description: 'Comma-separated list of fields to include in output' },
     'no-retry': { type: 'boolean', description: 'Disable automatic retry on rate limits/errors' },
     retries: { type: 'number', default: 3, description: 'Max retry attempts' },
-    format: { type: 'string', enum: ['json', 'csv'], description: 'Output format (default: json)' }
+    format: { type: 'string', enum: ['json', 'csv'], description: 'Output format (default: json)' },
+    'x402-payment-signature': { type: 'string', description: 'Pre-signed x402 payment signature header' }
   },
   chains: ['ethereum', 'solana', 'base', 'bnb', 'arbitrum', 'polygon', 'optimism', 'avalanche', 'linea', 'scroll', 'mantle', 'ronin', 'sei', 'plasma', 'sonic', 'monad', 'hyperevm', 'iotaevm'],
   smartMoneyLabels: ['Fund', 'Smart Trader', '30D Smart Trader', '90D Smart Trader', '180D Smart Trader', 'Smart HL Perps Trader']
@@ -825,9 +844,9 @@ COMMANDS:
   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)
+  token          Token God Mode (info, indicators, 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)
@@ -847,6 +866,7 @@ GLOBAL OPTIONS:
   --symbol       Token symbol (for perp endpoints)
   --no-retry     Disable automatic retry on rate limits/errors
   --retries <n>  Max retry attempts (default: 3)
+  --x402-payment-signature <sig>  Pre-signed x402 payment signature header
   --cache        Enable response caching (default: off)
   --no-cache     Disable cache for this request
   --cache-ttl <s> Cache TTL in seconds (default: 300)
@@ -1179,7 +1199,8 @@ export function buildCommands(deps = {}) {
       }
 
       const handlers = {
-        'info': () => apiInstance.tokenInformation({ tokenAddress, chain, timeframe }),
+        'indicators': () => apiInstance.tokenIndicators({ tokenAddress, chain }),
+        'info': () => apiInstance.tokenInformation({ tokenAddress, chain, timeframe: options.timeframe }),
         'screener': async () => {
           const search = options.search;
           // When searching, fetch more results to filter from (API has no server-side search)
@@ -1292,6 +1313,15 @@ export function buildCommands(deps = {}) {
       return handlers[subcommand]();
     },
 
+    'search': async (args, apiInstance, flags, options) => {
+      return apiInstance.generalSearch({
+        query: args[0] || options.query,
+        resultType: options.type,
+        chain: options.chain,
+        limit: options.limit
+      });
+    },
+
     'points': async (args, apiInstance, flags, options) => {
       const subcommand = args[0] || 'help';
       const tier = options.tier;
@@ -1538,7 +1568,11 @@ export async function runCLI(rawArgs, deps = {}) {
       ttl: options['cache-ttl'] !== undefined ? options['cache-ttl'] : 300
     };
     
-    const api = new NansenAPIClass(undefined, undefined, { retry: retryOptions, cache: cacheOptions });
+    const defaultHeaders = {};
+    if (options['x402-payment-signature']) {
+      defaultHeaders['Payment-Signature'] = options['x402-payment-signature'];
+    }
+    const api = new NansenAPIClass(undefined, undefined, { retry: retryOptions, cache: cacheOptions, defaultHeaders });
     let result = await commands[command](subArgs, api, flags, options);
     
     // Apply field filtering if --fields is specified
@@ -1566,7 +1600,7 @@ export async function runCLI(rawArgs, deps = {}) {
   } catch (error) {
     const errorData = formatError(error);
     const formatted = formatOutput(errorData, { pretty, table, csv });
-    errorOutput(formatted.text);
+    output(formatted.text);
     notify();
     exit(1);
     return { type: 'error', data: errorData };