nansen-cli 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.22.0
+
+### Minor Changes
+
+- [#336](https://github.com/nansen-ai/nansen-cli/pull/336) [`c3b1fbd`](https://github.com/nansen-ai/nansen-cli/commit/c3b1fbdee46c15326a1656bf27a314f6c55dddf8) Thanks [@kome12](https://github.com/kome12)! - Add --label option to `token flows` command to filter by holder segment (top_100_holders, smart_money, public_figure, whale, exchange).
+
+- [#334](https://github.com/nansen-ai/nansen-cli/pull/334) [`83244c6`](https://github.com/nansen-ai/nansen-cli/commit/83244c658d4ece2072dea0c6ed405a088c98aa4f) Thanks [@kome12](https://github.com/kome12)! - Add `--include-stablecoins` flag to `token screener` command. Pass `--include-stablecoins false` to exclude stablecoins from screener results (API default is `true`). Supports combined usage with `--smart-money`.
+
+- [#339](https://github.com/nansen-ai/nansen-cli/pull/339) [`27ebcfc`](https://github.com/nansen-ai/nansen-cli/commit/27ebcfc2a3afd836db595df6d5a2a5f9242b624c) Thanks [@TimNooren](https://github.com/TimNooren)! - Add --amount-unit token flag to trade quote for human-readable amounts
+
 ## 1.21.0
 
 ### Minor Changes

package/package.json

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

package/skills/nansen-trading/SKILL.md

@@ -58,9 +58,16 @@ nansen trade execute --quote "$quote_id"
 | ETH | Base | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` |
 | USDC | Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 
-## Amounts are in base units — NEVER USD
+## Amounts
 
-`--amount` accepts **integer base units only** (lamports, wei, etc). It is never a USD value.
+By default, `--amount` accepts **integer base units** (lamports, wei, etc). Use `--amount-unit token` to specify human-readable token amounts instead — the CLI resolves decimals locally and sends base units to the API.
+
+```bash
+# Base units (default)
+nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+# Token units (0.5 SOL = 500000000 lamports, resolved automatically)
+nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token
+```
 
 | Token | Decimals | 1 token = |
 |-------|----------|-----------|
@@ -68,7 +75,7 @@ nansen trade execute --quote "$quote_id"
 | ETH | 18 | `1000000000000000000` |
 | USDC | 6 | `1000000` |
 
-If the user says "$20 worth of X", you must convert USD → token amount → base units. For example, to buy $20 of SOL at $150/SOL: $20 ÷ $150 = 0.1333 SOL = 133,300,000 lamports → `--amount 133300000`. Use a price lookup (e.g. `nansen research token info`) to get the current price first.
+If the user says "$20 worth of X", you must convert USD → token amount, then either pass base units or use `--amount-unit token`. For example, to buy $20 of SOL at $150/SOL: $20 ÷ $150 = 0.1333 SOL → `--amount 0.1333 --amount-unit token`. Use a price lookup (e.g. `nansen research token info`) to get the current price first.
 
 ## Flags
 
@@ -77,7 +84,8 @@ If the user says "$20 worth of X", you must convert USD → token amount → bas
 | `--chain` | `solana` or `base` |
 | `--from` | Source token (symbol or address) |
 | `--to` | Destination token (symbol or address) |
-| `--amount` | Amount in base units (integer) |
+| `--amount` | Amount in base units (integer), or token units with `--amount-unit token` |
+| `--amount-unit` | Set to `token` to specify amount in token units (e.g. 0.5 SOL) |
 | `--wallet` | Wallet name (default: default wallet) |
 | `--slippage` | Slippage tolerance as decimal (e.g. 0.03) |
 | `--quote` | Quote ID for execute |

package/src/api.js

@@ -974,7 +974,7 @@ export class NansenAPI {
   }
 
   async tokenFlows(params = {}) {
-    const { tokenAddress, chain = 'solana', filters = {}, orderBy, pagination, days = 30, date } = params;
+    const { tokenAddress, chain = 'solana', label, filters = {}, orderBy, pagination, days = 30, date } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
@@ -984,6 +984,7 @@ export class NansenAPI {
       token_address: tokenAddress,
       chain,
       date: dateRange,
+      label,
       filters,
       order_by: orderBy,
       pagination

package/src/cli.js

@@ -1200,10 +1200,15 @@ export function buildCommands(deps = {}) {
       // Convenience filter for smart money only
       const onlySmartMoney = options['smart-money'] || flags['smart-money'] || false;
       if (onlySmartMoney) {
-        filters.include_smart_money_labels = filters.include_smart_money_labels || 
+        filters.include_smart_money_labels = filters.include_smart_money_labels ||
           ['Fund', 'Smart Trader', '30D Smart Trader', '90D Smart Trader', '180D Smart Trader'];
       }
 
+      const includeStablecoins = options['include-stablecoins'] ?? flags['include-stablecoins'];
+      if (includeStablecoins !== undefined) {
+        filters.include_stablecoins = includeStablecoins;
+      }
+
       const handlers = {
         'indicators': () => apiInstance.tokenIndicators({ tokenAddress, chain }),
         'ohlcv': () => apiInstance.tokenOhlcv({ tokenAddress, chain, timeframe: options.timeframe || '1d' }),
@@ -1235,7 +1240,8 @@ export function buildCommands(deps = {}) {
         'holders': () => apiInstance.tokenHolders({ tokenAddress, chain, labelType: onlySmartMoney ? 'smart_money' : 'all_holders', filters, orderBy, pagination }),
         'flows': () => {
           const date = parseDateOption(options.date, days);
-          return apiInstance.tokenFlows({ tokenAddress, chain, filters, orderBy, pagination, days, date });
+          const label = options.label;
+          return apiInstance.tokenFlows({ tokenAddress, chain, label, filters, orderBy, pagination, days, date });
         },
         'dex-trades': () => apiInstance.tokenDexTrades({ tokenAddress, chain, onlySmartMoney, filters, orderBy, pagination, days }),
         'pnl': () => apiInstance.tokenPnlLeaderboard({ tokenAddress, chain, filters, orderBy, pagination, days }),
@@ -1257,7 +1263,7 @@ export function buildCommands(deps = {}) {
         'help': () => ({
           commands: ['info', 'ohlcv', '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'
+          example: 'nansen token screener --chain solana --timeframe 24h --smart-money --include-stablecoins false'
         })
       };
 

package/src/schema.json

@@ -280,6 +280,11 @@
                 },
                 "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"
                 }
               }
             },
@@ -463,6 +468,10 @@
                 },
                 "chain": {
                   "default": "solana"
+                },
+                "include-stablecoins": {
+                  "description": "Whether to include stablecoins in screener results (default true on API side)",
+                  "default": true
                 }
               }
             }
@@ -762,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",

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;