nansen-cli 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.24.0
+
+### Minor Changes
+
+- [#333](https://github.com/nansen-ai/nansen-cli/pull/333) [`c8fe79c`](https://github.com/nansen-ai/nansen-cli/commit/c8fe79c4ec5e1ba6acf2498d9bfbe14c726a913c) Thanks [@imhta](https://github.com/imhta)! - Add cross-chain swap support between Solana and Base via Li.Fi bridge.
+
+  `nansen trade quote --chain base --to-chain solana --from ETH --to SOL --amount 0.01 --amount-unit token`
+  `nansen trade execute --quote <id>`
+
+  Bridge status can be checked with `nansen trade bridge-status`.
+
+### Patch Changes
+
+- [#365](https://github.com/nansen-ai/nansen-cli/pull/365) [`56335af`](https://github.com/nansen-ai/nansen-cli/commit/56335af600e51436b30ad2fc1530aa754bac2a2f) Thanks [@TimNooren](https://github.com/TimNooren)! - Add balance pre-check before quote API calls. Validates sell token balance, auto-adjusts near-full-balance trades (≤2% over), and reserves gas fees for native token swaps (SOL/ETH).
+
+## 1.23.1
+
+### Patch Changes
+
+- [#361](https://github.com/nansen-ai/nansen-cli/pull/361) [`ff22da3`](https://github.com/nansen-ai/nansen-cli/commit/ff22da376c1072ef06e84054f6ee31c058e6e08c) Thanks [@TimNooren](https://github.com/TimNooren)! - fix(alerts): error when --webhook-secret is passed without --webhook
+
+  Previously, passing --webhook-secret with a non-webhook channel (e.g. --telegram)
+  silently discarded the secret with no warning. The alert was created successfully
+  but without any signing, giving the false impression that the secret was active.
+
+  Now throws an actionable error: "--webhook-secret requires --webhook".
+
+- [#358](https://github.com/nansen-ai/nansen-cli/pull/358) [`70ee712`](https://github.com/nansen-ai/nansen-cli/commit/70ee71205343fb2d003eb5f50144e266bdc6109e) Thanks [@TimNooren](https://github.com/TimNooren)! - Add pre-quote trade input validation: rejects same-token swaps, invalid address formats, and non-positive amounts before any network call.
+
 ## 1.23.0
 
 ### Minor Changes

package/README.md

@@ -36,7 +36,7 @@ nansen schema [command] [--pretty]    # full command reference (no API key neede
 
 **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`, `points`
 
-**Trade:** `quote`, `execute` — DEX swaps on Solana and Base.
+**Trade:** `quote`, `execute`, `bridge-status` — DEX swaps on Solana and Base, including cross-chain bridges.
 
 **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local or Privy server-side wallets (EVM + Solana).
 

package/package.json

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

package/skills/nansen-trading/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nansen-trading
-description: Execute DEX swaps on Solana or Base. Use when buying or selling a token, getting a swap quote, or executing a trade.
+description: Execute DEX swaps on Solana or Base, including cross-chain bridges. Use when buying or selling a token, getting a swap quote, or executing a trade.
 metadata:
   openclaw:
     requires:
@@ -41,6 +41,31 @@ Symbols resolve automatically: `SOL`, `ETH`, `USDC`, `USDT`, `WETH`. Raw address
 nansen trade execute --quote <quote-id>
 ```
 
+## Cross-Chain Swap
+
+Bridge tokens between Solana and Base using `--to-chain`:
+
+```bash
+nansen trade quote \
+  --chain base \
+  --to-chain solana \
+  --from USDC \
+  --to USDC \
+  --amount 1000000
+```
+
+For Solana↔Base bridges, the destination wallet address is auto-derived from your wallet (which stores both EVM and Solana keys). Override with `--to-wallet <address>` if needed.
+
+Note: you need gas on the **source** chain to submit the initial transaction (e.g. SOL for Solana→Base, ETH for Base→Solana).
+
+## Bridge Status
+
+After executing a cross-chain swap, the CLI polls bridge status automatically. To check manually:
+
+```bash
+nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
+```
+
 ## Agent pattern
 
 ```bash
@@ -81,15 +106,19 @@ If the user says "$20 worth of X", you must convert USD → token amount, then e
 
 | Flag | Purpose |
 |------|---------|
-| `--chain` | `solana` or `base` |
+| `--chain` | Source chain: `solana` or `base` |
+| `--to-chain` | Destination chain for cross-chain swap (omit for same-chain) |
 | `--from` | Source token (symbol or address) |
-| `--to` | Destination token (symbol or address) |
+| `--to` | Destination token (symbol or address, resolved against destination chain) |
 | `--amount` | Amount in base units (integer), or token units with `--amount-unit token` |
 | `--amount-unit` | Set to `token` to specify amount in token units (e.g. 0.5 SOL) |
 | `--wallet` | Wallet name (default: default wallet) |
+| `--to-wallet` | Destination wallet address (auto-derived for cross-chain if omitted) |
 | `--slippage` | Slippage tolerance as decimal (e.g. 0.03) |
 | `--quote` | Quote ID for execute |
 | `--no-simulate` | Skip pre-broadcast simulation |
+| `--tx-hash` | Source tx hash (for bridge-status) |
+| `--from-chain` | Source chain (for bridge-status) |
 
 ## Environment Variables
 

package/src/cli.js

@@ -1447,18 +1447,22 @@ export function buildCommands(deps = {}) {
       log(`nansen trade — DEX trading commands
 
 SUBCOMMANDS:
-  quote       Get a swap quote (price, route, fees)
-  execute     Sign and broadcast a quoted swap
+  quote          Get a swap quote (price, route, fees)
+  execute        Sign and broadcast a quoted swap
+  bridge-status  Check cross-chain bridge transaction status
 
 USAGE:
   nansen trade quote --chain <chain> --from <token> --to <token> --amount <units> [--wallet <name>]
+  nansen trade quote --chain <chain> --to-chain <chain> --from <token> --to <token> --amount <units>
   nansen trade execute --quote <quoteId> [--wallet <name>]
+  nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
 
 EXAMPLES:
   nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
   nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
-  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000 --wallet walletconnect
+  nansen trade quote --chain base --to-chain solana --from USDC --to USDC --amount 1000000
   nansen trade execute --quote 1708900000000-abc123
+  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana
 
 WALLET:
   --wallet <name>   Use a named wallet, or "walletconnect" / "wc" for WalletConnect (EVM only).
@@ -1470,7 +1474,7 @@ SYMBOLS:
       return;
     }
     if (!tradingCmds[sub]) {
-      throw new NansenError(`Unknown trade subcommand: ${sub}. Available: quote, execute`, ErrorCode.UNKNOWN);
+      throw new NansenError(`Unknown trade subcommand: ${sub}. Available: quote, execute, bridge-status`, ErrorCode.UNKNOWN);
     }
     return tradingCmds[sub](args.slice(1), apiInstance, flags, options);
   };

package/src/commands/alerts.js

@@ -560,8 +560,11 @@ USAGE:
         return;
       }
 
-      // Build channels array from --telegram/--slack/--discord flags
+      // Build channels array from --telegram/--slack/--discord/--webhook flags
       function buildChannels() {
+        if (options["webhook-secret"] && !options.webhook) {
+          throw new NansenError('--webhook-secret requires --webhook', ErrorCode.INVALID_PARAMS);
+        }
         const channels = [];
         if (options.telegram) channels.push({ type: 'telegram', data: { chatId: String(options.telegram) } });
         if (options.slack) channels.push({ type: 'slack', data: { webhookUrl: options.slack } });

package/src/schema.json

@@ -772,12 +772,16 @@
       "description": "DEX trading commands",
       "subcommands": {
         "quote": {
-          "description": "Get a DEX swap quote (chain, tokens, amount)",
+          "description": "Get a DEX swap quote (same-chain or cross-chain)",
           "options": {
             "chain": {
               "type": "string",
               "default": "base",
-              "description": "Blockchain (solana or base)"
+              "description": "Source blockchain (solana or base)"
+            },
+            "to-chain": {
+              "type": "string",
+              "description": "Destination blockchain for cross-chain swap (solana or base). Omit for same-chain."
             },
             "from": {
               "type": "string",
@@ -787,7 +791,7 @@
             "to": {
               "type": "string",
               "required": true,
-              "description": "Token to buy (address or symbol)"
+              "description": "Token to buy (address or symbol, resolved against destination chain for cross-chain)"
             },
             "amount": {
               "type": "string",
@@ -801,6 +805,10 @@
             "wallet": {
               "type": "string",
               "description": "Wallet name (or \"walletconnect\"/\"wc\" for WalletConnect, EVM only). A configured wallet is required \u2014 run `nansen wallet create` if you haven't set one up yet."
+            },
+            "to-wallet": {
+              "type": "string",
+              "description": "Destination wallet address for cross-chain swaps. Auto-derived from wallet if omitted."
             }
           },
           "prerequisites": [
@@ -820,6 +828,26 @@
               "description": "Wallet name, or \"walletconnect\"/\"wc\" for WalletConnect (EVM only)"
             }
           }
+        },
+        "bridge-status": {
+          "description": "Check cross-chain bridge transaction status",
+          "options": {
+            "tx-hash": {
+              "type": "string",
+              "required": true,
+              "description": "Source chain transaction hash"
+            },
+            "from-chain": {
+              "type": "string",
+              "required": true,
+              "description": "Source chain (solana or base)"
+            },
+            "to-chain": {
+              "type": "string",
+              "required": true,
+              "description": "Destination chain (solana or base)"
+            }
+          }
         }
       }
     },

package/src/trade-validation.js

@@ -0,0 +1,270 @@
+/**
+ * Trade input validation for the Nansen CLI.
+ * Catches common agent errors (wrong addresses, same-token swaps,
+ * bad amounts) before any network call.
+ */
+
+import { validateAddress } from './api.js';
+import { CHAIN_RPCS } from './rpc-urls.js';
+
+const SUPPORTED_CHAINS = ['solana', 'base'];
+
+/**
+ * Validate quote inputs before any network call.
+ * Throws on validation failure with an actionable error message.
+ */
+export function validateQuoteInput({ chain, toChain, from, to, amount }) {
+  // 1. Chain must be supported
+  const normalizedChain = chain?.toLowerCase();
+  if (!SUPPORTED_CHAINS.includes(normalizedChain)) {
+    throw new Error(
+      `Unsupported chain "${chain}". Supported chains: ${SUPPORTED_CHAINS.join(', ')}.`
+    );
+  }
+
+  const normalizedToChain = toChain ? toChain.toLowerCase() : normalizedChain;
+  if (toChain && !SUPPORTED_CHAINS.includes(normalizedToChain)) {
+    throw new Error(
+      `Unsupported destination chain "${toChain}". Supported chains: ${SUPPORTED_CHAINS.join(', ')}.`
+    );
+  }
+
+  // 2. Amount must be a positive finite number
+  const numAmount = Number(amount);
+  if (!Number.isFinite(numAmount) || numAmount <= 0) {
+    throw new Error(
+      `Invalid amount "${amount}". Must be a positive number.`
+    );
+  }
+
+  // 3. Token address format must match the chain (reuses api.js validateAddress)
+  const fromResult = validateAddress(from, normalizedChain);
+  if (!fromResult.valid) {
+    throw new Error(
+      `Invalid sell token address for ${normalizedChain}. ${fromResult.error}`
+    );
+  }
+  const toResult = validateAddress(to, normalizedToChain);
+  if (!toResult.valid) {
+    throw new Error(
+      `Invalid buy token address for ${normalizedToChain}. ${toResult.error}`
+    );
+  }
+
+  // 4. Sell and buy token must be different (only applies to same-chain swaps)
+  if (normalizedChain === normalizedToChain) {
+    const fromNorm = normalizedChain === 'solana' ? from : from.toLowerCase();
+    const toNorm = normalizedChain === 'solana' ? to : to.toLowerCase();
+    if (fromNorm === toNorm) {
+      throw new Error(
+        `Cannot swap ${from} for itself. Sell and buy tokens must be different.`
+      );
+    }
+  }
+}
+
+// Native token decimals per chain (for converting balance from base units)
+const NATIVE_DECIMALS = { solana: 9, base: 18 };
+
+/**
+ * Fetch the native token balance (ETH or SOL) for a wallet.
+ * Returns balance in human-readable token units (e.g. 1.5 ETH), or null on RPC failure.
+ *
+ * Uses Number (not BigInt) for the result — acceptable precision loss for a
+ * best-effort pre-check with 2% tolerance. Transaction amounts use BigInt elsewhere.
+ */
+export async function fetchNativeBalance(chain, walletAddress) {
+  try {
+    const rpcUrl = CHAIN_RPCS[chain];
+    if (!rpcUrl) return null;
+
+    const chainType = chain === 'solana' ? 'solana' : 'evm';
+
+    if (chainType === 'evm') {
+      const res = await fetch(rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_getBalance', params: [walletAddress, 'latest'] }),
+      });
+      const body = await res.json();
+      if (body.error || body.result === undefined) return null;
+      const wei = BigInt(body.result);
+      return Number(wei) / 10 ** NATIVE_DECIMALS[chain];
+    }
+
+    // Solana — getBalance returns { value: <lamports> }
+    const res = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getBalance', params: [walletAddress] }),
+    });
+    const body = await res.json();
+    if (body.error || body.result?.value === undefined) return null;
+    return body.result.value / 10 ** NATIVE_DECIMALS[chain];
+  } catch {
+    return null;
+  }
+}
+
+// Addresses that represent native tokens (SOL, ETH) — not ERC-20/SPL contracts.
+const NATIVE_TOKEN_ADDRESSES = {
+  solana: 'So11111111111111111111111111111111111111112',
+  base: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+};
+
+// Native token symbols for error messages.
+const NATIVE_SYMBOLS = { solana: 'SOL', base: 'ETH' };
+
+const FEE_BUFFER = { solana: 0.005, base: 0.00004 };
+const HIGH_PERCENTAGE_THRESHOLD = 95;
+const AUTO_ADJUST_THRESHOLD_PERCENT = 2;
+
+/**
+ * Check if an address is the native token for a chain (case-insensitive for EVM).
+ */
+function isNativeAddress(address, chain) {
+  const native = NATIVE_TOKEN_ADDRESSES[chain];
+  if (!native) return false;
+  if (chain === 'solana') return address === native;
+  return address.toLowerCase() === native.toLowerCase();
+}
+
+/**
+ * Validate that the wallet has sufficient balance of the sell token.
+ * Only applies when amountUnit is 'token' (human-readable amounts).
+ *
+ * Returns { adjustedAmount } — may differ from input if auto-adjusted
+ * to 100% of balance (when amount exceeds balance by ≤2%).
+ *
+ * Throws on validation failure. Returns without action if RPC fails (best-effort).
+ */
+export async function validateBalance({ chain, from, amount, amountUnit, walletAddress, decimals, symbol: callerSymbol }) {
+  // Only validate when amount is in token units — we can compare directly.
+  if (amountUnit !== 'token') return { adjustedAmount: amount };
+
+  const normalizedChain = chain.toLowerCase();
+  const isNative = isNativeAddress(from, normalizedChain);
+  const symbol = callerSymbol
+    || (isNative ? NATIVE_SYMBOLS[normalizedChain] : null)
+    || from;
+
+  let balance;
+  if (isNative) {
+    balance = await fetchNativeBalance(normalizedChain, walletAddress);
+  } else {
+    if (decimals === undefined) return { adjustedAmount: amount };
+    balance = await fetchTokenBalance(normalizedChain, from, walletAddress, decimals);
+  }
+
+  // Best-effort: if RPC failed, proceed without validation.
+  if (balance === null) return { adjustedAmount: amount };
+
+  // Check 1: wallet must hold the token
+  if (balance === 0) {
+    throw new Error(
+      `No ${symbol} balance in wallet. You cannot trade a token you don't own.`
+    );
+  }
+
+  // Check 2: amount vs balance
+  let numAmount = Number(amount);
+  if (numAmount > balance) {
+    const excessPercent = ((numAmount - balance) / balance) * 100;
+    if (excessPercent > AUTO_ADJUST_THRESHOLD_PERCENT) {
+      throw new Error(
+        `Insufficient balance. You have ${balance} ${symbol} but the trade requires ${amount} ${symbol}.`
+      );
+    }
+    // Auto-adjust to 100% of balance
+    const adjustedAmount = String(balance);
+    numAmount = balance;
+    process.stderr.write(
+      `Warning: Amount ${amount} exceeds balance ${balance}. Auto-adjusting to ${adjustedAmount} ${symbol}.\n`
+    );
+    if (!isNative) return { adjustedAmount };
+    // Native tokens fall through to the fee buffer check below — selling 100%
+    // of a native balance still needs a gas reserve applied.
+  }
+
+  // Check 3: native token fee buffer when selling ≥95% of balance
+  if (isNative) {
+    const percentOfBalance = (numAmount / balance) * 100;
+    if (percentOfBalance >= HIGH_PERCENTAGE_THRESHOLD) {
+      const reserve = FEE_BUFFER[normalizedChain] || 0;
+      const maxSellable = parseFloat((balance - reserve).toFixed(NATIVE_DECIMALS[normalizedChain]));
+      if (maxSellable <= 0) {
+        throw new Error(
+          `Insufficient ${symbol} balance after reserving gas fees.`
+        );
+      }
+      if (numAmount > maxSellable) {
+        const adjustedAmount = String(maxSellable);
+        process.stderr.write(
+          `Warning: Reserving ${reserve} ${symbol} for gas. Adjusted sell amount to ${adjustedAmount} ${symbol}.\n`
+        );
+        return { adjustedAmount };
+      }
+    }
+  }
+
+  return { adjustedAmount: amount };
+}
+
+/**
+ * Fetch an ERC-20 or SPL token balance for a wallet.
+ * Returns balance in human-readable token units, or null on RPC failure.
+ * Requires `decimals` to convert from base units.
+ *
+ * Uses Number (not BigInt) for the result — see fetchNativeBalance note on precision.
+ */
+export async function fetchTokenBalance(chain, tokenAddress, walletAddress, decimals) {
+  try {
+    const rpcUrl = CHAIN_RPCS[chain];
+    if (!rpcUrl) return null;
+
+    const chainType = chain === 'solana' ? 'solana' : 'evm';
+
+    if (chainType === 'evm') {
+      // balanceOf(address) selector = 0x70a08231, address padded to 32 bytes
+      const paddedAddress = walletAddress.replace('0x', '').toLowerCase().padStart(64, '0');
+      const data = '0x70a08231' + paddedAddress;
+      const res = await fetch(rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_call', params: [{ to: tokenAddress, data }, 'latest'] }),
+      });
+      const body = await res.json();
+      if (body.error || !body.result) return null;
+      const raw = BigInt(body.result);
+      return Number(raw) / 10 ** decimals;
+    }
+
+    // Solana — getTokenAccountsByOwner with the mint filter
+    const res = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0', id: 1,
+        method: 'getTokenAccountsByOwner',
+        params: [
+          walletAddress,
+          { mint: tokenAddress },
+          { encoding: 'jsonParsed' },
+        ],
+      }),
+    });
+    const body = await res.json();
+    if (body.error) return null;
+    const accounts = body.result?.value || [];
+    if (accounts.length === 0) return 0;
+    // Sum across all token accounts for this mint (rare but possible)
+    let total = 0n;
+    for (const acct of accounts) {
+      const amount = acct.account?.data?.parsed?.info?.tokenAmount?.amount;
+      if (amount) total += BigInt(amount);
+    }
+    return Number(total) / 10 ** decimals;
+  } catch {
+    return null;
+  }
+}

