nansen-cli 1.26.0 → 1.27.0

package/src/cli.js

@@ -3,7 +3,7 @@
  * Extracted from index.js for coverage
  */
 
-import { NansenAPI, NansenError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, normalizeAddress, sleep } from './api.js';
+import { NansenAPI, NansenError, CommandError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, normalizeAddress, sleep } from './api.js';
 import { buildWalletCommands } from './wallet.js';
 import { buildTradingCommands } from './trading.js';
 import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
@@ -793,7 +793,6 @@ export function buildCommands(deps = {}) {
     saveConfigFn = saveConfig,
     deleteConfigFn = deleteConfig,
     getConfigFileFn = getConfigFile,
-    exit = process.exit,
     isTTY = process.stdin.isTTY
   } = deps;
 
@@ -895,12 +894,10 @@ export function buildCommands(deps = {}) {
 
       if (!apiKey && flags.human) {
         if (!isTTY) {
-          log(JSON.stringify({
+          throw new CommandError('--human requires an interactive terminal. Use --api-key or NANSEN_API_KEY env var instead.', 'NOT_A_TTY', {
             error: 'NOT_A_TTY',
             message: '--human requires an interactive terminal. Use --api-key or NANSEN_API_KEY env var instead.',
-          }));
-          exit(1);
-          return;
+          });
         }
         log('Nansen CLI Login\n');
         log('Get your API key at: https://app.nansen.ai/auth/agent-setup\n');
@@ -908,7 +905,7 @@ export function buildCommands(deps = {}) {
       }
 
       if (!apiKey || apiKey.trim().length === 0) {
-        log(JSON.stringify({
+        throw new CommandError('No API key provided.', 'API_KEY_REQUIRED', {
           error: 'API_KEY_REQUIRED',
           message: 'No API key provided.',
           resolution: [
@@ -916,9 +913,7 @@ export function buildCommands(deps = {}) {
             'Or set NANSEN_API_KEY environment variable',
             'Get your API key at: https://app.nansen.ai/auth/agent-setup',
           ],
-        }));
-        exit(1);
-        return;
+        });
       }
 
       // Verify API key before saving
@@ -933,20 +928,17 @@ export function buildCommands(deps = {}) {
         accountInfo = await testApi.getAccount();
       } catch (error) {
         if (error.code === ErrorCode.UNAUTHORIZED) {
-          log(JSON.stringify({
+          throw new CommandError('The API key is not valid.', 'INVALID_API_KEY', {
             error: 'INVALID_API_KEY',
             message: 'The API key is not valid.',
-            resolution: ['Check your key at https://app.nansen.ai/auth/agent-setup']
-          }));
-        } else {
-          log(JSON.stringify({
-            error: 'VERIFICATION_FAILED',
-            message: `Could not verify API key: ${error.message}`,
-            resolution: ['Check your internet connection', 'Try again']
-          }));
+            resolution: ['Check your key at https://app.nansen.ai/auth/agent-setup'],
+          });
         }
-        exit(1);
-        return;
+        throw new CommandError(`Could not verify API key: ${error.message}`, 'VERIFICATION_FAILED', {
+          error: 'VERIFICATION_FAILED',
+          message: `Could not verify API key: ${error.message}`,
+          resolution: ['Check your internet connection', 'Try again'],
+        });
       }
 
       // Key is valid - now save
@@ -1415,23 +1407,40 @@ export function buildCommands(deps = {}) {
       const sortBy = options['sort-by'];
       const query = options.query;
       const status = options.status;
-      const sort = parseSort(options.sort);
+      const orderBy = parseSort(options.sort, options['order-by']);
       const pagination = buildPagination(options);
 
+      // Screener-specific filter options
+      const tags = options.tags ? options.tags.split(',').map(t => t.trim()) : undefined;
+      const minLiquidity = options['min-liquidity'] != null ? Number(options['min-liquidity']) : undefined;
+      const maxLiquidity = options['max-liquidity'] != null ? Number(options['max-liquidity']) : undefined;
+      const minUniqueTraders24h = options['min-unique-traders-24h'] != null ? Number(options['min-unique-traders-24h']) : undefined;
+      const maxUniqueTraders24h = options['max-unique-traders-24h'] != null ? Number(options['max-unique-traders-24h']) : undefined;
+      const minVolume24hr = options['min-volume-24hr'] != null ? Number(options['min-volume-24hr']) : undefined;
+      const maxVolume24hr = options['max-volume-24hr'] != null ? Number(options['max-volume-24hr']) : undefined;
+      const negRisk = options['neg-risk'] != null ? options['neg-risk'] === 'true' : undefined;
+      const minOpenInterest = options['min-open-interest'] != null ? Number(options['min-open-interest']) : undefined;
+      const maxOpenInterest = options['max-open-interest'] != null ? Number(options['max-open-interest']) : undefined;
+      const endDateBefore = options['end-date-before'];
+      const endDateAfter = options['end-date-after'];
+      const minPrice = options['min-price'] != null ? Number(options['min-price']) : undefined;
+      const maxPrice = options['max-price'] != null ? Number(options['max-price']) : undefined;
+
       const handlers = {
-        'ohlcv': () => apiInstance.pmOhlcv({ marketId, sort, pagination }),
+        'ohlcv': () => apiInstance.pmOhlcv({ marketId, orderBy, pagination }),
         'orderbook': () => apiInstance.pmOrderbook({ marketId, pagination }),
-        'top-holders': () => apiInstance.pmTopHolders({ marketId, sort, pagination }),
-        'trades-by-market': () => apiInstance.pmTradesByMarket({ marketId, pagination }),
-        'trades-by-address': () => apiInstance.pmTradesByAddress({ address, pagination }),
-        'market-screener': () => apiInstance.pmMarketScreener({ sortBy, query, status, pagination }),
-        'event-screener': () => apiInstance.pmEventScreener({ sortBy, query, status, pagination }),
-        'pnl-by-market': () => apiInstance.pmPnlByMarket({ marketId, pagination }),
-        'pnl-by-address': () => apiInstance.pmPnlByAddress({ address, pagination }),
+        'top-holders': () => apiInstance.pmTopHolders({ marketId, orderBy, pagination }),
+        'trades-by-market': () => apiInstance.pmTradesByMarket({ marketId, orderBy, pagination }),
+        'trades-by-address': () => apiInstance.pmTradesByAddress({ address, orderBy, pagination }),
+        'market-screener': () => apiInstance.pmMarketScreener({ orderBy, sortBy, query, status, tags, minLiquidity, maxLiquidity, minUniqueTraders24h, maxUniqueTraders24h, minVolume24hr, maxVolume24hr, negRisk, minOpenInterest, maxOpenInterest, endDateBefore, endDateAfter, minPrice, maxPrice, pagination }),
+        'event-screener': () => apiInstance.pmEventScreener({ orderBy, sortBy, query, status, tags, minLiquidity, maxLiquidity, minUniqueTraders24h, maxUniqueTraders24h, minVolume24hr, maxVolume24hr, negRisk, minOpenInterest, maxOpenInterest, endDateBefore, endDateAfter, pagination }),
+        'pnl-by-market': () => apiInstance.pmPnlByMarket({ marketId, orderBy, pagination }),
+        'pnl-by-address': () => apiInstance.pmPnlByAddress({ address, orderBy, pagination }),
         'position-detail': () => apiInstance.pmPositionDetail({ marketId, pagination }),
         'categories': () => apiInstance.pmCategories({ pagination }),
+        'address-summary': () => apiInstance.pmAddressSummary({ address, pagination }),
         'help': () => ({
-          commands: ['ohlcv', 'orderbook', 'top-holders', 'trades-by-market', 'trades-by-address', 'market-screener', 'event-screener', 'pnl-by-market', 'pnl-by-address', 'position-detail', 'categories'],
+          commands: ['ohlcv', 'orderbook', 'top-holders', 'trades-by-market', 'trades-by-address', 'market-screener', 'event-screener', 'pnl-by-market', 'pnl-by-address', 'position-detail', 'categories', 'address-summary'],
           description: 'Polymarket prediction market analytics',
           example: 'nansen research pm market-screener --sort-by volume_24hr --limit 20'
         })
@@ -1732,7 +1741,7 @@ export async function runCLI(rawArgs, deps = {}) {
     };
     const formatted = formatOutput(errorData, { pretty, table });
     output(formatted.text);
-    trackCommandFailed({ command: fullCommand, duration_ms: Date.now() - startTime, error_code: 'UNKNOWN_COMMAND', flags: usedFlags, chain });
+    await trackCommandFailed({ command: fullCommand, duration_ms: Date.now() - startTime, error_code: 'UNKNOWN_COMMAND', flags: usedFlags, chain });
     exit(1);
     return { type: 'error', data: errorData };
   }
@@ -1759,7 +1768,7 @@ export async function runCLI(rawArgs, deps = {}) {
 
     // Commands that handle their own output return undefined
     if (result === undefined) {
-      trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
+      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       return { type: 'no-output', command };
     }
 
@@ -1767,7 +1776,7 @@ export async function runCLI(rawArgs, deps = {}) {
     if (command === 'schema') {
       const formatted = formatOutput(result, { pretty, table: false });
       output(formatted.text);
-      trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
+      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       return { type: 'schema', data: result };
     }
 
@@ -1780,6 +1789,7 @@ export async function runCLI(rawArgs, deps = {}) {
     // Alerts list with --table uses custom table format
     if (command === 'alerts' && subcommand === 'list' && table) {
       output(formatAlertsTable(result));
+      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       return { type: 'success', data: result };
     }
 
@@ -1790,20 +1800,26 @@ export async function runCLI(rawArgs, deps = {}) {
       if (streamOutput) {
         output(streamOutput);
       }
-      trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
+      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
       return { type: 'stream', data: result };
     }
 
     const successData = { success: true, data: result };
     const formatted = formatOutput(successData, { pretty, table, csv });
     output(formatted.text);
-    trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
+    await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
     return { type: csv ? 'csv' : 'success', data: result };
   } catch (error) {
-    const errorData = formatError(error);
-    const formatted = formatOutput(errorData, { pretty, table, csv });
-    output(formatted.text);
-    trackCommandFailed({
+    let errorData;
+    if (error instanceof CommandError) {
+      output(error.data ? JSON.stringify(error.data) : error.message);
+      errorData = { error: error.message, code: error.code };
+    } else {
+      errorData = formatError(error);
+      const formatted = formatOutput(errorData, { pretty, table, csv });
+      output(formatted.text);
+    }
+    await trackCommandFailed({
       command: fullCommand,
       duration_ms: Date.now() - startTime,
       error_code: error.code || 'UNKNOWN',

package/src/index.js

@@ -14,4 +14,4 @@
 import { runCLI } from './cli.js';
 
 // Main entry point
-runCLI(process.argv.slice(2));
+await runCLI(process.argv.slice(2));

package/src/schema.json

@@ -588,18 +588,42 @@
               "endpoint": "/api/v1/prediction-market/market-screener",
               "description": "Get Prediction Market Screener",
               "options": {
-                "query": {
-                  "default": ""
-                }
+                "query": { "default": "" },
+                "sort-by": { "description": "Deprecated: use --sort field:dir instead" },
+                "tags": {},
+                "min-liquidity": {},
+                "max-liquidity": {},
+                "min-unique-traders-24h": {},
+                "max-unique-traders-24h": {},
+                "min-volume-24hr": {},
+                "max-volume-24hr": {},
+                "neg-risk": {},
+                "min-open-interest": {},
+                "max-open-interest": {},
+                "end-date-before": {},
+                "end-date-after": {},
+                "min-price": {},
+                "max-price": {}
               }
             },
             "event-screener": {
               "endpoint": "/api/v1/prediction-market/event-screener",
               "description": "Get Prediction Market Event Screener",
               "options": {
-                "query": {
-                  "default": ""
-                }
+                "query": { "default": "" },
+                "sort-by": { "description": "Deprecated: use --sort field:dir instead" },
+                "tags": {},
+                "min-liquidity": {},
+                "max-liquidity": {},
+                "min-unique-traders-24h": {},
+                "max-unique-traders-24h": {},
+                "min-volume-24hr": {},
+                "max-volume-24hr": {},
+                "neg-risk": {},
+                "min-open-interest": {},
+                "max-open-interest": {},
+                "end-date-before": {},
+                "end-date-after": {}
               }
             },
             "pnl-by-market": {
@@ -641,6 +665,15 @@
             "categories": {
               "endpoint": "/api/v1/prediction-market/categories",
               "description": "Get Prediction Market Categories"
+            },
+            "address-summary": {
+              "endpoint": "/api/v1/prediction-market/address-summary",
+              "description": "Get wallet-level PnL summary for a Polymarket address",
+              "options": {
+                "address": {
+                  "required": true
+                }
+              }
             }
           },
           "description": "Polymarket prediction market analytics"

package/src/telemetry.js

@@ -22,7 +22,7 @@ const { version: cliVersion } = JSON.parse(
 const TELEMETRY_URL =
   'https://bi-data-sources.nansen.ai/events-service-68ifmnpsx2uq7cgab8dw/v2/event';
 
-const TIMEOUT_MS = 2000;
+const TIMEOUT_MS = 1000;
 
 // ─── opt-out ──────────────────────────────────────────────
 
@@ -122,15 +122,17 @@ export function getSessionId() {
 // ─── send ──────────────────────────────────────────────────
 
 /**
- * Send a telemetry event. Fire-and-forget — never throws.
+ * Send a telemetry event. Returns a promise that resolves when the request
+ * completes (or fails/times out). Never rejects — errors are swallowed.
+ * Callers that need to ensure delivery before process.exit can await this.
  */
 function sendEvent(event) {
-  if (TELEMETRY_DISABLED) return;
+  if (TELEMETRY_DISABLED) return Promise.resolve();
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
   timer.unref();
 
-  fetch(TELEMETRY_URL, {
+  return fetch(TELEMETRY_URL, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(event),
@@ -178,7 +180,7 @@ export function trackCommandSucceeded({
   flags = [],
   chain = null,
 }) {
-  sendEvent({
+  return sendEvent({
     event: 'cli_command_succeeded',
     event_source: getEventSource(),
     event_id: crypto.randomUUID(),
@@ -216,7 +218,7 @@ export function trackCommandFailed({
   flags = [],
   chain = null,
 }) {
-  sendEvent({
+  return sendEvent({
     event: 'cli_command_failed',
     event_source: getEventSource(),
     event_id: crypto.randomUUID(),

package/src/trade-validation.js

@@ -61,6 +61,16 @@ export function validateQuoteInput({ chain, toChain, from, to, amount }) {
       );
     }
   }
+
+  // 5. At least one side must be USDC or the native token
+  const fromIsAnchor = isUsdcOrNative(from, normalizedChain);
+  const toIsAnchor = isUsdcOrNative(to, normalizedToChain);
+  if (!fromIsAnchor && !toIsAnchor) {
+    const anchorDesc = normalizedChain === normalizedToChain
+      ? `USDC or the native token (${NATIVE_SYMBOLS[normalizedChain] ?? normalizedChain})`
+      : `USDC or the native token on either side (${NATIVE_SYMBOLS[normalizedChain] ?? normalizedChain} on ${normalizedChain}, ${NATIVE_SYMBOLS[normalizedToChain] ?? normalizedToChain} on ${normalizedToChain})`;
+    throw new Error(`Invalid swap: at least one token must be ${anchorDesc}. Got: ${from} → ${to}.`);
+  }
 }
 
 // Native token decimals per chain (for converting balance from base units)
@@ -112,13 +122,35 @@ const NATIVE_TOKEN_ADDRESSES = {
   base: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
 };
 
+// USDC contract addresses per chain.
+const USDC_ADDRESSES = {
+  solana: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+  base: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+};
+
 // Native token symbols for error messages.
 const NATIVE_SYMBOLS = { solana: 'SOL', base: 'ETH' };
 
+const MIN_GAS_AMOUNTS = { solana: 0.01, base: 0.000024 };
 const FEE_BUFFER = { solana: 0.005, base: 0.00004 };
 const HIGH_PERCENTAGE_THRESHOLD = 95;
 const AUTO_ADJUST_THRESHOLD_PERCENT = 2;
 
+/**
+ * Check if an address is USDC or the native token for a chain (case-insensitive for EVM).
+ */
+function isUsdcOrNative(address, chain) {
+  const usdc = USDC_ADDRESSES[chain];
+  const native = NATIVE_TOKEN_ADDRESSES[chain];
+  if (!usdc && !native) return false;
+  if (chain === 'solana') {
+    return address === usdc || address === native;
+  }
+  // EVM: case-insensitive
+  const lower = address.toLowerCase();
+  return (usdc && lower === usdc.toLowerCase()) || (native && lower === native.toLowerCase());
+}
+
 /**
  * Check if an address is the native token for a chain (case-insensitive for EVM).
  */
@@ -269,6 +301,32 @@ export async function resolvePercentAmount({ chain, from, walletAddress, percent
   return String(parseFloat(tokenAmount.toFixed(decimals)));
 }
 
+/**
+ * Validate that the wallet has enough native token for gas fees.
+ *
+ * Returns { hasSufficientNative } or throws on validation failure.
+ * Best-effort: if RPC fails, returns passing result.
+ */
+export async function validateGasBalance({ chain, walletAddress }) {
+  const normalizedChain = chain.toLowerCase();
+  const minGas = MIN_GAS_AMOUNTS[normalizedChain];
+  if (minGas === undefined) return { hasSufficientNative: true };
+
+  const balance = await fetchNativeBalance(normalizedChain, walletAddress);
+
+  // RPC failure — proceed without validation.
+  if (balance === null) return { hasSufficientNative: true };
+
+  if (balance >= minGas) {
+    return { hasSufficientNative: true };
+  }
+
+  const symbol = NATIVE_SYMBOLS[normalizedChain] || 'native token';
+  throw new Error(
+    `Insufficient ${symbol} for gas fees. Wallet has ${balance} ${symbol} but needs at least ${minGas} ${symbol}. Fund the wallet before trading.`
+  );
+}
+
 /**
  * Fetch an ERC-20 or SPL token balance for a wallet.
  * Returns balance in human-readable token units, or null on RPC failure.