nansen-cli 1.36.2 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.38.0
+
+### Minor Changes
+
+- [#486](https://github.com/nansen-ai/nansen-cli/pull/486) [`b752d81`](https://github.com/nansen-ai/nansen-cli/commit/b752d81336a5d9bda3ad85e62a4d42d98c069e58) Thanks [@gulshngill](https://github.com/gulshngill)! - Add `nansen auth status` and `nansen doctor`. `auth status` is fully offline: it reports whether an API key is configured and where it comes from (env var vs config file, masked), the active base URL, x402 wallet readiness, and OS keychain availability. `doctor` runs health checks over the whole setup — Node version, config file validity and permissions, wallet storage and password hygiene (flags the insecure `.credentials` file), keychain availability, Privy env credentials, caches, and telemetry — with an actionable fix per finding, plus a safe unauthenticated connectivity probe (no credits consumed; skip it with `--offline`). `--json` returns machine-readable checks.
+
+- [#494](https://github.com/nansen-ai/nansen-cli/pull/494) [`67027e6`](https://github.com/nansen-ai/nansen-cli/commit/67027e6a0faefcc797ec9407f199bc985dbbfc56) Thanks [@kome12](https://github.com/kome12)! - Harden EVM swap signing: scope ERC-20 approvals to the trade amount instead of granting an unlimited allowance, and validate the swap target before signing (reject an empty/zero address, a non-contract target, or a target equal to the token being sold). As a result, ERC-20 sells on Base now include a per-swap approval transaction. Native ETH swaps and all Solana swaps are unaffected. Note: this scopes approvals granted from now on; a pre-existing unlimited approval from an earlier version is not automatically reduced.
+
+  Also tightens the input validation on the quote a swap is signed from. Every approval-signing path (local, Privy, WalletConnect) now shares one encoder that requires a well-formed 20-byte spender, keeps the approved amount bounded (never unlimited) and within the request cap, and produces fixed-width approval calldata. EVM execution now requires complete request intent persisted by the quote command and revalidates each quote against it (chain, wallet, token pair, mode, and amount), so the signed transaction remains bound to what was requested. A same-chain swap whose transaction is a bare ERC-20 transfer/approve rather than a routed swap is refused (bridge routes excluded).
+
+  The swap-target contract check now fails closed: it retries and, if it still can't confirm the target carries contract code, refuses to sign rather than proceeding on an unverified target.
+
+  EVM (Base) exactOut swaps now require an explicit maximum input (spend ceiling) via `--max-input` in base units of the sell token. The quote persists that `maxInputAmount`, and the execute path refuses to sign, approve, or broadcast any quote whose input exceeds it, for native and ERC-20 swaps across all three EVM signing paths. Solana exactOut is unaffected and does not require the flag (there is no ERC-20 approval to scope on that path). Quotes already above the cap are dropped at quote time (and, when none fit, a clear `MAX_INPUT_EXCEEDED` error is returned) rather than saved and rejected only at execute. Relatedly, a quote missing a field the request-intent check needs (sell/buy token address or the bound amount) is now rejected rather than skipped, and the exactOut output binding accepts more-than-requested output (only a shortfall is rejected, since the input is independently capped).
+
+  The execute path also binds the signer to the wallet the quote was built for: it now refuses to sign a quote whose persisted wallet doesn't match the current signer (e.g. the default wallet changed between quote and execute), since the quoted transaction is constructed for a specific sender.
+
+### Patch Changes
+
+- [#494](https://github.com/nansen-ai/nansen-cli/pull/494) [`54b9d41`](https://github.com/nansen-ai/nansen-cli/commit/54b9d41fc9f99cd68bce416b95a129fe9e858981) Thanks [@kome12](https://github.com/kome12)! - Fix exactOut `--max-input` so it bounds the slippage-buffered approval, not the bare quote input. Previously an exactOut ERC-20 quote whose raw input equalled the cap (e.g. 1,000,000 at 3% slippage) passed the max-input filter and was saved, but execution scoped a larger approval (1,030,000) that the approval encoder then rejected for exceeding the cap — bricking the trade across local, Privy, and WalletConnect flows. Both the quote-time filter and the execute-time spend check now measure the same buffered amount the approval encoder does, so a quote that clears the cap can always be signed.
+
+## 1.37.0
+
+### Minor Changes
+
+- [#481](https://github.com/nansen-ai/nansen-cli/pull/481) [`ccaa40b`](https://github.com/nansen-ai/nansen-cli/commit/ccaa40beb570c2a6df5917ded308c3bb1722eb70) Thanks [@kome12](https://github.com/kome12)! - Add `research profiler first-funder` command to look up the first wallet that funded an EVM address. The funder is the earliest address to send native gas, resolved across chains, returned with its Nansen label and the funding transaction.
+
+- [#485](https://github.com/nansen-ai/nansen-cli/pull/485) [`b49c758`](https://github.com/nansen-ai/nansen-cli/commit/b49c75866379421c0738032e1f98a4a74b3fb5b4) Thanks [@MarcLlopart](https://github.com/MarcLlopart)! - `nansen perp order` and `perp close` now print the Hyperliquid order id (`oid`) and fill (size @ avg price) returned by the exchange, plus a ready-to-run `nansen perp cancel` command for any resting order — mirroring how spot trading surfaces its quote id. TP/SL bracket legs are labelled (parent / take-profit / stop-loss). Order ids are uint64; an id beyond JavaScript's safe integer range (2^53) is detected and its exact value and cancel hint are withheld rather than shown rounded, so a wrong id is never presented as actionable.
+
+### Patch Changes
+
+- [#483](https://github.com/nansen-ai/nansen-cli/pull/483) [`d0d10a2`](https://github.com/nansen-ai/nansen-cli/commit/d0d10a266e32aa086a8934acaa8e1d0b9ddff2e2) Thanks [@kome12](https://github.com/kome12)! - Unknown-command errors now detect when a whole multi-word command was passed as a single argument (a common shell-quoting mistake, e.g. `nansen "trade --help"` or an unquoted variable under zsh) and point at the likely cause instead of a bare "Unknown command".
+
+- [#484](https://github.com/nansen-ai/nansen-cli/pull/484) [`bc5f774`](https://github.com/nansen-ai/nansen-cli/commit/bc5f774165df7103eff9ba5cfcdc660bcec5d752) Thanks [@kome12](https://github.com/kome12)! - Write the cost-map and update-check cache files atomically (temp file + rename) so concurrent `nansen` processes can no longer observe an empty or truncated cache.
+
+- [#465](https://github.com/nansen-ai/nansen-cli/pull/465) [`4105193`](https://github.com/nansen-ai/nansen-cli/commit/41051932236a37121819e0d1bf47c8fb34422ec8) Thanks [@dobbydobap](https://github.com/dobbydobap)! - Fix `nansen quote --help`, `nansen trade quote --help`, and `nansen execute --help` to print the trade usage and exit with code 0 instead of erroring with exit code 1.
+
+- [#485](https://github.com/nansen-ai/nansen-cli/pull/485) [`c9aaf58`](https://github.com/nansen-ai/nansen-cli/commit/c9aaf58923819c014588cb2c068600ad9872276e) Thanks [@MarcLlopart](https://github.com/MarcLlopart)! - `nansen perp order` / `perp close` now emit an anonymous `perp_order_completed` telemetry event after the Hyperliquid `/exchange` response is parsed. Perp orders bypass the Nansen API on submit (the CLI signs and posts straight to Hyperliquid), so this client-side event is the only signal that an order was placed. The payload is deliberately minimal — only the trade side and the Hyperliquid order id (omitted when it exceeded JS safe-integer precision); no asset, price, size, or fill detail is sent. The telemetry disclosure (CLI help footer and module docs) names exactly these fields. Honours the existing `DO_NOT_TRACK` / `NANSEN_NO_TELEMETRY` opt-out; order rejections remain covered by `cli_command_failed`.
+
+- [#478](https://github.com/nansen-ai/nansen-cli/pull/478) [`758ce13`](https://github.com/nansen-ai/nansen-cli/commit/758ce13b7c65a5a88d20378ae1ad5cc7bba7d7ba) Thanks [@boleklebovski](https://github.com/boleklebovski)! - Document the missing `trade quote` and `trade execute` options in `src/schema.json`: `--swap-mode`, `--slippage`, `--auto-slippage`, `--max-auto-slippage`, `--quote`, `--quote-index` and `--no-simulate`. These options are already implemented and documented for humans, but were absent from the machine-readable schema.
+
+- [#488](https://github.com/nansen-ai/nansen-cli/pull/488) [`f653b37`](https://github.com/nansen-ai/nansen-cli/commit/f653b3761a4abc8e8a45d3ff42cedf0241a8ff20) Thanks [@gulshngill](https://github.com/gulshngill)! - Warn on logout when `NANSEN_API_KEY` remains active in the environment.
+
 ## 1.36.2
 
 ### Patch Changes

package/README.md

@@ -238,7 +238,8 @@ Any field may be absent or `null`, meaning unknown — never assume zero. A low-
 |---------|-----|
 | `command not found` | `npm install -g nansen-cli` |
 | Global install reports an older version | `npm i -g nansen-cli@latest --registry=https://registry.npmjs.org/ --prefer-online`, then check `which -a nansen` for stale binaries |
-| `UNAUTHORIZED` after login | `cat ~/.nansen/config.json` or set `NANSEN_API_KEY` |
+| `UNAUTHORIZED` after login | `nansen auth status` shows which key is active and where it comes from; re-run `nansen login` or set `NANSEN_API_KEY` |
+| Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
 | Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
 | `perp` _trading_ prints the usage banner | Trading needs `--coin BTC` (`--symbol` also works); see the Perpetuals section. |
 | `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.36.2",
+  "version": "1.38.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",

package/skills/nansen-trading/SKILL.md

@@ -216,6 +216,8 @@ nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type marke
 - `--type`: `limit` (default) or `market`. `--tif`: `Gtc` (default), `Ioc`, `Alo`.
 - `--slippage`: decimal in `[0,1]` for market orders (default `0.03` = 3%).
 
+On success the command prints the Hyperliquid order id (`oid`) and the fill (size @ avg price). A resting (unfilled) order also prints a ready-to-run `nansen perp cancel --coin <coin> --oid <oid>`. Attached take-profit/stop-loss legs are labelled and each print their own `oid`.
+
 ## Close / cancel
 
 ```bash

package/skills/nansen-wallet-keychain-migration/SKILL.md

@@ -31,24 +31,26 @@ Use this skill when a user already has a nansen-cli wallet set up with the
 ## Detect current state
 
 `wallet show` only displays addresses and does NOT load or check the password.
-To detect the actual password situation, check for stored password sources:
+To detect the actual password situation, check the stored password source directly:
 
 ```bash
-# 1. Check if a wallet exists at all
-nansen wallet list 2>&1
+# 1. Where is the password stored? Offline, decrypts nothing, prints no secrets
+nansen auth status --pretty     # → x402.password.source: "env" | "keychain" | "file" | null
 
-# 2. Check for insecure password stores
-ls -la ~/.nansen/.env 2>/dev/null && echo "FOUND: ~/.nansen/.env (insecure)"
-ls -la ~/.nansen/wallets/.credentials 2>/dev/null && echo "FOUND: .credentials file (insecure)"
+# 2. Full setup check — flags the insecure .credentials file with a fix
+nansen doctor --offline
 
-# 3. Try an operation that requires the password (without setting env var)
-nansen wallet export default 2>&1
+# 3. Legacy pattern doctor does not cover: password written to ~/.nansen/.env
+ls -la ~/.nansen/.env 2>/dev/null && echo "FOUND: ~/.nansen/.env (insecure)"
 ```
 
-Interpret the `export` output:
-- `⚠ Password loaded from ~/.nansen/wallets/.credentials` on stderr → needs migration (Path B)
-- Export succeeds silently → password is in keychain, no migration needed
-- `PASSWORD_REQUIRED` JSON error → password not persisted anywhere (Path C or D)
+Interpret `x402.password.source`:
+- `"file"` → password in `.credentials` file, needs migration (Path B)
+- `"keychain"` → already secure, no migration needed
+- `null` → password not persisted anywhere (Path C or D)
+- `"env"` → `NANSEN_WALLET_PASSWORD` is set; check where it is being exported from (a `.env` file → Path A)
+
+Do NOT use `nansen wallet export` to probe the password state — it prints private keys.
 
 ## Migration paths
 

package/src/api.js

@@ -1012,6 +1012,17 @@ export class NansenAPI {
     });
   }
 
+  async addressFirstFunder(params = {}) {
+    const { address } = params;
+    // EVM addresses only; the funder is resolved across chains server-side, so
+    // chain is fixed to 'all' and the endpoint forbids any extra fields.
+    if (address) requireValidAddress(address, 'ethereum');
+    return this.request('/api/v1/profiler/address/first-funder', {
+      address,
+      chain: 'all'
+    });
+  }
+
   async addressCounterparties(params = {}) {
     const { address, chain = 'ethereum', filters = {}, orderBy, pagination, days = 30 } = params;
     if (address) requireValidAddress(address, chain);

package/src/cli.js

@@ -15,6 +15,7 @@ import { buildResearchCommands, RESEARCH_HISTORICAL_SUBCOMMANDS } from './comman
 import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
+import { getAuthStatus, runDoctorChecks, runConnectivityChecks, formatDoctorReport } from './doctor.js';
 import { refreshCostMapIfStale, getCostForEndpoint, creditsCharged } from './cost-cache.js';
 import { creditWarning, noticeWarnings } from './response-meta.js';
 import { trackCommandSucceeded, trackCommandFailed } from './telemetry.js';
@@ -22,7 +23,7 @@ import { createRequire } from 'module';
 import * as readline from 'readline';
 
 const require = createRequire(import.meta.url);
-const { version: VERSION } = require('../package.json');
+const { version: VERSION, engines: ENGINES } = require('../package.json');
 
 // ============= Schema Definition =============
 
@@ -189,7 +190,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' || key === 'expert' || key === 'json') {
+      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' || key === 'offline') {
         result.flags[key] = true;
       } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
         // Try to parse as JSON first (for objects/arrays/booleans),
@@ -729,8 +730,10 @@ COMMANDS:
   alerts      list, create, update, toggle, delete
   web         search, fetch
   account     Show API key status, plan, and remaining credits
+  auth        status — offline auth status: key source, wallets (no network)
   login       Save API key (--api-key <key>, --human, or NANSEN_API_KEY env var)
   logout      Remove saved API key
+  doctor      Diagnostics: auth, wallets, caches, connectivity (--offline --json)
   schema      JSON schema for all commands (use "nansen schema <cmd>" for one)
   cache       clear
   changelog   --since <version> to filter
@@ -771,9 +774,54 @@ Labels: Fund, Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader
 Docs: https://docs.nansen.ai
 Skills: npx skills add nansen-ai/nansen-cli (agent-optimised docs per command group)
 
-Telemetry: anonymous usage stats collected. Disable: DO_NOT_TRACK=1
+Telemetry: anonymous usage stats (commands, timing, errors). Perp order/close additionally send the order side and Hyperliquid order id. Disable: DO_NOT_TRACK=1
 `;
 
+// Usage text for the `trade` command group. Shared by the trade handler and the
+// --help path in runCLI, so `nansen trade`, `nansen trade <sub> --help`, and the
+// deprecated top-level `quote`/`execute --help` all show the same usage.
+export const TRADE_USAGE = `nansen trade — DEX trading commands
+
+SUBCOMMANDS:
+  quote          Get a swap quote (price, route, fees)
+  execute        Sign and broadcast a quoted swap
+  bridge-status  Check cross-chain bridge transaction status
+  limit-order    Limit order management (Solana only)
+
+USAGE:
+  nansen trade quote --chain <chain> --from <token> --to <token> --amount <units> [--wallet <name>]
+  nansen trade quote --chain <chain> --to-chain <chain> --from <token> --to <token> --amount <units>
+  nansen trade execute --quote <quoteId> [--wallet <name>]
+  nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
+  nansen trade limit-order <create|list|cancel|update> [options]
+
+EXAMPLES:
+  nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
+  nansen trade quote --chain base --to-chain solana --from USDC --to USDC --amount 1000000
+  nansen trade execute --quote 1708900000000-abc123
+  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana
+  nansen trade limit-order create --from SOL --to USDC --amount 1.5 --trigger-mint SOL --trigger-condition below --trigger-price 80
+  nansen trade limit-order list
+
+WALLET:
+  --wallet <name>   Use a named wallet, or "walletconnect" / "wc" for WalletConnect.
+                    Defaults to the default local wallet if omitted.
+
+SYMBOLS:
+  Common tokens resolve automatically: SOL, ETH, USDC, USDT, WETH
+  Raw addresses are also accepted.
+
+CROSS-CHAIN NOTES (when using --to-chain):
+  Supported combos:
+    native → native (ETH <-> SOL)
+    USDC → USDC (both directions)
+    USDC → native (USDC → ETH or SOL)
+    native → USDC (ETH/SOL → USDC)
+    non-native → non-native — not supported (use USDC as intermediate)
+  Bridge providers: Li.Fi or Relay (selected automatically based on best price)
+  Typical bridge time: 1-5 minutes`;
+
 // Helper to prompt for input (exported for mocking)
 export async function prompt(question, hidden = false) {
   return new Promise((resolve) => {
@@ -832,7 +880,8 @@ export function buildCommands(deps = {}) {
     saveConfigFn = saveConfig,
     deleteConfigFn = deleteConfig,
     getConfigFileFn = getConfigFile,
-    isTTY = process.stdin.isTTY
+    isTTY = process.stdin.isTTY,
+    env = process.env
   } = deps;
 
   const cmds = {
@@ -840,6 +889,31 @@ export function buildCommands(deps = {}) {
       return apiInstance.getAccount();
     },
 
+    'auth': async (args, _apiInstance, _flags, _options) => {
+      const subcommand = args[0] || 'status';
+      if (subcommand !== 'status') {
+        throw new NansenError(`Unknown auth subcommand: ${subcommand}. Available: status`, ErrorCode.UNKNOWN);
+      }
+      return getAuthStatus();
+    },
+
+    'doctor': async (_args, _apiInstance, flags, _options) => {
+      const checks = runDoctorChecks({ cliVersion: VERSION, engines: ENGINES });
+      if (!flags.offline) {
+        checks.push(...await runConnectivityChecks());
+      }
+      if (flags.json) {
+        return {
+          version: VERSION,
+          offline: Boolean(flags.offline),
+          checks,
+          errors: checks.filter(c => c.status === 'error').length,
+          warnings: checks.filter(c => c.status === 'warn').length,
+        };
+      }
+      log(formatDoctorReport(checks, { cliVersion: VERSION, offline: Boolean(flags.offline) }));
+    },
+
     'web': async (args, apiInstance, flags, options) => {
       const subcommand = args[0] || 'help';
       const subArgs = args.slice(1);
@@ -1004,6 +1078,9 @@ export function buildCommands(deps = {}) {
       } else {
         log('No saved credentials found');
       }
+      if (env.NANSEN_API_KEY) {
+        log('Warning: NANSEN_API_KEY remains active. Run: unset NANSEN_API_KEY');
+      }
     },
 
     'help': async (_args, _apiInstance, _flags, _options) => {
@@ -1147,7 +1224,8 @@ export function buildCommands(deps = {}) {
       let ensName;
       if (address && isEnsName(address)) {
         try {
-          const resolved = await resolveAddress(address, chain);
+          const ensChain = subcommand === 'first-funder' ? 'ethereum' : chain;
+          const resolved = await resolveAddress(address, ensChain);
           address = resolved.address;
           ensName = resolved.ensName;
         } catch (err) {
@@ -1173,6 +1251,7 @@ export function buildCommands(deps = {}) {
         'search': () => apiInstance.entitySearch({ query: options.query }),
         'historical-balances': () => apiInstance.addressHistoricalBalances({ address, chain, filters, orderBy, pagination, days }),
         'related-wallets': () => apiInstance.addressRelatedWallets({ address, chain, orderBy, pagination }),
+        'first-funder': () => apiInstance.addressFirstFunder({ address }),
         'counterparties': () => apiInstance.addressCounterparties({ address, chain, filters, orderBy, pagination, days }),
         'pnl-summary': () => apiInstance.addressPnlSummary({ address, chain, orderBy, pagination, days }),
         'perp-positions': () => apiInstance.addressPerpPositions({ address, filters, orderBy, pagination }),
@@ -1219,7 +1298,7 @@ export function buildCommands(deps = {}) {
           return compareWallets(apiInstance, { addresses: addrs, chain, days });
         },
         'help': () => ({
-          commands: ['balance', 'labels', 'transactions', 'pnl', 'search', 'historical-balances', 'related-wallets', 'counterparties', 'pnl-summary', 'perp-positions', 'perp-trades', 'dex-trades', 'batch', 'trace', 'compare'],
+          commands: ['balance', 'labels', 'transactions', 'pnl', 'search', 'historical-balances', 'related-wallets', 'first-funder', 'counterparties', 'pnl-summary', 'perp-positions', 'perp-trades', 'dex-trades', 'batch', 'trace', 'compare'],
           description: 'Wallet profiling endpoints',
           example: 'nansen research profiler compare --addresses "0xABC...,0xDEF..." --chain ethereum'
         })
@@ -1558,47 +1637,7 @@ export function buildCommands(deps = {}) {
   cmds['trade'] = async (args, apiInstance, flags, options) => {
     const sub = args[0];
     if (!sub || sub === 'help') {
-      log(`nansen trade — DEX trading commands
-
-SUBCOMMANDS:
-  quote          Get a swap quote (price, route, fees)
-  execute        Sign and broadcast a quoted swap
-  bridge-status  Check cross-chain bridge transaction status
-  limit-order    Limit order management (Solana only)
-
-USAGE:
-  nansen trade quote --chain <chain> --from <token> --to <token> --amount <units> [--wallet <name>]
-  nansen trade quote --chain <chain> --to-chain <chain> --from <token> --to <token> --amount <units>
-  nansen trade execute --quote <quoteId> [--wallet <name>]
-  nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
-  nansen trade limit-order <create|list|cancel|update> [options]
-
-EXAMPLES:
-  nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
-  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
-  nansen trade quote --chain base --to-chain solana --from USDC --to USDC --amount 1000000
-  nansen trade execute --quote 1708900000000-abc123
-  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana
-  nansen trade limit-order create --from SOL --to USDC --amount 1.5 --trigger-mint SOL --trigger-condition below --trigger-price 80
-  nansen trade limit-order list
-
-WALLET:
-  --wallet <name>   Use a named wallet, or "walletconnect" / "wc" for WalletConnect.
-                    Defaults to the default local wallet if omitted.
-
-SYMBOLS:
-  Common tokens resolve automatically: SOL, ETH, USDC, USDT, WETH
-  Raw addresses are also accepted.
-
-CROSS-CHAIN NOTES (when using --to-chain):
-  Supported combos:
-    native → native (ETH <-> SOL)
-    USDC → USDC (both directions)
-    USDC → native (USDC → ETH or SOL)
-    native → USDC (ETH/SOL → USDC)
-    non-native → non-native — not supported (use USDC as intermediate)
-  Bridge providers: Li.Fi or Relay (selected automatically based on best price)
-  Typical bridge time: 1-5 minutes`);
+      log(TRADE_USAGE);
       return;
     }
     if (sub === 'limit-order') {
@@ -1804,10 +1843,17 @@ export async function runCLI(rawArgs, deps = {}) {
   const stream = flags.stream || flags.s;
   const csv = options.format === 'csv';
 
+  // `auth` and `doctor --offline` promise zero network activity — that
+  // contract covers the background update-check fetch and telemetry too,
+  // not just the command's own requests.
+  const isOfflineCommand = command === 'auth' || (command === 'doctor' && flags.offline);
+  const trackSucceeded = isOfflineCommand ? async () => {} : trackCommandSucceeded;
+  const trackFailed = isOfflineCommand ? async () => {} : trackCommandFailed;
+
   // Update check (read cached result + schedule background refresh)
   const updateNotification = getUpdateNotification(VERSION);
   const upgradeNotice = getUpgradeNotice(VERSION);
-  scheduleUpdateCheck();
+  if (!isOfflineCommand) scheduleUpdateCheck();
   const notify = () => {
     if (upgradeNotice) errorOutput(upgradeNotice);
     if (updateNotification) errorOutput(updateNotification);
@@ -1828,7 +1874,9 @@ export async function runCLI(rawArgs, deps = {}) {
   }
 
   if (command === 'help' || flags.help || flags.h) {
-    await refreshCostMapIfStale();
+    // Help for an offline command still owes the zero-network contract: the
+    // cost-map refresh fetches the OpenAPI spec and writes ~/.nansen/cost-map.json.
+    if (!isOfflineCommand) await refreshCostMapIfStale();
     // Check for subcommand-specific help: nansen <command> <subcommand> --help
     if (flags.help || flags.h) {
       // Handle 'research <category> <sub> --help' (3-level)
@@ -1922,7 +1970,16 @@ export async function runCLI(rawArgs, deps = {}) {
         return { type: 'command-help', command };
       }
     }
-    // Commands with handlers (e.g. quote, execute) show their own usage
+    // The trade group (and the deprecated top-level quote/execute aliases) use
+    // handler-based usage rather than schema help. Show it and exit 0, instead of
+    // falling through to command execution, which would error on missing required
+    // args and exit 1.
+    if (command === 'trade' || DEPRECATED_TO_TRADE.has(command)) {
+      output(deprecationNote(command) + TRADE_USAGE);
+      notify();
+      return { type: 'command-help', command };
+    }
+    // 'help' and unknown commands: full banner + command list
     if (command === 'help' || !commands[command]) {
       output(BANNER + HELP);
       notify();
@@ -1939,13 +1996,20 @@ export async function runCLI(rawArgs, deps = {}) {
   const chain = options.chain || null;
 
   if (!commands[command]) {
+    // A command token containing whitespace almost always means a multi-word
+    // invocation was passed as a single argument — e.g. `nansen "trade --help"`,
+    // or an unquoted shell variable under zsh (which, unlike bash, does not
+    // word-split `$var`). Point the user straight at the cause instead of a bare
+    // "Unknown command" that reads like a spurious failure.
     const errorData = {
-      error: `Unknown command: ${command}`,
+      error: /\s/.test(command)
+        ? `Unknown command: "${command}". This looks like multiple words passed as one argument — check your shell quoting (use \`nansen trade --help\`, not \`nansen "trade --help"\`).`
+        : `Unknown command: ${command}`,
       available: Object.keys(commands)
     };
     const formatted = formatOutput(errorData, { pretty, table });
     output(formatted.text);
-    await trackCommandFailed({ command: fullCommand, duration_ms: Date.now() - startTime, error_code: 'UNKNOWN_COMMAND', flags: usedFlags, chain });
+    await trackFailed({ command: fullCommand, duration_ms: Date.now() - startTime, error_code: 'UNKNOWN_COMMAND', flags: usedFlags, chain });
     exit(1);
     return { type: 'error', data: errorData };
   }
@@ -1998,7 +2062,7 @@ export async function runCLI(rawArgs, deps = {}) {
 
     // Commands that handle their own output return undefined
     if (result === undefined) {
-      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
+      await trackSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       return { type: 'no-output', command };
     }
 
@@ -2006,7 +2070,7 @@ export async function runCLI(rawArgs, deps = {}) {
     if (command === 'schema') {
       const formatted = formatOutput(result, { pretty, table: false });
       output(formatted.text);
-      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
+      await trackSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       return { type: 'schema', data: result };
     }
 
@@ -2019,7 +2083,7 @@ export async function runCLI(rawArgs, deps = {}) {
     // Alerts list with --table uses custom table format
     if (command === 'alerts' && subcommand === 'list' && table) {
       output(formatAlertsTable(result));
-      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
+      await trackSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       return { type: 'success', data: result };
     }
 
@@ -2030,14 +2094,14 @@ export async function runCLI(rawArgs, deps = {}) {
       if (streamOutput) {
         output(streamOutput);
       }
-      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
+      await trackSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
       return { type: 'stream', data: result };
     }
 
     const successData = { success: true, data: result };
     const formatted = formatOutput(successData, { pretty, table, csv });
     output(formatted.text);
-    await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
+    await trackSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
     return { type: csv ? 'csv' : 'success', data: result };
   } catch (error) {
     // Unified error envelope across all command families (perp/bridge/trade):
@@ -2052,7 +2116,7 @@ export async function runCLI(rawArgs, deps = {}) {
       const formatted = formatOutput(errorData, { pretty, table, csv });
       output(formatted.text);
     }
-    await trackCommandFailed({
+    await trackFailed({
       command: fullCommand,
       duration_ms: Date.now() - startTime,
       error_code: error.code || 'UNKNOWN',

package/src/cost-cache.js

@@ -14,6 +14,24 @@ 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';
 
+/**
+ * Write `data` to `file` atomically: write to a unique temp file in the same
+ * directory, then rename over the target. rename(2) is atomic on POSIX, so a
+ * concurrent reader always sees either the old file or the fully-written new
+ * one — never a truncated/empty file. The temp name includes the pid so
+ * concurrent writers don't clobber each other's temp files.
+ */
+function writeAtomic(file, data) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* temp file may not exist */ }
+    throw err;
+  }
+}
+
 /**
  * Returns { free, pro } credit cost for the given API path, or null if unavailable.
  */
@@ -75,7 +93,7 @@ export async function refreshCostMapIfStale() {
     }
 
     if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { mode: 0o700, recursive: true });
-    fs.writeFileSync(CACHE_FILE, JSON.stringify({ costs, fetchedAt: Date.now() }));
+    writeAtomic(CACHE_FILE, JSON.stringify({ costs, fetchedAt: Date.now() }));
   } catch {
     // silent — network failure, parse error, write error
   }