@alchemy/cli 0.7.2-alpha.21 → 0.7.2-alpha.29

package/dist/index.js

@@ -2,18 +2,20 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   registerAuth
-} from "./chunk-LQXLZLCY.js";
+} from "./chunk-XSN4XA5Z.js";
 import {
   openBrowser
-} from "./chunk-INVT5BV6.js";
+} from "./chunk-C5HNQOLB.js";
 import {
+  SETUP_CAPABILITY_LABELS,
+  SETUP_CAPABILITY_ORDER,
   getSetupStatus,
   isSetupComplete,
   shouldRunOnboarding
-} from "./chunk-EZ2ZD7YO.js";
+} from "./chunk-R4W44A6E.js";
 import {
   isInteractiveAllowed
-} from "./chunk-RE5HSYJJ.js";
+} from "./chunk-64A5W4M2.js";
 import {
   adminClientFromFlags,
   clearSession,
@@ -41,12 +43,12 @@ import {
   resolveX402Client,
   saveSession,
   updateSession
-} from "./chunk-5LCA2B6S.js";
+} from "./chunk-K6V3R7SH.js";
 import {
   getAvailableUpdate,
   getUpdateStatus,
   printUpdateNotice
-} from "./chunk-I5KTBL75.js";
+} from "./chunk-NNPVKNB4.js";
 import {
   bold,
   brand,
@@ -70,7 +72,7 @@ import {
   weiToEth,
   withSpinner,
   yellow
-} from "./chunk-DGKUBK7G.js";
+} from "./chunk-5IL2PMZ6.js";
 import {
   KEY_MAP,
   configDir,
@@ -81,7 +83,7 @@ import {
   save,
   toMap,
   validKeys
-} from "./chunk-BAZ4NGOD.js";
+} from "./chunk-JUCUKTP3.js";
 import {
   CLIError,
   EXIT_CODES,
@@ -117,7 +119,7 @@ import {
   setFlags,
   setNoColor,
   verbose
-} from "./chunk-KLPWJFWP.js";
+} from "./chunk-2BALTY22.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -624,7 +626,7 @@ function registerConfig(program2) {
       printJSON(toMap(cfg));
       return;
     }
-    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-ZCR3YCHJ.js");
+    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-WXT5ZCUK.js");
     const validToken = resolveAuthToken2(cfg);
     const authStatus = cfg.auth_token ? validToken ? `${green("\u2713")} authenticated${cfg.auth_token_expires_at ? ` ${dim(`(expires ${cfg.auth_token_expires_at})`)}` : ""}` : `${yellow("\u25C6")} expired${cfg.auth_token_expires_at ? ` ${dim(`(${cfg.auth_token_expires_at})`)}` : ""}` : dim("(not set) \u2014 run 'alchemy auth' to log in");
     const pairs = [
@@ -738,6 +740,15 @@ function registerConfig(program2) {
         console.log(`  ${dim(`- ${command}`)}`);
       }
     }
+    console.log("");
+    console.log(`  ${dim("Capabilities:")}`);
+    printKeyValue(
+      SETUP_CAPABILITY_ORDER.map((capability) => {
+        const capabilityStatus = status.capabilities[capability];
+        const value = capabilityStatus.complete ? `ready (${capabilityStatus.satisfiedBy})` : `missing ${capabilityStatus.missing.join(", ")}`;
+        return [SETUP_CAPABILITY_LABELS[capability], value];
+      })
+    );
   });
 }
 
@@ -2682,6 +2693,8 @@ function registerWallets(program2) {
 }
 
 // src/lib/rest.ts