package/src/trading.js

@@ -13,6 +13,7 @@ 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 { CHAIN_RPCS } from './rpc-urls.js';
 
 // ============= Constants =============
@@ -20,8 +21,8 @@ import { CHAIN_RPCS } from './rpc-urls.js';
 const TRADING_API_URL = process.env.NANSEN_TRADING_API_URL || 'https://trading-api.nansen.ai';
 
 const CHAIN_MAP = {
-  solana:   { index: '501', type: 'solana', chainId: 501,  name: 'Solana',   explorer: 'https://solscan.io/tx/' },
-  base:     { index: '8453', type: 'evm',   chainId: 8453, name: 'Base',     explorer: 'https://basescan.org/tx/' },
+  solana:   { index: '501', type: 'solana', chainId: 501,  name: 'Solana',   explorer: 'https://solscan.io/tx/', lifiChainId: '1151111081099710' },
+  base:     { index: '8453', type: 'evm',   chainId: 8453, name: 'Base',     explorer: 'https://basescan.org/tx/', lifiChainId: '8453' },
 };
 
 // Extend when adding new EVM chains (e.g. arbitrum WETH, polygon WMATIC)
@@ -198,13 +199,93 @@ export async function executeTransaction(params, { retries = 2, retryDelayMs = 1
   throw lastError;
 }
 
+// ============= Bridge Status =============
+
+/**
+ * Check the status of a cross-chain bridge transaction.
+ * @param {string} txHash - Source chain transaction hash
+ * @param {string} fromChain - Source chain name (e.g. 'base')
+ * @param {string} toChain - Destination chain name (e.g. 'solana')
+ * @returns {Promise<object>} Bridge status
+ */
+export async function getBridgeStatus(txHash, fromChain, toChain) {
+  const fromConfig = resolveChain(fromChain);
+  const toConfig = resolveChain(toChain);
+  const url = new URL('/bridge/status', TRADING_API_URL);
+  url.searchParams.set('txHash', txHash);
+  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 text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw Object.assign(
+      new Error(`Bridge status API returned non-JSON response (status ${res.status}).`),
+      { code: 'BRIDGE_STATUS_ERROR', status: res.status, details: text.slice(0, 200) }
+    );
+  }
+  if (!res.ok) {
+    throw Object.assign(
+      new Error(body.message || `Bridge status check failed with status ${res.status}`),
+      { code: body.code || 'BRIDGE_STATUS_ERROR', status: res.status, details: body.details }
+    );
+  }
+  return body;
+}
+
+/**
+ * Poll bridge status until completion or timeout.
+ * @param {string} txHash - Source chain transaction hash
+ * @param {string} fromChain - Source chain name
+ * @param {string} toChain - Destination chain name
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=600000] - Timeout (default 10 min)
+ * @param {number} [opts.pollMs=10000] - Poll interval (default 10s)
+ * @param {Function} [opts.log=console.log] - Logger
+ * @returns {Promise<object>} Final bridge status
+ */
+export async function pollBridgeStatus(txHash, fromChain, toChain, { timeoutMs = 600000, pollMs = 10000, log = console.log } = {}) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    let status;
+    try {
+      status = await getBridgeStatus(txHash, fromChain, toChain);
+    } catch (err) {
+      // Transient errors (502, 503, network failures) — retry after poll interval.
+      log(`  Bridge: poll error (${err.status || err.code || 'unknown'}) — retrying...`);
+      await new Promise(r => setTimeout(r, pollMs));
+      continue;
+    }
+    const sending = status.sending?.status || status.status || 'pending';
+    const receiving = status.receiving?.status || 'pending';
+    log(`  Bridge: ${sending} → ${receiving}`);
+
+    if (status.status === 'DONE' || status.receiving?.status === 'DONE') return status;
+    if (status.status === 'FAILED') {
+      throw Object.assign(
+        new Error(`Bridge failed: ${status.substatusMessage || 'unknown error'}`),
+        { code: 'BRIDGE_FAILED', details: status }
+      );
+    }
+
+    await new Promise(r => setTimeout(r, pollMs));
+  }
+  throw Object.assign(
+    new Error(`Bridge status polling timed out after ${timeoutMs / 1000}s. Check manually with: nansen trade bridge-status --tx-hash ${txHash} --from-chain ${fromChain} --to-chain ${toChain}`),
+    { code: 'BRIDGE_TIMEOUT' }
+  );
+}
+
 // ============= Quote Storage =============
 
 /**
  * Save a quote response to disk for later execution.
  * @returns {string} Quote ID
  */
