nansen-cli 1.26.0 → 1.26.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.26.1
+
+### Patch Changes
+
+- [#392](https://github.com/nansen-ai/nansen-cli/pull/392) [`025993d`](https://github.com/nansen-ai/nansen-cli/commit/025993df798ddb406340511e0dada1f9a962be56) Thanks [@TimNooren](https://github.com/TimNooren)! - Add gas balance validation: rejects trades when the wallet lacks sufficient native token for gas fees.
+
 ## 1.26.0
 
 ### Minor Changes

package/package.json

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

package/src/api.js

@@ -60,6 +60,29 @@ export const ErrorCode = {
   UNKNOWN: 'UNKNOWN',                     // Unclassified error
 };
 
+/**
+ * Error thrown by command handlers for user-facing failures (validation errors,
+ * missing args, etc.).
+ *
+ * Handlers must throw rather than calling log() + exit() directly, because
+ * direct exits bypass runCLI's catch block and skip telemetry tracking.
+ *
+ * runCLI outputs CommandError.message as plain text (not JSON-formatted like
+ * NansenError), then fires trackCommandFailed before exiting.
+ *
+ * When `data` is provided, runCLI outputs JSON.stringify(data) instead of the
+ * plain message — this preserves structured JSON output for errors that agents
+ * parse (e.g. PASSWORD_REQUIRED, API_KEY_REQUIRED).
+ */
+export class CommandError extends Error {
+  constructor(message, code = 'COMMAND_ERROR', data = null) {
+    super(message);
+    this.name = 'CommandError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
 /**
  * Custom error class with structured error codes
  */

package/src/cli.js

@@ -3,7 +3,7 @@
  * Extracted from index.js for coverage
  */
 
-import { NansenAPI, NansenError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, normalizeAddress, sleep } from './api.js';
+import { NansenAPI, NansenError, CommandError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, normalizeAddress, sleep } from './api.js';
 import { buildWalletCommands } from './wallet.js';
 import { buildTradingCommands } from './trading.js';
 import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
@@ -793,7 +793,6 @@ export function buildCommands(deps = {}) {
     saveConfigFn = saveConfig,
     deleteConfigFn = deleteConfig,
     getConfigFileFn = getConfigFile,
-    exit = process.exit,
     isTTY = process.stdin.isTTY
   } = deps;
 
@@ -895,12 +894,10 @@ export function buildCommands(deps = {}) {
 
       if (!apiKey && flags.human) {
         if (!isTTY) {
-          log(JSON.stringify({
+          throw new CommandError('--human requires an interactive terminal. Use --api-key or NANSEN_API_KEY env var instead.', 'NOT_A_TTY', {
             error: 'NOT_A_TTY',
             message: '--human requires an interactive terminal. Use --api-key or NANSEN_API_KEY env var instead.',
-          }));
-          exit(1);
-          return;
+          });
         }
         log('Nansen CLI Login\n');
         log('Get your API key at: https://app.nansen.ai/auth/agent-setup\n');
@@ -908,7 +905,7 @@ export function buildCommands(deps = {}) {
       }
 
       if (!apiKey || apiKey.trim().length === 0) {
-        log(JSON.stringify({
+        throw new CommandError('No API key provided.', 'API_KEY_REQUIRED', {
           error: 'API_KEY_REQUIRED',
           message: 'No API key provided.',
           resolution: [
@@ -916,9 +913,7 @@ export function buildCommands(deps = {}) {
             'Or set NANSEN_API_KEY environment variable',
             'Get your API key at: https://app.nansen.ai/auth/agent-setup',
           ],
-        }));
-        exit(1);
-        return;
+        });
       }
 
       // Verify API key before saving
@@ -933,20 +928,17 @@ export function buildCommands(deps = {}) {
         accountInfo = await testApi.getAccount();
       } catch (error) {
         if (error.code === ErrorCode.UNAUTHORIZED) {
-          log(JSON.stringify({
+          throw new CommandError('The API key is not valid.', 'INVALID_API_KEY', {
             error: 'INVALID_API_KEY',
             message: 'The API key is not valid.',
-            resolution: ['Check your key at https://app.nansen.ai/auth/agent-setup']
-          }));
-        } else {
-          log(JSON.stringify({
-            error: 'VERIFICATION_FAILED',
-            message: `Could not verify API key: ${error.message}`,
-            resolution: ['Check your internet connection', 'Try again']
-          }));
+            resolution: ['Check your key at https://app.nansen.ai/auth/agent-setup'],
+          });
         }
-        exit(1);
-        return;
+        throw new CommandError(`Could not verify API key: ${error.message}`, 'VERIFICATION_FAILED', {
+          error: 'VERIFICATION_FAILED',
+          message: `Could not verify API key: ${error.message}`,
+          resolution: ['Check your internet connection', 'Try again'],
+        });
       }
 
       // Key is valid - now save
@@ -1732,7 +1724,7 @@ 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 });
+    await trackCommandFailed({ command: fullCommand, duration_ms: Date.now() - startTime, error_code: 'UNKNOWN_COMMAND', flags: usedFlags, chain });
     exit(1);
     return { type: 'error', data: errorData };
   }
@@ -1759,7 +1751,7 @@ 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 });
+      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       return { type: 'no-output', command };
     }
 
@@ -1767,7 +1759,7 @@ export async function runCLI(rawArgs, deps = {}) {
     if (command === 'schema') {
       const formatted = formatOutput(result, { pretty, table: false });
       output(formatted.text);
-      trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
+      await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       return { type: 'schema', data: result };
     }
 
@@ -1780,6 +1772,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 });
       return { type: 'success', data: result };
     }
 
