nansen-cli 1.20.0 → 1.22.0

package/src/schema.json

@@ -6,6 +6,7 @@
         "portfolio": {
           "subcommands": {
             "defi": {
+              "endpoint": "/api/v1/portfolio/defi-holdings",
               "description": "DeFi holdings across protocols",
               "options": {
                 "wallet": {
@@ -19,6 +20,7 @@
         "smart-money": {
           "subcommands": {
             "netflow": {
+              "endpoint": "/api/v1/smart-money/netflow",
               "description": "Net capital flows (inflows vs outflows)",
               "options": {
                 "chain": {
@@ -27,6 +29,7 @@
               }
             },
             "dex-trades": {
+              "endpoint": "/api/v1/smart-money/dex-trades",
               "description": "Real-time DEX trading activity",
               "options": {
                 "chain": {
@@ -35,12 +38,15 @@
               }
             },
             "perp-trades": {
+              "endpoint": "/api/v1/smart-money/perp-trades",
               "description": "Perpetual trading on Hyperliquid"
             },
             "dcas": {
+              "endpoint": "/api/v1/smart-money/dcas",
               "description": "DCA strategies on Jupiter"
             },
             "holdings": {
+              "endpoint": "/api/v1/smart-money/holdings",
               "description": "Aggregated token balances",
               "options": {
                 "chain": {
@@ -49,6 +55,7 @@
               }
             },
             "historical-holdings": {
+              "endpoint": "/api/v1/smart-money/historical-holdings",
               "description": "Historical holdings over time",
               "options": {
                 "chain": {
@@ -65,6 +72,7 @@
         "profiler": {
           "subcommands": {
             "transactions": {
+              "endpoint": "/api/v1/profiler/address/transactions",
               "description": "Transaction history",
               "options": {
                 "address": {
@@ -79,6 +87,7 @@
               }
             },
             "pnl-summary": {
+              "endpoint": "/api/v1/profiler/address/pnl-summary",
               "description": "Summarized PnL metrics",
               "options": {
                 "address": {
@@ -93,6 +102,7 @@
               }
             },
             "balance": {
+              "endpoint": "/api/v1/profiler/address/current-balance",
               "description": "Current token holdings",
               "options": {
                 "address": {
@@ -104,6 +114,7 @@
               }
             },
             "counterparties": {
+              "endpoint": "/api/v1/profiler/address/counterparties",
               "description": "Top counterparties by volume",
               "options": {
                 "address": {
@@ -118,6 +129,7 @@
               }
             },
             "historical-balances": {
+              "endpoint": "/api/v1/profiler/address/historical-balances",
               "description": "Historical balances over time",
               "options": {
                 "address": {
@@ -132,6 +144,7 @@
               }
             },
             "related-wallets": {
+              "endpoint": "/api/v1/profiler/address/related-wallets",
               "description": "Find wallets related to an address",
               "options": {
                 "address": {
@@ -143,6 +156,7 @@
               }
             },
             "pnl": {
+              "endpoint": "/api/v1/profiler/address/pnl",
               "description": "PnL and trade performance",
               "options": {
                 "address": {
@@ -157,6 +171,7 @@
               }
             },
             "labels": {
+              "endpoint": "/api/v1/profiler/address/labels",
               "description": "Behavioral and entity labels",
               "options": {
                 "address": {
@@ -168,6 +183,7 @@
               }
             },
             "perp-positions": {
+              "endpoint": "/api/v1/profiler/perp-positions",
               "description": "Current perpetual positions",
               "options": {
                 "address": {
@@ -176,6 +192,7 @@
               }
             },
             "perp-trades": {
+              "endpoint": "/api/v1/profiler/perp-trades",
               "description": "Perpetual trading history",
               "options": {
                 "address": {
@@ -187,6 +204,7 @@
               }
             },
             "search": {
+              "endpoint": "/api/v1/search/entity-name",
               "description": "Search for entities by name",
               "options": {
                 "query": {
@@ -251,6 +269,7 @@
         "token": {
           "subcommands": {
             "flows": {
+              "endpoint": "/api/v1/tgm/flows",
               "description": "Token flow metrics",
               "options": {
                 "chain": {
@@ -261,10 +280,16 @@
                 },
                 "days": {
                   "default": 30
+                },
+                "label": {
+                  "description": "Holder segment to filter flows by",
+                  "enum": ["top_100_holders", "smart_money", "public_figure", "whale", "exchange"],
+                  "default": "top_100_holders"
                 }
               }
             },
             "who-bought-sold": {
+              "endpoint": "/api/v1/tgm/who-bought-sold",
               "description": "Recent buyers and sellers",
               "options": {
                 "chain": {
@@ -279,6 +304,7 @@
               }
             },
             "dex-trades": {
+              "endpoint": "/api/v1/tgm/dex-trades",
               "description": "DEX trading activity",
               "options": {
                 "chain": {
@@ -293,6 +319,7 @@
               }
             },
             "transfers": {
+              "endpoint": "/api/v1/tgm/transfers",
               "description": "Token transfer history",
               "options": {
                 "chain": {
@@ -307,6 +334,7 @@
               }
             },
             "holders": {
+              "endpoint": "/api/v1/tgm/holders",
               "description": "Token holder analysis",
               "options": {
                 "chain": {
@@ -318,6 +346,7 @@
               }
             },
             "pnl": {
+              "endpoint": "/api/v1/tgm/pnl-leaderboard",
               "description": "PnL leaderboard",
               "options": {
                 "chain": {
@@ -332,6 +361,7 @@
               }
             },
             "perp-pnl-leaderboard": {
+              "endpoint": "/api/v1/tgm/perp-pnl-leaderboard",
               "description": "Perp PnL leaderboard by token",
               "options": {
                 "symbol": {
@@ -343,6 +373,7 @@
               }
             },
             "perp-positions": {
+              "endpoint": "/api/v1/tgm/perp-positions",
               "description": "Open perp positions by token symbol",
               "options": {
                 "symbol": {
@@ -351,6 +382,7 @@
               }
             },
             "perp-trades": {
+              "endpoint": "/api/v1/tgm/perp-trades",
               "description": "Perp trades by token symbol",
               "options": {
                 "symbol": {
@@ -362,6 +394,7 @@
               }
             },
             "flow-intelligence": {
+              "endpoint": "/api/v1/tgm/flow-intelligence",
               "description": "Detailed flow intelligence by label",
               "options": {
                 "chain": {
@@ -376,6 +409,7 @@
               }
             },
             "info": {
+              "endpoint": "/api/v1/tgm/token-information",
               "description": "Get detailed information for a specific token",
               "options": {
                 "chain": {
@@ -390,6 +424,7 @@
               }
             },
             "indicators": {
+              "endpoint": "/api/v1/tgm/indicators",
               "description": "Risk and reward indicators for a token (Nansen Score)",
               "options": {
                 "chain": {
@@ -401,6 +436,7 @@
               }
             },
             "ohlcv": {
+              "endpoint": "/api/v1/tgm/token-ohlcv",
               "description": "OHLCV candle data for a token",
               "options": {
                 "chain": {
@@ -415,6 +451,7 @@
               }
             },
             "jup-dca": {
+              "endpoint": "/api/v1/tgm/jup-dca",
               "description": "Jupiter DCA orders for token",
               "options": {
                 "token": {
@@ -423,6 +460,7 @@
               }
             },
             "screener": {
+              "endpoint": "/api/v1/token-screener",
               "description": "Discover and filter tokens",
               "options": {
                 "timeframe": {
@@ -430,6 +468,10 @@
                 },
                 "chain": {
                   "default": "solana"
+                },
+                "include-stablecoins": {
+                  "description": "Whether to include stablecoins in screener results (default true on API side)",
+                  "default": true
                 }
               }
             }
@@ -437,6 +479,7 @@
           "description": "Token God Mode - deep analytics for any token"
         },
         "search": {
+          "endpoint": "/api/v1/search/general",
           "description": "Search for tokens and entities across Nansen",
           "options": {
             "query": {
@@ -453,6 +496,7 @@
         "perp": {
           "subcommands": {
             "screener": {
+              "endpoint": "/api/v1/perp-screener",
               "description": "Screen perpetual futures contracts",
               "options": {
                 "days": {
@@ -461,6 +505,7 @@
               }
             },
             "leaderboard": {
+              "endpoint": "/api/v1/perp-leaderboard",
               "description": "Perpetual futures PnL leaderboard",
               "options": {
                 "days": {
@@ -474,6 +519,7 @@
         "prediction-market": {
           "subcommands": {
             "ohlcv": {
+              "endpoint": "/api/v1/prediction-market/ohlcv",
               "description": "Get Prediction Market OHLCV Candles",
               "options": {
                 "market-id": {
@@ -482,6 +528,7 @@
               }
             },
             "orderbook": {
+              "endpoint": "/api/v1/prediction-market/orderbook",
               "description": "Get Prediction Market Orderbook",
               "options": {
                 "market-id": {
@@ -490,6 +537,7 @@
               }
             },
             "top-holders": {
+              "endpoint": "/api/v1/prediction-market/top-holders",
               "description": "Get Prediction Market Top Holders",
               "options": {
                 "market-id": {
@@ -498,6 +546,7 @@
               }
             },
             "trades-by-market": {
+              "endpoint": "/api/v1/prediction-market/trades-by-market",
               "description": "Get Prediction Market Trades by Market",
               "options": {
                 "market-id": {
@@ -506,6 +555,7 @@
               }
             },
             "market-screener": {
+              "endpoint": "/api/v1/prediction-market/market-screener",
               "description": "Get Prediction Market Screener",
               "options": {
                 "query": {
@@ -514,6 +564,7 @@
               }
             },
             "event-screener": {
+              "endpoint": "/api/v1/prediction-market/event-screener",
               "description": "Get Prediction Market Event Screener",
               "options": {
                 "query": {
@@ -522,6 +573,7 @@
               }
             },
             "pnl-by-market": {
+              "endpoint": "/api/v1/prediction-market/pnl-by-market",
               "description": "Get Prediction Market PnL by Market",
               "options": {
                 "market-id": {
@@ -530,6 +582,7 @@
               }
             },
             "pnl-by-address": {
+              "endpoint": "/api/v1/prediction-market/pnl-by-address",
               "description": "Get Prediction Market PnL by Address",
               "options": {
                 "address": {
@@ -538,6 +591,7 @@
               }
             },
             "position-detail": {
+              "endpoint": "/api/v1/prediction-market/position-detail",
               "description": "Get Prediction Market Position Detail",
               "options": {
                 "market-id": {
@@ -546,6 +600,7 @@
               }
             },
             "trades-by-address": {
+              "endpoint": "/api/v1/prediction-market/trades-by-address",
               "description": "Get Prediction Market Trades by Address",
               "options": {
                 "address": {
@@ -554,6 +609,7 @@
               }
             },
             "categories": {
+              "endpoint": "/api/v1/prediction-market/categories",
               "description": "Get Prediction Market Categories"
             }
           },
@@ -715,7 +771,11 @@
             "amount": {
               "type": "string",
               "required": true,
-              "description": "Amount to swap"
+              "description": "Amount to swap (base units by default, or token units with --amount-unit token)"
+            },
+            "amount-unit": {
+              "type": "string",
+              "description": "\"token\" to specify amount in token units (e.g. 0.5 SOL), or \"base\" for base units (default). Decimals are resolved locally and the API always receives base units."
             },
             "wallet": {
               "type": "string",
@@ -826,6 +886,35 @@
           ]
         }
       }
+    },
+    "agent": {
+      "description": "Nansen AI research agent \u2014 ask questions about wallets, tokens, and on-chain activity",
+      "options": {
+        "expert": {
+          "type": "boolean",
+          "description": "Use expert mode (deeper analysis, slower). Default: fast mode."
+        },
+        "conversation-id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Continue a previous conversation by passing its UUID v4 ID"
+        },
+        "json": {
+          "type": "boolean",
+          "description": "Output raw JSON (conversation_id, mode, text, tool_calls) instead of formatted text"
+        }
+      },
+      "examples": [
+        "nansen agent \"What are the top smart money inflows on Ethereum today?\"",
+        "nansen agent \"Analyze wallet 0xd8dA...6045\" --expert",
+        "nansen agent \"Tell me more\" --conversation-id <id>"
+      ],
+      "returns": [
+        "conversation_id",
+        "mode",
+        "text",
+        "tool_calls"
+      ]
     }
   },
   "globalOptions": {

package/src/trading.js

@@ -683,6 +683,101 @@ export function getWrappedNativeFromWarning(tokenAddress, chain) {
   return null;
 }
 
+// ============= Token Decimal Resolution =============
+
+// Hardcoded decimals for well-known tokens — avoids RPC calls in the common case.
+const KNOWN_DECIMALS = {
+  // Solana
+  'So11111111111111111111111111111111111111112': 9,   // SOL/WSOL
+  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v': 6, // USDC
+  'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB': 6,  // USDT
+  // Base (EVM) — lowercase for case-insensitive matching
+  '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee': 18, // ETH native
+  '0x4200000000000000000000000000000000000006': 18, // WETH
+  '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': 6, // USDC
+  '0xfde4c96c8593536e31f229ea8f37b2ada2699bb2': 6, // USDT
+};
+
+/**
+ * Resolve the number of decimals for a token.
+ * Checks a hardcoded map first, then falls back to an RPC call.
+ * Solana: getAccountInfo with jsonParsed encoding.
+ * EVM: eth_call to decimals() selector 0x313ce567.
+ */
+export async function resolveTokenDecimals(tokenAddress, chainName) {
+  // Normalise for map lookup (EVM addresses are case-insensitive)
+  const key = tokenAddress.startsWith('0x') ? tokenAddress.toLowerCase() : tokenAddress;
+  if (KNOWN_DECIMALS[key] !== undefined) return KNOWN_DECIMALS[key];
+
+  const chain = chainName.toLowerCase();
+  const chainConfig = CHAIN_MAP[chain];
+  if (!chainConfig) throw new Error(`Unknown chain: ${chain}`);
+
+  // Validate address format before making RPC calls.
+  // A bare symbol like "SOL" that didn't resolve means it's not recognized on this chain.
+  if (chainConfig.type === 'solana') {
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(tokenAddress)) {
+      throw new Error(`"${tokenAddress}" is not a recognized token on ${chainName}. Use a valid Solana address (base58, 32-44 chars).`);
+    }
+  } else {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(tokenAddress)) {
+      throw new Error(`"${tokenAddress}" is not a recognized token on ${chainName}. Use a valid EVM address (0x + 40 hex chars).`);
+    }
+  }
+
+  if (chainConfig.type === 'solana') {
+    const rpcUrl = CHAIN_RPCS.solana;
+    const res = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getAccountInfo', params: [tokenAddress, { encoding: 'jsonParsed' }] }),
+    });
+    const body = await res.json();
+    const decimals = body.result?.value?.data?.parsed?.info?.decimals;
+    if (decimals === undefined) throw new Error(`Could not resolve decimals for Solana token ${tokenAddress}`);
+    return decimals;
+  }
+
+  // EVM — eth_call to decimals()
+  const result = await evmRpcCall(chain, 'eth_call', [{ to: tokenAddress, data: '0x313ce567' }, 'latest']);
+  const decimals = parseInt(result, 16);
+  if (isNaN(decimals) || decimals > 255) throw new Error(`Could not resolve decimals for EVM token ${tokenAddress}`);
+  return decimals;
+}
+
+/**
+ * Convert a human-readable token amount to base units using string math.
+ * Avoids floating-point precision issues by operating on digit strings.
+ * Example: convertToBaseUnits('0.5', 9) => '500000000'
+ */
+export function convertToBaseUnits(amount, decimals) {
+  const str = String(amount);
+  if (!/^\d+(\.\d+)?$/.test(str)) {
+    throw new Error(`Invalid amount: "${str}". Must be a non-negative number (e.g. "0.5", "100").`);
+  }
+  const dotIndex = str.indexOf('.');
+  if (dotIndex === -1) {
+    // Whole number — append zeros and strip leading zeros
+    const raw = str + '0'.repeat(decimals);
+    return raw.replace(/^0+/, '') || '0';
+  }
+  const whole = str.slice(0, dotIndex);
+  let frac = str.slice(dotIndex + 1);
+  if (frac.length > decimals) {
+    // Reject if meaningful (non-zero) digits would be lost
+    const excess = frac.slice(decimals);
+    if (/[1-9]/.test(excess)) {
+      throw new Error(`Amount "${str}" has more fractional digits than the token supports (${decimals} decimals). The smallest unit is ${decimals === 0 ? '1 token' : '0.' + '0'.repeat(decimals - 1) + '1'}.`);
+    }
+    frac = frac.slice(0, decimals);
+  } else {
+    frac = frac.padEnd(decimals, '0');
+  }
+  // Strip leading zeros from the combined result
+  const raw = (whole + frac).replace(/^0+/, '') || '0';
+  return raw;
+}
+
 /**
  * Check if amount contains a decimal point (i.e. not in base units).
  * Returns an error string if invalid, or null if OK. Pure function.
@@ -690,8 +785,12 @@ export function getWrappedNativeFromWarning(tokenAddress, chain) {
 export function validateBaseUnitAmount(amount) {
   if (!amount) return null;
   const str = String(amount);
+  if (str.startsWith('-')) {
+    return 'Amount cannot be negative. Got: ' + str;
+  }
   if (str.includes('.')) {
-    return 'Amount must be in base units (integer), not token units. ' +
+    return 'Amount must be in base units (integer). ' +
+      'Use --amount-unit token to specify token amounts (e.g. --amount 0.5 --amount-unit token). ' +
       'Examples: 1000000000 lamports = 1 SOL, 1000000000000000000 wei = 1 ETH, ' +
       '1000000 = 1 USDC. Got: ' + str;
   }
@@ -745,6 +844,7 @@ export function buildTradingCommands(deps = {}) {
       const autoSlippage = flags['auto-slippage'] || flags.autoSlippage;
       const maxAutoSlippage = options['max-auto-slippage'];
       const swapMode = options['swap-mode'] || 'exactIn';
+      const amountUnit = options['amount-unit'];
 
       if (!chain || !from || !to || !amount) {
         log(`
@@ -760,6 +860,7 @@ OPTIONS:
   --from <symbol|address>   Input token (symbol like SOL, USDC or address)
   --to <symbol|address>     Output token (symbol like USDC, ETH or address)
   --amount <units>          Amount in BASE UNITS (e.g. lamports, wei)
+  --amount-unit <unit>      "token" to specify amount in token units (e.g. 0.5 SOL)
   --wallet <name>           Wallet name (default: default wallet). Use "walletconnect" or "wc" for WalletConnect.
   --slippage <pct>          Slippage as decimal (e.g. 0.03 for 3%). Default: 0.03
   --auto-slippage           Enable auto slippage calculation
@@ -768,6 +869,7 @@ OPTIONS:
 
 EXAMPLES:
   nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+  nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token
   nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
   nansen trade quote --chain solana --from So11111111111111111111111111111111111111112 --to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --amount 1000000000
 `);
@@ -775,13 +877,35 @@ EXAMPLES:
         return;
       }
 
-      const amountError = validateBaseUnitAmount(amount);
-      if (amountError) {
-        log(`Error: ${amountError}`);
+      // Validate --amount-unit if provided
+      if (amountUnit && amountUnit !== 'token' && amountUnit !== 'base') {
+        log(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base`);
         exit(1);
         return;
       }
 
+      // When --amount-unit token is used, resolve decimals and convert to base units.
+      // Otherwise, validate that the amount is already in base units (integer).
+      let resolvedAmount = amount;
+      if (amountUnit === 'token') {
+        try {
+          const tokenForDecimals = swapMode === 'exactOut' ? to : from;
+          const decimals = await resolveTokenDecimals(tokenForDecimals, chain);
+          resolvedAmount = convertToBaseUnits(amount, decimals);
+        } catch (err) {
+          log(`Error resolving token decimals: ${err.message}`);
+          exit(1);
+          return;
+        }
+      } else {
+        const amountError = validateBaseUnitAmount(amount);
+        if (amountError) {
+          log(`Error: ${amountError}`);
+          exit(1);
+          return;
+        }
+      }
+
       try {
         const chainConfig = resolveChain(chain);
         const chainType = chainConfig.type === 'evm' ? 'evm' : 'solana';
@@ -837,7 +961,7 @@ EXAMPLES:
           chainIndex: chainConfig.index,
           fromTokenAddress: from,
           toTokenAddress: to,
-          amount,
+          amount: resolvedAmount,
           userWalletAddress: walletAddress,
         };
         if (slippage) params.slippagePercent = slippage;

package/src/wallet.js

@@ -596,8 +596,15 @@ export function buildWalletCommands(deps = {}) {
         // All other subcommands fall through to unified handlers below
       }
 
+      const isPrivy = options.provider === 'privy' || process.env.NANSEN_WALLET_PROVIDER === 'privy';
+
       const handlers = {
         'create': async () => {
+          // Privy wallets are handled above — if we reach here with provider=privy,
+          // the privy path already failed and called exit(). Guard against environments
+          // where exit() does not terminate (agent frameworks, test harnesses).
+          if (isPrivy) return;
+
           const name = options.name || args[1] || 'default';
 
           let password;