-export function saveQuote(quoteResponse, chain, signerType = 'local', privyWalletIds = null) {
+export function saveQuote(quoteResponse, chain, signerType = 'local', privyWalletIds = null, toChain = null) {
   const dir = getQuotesDir();
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -215,6 +296,7 @@ export function saveQuote(quoteResponse, chain, signerType = 'local', privyWalle
   const quoteId = `${timestamp}-${hash}`;
 
   const data = { quoteId, chain, timestamp, signerType, response: quoteResponse };
+  if (toChain) data.toChain = toChain;
   if (privyWalletIds) data.privyWalletIds = privyWalletIds;
 
   fs.writeFileSync(path.join(dir, `${quoteId}.json`), JSON.stringify(data, null, 2), { mode: 0o600 });
@@ -807,6 +889,15 @@ export function formatQuote(quote, index) {
   if (quote.tradingFeeInUsd) lines.push(`    Trading Fee:  $${quote.tradingFeeInUsd}`);
   if (quote.networkFeeInUsd) lines.push(`    Network Fee:  $${quote.networkFeeInUsd}`);
   if (quote.approvalAddress && !isNativeToken(quote.inputMint)) lines.push(`    ⚠ Requires token approval to: ${quote.approvalAddress}`);
+  const meta = quote.metadata || {};
+  if (meta.isCrossChain) {
+    if (meta.bridgeTool) lines.push(`    Bridge:       ${meta.bridgeTool}`);
+    if (meta.executionDuration) lines.push(`    Est. Time:    ~${Math.round(meta.executionDuration / 60)} min`);
+    if (meta.feeCosts?.length) {
+      const totalFees = meta.feeCosts.reduce((sum, f) => sum + parseFloat(f.amountUSD || 0), 0);
+      if (totalFees > 0) lines.push(`    Bridge Fees:  $${totalFees.toFixed(2)}`);
+    }
+  }
   if (quote.priceImpactPct) {
     const impactAbs = Math.abs(parseFloat(quote.priceImpactPct));
     if (impactAbs > 5) {
@@ -827,12 +918,15 @@ export function buildTradingCommands(deps = {}) {
   return {
     'quote': async (args, apiInstance, flags, options) => {
       const chain = options.chain || args[0];
+      const toChainRaw = options['to-chain'];
       const fromRaw = options.from || options['from-token'] || args[1];
       const toRaw = options.to || options['to-token'] || args[2];
+      const effectiveToChain = toChainRaw || chain;
       const from = resolveTokenAddress(fromRaw, chain);
-      const to = resolveTokenAddress(toRaw, chain);
+      const to = resolveTokenAddress(toRaw, effectiveToChain);
       const amount = options.amount || args[3];
       const walletName = options.wallet;
+      const toWallet = options['to-wallet'];
       const slippage = options.slippage;
       const autoSlippage = flags['auto-slippage'];
       const maxAutoSlippage = options['max-auto-slippage'];
@@ -849,12 +943,14 @@ PREREQUISITE:
   Set one up with: nansen wallet create
 
 OPTIONS:
-  --chain <chain>           Chain: solana, base
+  --chain <chain>           Source chain: solana, base
+  --to-chain <chain>        Destination chain for cross-chain swap (e.g. solana, base)
   --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" to specify amount in token units (e.g. 0.5 SOL)
   --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
   --auto-slippage           Enable auto slippage calculation
   --max-auto-slippage <pct> Max auto slippage when auto-slippage enabled
@@ -864,7 +960,8 @@ 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 base --from ETH --to USDC --amount 1000000000000000000
-  nansen trade quote --chain solana --from So11111111111111111111111111111111111111112 --to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --amount 1000000000
+  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;
@@ -877,14 +974,25 @@ EXAMPLES:
         return;
       }
 
+      // Static input validation — catches common agent errors (wrong addresses,
+      // same-token swaps, bad amounts) before any network or wallet call.
+      try {
+        validateQuoteInput({ chain, toChain: toChainRaw || null, from, to, amount });
+      } catch (validationErr) {
+        log(`Error: ${validationErr.message}`);
+        exit(1);
+        return;
+      }
+
       // When --amount-unit token is used, resolve decimals and convert to base units.
       // Otherwise, validate that the amount is already in base units (integer).
       let resolvedAmount = amount;
+      let resolvedDecimals;
       if (amountUnit === 'token') {
         try {
           const tokenForDecimals = swapMode === 'exactOut' ? to : from;
-          const decimals = await resolveTokenDecimals(tokenForDecimals, chain);
-          resolvedAmount = convertToBaseUnits(amount, decimals);
+          resolvedDecimals = await resolveTokenDecimals(tokenForDecimals, chain);
+          resolvedAmount = convertToBaseUnits(amount, resolvedDecimals);
         } catch (err) {
           log(`Error resolving token decimals: ${err.message}`);
           exit(1);
@@ -944,7 +1052,39 @@ EXAMPLES:
           return;
         }
 
-        log(`\nFetching quote on ${chainConfig.name}...`);
+        // Balance pre-check — catches zero balances and insufficient funds
+        // before wasting a quote API call. Only runs for --amount-unit token
+        // in exactIn mode (in exactOut, the amount is the buy amount so
+        // comparing it against the sell token balance is meaningless).
+        if (amountUnit === 'token' && swapMode !== 'exactOut') {
+          try {
+            const { adjustedAmount: balanceAdjusted } = await validateBalance({
+              chain,
+              from,
+              amount,
+              amountUnit,
+              walletAddress,
+              decimals: resolvedDecimals,
+              symbol: fromRaw,
+            });
+            if (balanceAdjusted !== amount) {
+              resolvedAmount = convertToBaseUnits(balanceAdjusted, resolvedDecimals);
+            }
+          } catch (balanceErr) {
+            log(`Error: ${balanceErr.message}`);
+            exit(1);
+            return;
+          }
+        }
+
+        const toChainConfig = toChainRaw ? resolveChain(toChainRaw) : null;
+        const isCrossChain = toChainConfig && toChainConfig.index !== chainConfig.index;
+
+        if (isCrossChain) {
+          log(`\nFetching cross-chain quote: ${chainConfig.name} → ${toChainConfig.name}...`);
+        } else {
+          log(`\nFetching quote on ${chainConfig.name}...`);
+        }
         log(`  Wallet: ${walletAddress}`);
 
         const fromWarning = getWrappedNativeFromWarning(from, chain);
@@ -957,6 +1097,20 @@ EXAMPLES:
           amount: resolvedAmount,
           userWalletAddress: walletAddress,
         };
+        if (isCrossChain) {
+          params.toChainIndex = toChainConfig.index;
+          if (toWallet) {
+            params.toWalletAddress = toWallet;
+          } else if (chainConfig.type !== toChainConfig.type) {
+            // Solana↔Base: auto-derive the destination address from the same wallet
+            const effectiveWalletName = walletName || getWalletConfig()?.defaultWallet;
+            if (effectiveWalletName) {
+              const walletData = showWallet(effectiveWalletName);
+              params.toWalletAddress = toChainConfig.type === 'solana' ? walletData.solana : walletData.evm;
+              log(`  Destination wallet: ${params.toWalletAddress}`);
+            }
+          }
+        }
         if (slippage) params.slippagePercent = slippage;
         if (autoSlippage) params.autoSlippage = true;
         if (maxAutoSlippage) params.maxAutoSlippagePercent = maxAutoSlippage;
@@ -977,7 +1131,7 @@ EXAMPLES:
         response.quotes.forEach((q, i) => log(formatQuote(q, i)));
 
         const signerType = isWalletConnect ? 'walletconnect' : walletProvider;
-        const quoteId = saveQuote(response, chain, signerType, privyWalletIds);
+        const quoteId = saveQuote(response, chain, signerType, privyWalletIds, isCrossChain ? toChainRaw : null);
         log(`\n  Quote ID: ${quoteId}`);
         log(`  Execute:  nansen trade execute --quote ${quoteId}`);
         if (response.quotes.length > 1) {
@@ -1481,6 +1635,23 @@ EXAMPLES:
                 log(`    Tx Hash:   ${wcResult.txHash}`);
                 log(`    Chain:       ${chainConfig.name}`);
                 log(`    Explorer:    ${chainConfig.explorer}${wcResult.txHash}`);
+
+                // Cross-chain: poll bridge status after source tx success
+                if (quoteData.toChain && quoteData.toChain !== quoteData.chain) {
+                  log(`\n  Cross-chain bridge in progress (${chainConfig.name} → ${resolveChain(quoteData.toChain).name})...`);
+                  try {
+                    const bridgeResult = await pollBridgeStatus(wcResult.txHash, quoteData.chain, quoteData.toChain, { log });
+                    log(`\n  ✓ Bridge completed!`);
+                    if (bridgeResult.receiving?.txHash) {
+                      const toChainConfig = resolveChain(quoteData.toChain);
+                      log(`    Destination tx: ${toChainConfig.explorer}${bridgeResult.receiving.txHash}`);
+                    }
+                  } catch (bridgeErr) {
+                    log(`\n  Bridge status: ${bridgeErr.message}`);
+                    log(`  Check later with: nansen trade bridge-status --tx-hash ${wcResult.txHash} --from-chain ${quoteData.chain} --to-chain ${quoteData.toChain}`);
+                  }
+                }
+
                 log('');
                 return undefined; // Success
               }
@@ -1667,6 +1838,23 @@ EXAMPLES:
                   log(`      ${e.inputAmount} ${e.inputMint?.slice(0, 8)}... → ${e.outputAmount} ${e.outputMint?.slice(0, 8)}...`);
                 });
               }
+
+              // Cross-chain: poll bridge status after source tx success
+              if (quoteData.toChain && quoteData.toChain !== quoteData.chain) {
+                log(`\n  Cross-chain bridge in progress (${chainConfig.name} → ${resolveChain(quoteData.toChain).name})...`);
+                try {
+                  const bridgeResult = await pollBridgeStatus(txId, quoteData.chain, quoteData.toChain, { log });
+                  log(`\n  ✓ Bridge completed!`);
+                  if (bridgeResult.receiving?.txHash) {
+                    const toChainConfig = resolveChain(quoteData.toChain);
+                    log(`    Destination tx: ${toChainConfig.explorer}${bridgeResult.receiving.txHash}`);
+                  }
+                } catch (bridgeErr) {
+                  log(`\n  Bridge status: ${bridgeErr.message}`);
+                  log(`  Check later with: nansen trade bridge-status --tx-hash ${txId} --from-chain ${quoteData.chain} --to-chain ${quoteData.toChain}`);
+                }
+              }
+
               log('');
               return undefined; // Success — done
             } else {
@@ -1677,8 +1865,12 @@ EXAMPLES:
             }
 
           } catch (quoteErr) {
-            log(`  ❌ Quote ${quoteName} failed: ${quoteErr.message}`);
-            lastQuoteError = `${quoteName}: ${quoteErr.message}`;
+            const msg = quoteErr.message || '';
+            log(`  ❌ Quote ${quoteName} failed: ${msg}`);
+            if (msg.includes('AccountNotFound') && chainType === 'solana') {
+              log(`  Hint: Your Solana wallet may not have enough SOL to cover transaction fees (~0.005 SOL minimum).`);
+            }
+            lastQuoteError = `${quoteName}: ${msg}`;
             if (qi + 1 < endIndex) log(`  Trying next quote...`);
           }
         }
@@ -1695,5 +1887,55 @@ EXAMPLES:
         exit(1);
       }
     },
