nansen-cli 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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
+
+- [#302](https://github.com/nansen-ai/nansen-cli/pull/302) [`3f0a5ab`](https://github.com/nansen-ai/nansen-cli/commit/3f0a5abad463c0386122efbe746809913aa823ba) Thanks [@arein](https://github.com/arein)! - Add post-install onboarding that interactively offers to install the Nansen AI coding skill and run a test query after `npm install -g nansen-cli`. Non-interactive environments (CI, piped stdin) receive a one-liner tip and are never blocked.
+
+### Patch Changes
+
+- [#313](https://github.com/nansen-ai/nansen-cli/pull/313) [`bb4d9e4`](https://github.com/nansen-ai/nansen-cli/commit/bb4d9e475158147645cae9b8bdd2555568a1e515) Thanks [@0xlaveen](https://github.com/0xlaveen)! - Update API key setup URL from app.nansen.ai/api to app.nansen.ai/auth/agent-setup across CLI help text, error messages, README, and postinstall script.
+
 ## 1.19.0
 
 ### Minor Changes

package/README.md

@@ -15,11 +15,13 @@ npx skills add nansen-ai/nansen-cli  # load agent skill files
 ## Auth
 
 ```bash
-nansen login              # interactive — saves to ~/.nansen/config.json
-export NANSEN_API_KEY=... # or env var (highest priority)
+nansen login --api-key <key>   # save key to ~/.nansen/config.json
+nansen login --human           # interactive prompt
+export NANSEN_API_KEY=...      # env var (highest priority)
+nansen logout                  # remove saved key
 ```
 
-Get your API key at [app.nansen.ai/api](https://app.nansen.ai/api). AI agents can use the [Agent Setup](https://app.nansen.ai/auth/agent-setup) flow instead.
+Get your API key at [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup).
 
 ## Commands
 
@@ -34,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.19.0",
+  "version": "1.21.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -12,9 +12,11 @@
     "src/**/*.json",
     "!src/__tests__/**",
     "skills/**",
+    "scripts/postinstall.js",
     "CHANGELOG.md"
   ],
   "scripts": {
+    "postinstall": "node scripts/postinstall.js",
     "start": "node src/index.js",
     "pretest": "node scripts/check-changeset.js",
     "test": "vitest run",

package/scripts/postinstall.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install onboarding for nansen-cli.
+ *
+ * Runs after `npm install -g nansen-cli` and offers two optional steps:
+ *   1. Install the Nansen AI coding skill (`npx skills add nansen-ai/nansen-cli`)
+ *   2. Check account status to verify the API key works (0 credits)
+ *
+ * Non-interactive environments (CI, piped stdin) get a one-liner tip instead.
+ * Always exits 0 — onboarding failures must never break installation.
+ */
+
+import { createInterface } from "readline";
+import { execFileSync, spawn } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+
+const SKILL_REPO = "nansen-ai/nansen-cli";
+const TEST_QUERY = ["account"];
+const TEST_QUERY_DISPLAY = "nansen account";
+
+// Path to the CLI entry point (works even if `nansen` bin isn't linked yet)
+const CLI_ENTRY = join(__dirname, "..", "src", "index.js");
+
+function log(msg = "") {
+  process.stderr.write(`  ${msg}\n`);
+}
+
+function hasTTY() {
+  return process.stdin.isTTY && process.stderr.isTTY;
+}
+
+function hasNpx() {
+  try {
+    execFileSync("npx", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLoggedIn() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  const configFile = join(home, ".nansen", "config.json");
+  if (!existsSync(configFile)) return false;
+  try {
+    const config = JSON.parse(readFileSync(configFile, "utf8"));
+    return !!(config.apiKey || config.api_key);
+  } catch {
+    return false;
+  }
+}
+
+function isSkillInstalled() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  const locations = [
+    join(home, ".claude", "skills", "nansen-cli"),
+    join(home, ".claude", "skills", "nansen-ai--nansen-cli"),
+  ];
+  return locations.some((loc) => existsSync(loc));
+}
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    let answered = false;
+    rl.on("close", () => { if (!answered) resolve(""); });
+    rl.question(question, (answer) => {
+      answered = true;
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function runCommand(cmd, args) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+    child.on("close", (code) => resolve(code === 0));
+    child.on("error", () => resolve(false));
+  });
+}
+
+async function installSkill() {
+  if (isSkillInstalled()) {
+    log(`${GREEN}✓${RESET} Nansen skill already installed.`);
+    return;
+  }
+
+  if (!hasNpx()) {
+    log(`${DIM}Tip: Run 'npx skills add ${SKILL_REPO}' to install the Nansen AI coding skill.${RESET}`);
+    return;
+  }
+
+  log(`The Nansen skill lets AI coding agents (Cursor, Claude Code, etc.) query`);
+  log(`on-chain data, track smart money, and analyze tokens on your behalf.`);
+  const answer = await prompt(`  Install Nansen skill for your AI coding agent? [Y/n] `);
+
+  if (/^n/i.test(answer)) {
+    log(`Skipped. You can install it later with: ${CYAN}npx skills add ${SKILL_REPO}${RESET}`);
+    return;
+  }
+
+  log(`Installing Nansen skill...`);
+  const ok = await runCommand("npx", ["-y", "skills", "add", SKILL_REPO]);
+  if (!ok) {
+    log(`${YELLOW}Skill installation failed. You can retry with: npx skills add ${SKILL_REPO}${RESET}`);
+  }
+}
+
+async function testQuery() {
+  if (!isLoggedIn()) {
+    log();
+    log(`Not logged in yet. Run ${CYAN}nansen login --api-key <key>${RESET} to authenticate.`);
+    log(`Get your API key at: ${CYAN}https://app.nansen.ai/auth/agent-setup${RESET}`);
+    return;
+  }
+
+  log();
+  log(`Your API key is configured. Let's verify it works.`);
+  const answer = await prompt(`  Check account status? (${DIM}${TEST_QUERY_DISPLAY}${RESET}) [Y/n] `);
+
+  if (/^n/i.test(answer)) {
+    log(`Skipped. You're all set! Try: ${CYAN}nansen research smart-money netflow --chain solana${RESET}`);
+    return;
+  }
+
+  log(`Running: ${DIM}${TEST_QUERY_DISPLAY}${RESET}`);
+  log();
+  // Use process.execPath + CLI_ENTRY so it works even if `nansen` bin isn't linked yet
+  const ok = await runCommand(process.execPath, [CLI_ENTRY, ...TEST_QUERY, "--pretty"]);
+  if (ok) {
+    log();
+    log(`${GREEN}✓${RESET} All set! Run ${CYAN}nansen help${RESET} to see all available commands.`);
+  } else {
+    log();
+    log(`${YELLOW}Query failed. Check your API key with: nansen login --api-key <key>${RESET}`);
+  }
+}
+
+async function main() {
+  // Only run for global installs; skip local npm install / npm ci
+  if (process.env.npm_lifecycle_event === "postinstall" && process.env.npm_config_global !== "true") {
+    return;
+  }
+
+  log();
+
+  if (!hasTTY()) {
+    log(`${BOLD}Nansen CLI installed!${RESET}`);
+    log();
+    log(`Tip: Run '${CYAN}npx skills add ${SKILL_REPO}${RESET}' to install the Nansen AI coding skill.`);
+    log(`Tip: Run '${CYAN}nansen login --api-key <key>${RESET}' to authenticate.`);
+    return;
+  }
+
+  log(`${BOLD}Nansen CLI installed!${RESET}`);
+  log();
+
+  await installSkill();
+  await testQuery();
+
+  log();
+}
+
+main().catch(() => {
+  // Never fail installation due to onboarding errors
+});

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

@@ -1,6 +1,6 @@
 ---
 name: nansen-wallet-manager
-description: Wallet management — create, list, show, export, send, delete. Use when creating wallets, checking balances, or sending tokens.
+description: Wallet management — create (local or Privy server-side), list, show, export, send, delete. Use when creating wallets, checking balances, or sending tokens.
 metadata:
   openclaw:
     requires:
@@ -30,7 +30,49 @@ NANSEN_API_KEY=<key> nansen login
 nansen research profiler labels --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum
 ```
 
-## Wallet Creation (Two-Step Agent Flow)
+## Wallet Providers
+
+The CLI supports two wallet providers:
+
+| | **Local** (default) | **Privy** (server-side) |
+|---|---|---|
+| Key storage | Encrypted on disk | Server-side via Privy API |
+| Password required | Yes (min 12 chars) | No |
+| Export private keys | Yes (`wallet export`) | No — keys are managed by Privy |
+| Best for | Human users, manual trading | Agents, automated workflows |
+| Flag | `--provider local` (default) | `--provider privy` |
+| Required env vars | `NANSEN_WALLET_PASSWORD` | `PRIVY_APP_ID` + `PRIVY_APP_SECRET` |
+
+## Privy Wallet Creation
+
+Privy wallets are server-side wallets managed by the Privy API. No password is needed — keys never touch the local machine.
+
+### Prerequisites
+
+The following environment variables must be set:
+
+| Var | Purpose |
+|-----|---------|
+| `PRIVY_APP_ID` | Privy application ID |
+| `PRIVY_APP_SECRET` | Privy application secret |
+
+### Create a Privy wallet
+
+```bash
+nansen wallet create --provider privy
+# Or with a custom name:
+nansen wallet create --name agent-wallet --provider privy
+```
+
+### Critical rules for agents (Privy)
+
+- **No password needed** — Privy manages keys server-side
+- **Cannot export keys** — `wallet export` only works for local wallets
+- All other operations (`list`, `show`, `send`, `delete`, `default`) work identically for both providers
+
+## Local Wallet Creation (Two-Step Agent Flow)
+
+> This section covers **local** wallet creation. For Privy server-side wallets, see the [Privy Wallet Creation](#privy-wallet-creation) section above — no password is needed.
 
 Wallet creation requires a password from the **human user**. The agent must NOT generate or store the password itself.
 
@@ -67,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
@@ -127,6 +181,7 @@ For detailed migration steps (from `~/.nansen/.env`, `.credentials`, or env-var-
 | `--chain` | `evm` or `solana` |
 | `--max` | Send entire balance |
 | `--dry-run` | Preview without broadcasting |
+| `--provider` | Wallet provider: `local` (default, encrypted on disk) or `privy` (server-side via Privy API) |
 | `--human` | Enable interactive prompts (human terminal use only — agents must NOT use this) |
 | `--unsafe-no-password` | Skip encryption (keys stored in plaintext — NOT recommended) |
 
@@ -136,5 +191,8 @@ For detailed migration steps (from `~/.nansen/.env`, `.credentials`, or env-var-
 |-----|---------|
 | `NANSEN_WALLET_PASSWORD` | Wallet encryption password — only needed for initial `wallet create`. After that, the OS keychain handles it. |
 | `NANSEN_API_KEY` | API key (also set via `nansen login --api-key <key>`) |
+| `PRIVY_APP_ID` | Privy application ID (required for `--provider privy`) |
+| `PRIVY_APP_SECRET` | Privy application secret (required for `--provider privy`) |
+| `NANSEN_WALLET_PROVIDER` | Default provider for wallet create — `local` or `privy` |
 | `NANSEN_EVM_RPC` | Custom EVM RPC endpoint |
 | `NANSEN_SOLANA_RPC` | Custom Solana RPC endpoint |

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++) {
@@ -630,7 +630,7 @@ export class NansenAPI {
                   } catch (x402Err) {
                     if (!this.apiKey) {
                       message = 'No API key configured. Two ways to authenticate:\n' +
-                        '  1. API key: nansen login --api-key <key> (get key at https://app.nansen.ai/api)\n' +
+                        '  1. API key: nansen login --api-key <key> (get key at https://app.nansen.ai/auth/agent-setup)\n' +
                         '  2. x402 micropayment: nansen wallet create + fund with USDC (no API key needed)';
                     } else {
                       message = `x402 auto-payment failed: ${x402Err.message}`;

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,10 +684,11 @@ 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
-  login       Save API key (--api-key <key> or NANSEN_API_KEY env var)
+  login       Save API key (--api-key <key>, --human, or NANSEN_API_KEY env var)
   logout      Remove saved API key
   schema      JSON schema for all commands (use "nansen schema <cmd>" for one)
   cache       clear
@@ -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
@@ -859,7 +866,7 @@ export function buildCommands(deps = {}) {
         log('  --api-key <key>   Your Nansen API key');
         log('  --human           Enable interactive prompt');
         log('  --help            Show this help\n');
-        log('Get your API key at: https://app.nansen.ai/api');
+        log('Get your API key at: https://app.nansen.ai/auth/agent-setup');
         return;
       }
 
@@ -879,7 +886,7 @@ export function buildCommands(deps = {}) {
           return;
         }
         log('Nansen CLI Login\n');
-        log('Get your API key at: https://app.nansen.ai/api\n');
+        log('Get your API key at: https://app.nansen.ai/auth/agent-setup\n');
         apiKey = await promptFn('Enter your API key: ', true);
       }
 
@@ -890,7 +897,7 @@ export function buildCommands(deps = {}) {
           resolution: [
             'Run: nansen login --api-key <key>',
             'Or set NANSEN_API_KEY environment variable',
-            'Get your API key at: https://app.nansen.ai/api',
+            'Get your API key at: https://app.nansen.ai/auth/agent-setup',
           ],
         }));
         exit(1);
@@ -912,7 +919,7 @@ export function buildCommands(deps = {}) {
           log(JSON.stringify({
             error: 'INVALID_API_KEY',
             message: 'The API key is not valid.',
-            resolution: ['Check your key at https://app.nansen.ai/api']
+            resolution: ['Check your key at https://app.nansen.ai/auth/agent-setup']
           }));
         } else {
           log(JSON.stringify({
@@ -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 };
   }