nansen-cli 1.25.1 → 1.26.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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
+
+- [#380](https://github.com/nansen-ai/nansen-cli/pull/380) [`12e4e25`](https://github.com/nansen-ai/nansen-cli/commit/12e4e25d50f50ff1ebbae160ba1016abd1cdbb4d) Thanks [@TimNooren](https://github.com/TimNooren)! - Add `--amount-unit percent` to trade commands, allowing trades as a percentage of wallet balance (e.g. `--amount 100 --amount-unit percent` to sell all)
+
+### Patch Changes
+
+- [#382](https://github.com/nansen-ai/nansen-cli/pull/382) [`d9c87ef`](https://github.com/nansen-ai/nansen-cli/commit/d9c87ef9df51a3e9c53ea59674ad9efe9aa33fb7) Thanks [@kome12](https://github.com/kome12)! - fix: default `profiler balance` chain to `'all'` instead of `'ethereum'`
+
+  Previously, `nansen profiler balance --address <addr>` without `--chain` defaulted to `ethereum`, returning empty results for wallets with no ETH mainnet holdings (e.g. Base-only or Solana-only wallets). Now defaults to `'all'`, letting the API auto-route based on address format.
+
 ## 1.25.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.25.1",
+  "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
  */
@@ -766,7 +789,7 @@ export class NansenAPI {
   // ============= Profiler Endpoints =============
 
   async addressBalance(params = {}) {
-    const { address, entityName, chain = 'ethereum', hideSpamToken = true, filters = {}, orderBy } = params;
+    const { address, entityName, chain = 'all', hideSpamToken = true, filters = {}, orderBy } = params;
     if (address) {
       const validation = validateAddress(address, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);

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
@@ -1110,7 +1102,7 @@ export function buildCommands(deps = {}) {
       const subcommand = args[0] || 'help';
       let address = options.address;
       const entityName = options.entity || options['entity-name'];
-      const chain = options.chain || 'ethereum';
+      const chain = options.chain || 'all';
 
       // Resolve ENS names (e.g. vitalik.eth → 0x...)
       let ensName;
@@ -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/schema.json

@@ -821,11 +821,11 @@
             "amount": {
               "type": "string",
               "required": true,
-              "description": "Amount to swap (base units by default, or token units with --amount-unit token, or USD with --amount-unit usd)"
+              "description": "Amount to swap (base units by default, or token units with --amount-unit token, USD with --amount-unit usd, or percentage of balance with --amount-unit percent)"
             },
             "amount-unit": {
               "type": "string",
-              "description": "\"token\" to specify amount in token units (e.g. 0.5 SOL), \"usd\" to specify amount in USD (e.g. 50), or \"base\" for base units (default). The CLI resolves the current token price and decimals locally; the API always receives base units."
+              "description": "\"token\" to specify amount in token units (e.g. 0.5 SOL), \"usd\" to specify amount in USD (e.g. 50), \"percent\" to sell a percentage of your balance (e.g. 100 for all), or \"base\" for base units (default). The CLI resolves the current token price, decimals, and balance locally; the API always receives base units."
             },
             "wallet": {
               "type": "string",

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;
@@ -210,6 +211,91 @@ export async function validateBalance({ chain, from, amount, amountUnit, walletA
   return { adjustedAmount: amount };
 }
 
+/**
+ * Resolve a percentage amount to a token-unit amount string.
+ * Fetches the wallet's balance of the sell token, calculates the percentage,
+ * and applies a native-token fee buffer when selling >=95%.
+ *
+ * Returns the amount in human-readable token units (e.g. "1.5"),
+ * ready for convertToBaseUnits().
+ */
+export async function resolvePercentAmount({ chain, from, walletAddress, percentage, decimals }) {
+  if (!Number.isFinite(percentage) || percentage <= 0 || percentage > 100) {
+    throw new Error(
+      percentage > 100
+        ? `Cannot sell more than 100% of balance. Got: ${percentage}%`
+        : `Percentage must be between 0 and 100. Got: ${percentage}%`
+    );
+  }
+
+  const normalizedChain = chain.toLowerCase();
+  const isNative = isNativeAddress(from, normalizedChain);
+
+  let balance;
+  if (isNative) {
+    balance = await fetchNativeBalance(normalizedChain, walletAddress);
+  } else {
+    balance = await fetchTokenBalance(normalizedChain, from, walletAddress, decimals);
+  }
+
+  if (balance === null) {
+    throw new Error(`Could not fetch balance for ${from} on ${normalizedChain}. Check your RPC connection.`);
+  }
+  if (balance === 0) {
+    const symbol = isNative ? (NATIVE_SYMBOLS[normalizedChain] || from) : from;
+    throw new Error(`No ${symbol} balance in wallet. You cannot trade a token you don't own.`);
+  }
+
+  // Calculate token amount from percentage.
+  // Use exact balance for 100% to avoid floating-point precision loss.
+  let tokenAmount = percentage === 100 ? balance : balance * (percentage / 100);
+
+  // Native token fee buffer: when selling >=95%, cap at balance - reserve.
+  if (isNative && percentage >= HIGH_PERCENTAGE_THRESHOLD) {
+    const reserve = FEE_BUFFER[normalizedChain] || 0;
+    const maxSellable = parseFloat((balance - reserve).toFixed(NATIVE_DECIMALS[normalizedChain]));
+    if (maxSellable <= 0) {
+      const symbol = NATIVE_SYMBOLS[normalizedChain] || from;
+      throw new Error(`Insufficient ${symbol} balance after reserving gas fees.`);
+    }
+    if (tokenAmount > maxSellable) {
+      const symbol = NATIVE_SYMBOLS[normalizedChain] || from;
+      process.stderr.write(
+        `Warning: Reserving ${reserve} ${symbol} for gas. Adjusted sell amount to ${maxSellable} ${symbol}.\n`
+      );
+      tokenAmount = maxSellable;
+    }
+  }
+
+  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 } 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:
@@ -975,7 +978,7 @@ OPTIONS:
   --from <symbol|address>   Input token (symbol like SOL, USDC or address)
   --to <symbol|address>     Output token (symbol like USDC, ETH or address)
   --amount <units>          Amount in BASE UNITS (e.g. lamports, wei)
-  --amount-unit <unit>      "token" for token units (e.g. 0.5 SOL), "usd" for USD (e.g. 50)
+  --amount-unit <unit>      "token" for token units, "usd" for USD, "percent" for % of balance
   --wallet <name>           Wallet name (default: default wallet). Use "walletconnect" or "wc" for WalletConnect.
   --to-wallet <address>     Destination wallet address (auto-derived for cross-chain if omitted)
   --slippage <pct>          Slippage as decimal (e.g. 0.03 for 3%). Default: 0.03
@@ -987,19 +990,21 @@ EXAMPLES:
   nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
   nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token
   nansen trade quote --chain solana --from SOL --to USDC --amount 50 --amount-unit usd
+  nansen trade quote --chain solana --from SOL --to USDC --amount 100 --amount-unit percent
   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') {
-        log(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base, usd`);
-        exit(1);
-        return;
+      if (amountUnit && amountUnit !== 'token' && amountUnit !== 'base' && amountUnit !== 'usd' && amountUnit !== 'percent') {
+        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') {
+        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,
@@ -1007,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.
@@ -1028,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 {
@@ -1038,16 +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');
         }
       }
 
@@ -1063,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);
@@ -1091,9 +1088,25 @@ 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.
+        // Placed after wallet resolution because we need the wallet address to fetch balance.
+        if (amountUnit === 'percent') {
+          try {
+            resolvedDecimals = await resolveTokenDecimals(from, chain);
+            const tokenAmount = await resolvePercentAmount({
+              chain,
+              from,
+              walletAddress,
+              percentage: parseFloat(amount),
+              decimals: resolvedDecimals,
+            });
+            resolvedAmount = convertToBaseUnits(tokenAmount, resolvedDecimals);
+          } catch (err) {
+            throw new CommandError(`Error: ${err.message}`, 'INVALID_INPUT');
+          }
         }
 
         // Balance pre-check — catches zero balances and insufficient funds
@@ -1118,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');
           }
         }
 
@@ -1167,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}`);
@@ -1195,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');
       }
     },
 
@@ -1211,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'
@@ -1220,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 {
@@ -1234,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)
@@ -1247,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
@@ -1271,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;
+              });
             }
           }
 
@@ -1290,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);
@@ -1300,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
@@ -1310,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');
           }
         }
 