+
+    'bridge-status': async (args, _apiInstance, _flags, options) => {
+      const txHash = options['tx-hash'] || args[0];
+      const fromChain = options['from-chain'] || args[1];
+      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>
+
+Check the status of a cross-chain bridge transaction.
+
+OPTIONS:
+  --tx-hash <hash>          Source chain transaction hash
+  --from-chain <chain>      Source chain (solana or base)
+  --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;
+      }
+
+      try {
+        const status = await getBridgeStatus(txHash, fromChain, toChain);
+        log(`\nBridge Status: ${status.status || 'unknown'}`);
+        if (status.substatus) log(`  Substatus:   ${status.substatus}`);
+        if (status.substatusMessage) log(`  Message:     ${status.substatusMessage}`);
+        if (status.tool) log(`  Bridge:      ${status.tool}`);
+        if (status.sending?.txHash) {
+          log(`  Sending:`);
+          log(`    Tx:        ${status.sending.txHash}`);
+          if (status.sending.amount) log(`    Amount:    ${status.sending.amount}`);
+          if (status.sending.txLink) log(`    Explorer:  ${status.sending.txLink}`);
+        }
+        if (status.receiving?.txHash) {
+          log(`  Receiving:`);
+          log(`    Tx:        ${status.receiving.txHash}`);
+          if (status.receiving.amount) log(`    Amount:    ${status.receiving.amount}`);
+          if (status.receiving.txLink) log(`    Explorer:  ${status.receiving.txLink}`);
+        }
+        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);
+      }
+    },
   };
 }

