nansen-cli 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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.21.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,9 @@ nansen trade execute --quote "$quote_id"
 | ETH | Base | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` |
 | USDC | Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 
-## Amounts are in base units
+## Amounts are in base units — NEVER USD
+
+`--amount` accepts **integer base units only** (lamports, wei, etc). It is never a USD value.
 
 | Token | Decimals | 1 token = |
 |-------|----------|-----------|
@@ -66,6 +68,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 → 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.
+
 ## Flags
 
 | Flag | Purpose |

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++) {

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
@@ -1509,6 +1516,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 +1560,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 +1576,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 +1591,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 +1622,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 +1653,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 +1696,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 +1723,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 +1731,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 +1743,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 +1754,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 +1761,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 +1774,6 @@ export async function runCLI(rawArgs, deps = {}) {
       flags: usedFlags,
       chain,
     });
-    notify();
     exit(1);
     return { type: 'error', data: errorData };
   }

package/src/commands/agent.js

@@ -0,0 +1,344 @@
+/**
+ * Nansen CLI - Agent command
+ * Interactive research agent with fast/expert modes via SSE streaming.
+ */
+
+import crypto from 'crypto';
+import { NansenError, ErrorCode, statusToErrorCode, telemetryHeaders, packageVersion } from '../api.js';
+import { getCostForEndpoint } from '../cost-cache.js';
+
+/**
+ * Build standard request headers, matching apiInstance.request() conventions.
+ */
+function buildHeaders(apiInstance) {
+  return {
+    'Content-Type': 'application/json',
+    'X-Client-Type': 'nansen-cli',
+    'X-Client-Version': packageVersion,
+    ...telemetryHeaders(),
+    ...(apiInstance.apiKey ? { 'apikey': apiInstance.apiKey } : {}),
+    ...(apiInstance.defaultHeaders || {}),
+  };
+}
+
+/**
+ * Throw a NansenError with the same structure as apiInstance.request() errors.
+ * Includes `details` field for consistency with other commands.
+ */
+function throwApiError(message, status, serverDetail) {
+  // Match the friendly wrapper messages from apiInstance.request()
+  let friendlyMessage = message;
+  if (status === 401) {
+    friendlyMessage = 'Not logged in. Run: nansen login';
+  } else if (status === 429) {
+    friendlyMessage = 'Rate limited. Try again in a few seconds.';
+  }
+
+  throw new NansenError(
+    friendlyMessage,
+    statusToErrorCode(status),
+    status,
+    { detail: serverDetail || message, attempt: 1, retryAfterMs: null },
+  );
+}
+
+/**
+ * Process an SSE response from the agent endpoint.
+ *
+ * In buffered mode (no callbacks), collects everything and returns it.
+ * In streaming mode (callbacks provided), invokes them as events arrive.
+ *
+ * @param {Response} response   – fetch Response with SSE body
+ * @param {object}   [callbacks]
+ * @param {Function} [callbacks.onDelta]    – called with each text chunk
+ * @param {Function} [callbacks.onToolCall] – called with each tool name
+ * @returns {{ text: string, toolCalls: string[], conversationId: string|null }}
+ */
+export async function consumeSSEStream(response, callbacks = {}) {
+  const { onDelta, onToolCall } = callbacks;
+  const chunks = [];
+  const toolCalls = [];
+  let conversationId = null;
+  let errorPayload = null;
+
+  const reader = response.body;
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  for await (const raw of reader) {
+    buffer += decoder.decode(raw, { stream: true });
+
+    // Normalize \r\n and \r to \n (SSE spec allows all three line terminators)
+    buffer = buffer.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+    // SSE: split on double-newline boundaries
+    let boundary;
+    let done = false;
+    while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+      const frame = buffer.slice(0, boundary);
+      buffer = buffer.slice(boundary + 2);
+
+      for (const line of frame.split('\n')) {
+        if (!line.startsWith('data: ')) continue;
+        const payload = line.slice(6);
+        if (payload === '[DONE]') { done = true; break; }
+
+        let event;
+        try {
+          event = JSON.parse(payload);
+        } catch {
+          continue;
+        }
+
+        switch (event.type) {
+          case 'delta':
+            if (event.text) {
+              chunks.push(event.text);
+              if (onDelta) onDelta(event.text);
+            }
+            break;
+          case 'tool_call':
+            if (event.name) {
+              toolCalls.push(event.name);
+              if (onToolCall) onToolCall(event.name);
+            }
+            break;
+          case 'finish':
+            conversationId = event.conversation_id ?? null;
+            break;
+          case 'error':
+            errorPayload = event;
+            break;
+        }
+      }
+      if (done) break;
+    }
+    if (done) break;
+  }
+
+  if (errorPayload) {
+    const status = errorPayload.status_code || 502;
+    throwApiError(
+      errorPayload.error || 'Agent request failed',
+      status,
+      errorPayload.error,
+    );
+  }
+
+  return { text: chunks.join(''), toolCalls, conversationId };
+}
+
+/**
+ * Build the `agent` command handler.
+ *
+ * @param {object} [deps]
+ * @param {Function} [deps.log]      – stdout line output (default: console.log)
+ * @param {Function} [deps.errorLog] – stderr line output (default: console.error)
+ * @param {Function} [deps.write]    – raw stdout writer, no trailing newline (default: process.stdout.write)
+ * @returns {object} command map
+ */
+export function buildAgentCommands(deps = {}) {
+  const {
+    log = console.log,
+    errorLog = console.error,
+    write = (s) => process.stdout.write(s),
+  } = deps;
+
+  return {
+    'agent': async (args, apiInstance, flags, options) => {
+      // ── Help ──
+      if (flags.help || flags.h || args[0] === 'help' || args.length === 0) {
+        const fmtCost = (c) => `${c.free} credit${c.free === 1 ? '' : 's'} (Free tier) / ${c.pro} credit${c.pro === 1 ? '' : 's'} (Pro tier)`;
+        const fastCost = getCostForEndpoint('/api/v1/agent/fast');
+        const expertCost = getCostForEndpoint('/api/v1/agent/expert');
+        const costSection = (fastCost || expertCost)
+          ? `\nCOST:\n${fastCost ? `  fast:   ${fmtCost(fastCost)}\n` : ''}${expertCost ? `  expert: ${fmtCost(expertCost)}\n` : ''}`
+          : '';
+        log(`nansen agent — Nansen Research Agent
+
+Ask the Nansen AI agent research questions about crypto wallets, tokens,
+smart money flows, and on-chain activity. The agent uses Nansen's full
+data platform to answer your questions.
+
+MODES:
+  fast      Faster responses, best for simple lookups (default)
+  expert    Deeper analysis, uses a more capable model
+
+USAGE:
+  nansen agent "<question>"
+  nansen agent "<question>" --expert
+  nansen agent "<question>" --conversation-id <id>
+
+OPTIONS:
+  --expert                     Use expert mode (default: fast)
+  --conversation-id <uuid>     Continue a previous conversation (UUID v4)
+  --json                       Output raw JSON instead of formatted text
+${costSection}
+CONVERSATION FLOW:
+  Each request generates a UUID v4 conversation ID. To continue a
+  multi-turn conversation, pass it back with --conversation-id. The ID
+  and a ready-to-copy follow-up command are printed to stderr after each
+  response.
+
+EXAMPLES:
+  nansen agent "What are the top smart money inflows on Ethereum today?"
+  nansen agent "Show me the largest whale wallets on Solana"
+  nansen agent "Analyze wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" --expert
+  nansen agent "Tell me more about their DeFi positions" --conversation-id 550e8400-e29b-41d4-a716-446655440000`);
+        return;
+      }
+
+      // ── Parse question ──
+      const question = args.join(' ').trim();
+      if (!question) {
+        throw new NansenError(
+          'Query cannot be empty. Usage: nansen agent "<question>"',
+          ErrorCode.INVALID_PARAMS,
+          null,
+          { detail: 'Empty query string' },
+        );
+      }
+
+      // ── Mode ──
+      const expert = !!flags.expert;
+      const endpoint = expert ? '/api/v1/agent/expert' : '/api/v1/agent/fast';
+      const modeName = expert ? 'expert' : 'fast';
+
+      // ── Conversation ID (must be UUID v4) ──
+      const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      const rawConvId = options['conversation-id'];
+      let conversationId;
+      if (typeof rawConvId === 'string' && rawConvId) {
+        if (!UUID_RE.test(rawConvId)) {
+          throw new NansenError(
+            `Invalid --conversation-id: expected a UUID (e.g. 550e8400-e29b-41d4-a716-446655440000), got "${rawConvId.slice(0, 60)}${rawConvId.length > 60 ? '...' : ''}"`,
+            ErrorCode.INVALID_PARAMS,
+            null,
+            { detail: 'conversation-id must be a UUID v4' },
+          );
+        }
+        conversationId = rawConvId;
+      } else {
+        conversationId = crypto.randomUUID();
+      }
+
+      // ── Auth guard ──
+      if (!apiInstance.apiKey) {
+        throw new NansenError(
+          'Not logged in. Run: nansen login',
+          ErrorCode.UNAUTHORIZED,
+          401,
+          { detail: 'No API key configured' },
+        );
+      }
+
+      // ── Request (no retry — SSE streams are not idempotent) ──
+      const url = `${apiInstance.baseUrl}${endpoint}`;
+      const body = {
+        text: question,
+        conversation_id: conversationId,
+      };
+
+      // ── Timeout ──
+      const timeoutMs = expert ? 300_000 : 120_000; // 5min expert, 2min fast
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+      let response;
+      try {
+        response = await fetch(url, {
+          method: 'POST',
+          headers: buildHeaders(apiInstance),
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        if (err.name === 'AbortError') {
+          throw new NansenError(
+            `Request timed out after ${timeoutMs / 1000}s`,
+            ErrorCode.TIMEOUT,
+            504,
+            { detail: `${modeName} mode timeout (${timeoutMs / 1000}s)` },
+          );
+        }
+        throw new NansenError(
+          `Network error: ${err.message}`,
+          ErrorCode.NETWORK_ERROR,
+          null,
+          { originalError: err.message },
+        );
+      }
+
+      if (!response.ok) {
+        clearTimeout(timer);
+        let serverDetail;
+        if (response.headers.get('content-type')?.includes('application/json')) {
+          try {
+            const errData = await response.json();
+            serverDetail = errData.detail || errData.message;
+          } catch { /* ignore parse failure */ }
+        }
+        throwApiError(
+          serverDetail || `Agent returned ${response.status}`,
+          response.status,
+          serverDetail,
+        );
+      }
+
+      // ── JSON mode: buffer everything, return structured data ──
+      if (flags.json) {
+        let result;
+        try {
+          result = await consumeSSEStream(response);
+        } finally {
+          clearTimeout(timer);
+        }
+        return {
+          conversation_id: result.conversationId || conversationId,
+          mode: modeName,
+          text: result.text,
+          tool_calls: result.toolCalls,
+        };
+      }
+
+      // ── Streaming output mode ──
+      let hasOutput = false;
+      let midLine = false; // true when write() was called without a trailing newline
+      let result;
+      try {
+        result = await consumeSSEStream(response, {
+          onDelta(text) {
+            if (!midLine && text.trim() === '') return;
+            write(text);
+            hasOutput = true;
+            midLine = text.length > 0 && !text.endsWith('\n');
+          },
+          onToolCall(name) {
+            if (midLine) { write('\n'); midLine = false; }
+            errorLog(`⚙ ${name}`);
+          },
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+
+      // Ensure a trailing newline after streamed text
+      if (midLine) {
+        write('\n');
+      }
+
+      if (!hasOutput) {
+        log('(no response from agent)');
+      }
+
+      // Print conversation continuation hint
+      const effectiveConvId = result.conversationId || conversationId;
+      const expertFlag = expert ? ' --expert' : '';
+      errorLog(`\nTo continue this conversation:`);
+      errorLog(`  nansen agent "<follow-up>" --conversation-id "${effectiveConvId}"${expertFlag}`);
+
+      return;
+    },
+  };
+}

package/src/cost-cache.js

@@ -0,0 +1,67 @@
+/**
+ * Credit cost cache — reads per-endpoint costs from a local cache populated
+ * by an inline fetch of the Nansen OpenAPI spec (at most once per 24h).
+ *
+ * getCostForEndpoint(endpoint)  — sync, reads cache, returns { free, pro } or null
+ * refreshCostMapIfStale()       — async, fetches inline if cache is missing or stale
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '', '.nansen');
+const CACHE_FILE = path.join(CONFIG_DIR, 'cost-map.json');
+const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
+const OPENAPI_URL = 'https://api.nansen.ai/openapi.json';
+
+/**
+ * Returns { free, pro } credit cost for the given API path, or null if unavailable.
+ */
+export function getCostForEndpoint(endpoint) {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) return null;
+    const { costs } = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    return costs?.[endpoint] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetches the OpenAPI spec and writes the cost map to disk if the cache is
+ * missing or older than 24h. Awaited inline — only blocks on cold/stale cache.
+ * Silent on any error.
+ */
+export async function refreshCostMapIfStale() {
+  try {
+    if (fs.existsSync(CACHE_FILE)) {
+      const { fetchedAt } = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+      if (fetchedAt && Date.now() - fetchedAt < STALE_MS) return;
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    let spec;
+    try {
+      const res = await fetch(OPENAPI_URL, { signal: controller.signal });
+      spec = await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const costs = {};
+    for (const [p, methods] of Object.entries(spec.paths || {})) {
+      for (const op of Object.values(methods)) {
+        if (op['x-credit-cost']) {
+          costs[p] = op['x-credit-cost'];
+          break;
+        }
+      }
+    }
+
+    if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { mode: 0o700, recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({ costs, fetchedAt: Date.now() }));
+  } catch {
+    // silent — network failure, parse error, write error
+  }
+}

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": {
@@ -265,6 +284,7 @@
               }
             },
             "who-bought-sold": {
+              "endpoint": "/api/v1/tgm/who-bought-sold",
               "description": "Recent buyers and sellers",
               "options": {
                 "chain": {
@@ -279,6 +299,7 @@
               }
             },
             "dex-trades": {
+              "endpoint": "/api/v1/tgm/dex-trades",
               "description": "DEX trading activity",
               "options": {
                 "chain": {
@@ -293,6 +314,7 @@
               }
             },
             "transfers": {
+              "endpoint": "/api/v1/tgm/transfers",
               "description": "Token transfer history",
               "options": {
                 "chain": {
@@ -307,6 +329,7 @@
               }
             },
             "holders": {
+              "endpoint": "/api/v1/tgm/holders",
               "description": "Token holder analysis",
               "options": {
                 "chain": {
@@ -318,6 +341,7 @@
               }
             },
             "pnl": {
+              "endpoint": "/api/v1/tgm/pnl-leaderboard",
               "description": "PnL leaderboard",
               "options": {
                 "chain": {
@@ -332,6 +356,7 @@
               }
             },
             "perp-pnl-leaderboard": {
+              "endpoint": "/api/v1/tgm/perp-pnl-leaderboard",
               "description": "Perp PnL leaderboard by token",
               "options": {
                 "symbol": {
@@ -343,6 +368,7 @@
               }
             },
             "perp-positions": {
+              "endpoint": "/api/v1/tgm/perp-positions",
               "description": "Open perp positions by token symbol",
               "options": {
                 "symbol": {
@@ -351,6 +377,7 @@
               }
             },
             "perp-trades": {
+              "endpoint": "/api/v1/tgm/perp-trades",
               "description": "Perp trades by token symbol",
               "options": {
                 "symbol": {
@@ -362,6 +389,7 @@
               }
             },
             "flow-intelligence": {
+              "endpoint": "/api/v1/tgm/flow-intelligence",
               "description": "Detailed flow intelligence by label",
               "options": {
                 "chain": {
@@ -376,6 +404,7 @@
               }
             },
             "info": {
+              "endpoint": "/api/v1/tgm/token-information",
               "description": "Get detailed information for a specific token",
               "options": {
                 "chain": {
@@ -390,6 +419,7 @@
               }
             },
             "indicators": {
+              "endpoint": "/api/v1/tgm/indicators",
               "description": "Risk and reward indicators for a token (Nansen Score)",
               "options": {
                 "chain": {
@@ -401,6 +431,7 @@
               }
             },
             "ohlcv": {
+              "endpoint": "/api/v1/tgm/token-ohlcv",
               "description": "OHLCV candle data for a token",
               "options": {
                 "chain": {
@@ -415,6 +446,7 @@
               }
             },
             "jup-dca": {
+              "endpoint": "/api/v1/tgm/jup-dca",
               "description": "Jupiter DCA orders for token",
               "options": {
                 "token": {
@@ -423,6 +455,7 @@
               }
             },
             "screener": {
+              "endpoint": "/api/v1/token-screener",
               "description": "Discover and filter tokens",
               "options": {
                 "timeframe": {
@@ -437,6 +470,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 +487,7 @@
         "perp": {
           "subcommands": {
             "screener": {
+              "endpoint": "/api/v1/perp-screener",
               "description": "Screen perpetual futures contracts",
               "options": {
                 "days": {
@@ -461,6 +496,7 @@
               }
             },
             "leaderboard": {
+              "endpoint": "/api/v1/perp-leaderboard",
               "description": "Perpetual futures PnL leaderboard",
               "options": {
                 "days": {
@@ -474,6 +510,7 @@
         "prediction-market": {
           "subcommands": {
             "ohlcv": {
+              "endpoint": "/api/v1/prediction-market/ohlcv",
               "description": "Get Prediction Market OHLCV Candles",
               "options": {
                 "market-id": {
@@ -482,6 +519,7 @@
               }
             },
             "orderbook": {
+              "endpoint": "/api/v1/prediction-market/orderbook",
               "description": "Get Prediction Market Orderbook",
               "options": {
                 "market-id": {
@@ -490,6 +528,7 @@
               }
             },
             "top-holders": {
+              "endpoint": "/api/v1/prediction-market/top-holders",
               "description": "Get Prediction Market Top Holders",
               "options": {
                 "market-id": {
@@ -498,6 +537,7 @@
               }
             },
             "trades-by-market": {
+              "endpoint": "/api/v1/prediction-market/trades-by-market",
               "description": "Get Prediction Market Trades by Market",
               "options": {
                 "market-id": {
@@ -506,6 +546,7 @@
               }
             },
             "market-screener": {
+              "endpoint": "/api/v1/prediction-market/market-screener",
               "description": "Get Prediction Market Screener",
               "options": {
                 "query": {
@@ -514,6 +555,7 @@
               }
             },
             "event-screener": {
+              "endpoint": "/api/v1/prediction-market/event-screener",
               "description": "Get Prediction Market Event Screener",
               "options": {
                 "query": {
@@ -522,6 +564,7 @@
               }
             },
             "pnl-by-market": {
+              "endpoint": "/api/v1/prediction-market/pnl-by-market",
               "description": "Get Prediction Market PnL by Market",
               "options": {
                 "market-id": {
@@ -530,6 +573,7 @@
               }
             },
             "pnl-by-address": {
+              "endpoint": "/api/v1/prediction-market/pnl-by-address",
               "description": "Get Prediction Market PnL by Address",
               "options": {
                 "address": {
@@ -538,6 +582,7 @@
               }
             },
             "position-detail": {
+              "endpoint": "/api/v1/prediction-market/position-detail",
               "description": "Get Prediction Market Position Detail",
               "options": {
                 "market-id": {
@@ -546,6 +591,7 @@
               }
             },
             "trades-by-address": {
+              "endpoint": "/api/v1/prediction-market/trades-by-address",
               "description": "Get Prediction Market Trades by Address",
               "options": {
                 "address": {
@@ -554,6 +600,7 @@
               }
             },
             "categories": {
+              "endpoint": "/api/v1/prediction-market/categories",
               "description": "Get Prediction Market Categories"
             }
           },
@@ -826,6 +873,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/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;