nansen-cli 1.23.1 → 1.25.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.25.0
+
+### Minor Changes
+
+- [#363](https://github.com/nansen-ai/nansen-cli/pull/363) [`6ae402e`](https://github.com/nansen-ai/nansen-cli/commit/6ae402ef1e5bdeacf83fe04bcf6e8e0c9f9c91b7) Thanks [@TimNooren](https://github.com/TimNooren)! - Add `--amount-unit usd` to trade commands — specify swap amounts in USD
+
+### Patch Changes
+
+- [#374](https://github.com/nansen-ai/nansen-cli/pull/374) [`0f14803`](https://github.com/nansen-ai/nansen-cli/commit/0f148031ef7590f3405c1dba9f31ad83768a7141) Thanks [@TimNooren](https://github.com/TimNooren)! - Fix cross-chain quote display: show adaptive precision for sub-cent bridge fees, "< 1 min" for fast bridges, and echo --to-wallet address in output
+
+- [#366](https://github.com/nansen-ai/nansen-cli/pull/366) [`f358fff`](https://github.com/nansen-ai/nansen-cli/commit/f358fffcc80136c4e609f2e056f2c5ffb052d626) Thanks [@kome12](https://github.com/kome12)! - fix(token): replace dead `--days` param with working `--timeframe` for `token flow-intelligence`
+
+  The `--days` option was accepted but never sent to the API, resulting in always fetching `1d` data. This replaces it with `--timeframe` (enum: `1h | 6h | 12h | 1d | 7d`, default `1d`) which maps correctly to the API parameter.
+
+## 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

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.1",
+  "version": "1.25.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/api.js

@@ -1061,14 +1061,15 @@ export class NansenAPI {
   }
 
   async tokenFlowIntelligence(params = {}) {
-    const { tokenAddress, chain = 'solana' } = params;
+    const { tokenAddress, chain = 'solana', timeframe = '1d' } = params;
     if (tokenAddress) {
       const validation = validateTokenAddress(tokenAddress, chain);
       if (!validation.valid) throw new NansenError(validation.error, validation.code);
     }
     return this.request('/api/v1/tgm/flow-intelligence', {
       token_address: tokenAddress,
-      chain
+      chain,
+      timeframe
     });
   }
 

package/src/cli.js

@@ -1250,7 +1250,7 @@ export function buildCommands(deps = {}) {
           const buyOrSell = (options['buy-or-sell'] || 'BUY').toUpperCase();
           return apiInstance.tokenWhoBoughtSold({ tokenAddress, chain, buyOrSell, filters, orderBy, pagination, days, date });
         },
-        'flow-intelligence': () => apiInstance.tokenFlowIntelligence({ tokenAddress, chain, days }),
+        'flow-intelligence': () => apiInstance.tokenFlowIntelligence({ tokenAddress, chain, timeframe: options.timeframe || '1d' }),
         'transfers': () => {
           // Inject --from/--to into filters
           if (options.from) filters.from_address = options.from;
@@ -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/schema.json

@@ -408,8 +408,8 @@
                 "token": {
                   "required": true
                 },
-                "days": {
-                  "default": 30
+                "timeframe": {
+                  "default": "1d"
                 }
               }
             },
@@ -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,20 +791,24 @@
             "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",
               "required": true,
-              "description": "Amount to swap (base units by default, or token units with --amount-unit token)"
+              "description": "Amount to swap (base units by default, or token units with --amount-unit token, or USD with --amount-unit usd)"
             },
             "amount-unit": {
               "type": "string",
-              "description": "\"token\" to specify amount in token units (e.g. 0.5 SOL), or \"base\" for base units (default). Decimals are resolved locally and 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), or \"base\" for base units (default). The CLI resolves the current token price and decimals locally; the API always receives base units."
             },
             "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

@@ -5,6 +5,7 @@
  */
 
 import { validateAddress } from './api.js';
+import { CHAIN_RPCS } from './rpc-urls.js';
 
 const SUPPORTED_CHAINS = ['solana', 'base'];
 
@@ -12,7 +13,7 @@ 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, from, to, amount }) {
+export function validateQuoteInput({ chain, toChain, from, to, amount }) {
   // 1. Chain must be supported
   const normalizedChain = chain?.toLowerCase();
   if (!SUPPORTED_CHAINS.includes(normalizedChain)) {
@@ -21,6 +22,13 @@ export function validateQuoteInput({ chain, from, to, amount }) {
     );
   }
 
+  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) {
@@ -36,19 +44,227 @@ export function validateQuoteInput({ chain, from, to, amount }) {
       `Invalid sell token address for ${normalizedChain}. ${fromResult.error}`
     );
   }
-  const toResult = validateAddress(to, normalizedChain);
+  const toResult = validateAddress(to, normalizedToChain);
   if (!toResult.valid) {
     throw new Error(
-      `Invalid buy token address for ${normalizedChain}. ${toResult.error}`
+      `Invalid buy token address for ${normalizedToChain}. ${toResult.error}`
     );
   }
 
-  // 4. Sell and buy tokens must be different
-  const fromNorm = normalizedChain === 'solana' ? from : from.toLowerCase();
-  const toNorm = normalizedChain === 'solana' ? to : to.toLowerCase();
-  if (fromNorm === toNorm) {
+  // 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(
-      `Cannot swap ${from} for itself. Sell and buy tokens must be different.`
+      `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,7 +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 } from './trade-validation.js';
+import { validateQuoteInput, validateBalance } from './trade-validation.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
 
 // ============= Constants =============
@@ -21,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)
@@ -199,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 });
@@ -216,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 });
@@ -772,6 +853,27 @@ export function convertToBaseUnits(amount, decimals) {
   return raw;
 }
 
+/**
+ * Fetch the current USD price for a token via the Nansen search API.
+ * Used by --amount-unit usd to convert dollar amounts to token amounts.
+ */
+export async function resolveUsdPrice(apiInstance, tokenAddress, chain) {
+  const result = await apiInstance.generalSearch({
+    query: tokenAddress,
+    resultType: 'token',
+    chain,
+    limit: 1,
+  });
+  const isEvm = tokenAddress.startsWith('0x');
+  const token = result.tokens?.find(t =>
+    isEvm ? t.address?.toLowerCase() === tokenAddress.toLowerCase() : t.address === tokenAddress
+  );
+  if (!token?.price) {
+    throw new Error(`Could not resolve USD price for ${tokenAddress} on ${chain}. The token may not have pricing data.`);
+  }
+  return token.price;
+}
+
 /**
  * Check if amount contains a decimal point (i.e. not in base units).
  * Returns an error string if invalid, or null if OK. Pure function.
@@ -808,6 +910,21 @@ 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) {
+      const mins = Math.round(meta.executionDuration / 60);
+      lines.push(`    Est. Time:    ${mins < 1 ? '< 1 min' : `~${mins} min`}`);
+    }
+    if (meta.feeCosts?.length) {
+      const totalFees = meta.feeCosts.reduce((sum, f) => sum + parseFloat(f.amountUSD || 0), 0);
+      if (totalFees > 0) {
+        const feeStr = totalFees < 0.01 ? totalFees.toPrecision(1) : totalFees.toFixed(2);
+        lines.push(`    Bridge Fees:  $${feeStr}`);
+      }
+    }
+  }
   if (quote.priceImpactPct) {
     const impactAbs = Math.abs(parseFloat(quote.priceImpactPct));
     if (impactAbs > 5) {
@@ -828,12 +945,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'];
@@ -850,12 +970,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)
+  --amount-unit <unit>      "token" for token units (e.g. 0.5 SOL), "usd" for USD (e.g. 50)
   --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,16 +986,18 @@ OPTIONS:
 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 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;
       }
 
       // Validate --amount-unit if provided
-      if (amountUnit && amountUnit !== 'token' && amountUnit !== 'base') {
-        log(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base`);
+      if (amountUnit && amountUnit !== 'token' && amountUnit !== 'base' && amountUnit !== 'usd') {
+        log(`Error: Unknown --amount-unit "${amountUnit}". Supported values: token, base, usd`);
         exit(1);
         return;
       }
@@ -881,7 +1005,7 @@ EXAMPLES:
       // Static input validation — catches common agent errors (wrong addresses,
       // same-token swaps, bad amounts) before any network or wallet call.
       try {
-        validateQuoteInput({ chain, from, to, amount });
+        validateQuoteInput({ chain, toChain: toChainRaw || null, from, to, amount });
       } catch (validationErr) {
         log(`Error: ${validationErr.message}`);
         exit(1);
@@ -891,11 +1015,28 @@ EXAMPLES:
       // 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;
-      if (amountUnit === 'token') {
+      let resolvedDecimals;
+      let usdTokenAmount; // token-unit amount after USD conversion (for balance pre-check)
+      if (amountUnit === 'usd') {
+        try {
+          const tokenForPrice = swapMode === 'exactOut' ? to : from;
+          const price = await resolveUsdPrice(apiInstance, tokenForPrice, chain);
+          resolvedDecimals = await resolveTokenDecimals(tokenForPrice, chain);
+          // Convert USD to token amount, then to base units via string math.
+          // Use toFixed() instead of String() to avoid scientific notation for small values.
+          const tokenAmount = parseFloat(amount) / price;
+          usdTokenAmount = tokenAmount.toFixed(resolvedDecimals);
+          resolvedAmount = convertToBaseUnits(usdTokenAmount, resolvedDecimals);
+        } catch (err) {
+          log(`Error converting USD amount: ${err.message}`);
+          exit(1);
+          return;
+        }
+      } else 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);
@@ -955,7 +1096,42 @@ EXAMPLES:
           return;
         }
 
-        log(`\nFetching quote on ${chainConfig.name}...`);
+        // Balance pre-check — catches zero balances and insufficient funds
+        // before wasting a quote API call. Runs for --amount-unit token and
+        // usd (after USD→token conversion) in exactIn mode. In exactOut the
+        // amount is the buy amount so comparing against sell balance is meaningless.
+        if ((amountUnit === 'token' || amountUnit === 'usd') && swapMode !== 'exactOut') {
+          try {
+            // For USD, pass the converted token-unit amount so validateBalance
+            // can compare against the wallet balance in token units.
+            const tokenUnitAmount = amountUnit === 'usd' ? usdTokenAmount : amount;
+            const { adjustedAmount: balanceAdjusted } = await validateBalance({
+              chain,
+              from,
+              amount: tokenUnitAmount,
+              amountUnit: 'token',
+              walletAddress,
+              decimals: resolvedDecimals,
+              symbol: fromRaw,
+            });
+            if (balanceAdjusted !== tokenUnitAmount) {
+              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);
@@ -968,6 +1144,21 @@ EXAMPLES:
           amount: resolvedAmount,
           userWalletAddress: walletAddress,
         };
+        if (isCrossChain) {
+          params.toChainIndex = toChainConfig.index;
+          if (toWallet) {
+            params.toWalletAddress = toWallet;
+            log(`  Destination wallet: ${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;
@@ -988,7 +1179,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) {
@@ -1492,6 +1683,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
               }
@@ -1678,6 +1886,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 {
@@ -1688,8 +1913,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...`);
           }
         }
@@ -1706,5 +1935,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,8 @@
  */
 
 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';
+import { encodeCompactU16 } from './transfer.js';
 
 // ============= Constants =============
 
@@ -24,41 +19,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)
-
-export function encodeCompactU16(value) {
-  if (value < 0x80) return Buffer.from([value]);
-  if (value < 0x4000) return Buffer.from([
-    (value & 0x7f) | 0x80,
-    (value >> 7) & 0x7f,
-  ]);
-  return Buffer.from([
-    (value & 0x7f) | 0x80,
-    ((value >> 7) & 0x7f) | 0x80,
-    (value >> 14) & 0x03,
-  ]);
-}
-
 // ============= PDA Derivation =============
 
 /**