@@ -1790,20 +1783,26 @@ export async function runCLI(rawArgs, deps = {}) {
       if (streamOutput) {
         output(streamOutput);
       }
-      trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
+      await trackCommandSucceeded({ 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);
-    trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
+    await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
     return { type: csv ? 'csv' : 'success', data: result };
   } catch (error) {
-    const errorData = formatError(error);
-    const formatted = formatOutput(errorData, { pretty, table, csv });
-    output(formatted.text);
-    trackCommandFailed({
+    let errorData;
+    if (error instanceof CommandError) {
+      output(error.data ? JSON.stringify(error.data) : error.message);
+      errorData = { error: error.message, code: error.code };
+    } else {
+      errorData = formatError(error);
+      const formatted = formatOutput(errorData, { pretty, table, csv });
+      output(formatted.text);
+    }
+    await trackCommandFailed({
       command: fullCommand,
       duration_ms: Date.now() - startTime,
       error_code: error.code || 'UNKNOWN',

package/src/telemetry.js

@@ -22,7 +22,7 @@ const { version: cliVersion } = JSON.parse(
 const TELEMETRY_URL =
   'https://bi-data-sources.nansen.ai/events-service-68ifmnpsx2uq7cgab8dw/v2/event';
 
-const TIMEOUT_MS = 2000;
+const TIMEOUT_MS = 1000;
 
 // ─── opt-out ──────────────────────────────────────────────
 
@@ -122,15 +122,17 @@ export function getSessionId() {
 // ─── send ──────────────────────────────────────────────────
 
 /**
- * Send a telemetry event. Fire-and-forget — never throws.
+ * Send a telemetry event. Returns a promise that resolves when the request
+ * completes (or fails/times out). Never rejects — errors are swallowed.
+ * Callers that need to ensure delivery before process.exit can await this.
  */
 function sendEvent(event) {
-  if (TELEMETRY_DISABLED) return;
+  if (TELEMETRY_DISABLED) return Promise.resolve();
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
   timer.unref();
 
-  fetch(TELEMETRY_URL, {
+  return fetch(TELEMETRY_URL, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(event),
@@ -178,7 +180,7 @@ export function trackCommandSucceeded({
   flags = [],
   chain = null,
 }) {
-  sendEvent({
+  return sendEvent({
     event: 'cli_command_succeeded',
     event_source: getEventSource(),
     event_id: crypto.randomUUID(),
@@ -216,7 +218,7 @@ export function trackCommandFailed({
   flags = [],
   chain = null,
 }) {
-  sendEvent({
+  return sendEvent({
     event: 'cli_command_failed',
     event_source: getEventSource(),
     event_id: crypto.randomUUID(),

package/src/trade-validation.js

@@ -115,6 +115,7 @@ const NATIVE_TOKEN_ADDRESSES = {
 // Native token symbols for error messages.
 const NATIVE_SYMBOLS = { solana: 'SOL', base: 'ETH' };
 
+const MIN_GAS_AMOUNTS = { solana: 0.01, base: 0.000024 };
 const FEE_BUFFER = { solana: 0.005, base: 0.00004 };
 const HIGH_PERCENTAGE_THRESHOLD = 95;
 const AUTO_ADJUST_THRESHOLD_PERCENT = 2;
@@ -269,6 +270,32 @@ export async function resolvePercentAmount({ chain, from, walletAddress, percent
   return String(parseFloat(tokenAmount.toFixed(decimals)));
 }
 
+/**
+ * Validate that the wallet has enough native token for gas fees.
+ *
+ * Returns { hasSufficientNative } or throws on validation failure.
+ * Best-effort: if RPC fails, returns passing result.
+ */
+export async function validateGasBalance({ chain, walletAddress }) {
+  const normalizedChain = chain.toLowerCase();
+  const minGas = MIN_GAS_AMOUNTS[normalizedChain];
+  if (minGas === undefined) return { hasSufficientNative: true };
+
+  const balance = await fetchNativeBalance(normalizedChain, walletAddress);
+
+  // RPC failure — proceed without validation.
+  if (balance === null) return { hasSufficientNative: true };
+
+  if (balance >= minGas) {
+    return { hasSufficientNative: true };
+  }
+
+  const symbol = NATIVE_SYMBOLS[normalizedChain] || 'native token';
+  throw new Error(
+    `Insufficient ${symbol} for gas fees. Wallet has ${balance} ${symbol} but needs at least ${minGas} ${symbol}. Fund the wallet before trading.`
+  );
+}
+
 /**
  * Fetch an ERC-20 or SPL token balance for a wallet.
  * Returns balance in human-readable token units, or null on RPC failure.

package/src/trading.js

@@ -13,12 +13,14 @@ import { base58Decode } from './transfer.js';
 import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect, sendSolanaTransactionViaWalletConnect, sendApprovalViaWalletConnect } from './walletconnect-trading.js';
 import { retrievePassword } from './keychain.js';
-import { validateQuoteInput, validateBalance, resolvePercentAmount } from './trade-validation.js';
+import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance } from './trade-validation.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
+import { packageVersion, CommandError } from './api.js';
 
 // ============= Constants =============
 
 const TRADING_API_URL = process.env.NANSEN_TRADING_API_URL || 'https://trading-api.nansen.ai';
+const CLIENT_USER_AGENT = `nansen-cli/${packageVersion}`;
 
 const CHAIN_MAP = {
   solana:   { index: '501', type: 'solana', chainId: 501,  name: 'Solana',   explorer: 'https://solscan.io/tx/', lifiChainId: '1151111081099710' },
@@ -115,7 +117,7 @@ export async function getQuote(params) {
     }
   }
 
-  const headers = { 'Accept': 'application/json' };
+  const headers = { 'Accept': 'application/json', 'User-Agent': CLIENT_USER_AGENT };
 
   const res = await fetch(url.toString(), { headers });
 
@@ -153,6 +155,7 @@ export async function executeTransaction(params, { retries = 2, retryDelayMs = 1
   const headers = {
     'Content-Type': 'application/json',
     'Accept': 'application/json',
+    'User-Agent': CLIENT_USER_AGENT,
   };
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
@@ -216,7 +219,7 @@ export async function getBridgeStatus(txHash, fromChain, toChain) {
   url.searchParams.set('fromChain', fromConfig.lifiChainId || fromConfig.index);
   url.searchParams.set('toChain', toConfig.lifiChainId || toConfig.index);
 
-  const res = await fetch(url.toString(), { headers: { 'Accept': 'application/json' } });
+  const res = await fetch(url.toString(), { headers: { 'Accept': 'application/json', 'User-Agent': CLIENT_USER_AGENT } });
   const text = await res.text();
   let body;
   try {
@@ -940,7 +943,7 @@ export function formatQuote(quote, index) {
  * Build trading command handlers for CLI integration.
  */
 export function buildTradingCommands(deps = {}) {
-  const { log = console.log, exit = process.exit } = deps;
+  const { log = console.log } = deps;
 
   return {
     'quote': async (args, apiInstance, flags, options) => {
@@ -961,7 +964,7 @@ export function buildTradingCommands(deps = {}) {
       const amountUnit = options['amount-unit'];
 
       if (!chain || !from || !to || !amount) {
-        log(`
+        throw new CommandError(`
 Usage: nansen trade quote --chain <chain> --from <token> --to <token> --amount <baseUnits>
 
 PREREQUISITE:
@@ -991,23 +994,17 @@ EXAMPLES:
   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 quote --chain solana --to-chain base --from SOL --to ETH --amount 1000000000
-`);
-        exit(1);
-        return;
+`, 'MISSING_ARGS');
       }
 
       // Validate --amount-unit if provided
       if (amountUnit && amountUnit !== 'token' && amountUnit !== 'base' && amountUnit !== 'usd' && amountUnit !== 'percent') {
-        log(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base, usd, percent`);
-        exit(1);
-        return;
+        throw new CommandError(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base, usd, percent`, 'INVALID_INPUT');
       }
 
       // --amount-unit percent is only valid for exactIn (sell-side)
       if (amountUnit === 'percent' && swapMode === 'exactOut') {
-        log('Error: --amount-unit percent is not supported with --swap-mode exactOut. Percentage is relative to your sell-token balance.');
-        exit(1);
-        return;
+        throw new CommandError('Error: --amount-unit percent is not supported with --swap-mode exactOut. Percentage is relative to your sell-token balance.', 'INVALID_INPUT');
       }
 
       // Static input validation — catches common agent errors (wrong addresses,
@@ -1015,9 +1012,7 @@ EXAMPLES:
       try {
         validateQuoteInput({ chain, toChain: toChainRaw || null, from, to, amount });
       } catch (validationErr) {
-        log(`Error: ${validationErr.message}`);
-        exit(1);
-        return;
+        throw new CommandError(`Error: ${validationErr.message}`, 'INVALID_INPUT');
       }
 
       // When --amount-unit token is used, resolve decimals and convert to base units.
@@ -1036,9 +1031,7 @@ EXAMPLES:
           usdTokenAmount = tokenAmount.toFixed(resolvedDecimals);
           resolvedAmount = convertToBaseUnits(usdTokenAmount, resolvedDecimals);
         } catch (err) {
-          log(`Error converting USD amount: ${err.message}`);
-          exit(1);
-          return;
+          throw new CommandError(`Error converting USD amount: ${err.message}`, 'INVALID_INPUT');
         }
       } else if (amountUnit === 'token') {
         try {
@@ -1046,18 +1039,14 @@ EXAMPLES:
           resolvedDecimals = await resolveTokenDecimals(tokenForDecimals, chain);
           resolvedAmount = convertToBaseUnits(amount, resolvedDecimals);
         } catch (err) {
-          log(`Error resolving token decimals: ${err.message}`);
-          exit(1);
-          return;
+          throw new CommandError(`Error resolving token decimals: ${err.message}`, 'INVALID_INPUT');
         }
       } else if (amountUnit === 'percent') {
         // Resolved after wallet address is available — see percent resolution block below.
       } else {
         const amountError = validateBaseUnitAmount(amount);
         if (amountError) {
-          log(`Error: ${amountError}`);
-          exit(1);
-          return;
+          throw new CommandError(`Error: ${amountError}`, 'INVALID_INPUT');
         }
       }
 
@@ -1073,9 +1062,7 @@ EXAMPLES:
         if (isWalletConnect) {
           walletAddress = await getWalletConnectAddress(chainType);
           if (!walletAddress) {
-            log('No WalletConnect session active. Run: walletconnect connect');
-            exit(1);
-            return;
+            throw new CommandError('No WalletConnect session active. Run: walletconnect connect', 'NO_WALLET');
           }
         } else if (walletName) {
           const wallet = showWallet(walletName);
@@ -1101,9 +1088,7 @@ EXAMPLES:
         }
 
         if (!walletAddress) {
-          log('No wallet found. A wallet address is required for quotes because the trading API builds a transaction specific to the sender.\nCreate one with: nansen wallet create');
-          exit(1);
-          return;
+          throw new CommandError('No wallet found. A wallet address is required for quotes because the trading API builds a transaction specific to the sender.\nCreate one with: nansen wallet create', 'NO_WALLET');
         }
 
         // --amount-unit percent: fetch balance, calculate percentage, convert to base units.
@@ -1120,9 +1105,7 @@ EXAMPLES:
             });
             resolvedAmount = convertToBaseUnits(tokenAmount, resolvedDecimals);
           } catch (err) {
-            log(`Error: ${err.message}`);
-            exit(1);
-            return;
+            throw new CommandError(`Error: ${err.message}`, 'INVALID_INPUT');
           }
         }
 
@@ -1148,9 +1131,7 @@ EXAMPLES:
               resolvedAmount = convertToBaseUnits(balanceAdjusted, resolvedDecimals);
             }
           } catch (balanceErr) {
-            log(`Error: ${balanceErr.message}`);
-            exit(1);
-            return;
+            throw new CommandError(`Error: ${balanceErr.message}`, 'INSUFFICIENT_BALANCE');
           }
         }
 
@@ -1197,17 +1178,23 @@ EXAMPLES:
         const response = await getQuote(params);
 
         if (!response.success || !response.quotes?.length) {
-          log('No quotes available');
+          let msg = 'No quotes available';
           if (response.warnings?.length) {
-            response.warnings.forEach(w => log(`  Warning: ${w}`));
+            msg += '\n' + response.warnings.map(w => `  Warning: ${w}`).join('\n');
           }
-          exit(1);
-          return;
+          throw new CommandError(msg, 'NO_QUOTES');
         }
 
         log('');
         response.quotes.forEach((q, i) => log(formatQuote(q, i)));
 
+        // Gas balance validation — check that the wallet has enough native token for gas.
+        try {
+          await validateGasBalance({ chain, walletAddress });
+        } catch (gasErr) {
+          throw new CommandError(`Error: ${gasErr.message}`, 'INSUFFICIENT_GAS');
+        }
+
         const signerType = isWalletConnect ? 'walletconnect' : walletProvider;
         const quoteId = saveQuote(response, chain, signerType, privyWalletIds, isCrossChain ? toChainRaw : null);
         log(`\n  Quote ID: ${quoteId}`);
@@ -1225,13 +1212,14 @@ EXAMPLES:
         return undefined; // Output already printed above
 
       } catch (err) {
+        if (err instanceof CommandError) throw err;
         let message = err.message;
         if (err.code === 'INVALID_AMOUNT' || /amount/i.test(err.message)) {
           message += '. Amounts must be in base units (e.g., 1000000000 lamports for 1 SOL, 1000000000000000000 wei for 1 ETH)';
         }
-        log(`Error: ${message}`);
-        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
-        exit(1);
+        let msg = `Error: ${message}`;
+        if (err.details) msg += `\n  Details: ${JSON.stringify(err.details)}`;
+        throw new CommandError(msg, err.code || 'QUOTE_ERROR');
       }
     },
 
@@ -1241,8 +1229,7 @@ EXAMPLES:
       const noSimulate = flags['no-simulate'];
 
       if (!quoteId) {
-        log(`
-Usage: nansen trade execute --quote <quoteId> [options]
+        throw new CommandError(`Usage: nansen trade execute --quote <quoteId> [options]
 
 OPTIONS:
   --quote <id>              Quote ID from 'nansen quote'
@@ -1250,10 +1237,7 @@ OPTIONS:
   --no-simulate             Skip pre-broadcast simulation
 
 EXAMPLES:
-  nansen trade execute --quote 1708900000000-abc123
-`);
-        exit(1);
-        return;
+  nansen trade execute --quote 1708900000000-abc123`, 'MISSING_ARGS');
       }
 
       try {
@@ -1264,9 +1248,7 @@ EXAMPLES:
 
         const allQuotes = quoteData.response.quotes || [];
         if (!allQuotes.length) {
-          log('❌ No quote data found');
-          exit(1);
-          return;
+          throw new CommandError('❌ No quote data found', 'NO_QUOTES');
         }
 
         // --quote-index pins a specific quote (no fallback)
@@ -1277,10 +1259,7 @@ EXAMPLES:
         // Check if any quote in range has transaction data before prompting for password
         const hasAnyTransaction = allQuotes.slice(startIndex, endIndex).some(q => q?.transaction);
         if (!hasAnyTransaction) {
-          log('❌ No quotes contain transaction data.');
-          log('  Ensure userWalletAddress was provided when fetching the quote.');
-          exit(1);
-          return;
+          throw new CommandError('❌ No quotes contain transaction data.\n  Ensure userWalletAddress was provided when fetching the quote.', 'NO_TRANSACTION');
         }
 
         // Determine if this is a WalletConnect or Privy-signed quote
@@ -1301,16 +1280,14 @@ EXAMPLES:
           if (walletConfig.passwordHash) {
             password = resolveTradePassword();
             if (!password) {
-              log(JSON.stringify({
+              throw new CommandError('Wallet is encrypted and no password was found.', 'PASSWORD_REQUIRED', {
                 error: 'PASSWORD_REQUIRED',
                 message: 'Wallet is encrypted and no password was found.',
                 resolution: [
                   'Set NANSEN_WALLET_PASSWORD environment variable',
                   'Or run: nansen wallet create (password is saved to OS keychain automatically)',
                 ],
-              }));
-              exit(1);
-              return;
+              });
             }
           }
 
@@ -1320,9 +1297,7 @@ EXAMPLES:
             effectiveWalletName = list.defaultWallet;
           }
           if (!effectiveWalletName) {
-            log('No wallet found. Create one with: nansen wallet create');
-            exit(1);
-            return;
+            throw new CommandError('No wallet found. Create one with: nansen wallet create', 'NO_WALLET');
           }
 
           exported = exportWallet(effectiveWalletName, password);
@@ -1330,9 +1305,7 @@ EXAMPLES:
           // Verify WalletConnect session is still active and address matches quote
           const wcAddress = await getWalletConnectAddress(chainType);
           if (!wcAddress) {
-            log('No WalletConnect session active. Run: walletconnect connect');
-            exit(1);
-            return;
+            throw new CommandError('No WalletConnect session active. Run: walletconnect connect', 'NO_WALLET');
           }
           // Check address matches the one used during quoting
           const quoteWallet = quoteData.response?.quotes?.[0]?.transaction?.from
@@ -1340,9 +1313,7 @@ EXAMPLES:
           if (quoteWallet && (chainType === 'solana'
             ? wcAddress.trim() !== quoteWallet.trim()
             : wcAddress.toLowerCase().trim() !== quoteWallet.toLowerCase().trim())) {
-            log(`Connected wallet (${wcAddress}) doesn't match quote. Get a new quote with --wallet walletconnect`);
-            exit(1);
-            return;
+            throw new CommandError(`Connected wallet (${wcAddress}) doesn't match quote. Get a new quote with --wallet walletconnect`, 'WALLET_MISMATCH');
           }
         }
 
@@ -1705,8 +1676,7 @@ EXAMPLES:
                     lastQuoteError = `${quoteName} reverted on-chain`;
                     continue;
                   }
-                  exit(1);
-                  return;
+                  throw new CommandError(`\n  ⚠ Transaction was broadcast but REVERTED on-chain!\n    Tx Hash:   ${wcResult.txHash}\n    Explorer:  ${chainConfig.explorer}${wcResult.txHash}\n    Error:     ${receiptErr.message}`, 'TX_REVERTED');
                 }
 
                 log(`\n  ✓ Transaction successful!`);
@@ -1896,10 +1866,7 @@ EXAMPLES:
                     lastQuoteError = `${quoteName} reverted on-chain`;
                     continue;
                   }
-                  log(`\n  The trading API reported success, but the contract execution failed.`);
-                  log(`  This can happen due to: stale quotes, insufficient gas, or liquidity changes.`);
-                  exit(1);
-                  return;
+                  throw new CommandError(`\n  ⚠ Transaction was broadcast but REVERTED on-chain!\n    Tx Hash:   ${result.txHash}\n    Explorer:  ${explorerUrl}\n    Error:     ${receiptErr.message}\n\n  The trading API reported success, but the contract execution failed.\n  This can happen due to: stale quotes, insufficient gas, or liquidity changes.`, 'TX_REVERTED');
                 }
               }
 
@@ -1954,15 +1921,13 @@ EXAMPLES:
         }
 
         // All quotes exhausted
-        log(`\n❌ All quotes failed. Last error: ${lastQuoteError || 'unknown'}`);
-        log('');
-        exit(1);
-        return undefined;
+        throw new CommandError(`\n❌ All quotes failed. Last error: ${lastQuoteError || 'unknown'}\n`, 'ALL_QUOTES_FAILED');
 
       } catch (err) {
-        log(`Error: ${err.message}`);
-        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
-        exit(1);
+        if (err instanceof CommandError) throw err;
+        let msg = `Error: ${err.message}`;
+        if (err.details) msg += `\n  Details: ${JSON.stringify(err.details)}`;
+        throw new CommandError(msg, err.code || 'EXECUTE_ERROR');
       }
     },
 
@@ -1972,8 +1937,7 @@ EXAMPLES:
       const toChain = options['to-chain'] || args[2];
 
       if (!txHash || !fromChain || !toChain) {
-        log(`
-Usage: nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
+        throw new CommandError(`Usage: nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
 
 Check the status of a cross-chain bridge transaction.
 
@@ -1983,10 +1947,7 @@ OPTIONS:
   --to-chain <chain>        Destination chain (solana or base)
 
 EXAMPLES:
-  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana
-`);
-        exit(1);
-        return;
+  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana`, 'MISSING_ARGS');
       }
 
       try {
@@ -2010,9 +1971,10 @@ EXAMPLES:
         if (status.lifiExplorerLink) log(`  Li.Fi:       ${status.lifiExplorerLink}`);
         log('');
       } catch (err) {
-        log(`Error: ${err.message}`);
-        if (err.details) log(`  Details: ${JSON.stringify(err.details)}`);
-        exit(1);
+        if (err instanceof CommandError) throw err;
+        let msg = `Error: ${err.message}`;
+        if (err.details) msg += `\n  Details: ${JSON.stringify(err.details)}`;
+        throw new CommandError(msg, err.code || 'BRIDGE_STATUS_ERROR');
       }
     },
   };

package/src/wallet.js

@@ -9,6 +9,7 @@ import path from 'path';
 import * as readline from 'readline';
 import { base58 } from '@scure/base';
 import { storePassword, retrievePassword, deletePassword, deleteCredentialsFile } from './keychain.js';
+import { CommandError } from './api.js';
 
 // ============= Constants =============
 
@@ -335,8 +336,8 @@ function resolveWalletPassword() {
  *
  * @param {object} config - wallet config (needs config.passwordHash)
  * @param {object} flags - CLI flags
- * @param {object} deps - { promptFn, log, exit }
- * @returns {{ password: string|null, error: string|null }}
+ * @param {object} deps - { promptFn, log }
+ * @returns {{ password: string|null, error: object|null }}
  */
 async function resolvePasswordForCommand(config, flags, deps) {
   if (!config.passwordHash) {
@@ -353,14 +354,14 @@ async function resolvePasswordForCommand(config, flags, deps) {
 
   return {
     password: null,
-    error: JSON.stringify({
+    error: {
       error: 'PASSWORD_REQUIRED',
       message: 'Wallet is encrypted and no password was found.',
       resolution: [
         'Set NANSEN_WALLET_PASSWORD environment variable',
         'Or re-run wallet create with the password (it will be persisted for future use)',
       ],
-    }),
+    },
   };
 }
 
@@ -580,7 +581,7 @@ export async function deleteWallet(name, password) {
  * Build wallet command handlers for integration into CLI.
  */
 export function buildWalletCommands(deps = {}) {
-  const { log = console.log, promptFn: _promptFn, exit = process.exit } = deps;
+  const { log = console.log } = deps;
 
   return {
     'wallet': async (args, apiInstance, flags, options) => {
@@ -599,9 +600,7 @@ export function buildWalletCommands(deps = {}) {
             log('');
             return;
           } catch (err) {
-            log(`❌ ${err.message}`);
-            exit(1);
-            return;
+            throw new CommandError(`❌ ${err.message}`, 'PRIVY_ERROR');
           }
         }
         // All other subcommands fall through to unified handlers below
@@ -612,8 +611,8 @@ export function buildWalletCommands(deps = {}) {
       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).
+          // the privy path already threw CommandError. Guard against environments
+          // where throw does not propagate (agent frameworks, test harnesses).
           if (isPrivy) return;
 
           const name = options.name || args[1] || 'default';
@@ -628,28 +627,22 @@ export function buildWalletCommands(deps = {}) {
 
             // Step 2: If --human flag, allow interactive prompt (requires TTY)
             if (!password && flags.human && !process.stdin.isTTY && !deps.promptFn) {
-              log(JSON.stringify({
+              throw new CommandError('--human requires an interactive terminal. Set NANSEN_WALLET_PASSWORD env var instead.', 'NOT_A_TTY', {
                 error: 'NOT_A_TTY',
                 message: '--human requires an interactive terminal. Set NANSEN_WALLET_PASSWORD env var instead.',
-              }));
-              exit(1);
-              return;
+              });
             }
             if (!password && flags.human && (process.stdin.isTTY || deps.promptFn)) {
               password = await promptPassword('Enter wallet password: ', deps);
               if (password && password.length < 12) {
-                log('❌ Password must be at least 12 characters');
-                exit(1);
-                return;
+                throw new CommandError('❌ Password must be at least 12 characters', 'INVALID_INPUT');
               }
               if (password) {
                 const config = getWalletConfig();
                 if (!config.passwordHash) {
                   const confirm = await promptPassword('Confirm password: ', deps);
                   if (password !== confirm) {
-                    log('❌ Passwords do not match');
-                    exit(1);
-                    return;
+                    throw new CommandError('❌ Passwords do not match', 'INVALID_INPUT');
                   }
                 }
               }
@@ -657,20 +650,16 @@ export function buildWalletCommands(deps = {}) {
 
             // Step 3: No password available — return structured error for agents
             if (!password) {
-              log(JSON.stringify({
+              throw new CommandError('A wallet password is required. Ask the user to provide one.', 'PASSWORD_REQUIRED', {
                 error: 'PASSWORD_REQUIRED',
                 message: 'A wallet password is required. Ask the user to provide one.',
                 instructions: 'Re-run with: NANSEN_WALLET_PASSWORD=<password> nansen wallet create',
                 note: 'Password must be at least 12 characters. After creation, the password is saved to the OS keychain automatically — future operations will not require it.',
-              }));
-              exit(1);
-              return;
+              });
             }
 
             if (password.length < 12) {
-              log('❌ Password must be at least 12 characters');
-              exit(1);
-              return;
+              throw new CommandError('❌ Password must be at least 12 characters', 'INVALID_INPUT');
             }
           }
 
@@ -678,9 +667,7 @@ export function buildWalletCommands(deps = {}) {
           if (password !== null) {
             const config = getWalletConfig();
             if (config.passwordHash && !verifyPassword(password, config)) {
-              log('❌ Incorrect password — does not match existing wallets.');
-              exit(1);
-              return;
+              throw new CommandError('❌ Incorrect password — does not match existing wallets.', 'INCORRECT_PASSWORD');
             }
           }
 
@@ -725,8 +712,7 @@ export function buildWalletCommands(deps = {}) {
             log('');
             return;
           } catch (err) {
-            log(`❌ ${err.message}`);
-            exit(1);
+            throw new CommandError(`❌ ${err.message}`, 'CREATE_FAILED');
           }
         },
 
@@ -750,9 +736,7 @@ export function buildWalletCommands(deps = {}) {
         'show': async () => {
           const name = options.name || args[1];
           if (!name) {
-            log('Usage: nansen wallet show <name>');
-            exit(1);
-            return;
+            throw new CommandError('Usage: nansen wallet show <name>', 'MISSING_ARGS');
           }
           try {
             const result = showWallet(name);
@@ -764,25 +748,20 @@ export function buildWalletCommands(deps = {}) {
             log(`    Created: ${result.createdAt}\n`);
             return;
           } catch (err) {
-            log(`❌ ${err.message}`);
-            exit(1);
+            throw new CommandError(`❌ ${err.message}`, 'SHOW_FAILED');
           }
         },
 
         'export': async () => {
           const name = options.name || args[1];
           if (!name) {
-            log('Usage: nansen wallet export <name>');
-            exit(1);
-            return;
+            throw new CommandError('Usage: nansen wallet export <name>', 'MISSING_ARGS');
           }
 
           const config = getWalletConfig();
           const { password, error } = await resolvePasswordForCommand(config, flags, deps);
           if (error) {
-            log(error);
-            exit(1);
-            return;
+            throw new CommandError(error.message, 'PASSWORD_REQUIRED', error);
           }
           try {
             const result = exportWallet(name, password);
@@ -796,34 +775,28 @@ export function buildWalletCommands(deps = {}) {
             log('');
             return;
           } catch (err) {
-            log(`❌ ${err.message}`);
-            exit(1);
+            throw new CommandError(`❌ ${err.message}`, 'EXPORT_FAILED');
           }
         },
 
         'default': async () => {
           const name = options.name || args[1];
           if (!name) {
-            log('Usage: nansen wallet default <name>');
-            exit(1);
-            return;
+            throw new CommandError('Usage: nansen wallet default <name>', 'MISSING_ARGS');
           }
           try {
             const result = setDefaultWallet(name);
             log(`✓ Default wallet set to "${result.defaultWallet}"`);
             return;
           } catch (err) {
-            log(`❌ ${err.message}`);
-            exit(1);
+            throw new CommandError(`❌ ${err.message}`, 'DEFAULT_FAILED');
           }
         },
 
         'delete': async () => {
           const name = options.name || args[1];
           if (!name) {
-            log('Usage: nansen wallet delete <name>');
-            exit(1);
-            return;
+            throw new CommandError('Usage: nansen wallet delete <name>', 'MISSING_ARGS');
           }
 
           // Check if this is a Privy wallet (no password needed)
@@ -839,9 +812,7 @@ export function buildWalletCommands(deps = {}) {
             const config = getWalletConfig();
             const resolved = await resolvePasswordForCommand(config, flags, deps);
             if (resolved.error) {
-              log(resolved.error);
-              exit(1);
-              return;
+              throw new CommandError(resolved.error.message, 'PASSWORD_REQUIRED', resolved.error);
             }
             password = resolved.password;
           }
@@ -857,8 +828,7 @@ export function buildWalletCommands(deps = {}) {
             }
             return;
           } catch (err) {
-            log(`❌ ${err.message}`);
-            exit(1);
+            throw new CommandError(`❌ ${err.message}`, 'DELETE_FAILED');
           }
         },
 
@@ -866,28 +836,20 @@ export function buildWalletCommands(deps = {}) {
           const { sendTokens } = await import('./transfer.js');
 
           if (!options.to) {
-            log('❌ --to <address> is required');
-            exit(1);
-            return;
+            throw new CommandError('--to <address> is required', 'MISSING_ARGS');
           }
 
           const isMax = flags.max || options.amount === 'max';
           if (!options.amount && !isMax) {
-            log('❌ --amount <number> or --max is required');
-            exit(1);
-            return;
+            throw new CommandError('--amount <number> or --max is required', 'MISSING_ARGS');
           }
 
           if (!options.chain) {
-            log('❌ --chain <evm|solana> is required');
-            exit(1);
-            return;
+            throw new CommandError('--chain <evm|solana> is required', 'MISSING_ARGS');
           }
 
           if (!['evm', 'solana', 'ethereum', 'base'].includes(options.chain)) {
-            log('❌ --chain must be one of: evm, solana, ethereum, base');
-            exit(1);
-            return;
+            throw new CommandError('--chain must be one of: evm, solana, ethereum, base', 'INVALID_INPUT');
           }
 
           const isWalletConnect = options.wallet === 'walletconnect' || options.wallet === 'wc';
@@ -912,9 +874,7 @@ export function buildWalletCommands(deps = {}) {
             const sendConfig = getWalletConfig();
             const resolved = await resolvePasswordForCommand(sendConfig, flags, deps);
             if (resolved.error) {
-              log(resolved.error);
-              exit(1);
-              return;
+              throw new CommandError(resolved.error.message, 'PASSWORD_REQUIRED', resolved.error);
             }
             password = resolved.password;
           }
@@ -960,8 +920,7 @@ export function buildWalletCommands(deps = {}) {
             log('');
             return;
           } catch (err) {
-            log(`Error: ${err.message}`);
-            exit(1);
+            throw new CommandError(err.message, 'SEND_FAILED');
           }
         },
 
@@ -979,16 +938,14 @@ export function buildWalletCommands(deps = {}) {
         'secure': async () => {
           const { password, source } = retrievePassword();
           if (!password) {
-            log(JSON.stringify({
+            throw new CommandError('No wallet password found in any store.', 'NO_PASSWORD_FOUND', {
               error: 'NO_PASSWORD_FOUND',
               message: 'No wallet password found in any store.',
               resolution: [
                 'Set NANSEN_WALLET_PASSWORD and run: nansen wallet secure',
                 'This will store it in the OS keychain.',
               ],
-            }));
-            exit(1);
-            return;
+            });
           }
 
           if (source === 'keychain') {
@@ -999,20 +956,19 @@ export function buildWalletCommands(deps = {}) {
           // Verify password actually decrypts wallets before overwriting keychain
           const walletConfig = getWalletConfig();
           if (walletConfig.passwordHash && !verifyPassword(password, walletConfig)) {
-            log(JSON.stringify({
+            const resolution = source === 'file'
+              ? [
+                  'The password in ~/.nansen/wallets/.credentials is incorrect.',
+                  'Run: nansen wallet forget-password  then re-run with the correct password: NANSEN_WALLET_PASSWORD=<pw> nansen wallet secure',
+                ]
+              : [
+                  'Unset NANSEN_WALLET_PASSWORD if it is stale, then re-run: nansen wallet secure',
+                ];
+            throw new CommandError(`Password from '${source}' does not match the wallet's stored hash.`, 'INCORRECT_PASSWORD', {
               error: 'INCORRECT_PASSWORD',
               message: `Password from '${source}' does not match the wallet's stored hash.`,
-              resolution: source === 'file'
-                ? [
-                    'The password in ~/.nansen/wallets/.credentials is incorrect.',
-                    'Run: nansen wallet forget-password  then re-run with the correct password: NANSEN_WALLET_PASSWORD=<pw> nansen wallet secure',
-                  ]
-                : [
-                    'Unset NANSEN_WALLET_PASSWORD if it is stale, then re-run: nansen wallet secure',
-                  ],
-            }));
-            exit(1);
-            return;
+              resolution,
+            });
           }
 
           // Try to migrate to keychain
@@ -1027,18 +983,17 @@ export function buildWalletCommands(deps = {}) {
               log('  Removed ~/.nansen/wallets/.credentials.');
             }
           } else {
-            log(JSON.stringify({
+            const msg = source === 'file'
+              ? 'OS keychain is not available. Password remains in ~/.nansen/wallets/.credentials (insecure).'
+              : 'OS keychain is not available. Password is only in the NANSEN_WALLET_PASSWORD env var (not persisted).';
+            throw new CommandError(msg, 'KEYCHAIN_UNAVAILABLE', {
               error: 'KEYCHAIN_UNAVAILABLE',
-              message: source === 'file'
-                ? 'OS keychain is not available. Password remains in ~/.nansen/wallets/.credentials (insecure).'
-                : 'OS keychain is not available. Password is only in the NANSEN_WALLET_PASSWORD env var (not persisted).',
+              message: msg,
               resolution: [
                 'Set NANSEN_WALLET_PASSWORD in a secrets manager or system keyring',
                 'Use a containerized secrets agent (e.g. Vault, 1Password CLI)',
               ],
-            }));
-            exit(1);
-            return;
+            });
           }
         },
 
@@ -1104,9 +1059,7 @@ EXAMPLES:
       };
 
       if (!handlers[subcommand]) {
-        log(`Unknown subcommand: ${subcommand}. Available: ${Object.keys(handlers).join(', ')}`);
-        exit(1);
-        return;
+        throw new CommandError(`Unknown subcommand: ${subcommand}. Available: ${Object.keys(handlers).join(', ')}`, 'UNKNOWN_COMMAND');
       }
 
       // --help on any wallet subcommand shows wallet help instead of executing

package/src/x402-svm.js

@@ -5,7 +5,7 @@
 
 import crypto from 'crypto';
 import { base58Encode, base58DecodePubkey } from './wallet.js';
-import { encodeCompactU16, isOnEd25519Curve } from './transfer.js';
+import { encodeCompactU16, deriveATA as _deriveATA } from './transfer.js';
 
 // ============= Constants =============
 
@@ -13,7 +13,6 @@ const TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
 const _TOKEN_2022_PROGRAM = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
 const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
 const MEMO_PROGRAM = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';
-const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
 const _SYSTEM_PROGRAM = '11111111111111111111111111111111';
 
 const DEFAULT_COMPUTE_UNIT_LIMIT = 20000;
@@ -23,29 +22,10 @@ const DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS = 1;
 
 /**
  * Derive Associated Token Account (ATA) address.
- * PDA seeds: [owner, tokenProgram, mint] with ATA program.
+ * Returns base58-encoded PDA. Delegates algorithm to transfer.js.
  */
 export function deriveATA(ownerBase58, mintBase58, tokenProgramBase58 = TOKEN_PROGRAM) {
-  const owner = base58DecodePubkey(ownerBase58);
-  const tokenProgram = base58DecodePubkey(tokenProgramBase58);
-  const mint = base58DecodePubkey(mintBase58);
-  const ataProgramKey = base58DecodePubkey(ATA_PROGRAM);
-
-  // find_program_address: try nonce 255 down to 0
-  // PDA = SHA256(seeds... || programId || "ProgramDerivedAddress")
-  // A valid PDA must NOT be on the ed25519 curve.
-  // Checking on-curve in pure JS without a full ed25519 implementation is hard.
-  // We use the mathematical approach: decode y-coordinate, compute x², check QR.
-  for (let nonce = 255; nonce >= 0; nonce--) {
-    const hash = crypto.createHash('sha256')
-      .update(Buffer.concat([owner, tokenProgram, mint, Buffer.from([nonce]), ataProgramKey, Buffer.from('ProgramDerivedAddress')]))
-      .digest();
-
-    if (!isOnEd25519Curve(hash)) {
-      return base58Encode(hash);
-    }
-  }
-  throw new Error('Could not derive ATA: no valid PDA found');
+  return base58Encode(_deriveATA(ownerBase58, mintBase58, tokenProgramBase58));
 }
 
 // ============= MessageV0 Builder =============