+var DATA_API_BASE_URL_ENV = "ALCHEMY_DATA_API_BASE_URL";
+var PRICES_API_BASE_URL_ENV = "ALCHEMY_PRICES_API_BASE_URL";
 function withQuery(url, query) {
   if (!query) return url;
   for (const [key, value] of Object.entries(query)) {
@@ -2715,13 +2728,15 @@ async function requestJSON(url, options) {
 }
 async function callApiData(apiKey, path, options = {}) {
   if (!apiKey) throw errAuthRequired();
-  const base2 = new URL(`https://api.g.${getBaseDomain()}/data/v1/${apiKey}/`);
+  const override = parseBaseURLOverride(DATA_API_BASE_URL_ENV);
+  const base2 = override ? new URL(`/data/v1/${apiKey}/`, override) : new URL(`https://api.g.${getBaseDomain()}/data/v1/${apiKey}/`);
   const url = withQuery(new URL(path.replace(/^\//, ""), base2), options.query);
   return requestJSON(url, { ...options, path });
 }
 async function callApiPrices(apiKey, path, options = {}) {
   if (!apiKey) throw errAuthRequired();
-  const base2 = new URL(`https://api.g.${getBaseDomain()}/prices/v1/${apiKey}/`);
+  const override = parseBaseURLOverride(PRICES_API_BASE_URL_ENV);
+  const base2 = override ? new URL(`/prices/v1/${apiKey}/`, override) : new URL(`https://api.g.${getBaseDomain()}/prices/v1/${apiKey}/`);
   const url = withQuery(new URL(path.replace(/^\//, ""), base2), options.query);
   return requestJSON(url, { ...options, path });
 }
@@ -3632,7 +3647,7 @@ async function performSolanaSend(program2, toArg, amountArg, tokenAddress, opts
 }
 
 // src/lib/smart-wallet.ts
-import { createSmartWalletClient, alchemyWalletTransport } from "@alchemy/wallet-apis";
+import { createSmartWalletClient } from "@alchemy/wallet-apis";
 import { privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
 
 // src/lib/chains.ts
@@ -3971,6 +3986,17 @@ function createDelegatedAccount(args) {
   });
 }
 
+// src/lib/wallet-transport.ts
+import { alchemyWalletTransport } from "@alchemy/wallet-apis";
+var WALLET_RPC_BASE_URL_ENV = "ALCHEMY_WALLET_RPC_BASE_URL";
+function createAlchemyWalletTransport(apiKey) {
+  const override = parseBaseURLOverride(WALLET_RPC_BASE_URL_ENV);
+  return alchemyWalletTransport({
+    apiKey,
+    ...override ? { url: override.toString() } : {}
+  });
+}
+
 // src/lib/smart-wallet.ts
 function normalizeKey(key) {
   const trimmed = key.trim();
@@ -4069,7 +4095,7 @@ function buildWalletClient(program2, options = {}) {
   }
   const paymaster = gasSponsored && gasPolicyId ? { policyId: gasPolicyId } : void 0;
   const client = createSmartWalletClient({
-    transport: alchemyWalletTransport({ apiKey }),
+    transport: createAlchemyWalletTransport(apiKey),
     chain,
     signer: signerConfig.signer,
     paymaster
@@ -4640,6 +4666,7 @@ var ERROR_RECOVERY = {
   RATE_LIMITED: "Wait and retry; consider upgrading your Alchemy plan",
   PAYMENT_REQUIRED: "Fund your x402 wallet or switch to API key auth",
   SETUP_REQUIRED: "Run preflight: alchemy --json --no-interactive config status, then follow nextCommands",
+  QUOTE_FAILED: "Quote unavailable; check data.cause for the specific reason (INSUFFICIENT_BALANCE, INSUFFICIENT_LIQUIDITY, UNSUPPORTED_ROUTE, QUOTE_REVERTED, QUOTE_FAILED) and follow the hint",
   INTERNAL_ERROR: "Unexpected error; retry or report a bug"
 };
 function buildCommandSchema(cmd) {
@@ -4694,11 +4721,13 @@ function buildAgentPrompt(program2) {
       "For general capability and usage questions, prefer npx -y @alchemy/cli@latest --json --no-interactive agent-prompt so stale local installs or PATH shims do not hide new commands",
       "Use the user's installed alchemy binary only when executing commands against their local config or diagnosing their installed version",
       "If installed alchemy help contradicts latest npm help, compare alchemy --json --no-interactive version with npx -y @alchemy/cli@latest --json --no-interactive version and check command -v alchemy",
-      "Run alchemy --json --no-interactive update-check when you need to detect available CLI upgrades"
+      "Run alchemy --json --no-interactive update-check when you need to detect available CLI upgrades",
+      "For state-changing EVM commands, prefer preview flags such as --dry-run when available before asking the user to execute",
+      "For large data reads, use output-size controls such as --limit or --summary when available"
     ],
     preflight: {
       command: "alchemy --json --no-interactive config status",
-      description: "Check auth readiness before first command. If complete is false, follow nextCommands in the response to configure auth."
+      description: "Check auth readiness before first command. Use capabilities.rpc_data/admin_api/notify_webhooks/wallet_signing/x402 to scope setup to the intended command family."
     },
     runtimeDiscovery: {
       installed: {
@@ -4810,9 +4839,11 @@ function buildAgentPrompt(program2) {
       "ALCHEMY_ACCESS_KEY=ak_xxx alchemy --json --no-interactive app list",
       "alchemy --json --no-interactive evm rpc eth_blockNumber --api-key $ALCHEMY_API_KEY",
       "alchemy --json --no-interactive evm network list",
-      "alchemy --json --no-interactive evm send 0xRecipient 0.001 -n eth-sepolia",
+      "alchemy --json --no-interactive evm send 0xRecipient 0.001 --dry-run -n eth-sepolia",
       `alchemy --json --no-interactive evm contract read 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 "balanceOf(address)(uint256)" --args '["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]' -n eth-mainnet`,
-      "alchemy --json --no-interactive evm swap quote --from 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE --to 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --amount 1.0 -n eth-mainnet",
+      "alchemy --json --no-interactive evm swap quote --from 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE --to 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --amount 1.0 --from-address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n eth-mainnet",
+      "alchemy --json --no-interactive evm logs --from-block latest --limit 25",
+      "alchemy --json --no-interactive evm block latest --summary",
       "alchemy --json --no-interactive evm status 0xCallId -n eth-mainnet"
     ],
     docs: "https://www.alchemy.com/docs"
@@ -5154,15 +5185,26 @@ async function performApprove(program2, spenderArg, opts) {
 }
 
 // src/commands/block.ts
+function summarizeBlock(block) {
+  return {
+    number: block.number ?? null,
+    hash: block.hash ?? null,
+    timestamp: block.timestamp ?? null,
+    transactionCount: Array.isArray(block.transactions) ? block.transactions.length : null,
+    miner: block.miner ?? null,
+    gasUsed: block.gasUsed ?? null,
+    gasLimit: block.gasLimit ?? null
+  };
+}
 function registerBlock(program2) {
-  program2.command("block").argument("<number>", "Block number, hex (0x...), or tag (latest, earliest, pending)").description("Get block details by number").addHelpText(
+  program2.command("block").argument("<number>", "Block number, hex (0x...), or tag (latest, earliest, pending)").description("Get block details by number").option("--summary", "Return compact block summary in JSON mode").addHelpText(
     "after",
     `
 Examples:
   alchemy evm block latest
   alchemy evm block 17000000
   alchemy evm block 0x1`
-  ).action(async (blockId) => {
+  ).action(async (blockId, opts) => {
     try {
       let blockParam;
       if (["latest", "earliest", "pending"].includes(blockId)) {
@@ -5189,7 +5231,7 @@ Examples:
       );
       if (!block) throw errNotFound(`block ${blockId}`);
       if (isJSONMode()) {
-        printJSON(block);
+        printJSON(opts.summary ? summarizeBlock(block) : block);
         return;
       }
       const pairs = [];
@@ -6237,60 +6279,74 @@ async function runDataCall(program2, title, path, body) {
     () => x402 ? x402.callRest(`data/v1${path}`, { method: "POST", body }) : callApiData(resolveAPIKey(program2), path, { method: "POST", body })
   );
 }
+function limitPayload(value, limit) {
+  if (limit === void 0) return value;
+  if (Array.isArray(value)) {
+    return value.slice(0, limit);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nested]) => [
+        key,
+        Array.isArray(nested) ? nested.slice(0, limit) : nested
+      ])
+    );
+  }
+  return value;
+}
+async function runPortfolioCommand(program2, title, path, opts) {
+  const limit = parseOptionalInt(opts.limit, "--limit");
+  const result = await runDataCall(program2, title, path, JSON.parse(opts.body));
+  const output = limitPayload(result, limit);
+  if (isJSONMode()) printJSON(output);
+  else printSyntaxJSON(output);
+}
 function registerPortfolio(program2) {
   const cmd = program2.command("portfolio").description("Portfolio API wrappers");
-  cmd.command("tokens").description("Get token portfolio by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/tokens/by-address").action(async (opts) => {
+  cmd.command("tokens").description("Get token portfolio by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/tokens/by-address").option("--limit <n>", "Limit arrays in output").action(async (opts) => {
     try {
-      const result = await runDataCall(
+      await runPortfolioCommand(
         program2,
         "token portfolio",
         "/assets/tokens/by-address",
-        JSON.parse(opts.body)
+        opts
       );
-      if (isJSONMode()) printJSON(result);
-      else printSyntaxJSON(result);
     } catch (err) {
       exitWithError(err);
     }
   });
-  cmd.command("token-balances").description("Get token balances by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/tokens/balances/by-address").action(async (opts) => {
+  cmd.command("token-balances").description("Get token balances by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/tokens/balances/by-address").option("--limit <n>", "Limit arrays in output").action(async (opts) => {
     try {
-      const result = await runDataCall(
+      await runPortfolioCommand(
         program2,
         "token balances",
         "/assets/tokens/balances/by-address",
-        JSON.parse(opts.body)
+        opts
       );
-      if (isJSONMode()) printJSON(result);
-      else printSyntaxJSON(result);
     } catch (err) {
       exitWithError(err);
     }
   });
-  cmd.command("nfts").description("Get NFT portfolio by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/nfts/by-address").action(async (opts) => {
+  cmd.command("nfts").description("Get NFT portfolio by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/nfts/by-address").option("--limit <n>", "Limit arrays in output").action(async (opts) => {
     try {
-      const result = await runDataCall(
+      await runPortfolioCommand(
         program2,
         "NFT portfolio",
         "/assets/nfts/by-address",
-        JSON.parse(opts.body)
+        opts
       );
-      if (isJSONMode()) printJSON(result);
-      else printSyntaxJSON(result);
     } catch (err) {
       exitWithError(err);
     }
   });
-  cmd.command("nft-contracts").description("Get NFT contracts by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/nfts/contracts/by-address").action(async (opts) => {
+  cmd.command("nft-contracts").description("Get NFT contracts by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/nfts/contracts/by-address").option("--limit <n>", "Limit arrays in output").action(async (opts) => {
     try {
-      const result = await runDataCall(
+      await runPortfolioCommand(
         program2,
         "NFT contracts",
         "/assets/nfts/contracts/by-address",
-        JSON.parse(opts.body)
+        opts
       );
-      if (isJSONMode()) printJSON(result);
-      else printSyntaxJSON(result);
     } catch (err) {
       exitWithError(err);
     }
@@ -6454,8 +6510,9 @@ Examples:
   alchemy evm logs --address 0xdAC17F958D2ee523a2206206994597C13D831ec7 --from-block 18000000 --to-block 18000010
   alchemy evm logs --address 0xdAC17F958D2ee523a2206206994597C13D831ec7 --topic 0xddf252ad...
   alchemy evm logs --from-block latest --json`
-  ).option("--address <address>", "Contract address to filter logs").option("--topic <topic...>", "Event topic(s) to filter (topic0, topic1, ...)").option("--from-block <block>", "Start block (number, hex, or tag)", "latest").option("--to-block <block>", "End block (number, hex, or tag)", "latest").action(async (opts) => {
+  ).option("--address <address>", "Contract address to filter logs").option("--topic <topic...>", "Event topic(s) to filter (topic0, topic1, ...)").option("--from-block <block>", "Start block (number, hex, or tag)", "latest").option("--to-block <block>", "End block (number, hex, or tag)", "latest").option("--limit <n>", "Limit returned logs in output").action(async (opts) => {
     try {
+      const outputLimit = parseOptionalInt(opts.limit, "--limit");
       const filter = {
         fromBlock: normalizeBlockParam(opts.fromBlock),
         toBlock: normalizeBlockParam(opts.toBlock)
@@ -6473,20 +6530,41 @@ Examples:
         () => client.call("eth_getLogs", [filter])
       );
       const network = resolveNetwork(program2);
+      const displayedLogs = outputLimit === void 0 ? logs : logs.slice(0, outputLimit);
       if (isJSONMode()) {
-        printJSON({ logs, count: logs.length, network });
+        printJSON({
+          logs: displayedLogs,
+          count: displayedLogs.length,
+          network,
+          ...outputLimit !== void 0 ? {
+            totalCount: logs.length,
+            truncated: displayedLogs.length < logs.length
+          } : {}
+        });
         return;
       }
       if (logs.length === 0) {
         console.log(dim("No logs found for the given filter."));
         return;
       }
+      if (displayedLogs.length === 0) {
+        console.log(dim(`Found ${logs.length} log${logs.length === 1 ? "" : "s"}; --limit 0 hides output.`));
+        return;
+      }
       const total = logs.length;
       const interactive = isInteractiveAllowed(program2);
+      const limitSummary = displayedLogs.length < total ? `Showing ${displayedLogs.length} of ${total} logs on ${network}
+` : `Found ${total} log${total === 1 ? "" : "s"} on ${network}
+`;
+      if (outputLimit !== void 0) {
+        console.log(limitSummary);
+        printTable(TABLE_HEADERS2, formatLogRows(displayedLogs));
+        return;
+      }
       if (!interactive) {
         console.log(`Found ${total} log${total === 1 ? "" : "s"} on ${network}
 `);
-        printTable(TABLE_HEADERS2, formatLogRows(logs));
+        printTable(TABLE_HEADERS2, formatLogRows(displayedLogs));
       } else {
         let offset = 0;
         const firstPage = logs.slice(0, PAGE_SIZE);
@@ -6616,8 +6694,15 @@ Examples:
 // src/commands/send-evm.ts
 import { encodeFunctionData as encodeFunctionData3, erc20Abi as erc20Abi2 } from "viem";
 var NATIVE_EVM_DECIMALS = 18;
+function formatCallPreview(call) {
+  return {
+    to: call.to,
+    ...call.value !== void 0 ? { value: call.value.toString() } : {},
+    ...call.data ? { data: call.data } : {}
+  };
+}
 function registerEvmSend(program2) {
-  const sendCmd = program2.command("send").description("Send native tokens or ERC-20 tokens to an address").argument("<to>", "Recipient address (0x... or ENS name)").argument("<amount>", "Amount to send (human-readable, e.g. 1.5)").option("--token <address>", "ERC-20 token contract address (omit for native token)");
+  const sendCmd = program2.command("send").description("Send native tokens or ERC-20 tokens to an address").argument("<to>", "Recipient address (0x... or ENS name)").argument("<amount>", "Amount to send (human-readable, e.g. 1.5)").option("--token <address>", "ERC-20 token contract address (omit for native token)").option("--dry-run", "Preview transaction without signing or sending");
   addSignerOption(sendCmd);
   sendCmd.option("--gas-sponsored", "Enable gas sponsorship (env: ALCHEMY_EVM_GAS_SPONSORED)").option("--gas-policy-id <id>", "Gas policy ID for sponsorship (env: ALCHEMY_EVM_GAS_POLICY_ID)").addHelpText(
     "after",
@@ -6626,16 +6711,18 @@ Examples:
   alchemy evm send 0xAbC...123 1.5                          Send 1.5 ETH
   alchemy evm send vitalik.eth 0.1 -n base-mainnet          Send 0.1 ETH on Base
   alchemy evm send 0xAbC...123 100 --token 0xA0b8...USDC    Send 100 USDC
+  alchemy evm send 0xAbC...123 1.5 --dry-run                Preview without signing or sending
   alchemy evm send 0xAbC...123 1 --gas-sponsored --gas-policy-id <id>
   alchemy evm send 0xAbC...123 1.5 --signer local           Force the local wallet`
   ).action(async (toArg, amountArg, _opts, cmd) => {
     try {
       const opts = cmd.opts();
       await performEvmSend(cmd, toArg, amountArg, opts.token, {
-        signer: parseSignerOpt(opts.signer)
+        signer: parseSignerOpt(opts.signer),
+        dryRun: opts.dryRun
       });
     } catch (err) {
-      const { exitWithError: exitWithError2 } = await import("./errors-J6HNGXVA.js");
+      const { exitWithError: exitWithError2 } = await import("./errors-E2P6WHTX.js");
       exitWithError2(err);
     }
   });
@@ -6666,6 +6753,37 @@ async function performEvmSend(program2, toArg, amountArg, tokenAddress, opts = {
       args: [to, wei]
     })
   }] : [{ to, value: wei }];
+  if (opts.dryRun) {
+    const previewCalls = calls.map(formatCallPreview);
+    if (isJSONMode()) {
+      printJSON({
+        dryRun: true,
+        action: "evm-send",
+        from,
+        to,
+        amount: amountArg,
+        token: tokenAddress ?? symbol,
+        tokenAddress: tokenAddress ?? null,
+        network,
+        sponsored: !!paymaster,
+        calls: previewCalls
+      });
+    } else {
+      const pairs = [
+        ["Dry Run", "yes"],
+        ["From", from],
+        ["To", to],
+        ["Amount", green(`${amountArg} ${symbol}`)],
+        ["Network", network],
+        ["Calls", String(previewCalls.length)]
+      ];
+      if (paymaster) {
+        pairs.push(["Gas", green("Sponsored")]);
+      }
+      printKeyValue(pairs);
+    }
+    return;
+  }
   const { id } = await withSpinner(
     "Sending transaction\u2026",
     "Transaction submitted",
@@ -6770,6 +6888,105 @@ function registerSimulate(program2) {
 import {
   swapActions
 } from "@alchemy/wallet-apis/experimental";
+
+// src/lib/wallet-quote-client.ts
+import { createClient } from "viem";
+import { parseAccount } from "viem/accounts";
+function buildWalletQuoteClient(program2, address2) {
+  const apiKey = resolveAPIKey(program2);
+  if (!apiKey) throw errAuthRequired();
+  const cfg = load();
+  const network = resolveNetwork(program2, cfg);
+  const chain = networkToChain(network);
+  const client = createClient({
+    account: parseAccount(address2),
+    transport: createAlchemyWalletTransport(apiKey),
+    chain,
+    name: "alchemyQuoteClient"
+  });
+  if (typeof client.extend !== "function") {
+    throw new Error("Quote client missing extend(); @alchemy/wallet-apis or viem may have changed.");
+  }
+  return {
+    client,
+    network,
+    chain,
+    address: address2,
+    paymaster: void 0
+  };
+}
+
+// src/lib/quote-errors.ts
+function errorText(err) {
+  if (err instanceof CLIError) {
+    return [err.message, err.details].filter(Boolean).join(" ");
+  }
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+}
+function classifyQuoteFailure(text) {
+  const lower = text.toLowerCase();
+  if (/liquidity|no route|route not found|cannot find route|unable to find route|no quote/.test(lower)) {
+    return "INSUFFICIENT_LIQUIDITY";
+  }
+  if (/insufficient (funds|balance)|exceeds balance|not enough (funds|balance)|balance too low/.test(lower)) {
+    return "INSUFFICIENT_BALANCE";
+  }
+  if (/unsupported|not supported|unsupported route|unsupported token|unsupported chain|unsupported network/.test(lower)) {
+    return "UNSUPPORTED_ROUTE";
+  }
+  if (/execution reverted|revert|call exception|internal json-rpc|rpc error|-32603/.test(lower)) {
+    return "QUOTE_REVERTED";
+  }
+  return "QUOTE_FAILED";
+}
+function quoteMessage(flow, cause) {
+  const label = flow === "swap" ? "Swap" : "Bridge";
+  switch (cause) {
+    case "INSUFFICIENT_BALANCE":
+      return `${label} quote unavailable: insufficient balance for the requested amount.`;
+    case "INSUFFICIENT_LIQUIDITY":
+      return `${label} quote unavailable: no route or insufficient liquidity for this trade.`;
+    case "UNSUPPORTED_ROUTE":
+      return `${label} quote unavailable: unsupported token, chain, or route.`;
+    case "QUOTE_REVERTED":
+      return `${label} quote unavailable: quote simulation reverted.`;
+    case "QUOTE_FAILED":
+      return `${label} quote unavailable.`;
+  }
+}
+function quoteHint(flow, cause) {
+  switch (cause) {
+    case "INSUFFICIENT_BALANCE":
+      return "Lower --amount or quote from an address that holds enough source token.";
+    case "INSUFFICIENT_LIQUIDITY":
+      return flow === "swap" ? "Try a smaller --amount, different tokens, or a different mainnet." : "Try a smaller --amount, different tokens, or a different destination network.";
+    case "UNSUPPORTED_ROUTE":
+      return flow === "swap" ? "Check token addresses and use an EVM mainnet supported by swap." : "Check token addresses and source/destination EVM mainnets.";
+    case "QUOTE_REVERTED":
+      return "Try a smaller --amount or different route. Use --json for typed error details.";
+    case "QUOTE_FAILED":
+      return "Retry later or try a different amount, token, or network.";
+  }
+}
+function normalizeQuoteError(err, flow) {
+  if (err instanceof CLIError && err.code !== ErrorCode.RPC_ERROR && err.code !== ErrorCode.INTERNAL_ERROR) {
+    return err;
+  }
+  const detail = errorText(err);
+  const cause = classifyQuoteFailure(detail);
+  return new CLIError(
+    ErrorCode.QUOTE_FAILED,
+    quoteMessage(flow, cause),
+    quoteHint(flow, cause),
+    detail || void 0,
+    { cause }
+  );
+}
+
+// src/commands/swap.ts
 var NATIVE_TOKEN_ADDRESS2 = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
 var NATIVE_DECIMALS = 18;
 function isNativeToken2(address2) {
@@ -6792,11 +7009,12 @@ async function resolveTokenInfo(network, program2, tokenAddress) {
     throw errInvalidArgs(`Failed to resolve token info for ${tokenAddress}.${detail}`);
   }
 }
-function createQuoteRequest(fromToken, toToken, fromAmount, slippagePercent, paymaster) {
+function createQuoteRequest(fromToken, toToken, fromAmount, slippagePercent, paymaster, account) {
   const request2 = {
     fromToken,
     toToken,
     fromAmount,
+    ...account ? { account } : {},
     ...slippagePercent !== void 0 ? { slippage: slippagePercentToBasisPoints(slippagePercent) } : {},
     ...paymaster ? { capabilities: { paymaster } } : {}
   };
@@ -6843,7 +7061,7 @@ async function prepareQuoteForExecution(client, quote) {
 }
 function registerSwap(program2) {
   const cmd = program2.command("swap").description("Swap tokens on the same chain");
-  const quoteCmd = cmd.command("quote").description("Get a swap quote without executing").requiredOption("--from <token_address>", "Token address to swap from (use 0xEeee...EEeE for the native token)").requiredOption("--to <token_address>", "Token address to swap to (use 0xEeee...EEeE for the native token)").requiredOption("--amount <number>", "Amount to swap in decimal token units (for example, 1.5)").option("--slippage <percent>", "Max slippage percentage (omit to use the API default)");
+  const quoteCmd = cmd.command("quote").description("Get a swap quote without executing").requiredOption("--from <token_address>", "Token address to swap from (use 0xEeee...EEeE for the native token)").requiredOption("--to <token_address>", "Token address to swap to (use 0xEeee...EEeE for the native token)").requiredOption("--amount <number>", "Amount to swap in decimal token units (for example, 1.5)").option("--from-address <address>", "Wallet/account address to quote from without changing signer selection").option("--slippage <percent>", "Max slippage percentage (omit to use the API default)");
   addSignerOption(quoteCmd);
   quoteCmd.addHelpText(
     "after",
@@ -6880,8 +7098,9 @@ async function performSwapQuote(program2, opts) {
   validateSwapNetwork(resolveNetwork(program2));
   validateAddress(opts.from);
   validateAddress(opts.to);
+  if (opts.fromAddress) validateAddress(opts.fromAddress);
   const signer = parseSignerOpt(opts.signer);
-  const { client, network, paymaster } = buildWalletClient(program2, { signer });
+  const { client, network, address: fromAddress, paymaster } = opts.fromAddress ? buildWalletQuoteClient(program2, opts.fromAddress) : buildWalletClient(program2, { signer });
   const swapClient = client.extend(swapActions);
   const fromInfo = await resolveTokenInfo(network, program2, opts.from);
   const rawAmount = parseAmount(opts.amount, fromInfo.decimals);
@@ -6889,17 +7108,23 @@ async function performSwapQuote(program2, opts) {
   if (slippage !== void 0 && (isNaN(slippage) || slippage < 0 || slippage > 100)) {
     throw errInvalidArgs("Slippage must be a number between 0 and 100.");
   }
-  const quote = await withSpinner(
-    "Fetching quote\u2026",
-    "Quote received",
-    () => swapClient.requestQuoteV0(createQuoteRequest(opts.from, opts.to, rawAmount, slippage, paymaster))
-  );
+  let quote;
+  try {
+    quote = await withSpinner(
+      "Fetching quote\u2026",
+      "Quote received",
+      () => swapClient.requestQuoteV0(createQuoteRequest(opts.from, opts.to, rawAmount, slippage, paymaster, fromAddress))
+    );
+  } catch (err) {
+    throw normalizeQuoteError(err, "swap");
+  }
   const toInfo = await resolveTokenInfo(network, program2, opts.to);
   const quoteData = extractQuoteData(quote);
   if (isJSONMode()) {
     printJSON({
       fromToken: opts.from,
       toToken: opts.to,
+      fromAddress,
       fromAmount: opts.amount,
       fromSymbol: fromInfo.symbol,
       toSymbol: toInfo.symbol,
@@ -6918,6 +7143,7 @@ async function performSwapQuote(program2, opts) {
       pairs.push(["To", `${toInfo.symbol}`]);
     }
     pairs.push(
+      ["Wallet", fromAddress],
       ["Slippage", slippage === void 0 ? "API default" : `${slippage}%`],
       ["Network", network]
     );
@@ -6937,11 +7163,16 @@ async function performSwapExecute(program2, opts) {
   if (slippage !== void 0 && (isNaN(slippage) || slippage < 0 || slippage > 100)) {
     throw errInvalidArgs("Slippage must be a number between 0 and 100.");
   }
-  const quote = await withSpinner(
-    "Fetching quote\u2026",
-    "Quote received",
-    () => swapClient.requestQuoteV0(createQuoteRequest(opts.from, opts.to, rawAmount, slippage, paymaster))
-  );
+  let quote;
+  try {
+    quote = await withSpinner(
+      "Fetching quote\u2026",
+      "Quote received",
+      () => swapClient.requestQuoteV0(createQuoteRequest(opts.from, opts.to, rawAmount, slippage, paymaster, from))
+    );
+  } catch (err) {
+    throw normalizeQuoteError(err, "swap");
+  }
   const preparedQuote = await prepareQuoteForExecution(client, quote);
   const { id } = await withSpinner(
     "Sending swap transaction\u2026",
@@ -7143,12 +7374,13 @@ async function resolveTokenInfo2(network, program2, tokenAddress) {
     throw errInvalidArgs(`Failed to resolve token info for ${tokenAddress}.${detail}`);
   }
 }
-function createBridgeQuoteRequest(fromToken, toToken, fromAmount, toChainId, slippagePercent, paymaster) {
+function createBridgeQuoteRequest(fromToken, toToken, fromAmount, toChainId, slippagePercent, paymaster, account) {
   const request2 = {
     fromToken,
     toToken,
     fromAmount,
     toChainId,
+    ...account ? { account } : {},
     ...slippagePercent !== void 0 ? { slippage: slippagePercentToBasisPoints2(slippagePercent) } : {},
     ...paymaster ? { capabilities: { paymaster } } : {}
   };
@@ -7214,7 +7446,7 @@ function extractQuoteData2(quote) {
 }
 function registerBridge(program2) {
   const cmd = program2.command("bridge").description("Bridge tokens from the source -n/--network to a destination --to-network");
-  const quoteCmd = cmd.command("quote").description("Get a bridge quote without executing").requiredOption("--from <token_address>", `Source token address (use ${NATIVE_TOKEN_ADDRESS3} for the native token)`).requiredOption("--to <token_address>", `Destination token address (use ${NATIVE_TOKEN_ADDRESS3} for the native token)`).requiredOption("--amount <number>", "Amount to bridge in decimal token units (for example, 1.5)").requiredOption("--to-network <network>", "Destination network (e.g. base-mainnet)").option("--slippage <percent>", "Max slippage percentage (omit to use the API default)");
+  const quoteCmd = cmd.command("quote").description("Get a bridge quote without executing").requiredOption("--from <token_address>", `Source token address (use ${NATIVE_TOKEN_ADDRESS3} for the native token)`).requiredOption("--to <token_address>", `Destination token address (use ${NATIVE_TOKEN_ADDRESS3} for the native token)`).requiredOption("--amount <number>", "Amount to bridge in decimal token units (for example, 1.5)").requiredOption("--to-network <network>", "Destination network (e.g. base-mainnet)").option("--from-address <address>", "Wallet/account address to quote from without changing signer selection").option("--slippage <percent>", "Max slippage percentage (omit to use the API default)");
   addSignerOption(quoteCmd);
   quoteCmd.addHelpText(
     "after",
@@ -7256,8 +7488,9 @@ async function performBridgeQuote(program2, opts) {
   validateAddress(opts.from);
   const toChainId = bridgeDestinationChainId(opts.toNetwork);
   validateAddress(opts.to);
+  if (opts.fromAddress) validateAddress(opts.fromAddress);
   const signer = parseSignerOpt(opts.signer);
-  const { client, network, paymaster } = buildWalletClient(program2, { signer });
+  const { client, network, address: fromAddress, paymaster } = opts.fromAddress ? buildWalletQuoteClient(program2, opts.fromAddress) : buildWalletClient(program2, { signer });
   validateBridgeNetworks(network, opts.toNetwork);
   const swapClient = client.extend(swapActions2);
   const fromInfo = await resolveTokenInfo2(network, program2, opts.from);
@@ -7266,17 +7499,23 @@ async function performBridgeQuote(program2, opts) {
   if (slippage !== void 0 && (isNaN(slippage) || slippage < 0 || slippage > 100)) {
     throw errInvalidArgs("Slippage must be a number between 0 and 100.");
   }
-  const quote = await withSpinner(
-    "Fetching bridge quote\u2026",
-    "Quote received",
-    () => swapClient.requestQuoteV0(createBridgeQuoteRequest(opts.from, opts.to, rawAmount, toChainId, slippage, paymaster))
-  );
+  let quote;
+  try {
+    quote = await withSpinner(
+      "Fetching bridge quote\u2026",
+      "Quote received",
+      () => swapClient.requestQuoteV0(createBridgeQuoteRequest(opts.from, opts.to, rawAmount, toChainId, slippage, paymaster, fromAddress))
+    );
+  } catch (err) {
+    throw normalizeQuoteError(err, "bridge");
+  }
   const toInfo = await resolveTokenInfo2(opts.toNetwork, program2, opts.to);
   const quoteData = extractQuoteData2(quote);
   if (isJSONMode()) {
     printJSON({
       fromToken: opts.from,
       toToken: opts.to,
+      fromAddress,
       fromAmount: opts.amount,
       fromSymbol: fromInfo.symbol,
       toSymbol: toInfo.symbol,
@@ -7296,6 +7535,7 @@ async function performBridgeQuote(program2, opts) {
       pairs.push(["To", toInfo.symbol]);
     }
     pairs.push(
+      ["Wallet", fromAddress],
       ["Slippage", slippage === void 0 ? "API default" : `${slippage}%`],
       ["From Network", network],
       ["To Network", opts.toNetwork]
@@ -7317,11 +7557,16 @@ async function performBridgeExecute(program2, opts) {
   if (slippage !== void 0 && (isNaN(slippage) || slippage < 0 || slippage > 100)) {
     throw errInvalidArgs("Slippage must be a number between 0 and 100.");
   }
-  const quote = await withSpinner(
-    "Fetching bridge quote\u2026",
-    "Quote received",
-    () => swapClient.requestQuoteV0(createBridgeQuoteRequest(opts.from, opts.to, rawAmount, toChainId, slippage, paymaster))
-  );
+  let quote;
+  try {
+    quote = await withSpinner(
+      "Fetching bridge quote\u2026",
+      "Quote received",
+      () => swapClient.requestQuoteV0(createBridgeQuoteRequest(opts.from, opts.to, rawAmount, toChainId, slippage, paymaster, from))
+    );
+  } catch (err) {
+    throw normalizeQuoteError(err, "bridge");
+  }
   const preparedQuote = await prepareQuoteForExecution2(client, quote);
   const { id } = await withSpinner(
     "Sending bridge transaction\u2026",
@@ -7866,13 +8111,62 @@ function registerInstall(program2) {
 }
 
 // src/commands/doctor.ts
+var DOCTOR_SETUP_CAPABILITY_ORDER = SETUP_CAPABILITY_ORDER.filter(
+  (capability) => capability !== "x402"
+);
+function removeX402SetupMissing(missing) {
+  return missing.map(
+    (item) => item.replace(" OR SIWx wallet", "").replace(" or x402 wallet", "")
+  );
+}
+function removeX402NextCommands(commands) {
+  return commands.filter((command) => !/x402|siwx/i.test(command));
+}
+function sanitizeCapabilityStatus(status) {
+  if (status.satisfiedBy !== "x402_wallet") {
+    return {
+      ...status,
+      missing: removeX402SetupMissing(status.missing),
+      nextCommands: removeX402NextCommands(status.nextCommands)
+    };
+  }
+  return {
+    complete: false,
+    satisfiedBy: null,
+    missing: ["api-key"],
+    nextCommands: ["alchemy config set app", "alchemy config set api-key <key>"]
+  };
+}
+function doctorSetupStatus(setup) {
+  const { x402: _x402, ...capabilities } = setup.capabilities;
+  const sanitizedCapabilities = Object.fromEntries(
+    Object.entries(capabilities).map(([capability, status]) => [
+      capability,
+      sanitizeCapabilityStatus(status)
+    ])
+  );
+  const x402OnlySetup = setup.satisfiedBy === "x402_wallet";
+  return {
+    ...setup,
+    complete: x402OnlySetup ? false : setup.complete,
+    satisfiedBy: x402OnlySetup ? null : setup.satisfiedBy,
+    missing: x402OnlySetup ? ["Provide one auth path: alchemy auth OR api-key OR ALCHEMY_ACCESS_KEY+app"] : removeX402SetupMissing(setup.missing),
+    nextCommands: x402OnlySetup ? [
+      "alchemy auth",
+      "alchemy config set app",
+      "alchemy config set access-key <key> && alchemy config set app <app-id>"
+    ] : removeX402NextCommands(setup.nextCommands),
+    capabilities: sanitizedCapabilities
+  };
+}
 function registerDoctor(program2) {
   program2.command("doctor").description("Run readiness checks and print suggested fixes").action(() => {
-    const setup = getSetupStatus(load());
+    const setup = doctorSetupStatus(getSetupStatus(load()));
     const payload = {
       ok: setup.complete,
       checks: {
-        setup
+        setup,
+        capabilities: setup.capabilities
       }
     };
     if (isJSONMode()) {
@@ -7891,6 +8185,15 @@ function registerDoctor(program2) {
         console.log(`  ${command}`);
       }
     }
+    console.log("");
+    console.log(`  ${dim("Capabilities:")}`);
+    printKeyValue(
+      DOCTOR_SETUP_CAPABILITY_ORDER.map((capability) => {
+        const status = setup.capabilities[capability];
+        const value = status.complete ? green(`ready${status.satisfiedBy ? ` (${status.satisfiedBy})` : ""}`) : dim(`missing ${status.missing.join(", ")}`);
+        return [SETUP_CAPABILITY_LABELS[capability], value];
+      })
+    );
   });
 }
 
@@ -7987,9 +8290,15 @@ function resetUpdateNoticeState() {
   cachedAvailableUpdate = void 0;
   updateShownDuringInteractiveStartup = false;
 }
+async function flushProcessOutput() {
+  await Promise.all([
+    new Promise((resolve) => process.stdout.write("", () => resolve())),
+    new Promise((resolve) => process.stderr.write("", () => resolve()))
+  ]);
+}
 program.name("alchemy").description(
   "The Alchemy CLI lets you query blockchain data, call JSON-RPC methods, and manage your Alchemy configuration."
-).version("0.7.2-alpha.21", "-v, --version", "display CLI version").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option(
+).version("0.7.2-alpha.29", "-v, --version", "display CLI version").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option(
   "-n, --network <network>",
   "Target network (default: eth-mainnet) (env: ALCHEMY_NETWORK)"
 ).option("--x402", "Use x402 wallet-based gateway auth").option(
@@ -8176,17 +8485,17 @@ ${styledLine}`;
     "wallet"
   ];
   if (!skipAppPrompt.includes(cmdName) && isInteractiveAllowed(program) && !opts.apiKey && !process.env.ALCHEMY_API_KEY) {
-    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-ZCR3YCHJ.js");
+    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-WXT5ZCUK.js");
     const authToken = resolveAuthToken2(cfg);
     const hasApiKey = Boolean(cfg.api_key?.trim() || cfg.app?.apiKey);
     if (authToken && !hasApiKey) {
-      const { selectAppAfterAuth } = await import("./auth-7QNYRHIK.js");
+      const { selectAppAfterAuth } = await import("./auth-F2IXC6CM.js");
       console.log("");
       console.log(`  No app selected. Please select an app to continue.`);
       await selectAppAfterAuth(authToken);
     }
   }
-}).hook("postAction", () => {
+}).hook("postAction", async () => {
   if (!isJSONMode() && !quiet) {
     console.log("");
     if (!updateShownDuringInteractiveStartup) {
@@ -8196,6 +8505,7 @@ ${styledLine}`;
   }
   resetUpdateNoticeState();
   if (!isReplMode()) {
+    await flushProcessOutput();
     process.exit(0);
   }
 }).action(async (_opts, cmd) => {
@@ -8214,7 +8524,7 @@ ${styledLine}`;
   if (isInteractiveAllowed(program)) {
     let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-Y6HXW4CX.js");
+      const { runOnboarding } = await import("./onboarding-CF24FH7O.js");
       const latest = getAvailableUpdateOnce();
       const completed = await runOnboarding(program, latest);
       updateShownDuringInteractiveStartup = Boolean(latest);
@@ -8228,7 +8538,7 @@ ${styledLine}`;
         latestForInteractiveStartup
       );
     }
-    const { startREPL } = await import("./interactive-OFBUWRE4.js");
+    const { startREPL } = await import("./interactive-WRGKS7C5.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {