nansen-cli 1.20.0 → 1.22.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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
+
+- [#315](https://github.com/nansen-ai/nansen-cli/pull/315) [`908fa0c`](https://github.com/nansen-ai/nansen-cli/commit/908fa0ccdf18cb79b7efb58b9b31f66e0afedff6) Thanks [@TimNooren](https://github.com/TimNooren)! - Add `nansen agent` command for the Nansen AI research agent with fast/expert modes, SSE streaming, conversation continuation, and JSON output.
+
+### Patch Changes
+
+- [#326](https://github.com/nansen-ai/nansen-cli/pull/326) [`1532ba4`](https://github.com/nansen-ai/nansen-cli/commit/1532ba420174ed7635a42641f0c1a2802077fdc0) Thanks [@TimNooren](https://github.com/TimNooren)! - Show API credit cost in research subcommand help text (fetched from OpenAPI spec, cached 24h).
+
+- [#330](https://github.com/nansen-ai/nansen-cli/pull/330) [`a6b9b8f`](https://github.com/nansen-ai/nansen-cli/commit/a6b9b8fc7d291ee7375941bb275c224939338161) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Suppress misleading PASSWORD_REQUIRED error when `--provider privy` is specified. Privy wallets don't need a password — only the Privy-specific credentials error is now shown when PRIVY_APP_ID/PRIVY_APP_SECRET are missing.
+
+- [#329](https://github.com/nansen-ai/nansen-cli/pull/329) [`f047833`](https://github.com/nansen-ai/nansen-cli/commit/f047833c7e6fb55cb713e0b69f82282fe87d4566) Thanks [@TimNooren](https://github.com/TimNooren)! - Limit deprecation warnings and update notices to help output only, keeping stdout/stderr clean for programmatic usage.
+
+- [#332](https://github.com/nansen-ai/nansen-cli/pull/332) [`e9b6de1`](https://github.com/nansen-ai/nansen-cli/commit/e9b6de17fdba3f46733dff026c2495c095bfbf35) Thanks [@0xlaveen](https://github.com/0xlaveen)! - docs: add trading examples and Privy wallet setup to README
+
 ## 1.20.0
 
 ### Minor Changes

package/README.md

@@ -36,10 +36,35 @@ nansen schema [command] [--pretty]    # full command reference (no API key neede
 
 **Trade:** `quote`, `execute` — DEX swaps on Solana and Base.
 
-**Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local keypairs (EVM + Solana).
+**Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local or Privy server-side wallets (EVM + Solana).
 
 Run `nansen schema --pretty` for the full subcommand and field reference.
 
+## Trading
+
+DEX swaps on `solana` and `base`. Two-step: quote then execute.
+
+```bash
+nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+nansen trade execute --quote <quoteId>
+```
+
+Amounts are in base units (lamports, wei). Common symbols (`SOL`, `ETH`, `USDC`, `USDT`) resolve automatically. A wallet is required — set one with `nansen wallet default <name>`.
+
+## Wallet
+
+```bash
+nansen wallet create --name my-wallet        # local keypair (EVM + Solana)
+nansen wallet create --name my-wallet --provider privy  # server-side via Privy
+nansen wallet list
+nansen wallet default <name>
+nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
+```
+
+**Local wallets** are password-encrypted. Set `NANSEN_WALLET_PASSWORD` to skip the prompt.
+
+**Privy wallets** are server-side — no password, no local key storage. Requires `PRIVY_APP_ID` and `PRIVY_APP_SECRET` env vars. Get credentials at [dashboard.privy.io](https://dashboard.privy.io).
+
 ## Key Options
 
 | Option | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.20.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,7 +58,16 @@ nansen trade execute --quote "$quote_id"
 | ETH | Base | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` |
 | USDC | Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 
-## Amounts are in base units
+## Amounts
+
+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 = |
 |-------|----------|-----------|
@@ -66,6 +75,8 @@ 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, 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
 
 | Flag | Purpose |
@@ -73,7 +84,8 @@ nansen trade execute --quote "$quote_id"
 | `--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/skills/nansen-wallet-manager/SKILL.md

@@ -109,6 +109,18 @@ If the `.credentials` file fallback is used, the CLI prints a warning on every o
 
 ## Create
 
+### Privy (server-side, no password)
+
+```bash
+nansen wallet create --provider privy
+# Or with a custom name:
+nansen wallet create --name trading --provider privy
+```
+
+Requires `PRIVY_APP_ID` + `PRIVY_APP_SECRET` env vars. No password needed.
+
+### Local (encrypted on disk, password required)
+
 ```bash
 # Ask the user for a password first, then:
 NANSEN_WALLET_PASSWORD="<password_from_user>" nansen wallet create

package/src/api.js

@@ -11,12 +11,12 @@ import { getAnonymousId, TELEMETRY_DISABLED } from './telemetry.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-function telemetryHeaders() {
+export function telemetryHeaders() {
   if (TELEMETRY_DISABLED) return {};
   return { 'X-Anonymous-Id': getAnonymousId() };
 }
 
-const { version: packageVersion } = JSON.parse(
+export const { version: packageVersion } = JSON.parse(
   fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
 );
 
@@ -85,7 +85,7 @@ export class NansenError extends Error {
 /**
  * Map HTTP status codes to error codes
  */
-function statusToErrorCode(status, data = {}) {
+export function statusToErrorCode(status, data = {}) {
   const message = data?.message || data?.error || '';
   const messageLower = message.toLowerCase();
   
@@ -486,7 +486,7 @@ export class NansenAPI {
         return cached;
       }
     }
-    
+
     let lastError;
     
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -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

@@ -7,9 +7,11 @@ import { NansenAPI, NansenError, ErrorCode, saveConfig, deleteConfig, getConfigF
 import { buildWalletCommands } from './wallet.js';
 import { buildTradingCommands } from './trading.js';
 import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
+import { buildAgentCommands } from './commands/agent.js';
 import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
+import { refreshCostMapIfStale, getCostForEndpoint } from './cost-cache.js';
 import { trackCommandSucceeded, trackCommandFailed } from './telemetry.js';
 import { createRequire } from 'module';
 import * as readline from 'readline';
@@ -165,7 +167,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled') {
+      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled' || key === 'expert' || key === 'json') {
         result.flags[key] = true;
       } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
         // Try to parse as JSON first (for objects/arrays/booleans),
@@ -682,6 +684,7 @@ COMMANDS:
   research    smart-money, profiler, token, search, perp, portfolio, points
   trade       quote, execute
   wallet      create, list, show, export, default, delete, forget-password
+  agent       Ask the Nansen AI research agent (fast/expert modes)
   alerts      list, create, update, toggle, delete
   web         search, fetch
   account     Show API key status, plan, and remaining credits
@@ -701,6 +704,10 @@ EXAMPLES:
   nansen research profiler balance --address 0x... --chain ethereum
   nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
 
+DEPRECATED ALIASES (still work, will be removed in a future version):
+  smart-money, profiler, token, search, perp, portfolio, points → use "nansen research <command>"
+  quote, execute → use "nansen trade <command>"
+
 Research chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
 Trade chains: solana, base
 Labels: Fund, Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader
@@ -1193,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' }),
@@ -1228,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 }),
@@ -1250,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'
         })
       };
 
@@ -1509,6 +1522,11 @@ export function generateSubcommandHelp(command, subcommand, prefix = null) {
     lines.push(`Params (* required): ${params.join(', ')}`);
   }
 
+  if (subSchema.endpoint) {
+    const cost = getCostForEndpoint(subSchema.endpoint);
+    if (cost) lines.push(`Cost: ${cost.free} credit${cost.free === 1 ? '' : 's'} (Free tier) / ${cost.pro} credit${cost.pro === 1 ? '' : 's'} (Pro tier)`);
+  }
+
   if (subSchema.returns?.length) {
     lines.push(`Returns: ${subSchema.returns.join(', ')}`);
   }
@@ -1548,12 +1566,7 @@ export async function runCLI(rawArgs, deps = {}) {
   const subArgs = positional.slice(1);
   const subcommand = subArgs[0];
 
-  // Deprecation warnings for commands that moved under 'research' or 'trade'
-  if (DEPRECATED_TO_RESEARCH.has(command)) {
-    errorOutput(`Warning: "nansen ${command}" is deprecated. Use "nansen research ${command}" instead.`);
-  } else if (DEPRECATED_TO_TRADE.has(command)) {
-    errorOutput(`Warning: "nansen ${command}" is deprecated. Use "nansen trade ${command}" instead.`);
-  }
+
 
   const pretty = flags.pretty || flags.p;
   const table = flags.table || flags.t;
@@ -1569,7 +1582,14 @@ export async function runCLI(rawArgs, deps = {}) {
     if (updateNotification) errorOutput(updateNotification);
   };
 
-  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...buildAlertsCommands(deps), ...commandOverrides };
+  // Deprecation note for help output
+  const deprecationNote = (cmd) => {
+    if (DEPRECATED_TO_RESEARCH.has(cmd)) return `Note: "nansen ${cmd}" is deprecated. Use "nansen research ${cmd}" instead.\n\n`;
+    if (DEPRECATED_TO_TRADE.has(cmd)) return `Note: "nansen ${cmd}" is deprecated. Use "nansen trade ${cmd}" instead.\n\n`;
+    return '';
+  };
+
+  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...buildAlertsCommands(deps), ...buildAgentCommands(deps), ...commandOverrides };
 
   if (flags.version || flags.v) {
     output(VERSION);
@@ -1577,6 +1597,7 @@ export async function runCLI(rawArgs, deps = {}) {
   }
 
   if (command === 'help' || flags.help || flags.h) {
+    await refreshCostMapIfStale();
     // Check for subcommand-specific help: nansen <command> <subcommand> --help
     if (flags.help || flags.h) {
       // Handle 'research <category> <sub> --help' (3-level)
@@ -1607,17 +1628,17 @@ export async function runCLI(rawArgs, deps = {}) {
       }
       // First try subcommand help
       // Skip for 'trade'/'alerts' — their handlers show their own rich usage
-      if (command && subcommand && command !== 'trade' && command !== 'alerts') {
+      if (command && subcommand && command !== 'trade' && command !== 'alerts' && command !== 'agent') {
         const subHelp = generateSubcommandHelp(command, subcommand);
         if (subHelp) {
-          output(subHelp);
+          output(deprecationNote(command) + subHelp);
           notify();
           return { type: 'subcommand-help', command, subcommand };
         }
       }
       // Then try command-level help (list subcommands)
       // Skip for 'trade'/'alerts' — let the handler show its own usage
-      const cmdSchemaLookup = command !== 'trade' && command !== 'alerts' && (SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command]);
+      const cmdSchemaLookup = command !== 'trade' && command !== 'alerts' && command !== 'agent' && (SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command]);
       if (command && cmdSchemaLookup) {
         const cmdSchema = cmdSchemaLookup;
         const lines = [`${command} — ${cmdSchema.description}`];
@@ -1638,7 +1659,7 @@ export async function runCLI(rawArgs, deps = {}) {
         if (cmdSchema.examples?.length) {
           lines.push(`\nExamples:\n  ${cmdSchema.examples.join('\n  ')}`);
         }
-        output(lines.join('\n'));
+        output(deprecationNote(command) + lines.join('\n'));
         notify();
         return { type: 'command-help', command };
       }
@@ -1681,7 +1702,6 @@ 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 });
-    notify();
     exit(1);
     return { type: 'error', data: errorData };
   }
@@ -1709,7 +1729,6 @@ 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 });
-      notify();
       return { type: 'no-output', command };
     }
 
@@ -1718,7 +1737,6 @@ export async function runCLI(rawArgs, deps = {}) {
       const formatted = formatOutput(result, { pretty, table: false });
       output(formatted.text);
       trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
-      notify();
       return { type: 'schema', data: result };
     }
 
@@ -1731,7 +1749,6 @@ export async function runCLI(rawArgs, deps = {}) {
     // Alerts list with --table uses custom table format
     if (command === 'alerts' && subcommand === 'list' && table) {
       output(formatAlertsTable(result));
-      notify();
       return { type: 'success', data: result };
     }
 
@@ -1743,7 +1760,6 @@ export async function runCLI(rawArgs, deps = {}) {
         output(streamOutput);
       }
       trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
-      notify();
       return { type: 'stream', data: result };
     }
 
@@ -1751,7 +1767,6 @@ export async function runCLI(rawArgs, deps = {}) {
     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 });
-    notify();
     return { type: csv ? 'csv' : 'success', data: result };
   } catch (error) {
     const errorData = formatError(error);
@@ -1765,7 +1780,6 @@ export async function runCLI(rawArgs, deps = {}) {
       flags: usedFlags,
       chain,
     });
-    notify();
     exit(1);
     return { type: 'error', data: errorData };
   }