package/src/transfer.js

@@ -4,8 +4,7 @@
  */
 
 import crypto from 'crypto';
-import { base58 } from '@scure/base';
-import { base58Encode, exportWallet, getWalletConfig, verifyPassword, showWallet } from './wallet.js';
+import { base58Encode, base58Decode, base58DecodePubkey, exportWallet, getWalletConfig, verifyPassword, showWallet } from './wallet.js';
 import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect } from './walletconnect-trading.js';
 import { EVM_CHAIN_IDS } from './chain-ids.js';
@@ -22,19 +21,6 @@ const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
 // Alias: buildEvmTransaction uses 'evm' as a generic fallback
 const CHAIN_IDS = { ...EVM_CHAIN_IDS, evm: 1 };
 
-// ============= Base58 =============
-
-function base58Decode(str) {
-  return Buffer.from(base58.decode(str));
-}
-
-function base58DecodePubkey(str) {
-  const raw = base58Decode(str);
-  if (raw.length === 32) return raw;
-  if (raw.length < 32) return Buffer.concat([Buffer.alloc(32 - raw.length), raw]);
-  return raw.subarray(raw.length - 32);
-}
-
 // ============= Address Validation =============
 
 function validateEvmAddress(address) {
@@ -825,13 +811,7 @@ async function sendTokensViaWalletConnect({ to, amount, chain, token, max, dryRu
   let txTo, txValue, txData;
 
   if (token) {
-    // Validate ERC-20 contract
-    const code = await rpcCall(rpcUrl, 'eth_getCode', [token, 'latest']);
-    if (!code || code === '0x' || code === '0x0') {
-      throw new Error(`Address ${token} is not a contract — not a valid ERC-20 token`);
-    }
-    const decResult = await rpcCall(rpcUrl, 'eth_call', [{ to: token, data: '0x313ce567' }, 'latest']);
-    const decimals = parseInt(decResult, 16);
+    const decimals = await validateErc20Token(rpcUrl, token);
 
     if (max) {
       // Max ERC-20: full token balance

package/src/wallet.js

@@ -40,6 +40,17 @@ export function base58Encode(buf) {
   return base58.encode(buf instanceof Uint8Array ? buf : Uint8Array.from(buf));
 }
 
+export function base58Decode(str) {
+  return Buffer.from(base58.decode(str));
+}
+
+export function base58DecodePubkey(str) {
+  const raw = base58Decode(str);
+  if (raw.length === 32) return raw;
+  if (raw.length < 32) return Buffer.concat([Buffer.alloc(32 - raw.length), raw]);
+  return raw.subarray(raw.length - 32);
+}
+
 // ============= Encryption =============
 
 /**

package/src/x402-svm.js

@@ -4,13 +4,7 @@
  */
 
 import crypto from 'crypto';
-import { base58 } from '@scure/base';
-
-// ============= Base58 Encode =============
-
-export function base58Encode(buf) {
-  return base58.encode(buf instanceof Uint8Array ? buf : Uint8Array.from(buf));
-}
+import { base58Encode, base58DecodePubkey } from './wallet.js';
 
 // ============= Constants =============
 
@@ -24,25 +18,6 @@ const _SYSTEM_PROGRAM = '11111111111111111111111111111111';
 const DEFAULT_COMPUTE_UNIT_LIMIT = 20000;
 const DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS = 1;
 
-// ============= Base58 Decode =============
-
-export function base58Decode(str) {
-  return Buffer.from(base58.decode(str));
-}
-
-/**
- * Decode a base58 string to exactly 32 bytes (left-pad with zeros).
- * Use for Solana public keys and hashes.
- */
-export function base58DecodePubkey(str) {
-  const raw = base58Decode(str);
-  if (raw.length === 32) return raw;
-  if (raw.length < 32) {
-    return Buffer.concat([Buffer.alloc(32 - raw.length), raw]);
-  }
-  return raw.subarray(raw.length - 32);
-}
-
 // ============= Compact-u16 Encoding =============
 // (Solana's variable-length integer format, from trading.js pattern)