@@ -1675,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!`);
@@ -1866,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');
                 }
               }
 
@@ -1924,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');
       }
     },
 
@@ -1942,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.
 
@@ -1953,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 {
@@ -1980,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/transfer.js

@@ -559,8 +559,7 @@ async function broadcastTransaction(signedTx, chain) {
 
 // ============= Public API =============
 
-// Exported for testing
-export { parseAmount, formatAmount, signEd25519, encodeCompactU16, base58Decode, base58DecodePubkey, deriveATA, validateEvmAddress, validateSolanaAddress, bigIntToHex };
+export { parseAmount, formatAmount, signEd25519, encodeCompactU16, base58Decode, base58DecodePubkey, deriveATA, isOnEd25519Curve, validateEvmAddress, validateSolanaAddress, bigIntToHex };
 
 /**
  * Send tokens via Privy server wallet. EVM uses Privy's sendTransaction (handles gas/nonce).

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 } 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,81 +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 (!isOnCurve(hash)) {
-      return base58Encode(hash);
-    }
-  }
-  throw new Error('Could not derive ATA: no valid PDA found');
-}
-
-/**
- * Check if a 32-byte buffer represents a valid ed25519 curve point.
- * Ed25519 curve: -x² + y² = 1 + d*x²*y²  over GF(p) where p = 2^255 - 19
- * 
- * Decode y from the 32 bytes, compute x² = (y² - 1) / (d*y² + 1),
- * then check if x² is a quadratic residue (QR) mod p.
- */
-function isOnCurve(bytes) {
-  const p = (1n << 255n) - 19n;
-  const d = -121665n * modInverse(121666n, p) % p;
-
-  // Read y-coordinate (little-endian, clear top bit which is sign of x)
-  let y = 0n;
-  for (let i = 0; i < 32; i++) {
-    y |= BigInt(bytes[i]) << (BigInt(i) * 8n);
-  }
-  y &= (1n << 255n) - 1n; // Clear top bit
-
-  if (y >= p) return false;
-
-  // y² mod p
-  const y2 = modPow(y, 2n, p);
-  
-  // x² = (y² - 1) * inverse(d*y² + 1) mod p
-  const num = ((y2 - 1n) % p + p) % p;
-  const den = ((d * y2 + 1n) % p + p) % p;
-  const denInv = modInverse(den, p);
-  if (denInv === null) return false;
-  
-  const x2 = (num * denInv) % p;
-  
-  // Check if x² is a quadratic residue: x^((p-1)/2) == 1 mod p
-  if (x2 === 0n) return true;
-  const euler = modPow(x2, (p - 1n) / 2n, p);
-  return euler === 1n;
-}
-
-function modPow(base, exp, mod) {
-  let result = 1n;
-  base = ((base % mod) + mod) % mod;
-  while (exp > 0n) {
-    if (exp & 1n) result = (result * base) % mod;
-    exp >>= 1n;
-    base = (base * base) % mod;
-  }
-  return result;
-}
-
-function modInverse(a, mod) {
-  return modPow(((a % mod) + mod) % mod, mod - 2n, mod);
+  return base58Encode(_deriveATA(ownerBase58, mintBase58, tokenProgramBase58));
 }
 
 // ============= MessageV0 Builder =============