feat(cli): add --network flag, human-readable network names, and audit fixes

- Add --network flag (fetch + mcp) for hard network filtering with clear
  error when unavailable ("Available: Solana, Base")
- Display "Base"/"Solana" instead of raw CAIP-2 IDs in payment output
- Use wildcard scheme registration (eip155:*, solana:*) via SDK helpers
- Derive solanaAddress for --solana-key flag and env var sources
- Port balance auto-detection to MCP command
- Fix MCP payment history: add amount, to, correct network access
- Remove debug prefix stripping from payment amounts
- Show USDC balances with 4 decimal places

Author: tenequm

packages/x402-proxy/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-13
+
+### Added
+- `--network` flag for `fetch` and `mcp` commands - hard filter that requires a specific network (base, solana, or CAIP-2 ID), fails with clear error if unavailable
+- Human-readable network names in payment output ("Base", "Solana" instead of "eip155:8453")
+- `displayNetwork()` exported from library for mapping CAIP-2 IDs to display names
+
+### Fixed
+- Wildcard scheme registration (`eip155:*`, `solana:*`) via SDK helpers - payment signing now works for any EVM chain a server requests, not just Base
+- Solana address derivation for `--solana-key` flag and `X402_PROXY_WALLET_SOLANA_KEY` env var - balance detection, wallet display, and history recording were broken without it
+- MCP command now auto-detects preferred network based on USDC balance (same fix previously applied to `fetch`)
+- MCP payment history records now include `amount`, `to`, and correct `network` (removed fragile type cast)
+- Removed debug prefix stripping from payment amounts in handler
+- USDC balance display now shows 4 decimal places (was 2)
+
 ## [0.3.2] - 2026-03-13
 
 ### Added
@@ -95,7 +110,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `appendHistory` / `readHistory` / `calcSpend` - JSONL transaction history
 - Re-exports from `@x402/fetch`, `@x402/svm`, `@x402/evm`
 
-[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.2.1...v0.3.0

packages/x402-proxy/README.md

@@ -46,6 +46,9 @@ $ npx x402-proxy --method POST \
   --body '{"url":"https://x402.org"}' \
   https://web.surf.cascade.fyi/v1/crawl
 
+# Force a specific network
+$ npx x402-proxy --network base https://api.example.com/data
+
 # Pipe-safe
 $ npx x402-proxy https://api.example.com/data | jq '.results'
 ```

packages/x402-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-proxy",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "curl for x402 paid APIs. Auto-pays any endpoint on Base and Solana.",
   "type": "module",
   "sideEffects": false,

packages/x402-proxy/src/commands/fetch.ts

@@ -2,7 +2,7 @@ import { buildCommand, type CommandContext } from "@stricli/core";
 import type { PaymentRequired } from "@x402/fetch";
 import pc from "picocolors";
 import { createX402ProxyHandler, extractTxSignature } from "../handler.js";
-import { appendHistory, type TxRecord } from "../history.js";
+import { appendHistory, displayNetwork, type TxRecord } from "../history.js";
 import { ensureConfigDir, getHistoryPath, isConfigured, loadConfig } from "../lib/config.js";
 import { dim, error, info, isTTY } from "../lib/output.js";
 import { buildX402Client, resolveWallet } from "../lib/resolve-wallet.js";
@@ -13,6 +13,7 @@ type FetchFlags = {
   header: string[] | undefined;
   evmKey: string | undefined;
   solanaKey: string | undefined;
+  network: string | undefined;
   json: boolean;
 };
 
@@ -59,6 +60,12 @@ Examples:
         parse: String,
         optional: true,
       },
+      network: {
+        kind: "parsed",
+        brief: "Require specific network (base, solana)",
+        parse: String,
+        optional: true,
+      },
       json: {
         kind: "boolean",
         brief: "Force JSON output",
@@ -158,8 +165,27 @@ Examples:
     }
 
     const config = loadConfig();
+
+    // Auto-detect preferred network based on balance when not configured
+    let preferredNetwork = config?.defaultNetwork;
+    if (!preferredNetwork && wallet.evmAddress && wallet.solanaAddress) {
+      const { fetchEvmBalances, fetchSolanaBalances } = await import("./wallet.js");
+      const [evmBal, solBal] = await Promise.allSettled([
+        fetchEvmBalances(wallet.evmAddress),
+        fetchSolanaBalances(wallet.solanaAddress),
+      ]);
+      const evmUsdc = evmBal.status === "fulfilled" ? Number(evmBal.value?.usdc ?? 0) : 0;
+      const solUsdc = solBal.status === "fulfilled" ? Number(solBal.value?.usdc ?? 0) : 0;
+      if (evmUsdc > solUsdc) {
+        preferredNetwork = "base";
+      } else if (solUsdc > evmUsdc) {
+        preferredNetwork = "solana";
+      }
+    }
+
     const client = await buildX402Client(wallet, {
-      preferredNetwork: config?.defaultNetwork,
+      preferredNetwork,
+      network: flags.network,
       spendLimitDaily: config?.spendLimitDaily,
       spendLimitPerTx: config?.spendLimitPerTx,
     });
@@ -196,7 +222,7 @@ Examples:
     const payment = shiftPayment();
     const txSig = extractTxSignature(response);
 
-    // Payment failed - show funding instructions from the endpoint's actual requirements
+    // Payment failed - check balances and show appropriate message
     if (response.status === 402 && isTTY()) {
       const prHeader =
         response.headers.get("PAYMENT-REQUIRED") ?? response.headers.get("X-PAYMENT-REQUIRED");
@@ -210,14 +236,14 @@ Examples:
         }
       }
 
+      let costNum = 0;
+      let costStr = "?";
       if (accepts.length > 0) {
         const cheapest = accepts.reduce((min, a) =>
           Number(a.amount) < Number(min.amount) ? a : min,
         );
-        const cost = (Number(cheapest.amount) / 1_000_000).toFixed(4);
-        error(`Payment required: ${cost} USDC`);
-      } else {
-        error("Payment required");
+        costNum = Number(cheapest.amount) / 1_000_000;
+        costStr = costNum.toFixed(4);
       }
 
       const hasEvm = accepts.some((a) => a.network.startsWith("eip155:"));
@@ -226,37 +252,104 @@ Examples:
         (a) => !a.network.startsWith("eip155:") && !a.network.startsWith("solana:"),
       );
 
-      if (hasEvm || hasSolana) {
+      // Check on-chain balances to give actionable feedback
+      const { fetchEvmBalances, fetchSolanaBalances } = await import("./wallet.js");
+      let evmUsdc = 0;
+      let solUsdc = 0;
+      if (hasEvm && wallet.evmAddress) {
+        try {
+          const bal = await fetchEvmBalances(wallet.evmAddress);
+          evmUsdc = Number(bal.usdc);
+        } catch {
+          // Network error - fall through with 0
+        }
+      }
+      if (hasSolana && wallet.solanaAddress) {
+        try {
+          const bal = await fetchSolanaBalances(wallet.solanaAddress);
+          solUsdc = Number(bal.usdc);
+        } catch {
+          // Network error - fall through with 0
+        }
+      }
+
+      const hasSufficientBalance =
+        (hasEvm && evmUsdc >= costNum) || (hasSolana && solUsdc >= costNum);
+
+      if (hasSufficientBalance) {
+        // Balance is sufficient but payment failed - read server error
+        let serverReason: string | undefined;
+        try {
+          const body = await response.text();
+          if (body) {
+            const parsed = JSON.parse(body) as { error?: string; message?: string };
+            serverReason = parsed.error || parsed.message;
+          }
+        } catch {
+          // Not JSON or no body
+        }
+
+        error(`Payment failed: ${costStr} USDC`);
         console.error();
-        dim("  Fund your wallet with USDC:");
-        if (hasEvm && wallet.evmAddress) {
-          console.error(`    Base:   ${pc.cyan(wallet.evmAddress)}`);
+        if (payment) {
+          dim("  Payment was signed and sent but rejected by the server.");
+        } else {
+          dim("  Payment was not attempted despite sufficient balance.");
         }
-        if (hasSolana && wallet.solanaAddress) {
-          console.error(`    Solana: ${pc.cyan(wallet.solanaAddress)}`);
+        if (serverReason) {
+          dim(`  Reason: ${serverReason}`);
         }
-        if (hasEvm && !wallet.evmAddress) {
-          dim("    Base:   endpoint accepts EVM but no EVM wallet configured");
+        if (hasEvm && wallet.evmAddress && evmUsdc > 0) {
+          console.error(
+            `    Base:   ${pc.cyan(wallet.evmAddress)} ${pc.dim(`(${evmUsdc.toFixed(4)} USDC)`)}`,
+          );
         }
-        if (hasSolana && !wallet.solanaAddress) {
-          dim("    Solana: endpoint accepts Solana but no Solana wallet configured");
+        if (hasSolana && wallet.solanaAddress && solUsdc > 0) {
+          console.error(
+            `    Solana: ${pc.cyan(wallet.solanaAddress)} ${pc.dim(`(${solUsdc.toFixed(4)} USDC)`)}`,
+          );
         }
-      } else if (hasOther) {
-        const networks = [...new Set(accepts.map((a) => a.network))].join(", ");
         console.error();
-        error(`This endpoint only accepts payment on unsupported networks: ${networks}`);
-      }
+        dim("  This may be a temporary server-side issue. Try again in a moment.");
+        console.error();
+      } else {
+        // Insufficient balance
+        error(`Payment required: ${costStr} USDC`);
+
+        if (hasEvm || hasSolana) {
+          console.error();
+          dim("  Fund your wallet with USDC:");
+          if (hasEvm && wallet.evmAddress) {
+            const balHint = evmUsdc > 0 ? pc.dim(` (${evmUsdc.toFixed(4)} USDC)`) : "";
+            console.error(`    Base:   ${pc.cyan(wallet.evmAddress)}${balHint}`);
+          }
+          if (hasSolana && wallet.solanaAddress) {
+            const balHint = solUsdc > 0 ? pc.dim(` (${solUsdc.toFixed(4)} USDC)`) : "";
+            console.error(`    Solana: ${pc.cyan(wallet.solanaAddress)}${balHint}`);
+          }
+          if (hasEvm && !wallet.evmAddress) {
+            dim("    Base:   endpoint accepts EVM but no EVM wallet configured");
+          }
+          if (hasSolana && !wallet.solanaAddress) {
+            dim("    Solana: endpoint accepts Solana but no Solana wallet configured");
+          }
+        } else if (hasOther) {
+          const networks = [...new Set(accepts.map((a) => a.network))].join(", ");
+          console.error();
+          error(`This endpoint only accepts payment on unsupported networks: ${networks}`);
+        }
 
-      console.error();
-      dim("  Then re-run:");
-      console.error(`    ${pc.cyan(`$ npx x402-proxy ${url}`)}`);
-      console.error();
+        console.error();
+        dim("  Then re-run:");
+        console.error(`    ${pc.cyan(`$ npx x402-proxy ${url}`)}`);
+        console.error();
+      }
       return;
     }
 
     if (payment && isTTY()) {
       info(
-        `  Payment: ${payment.amount ? (Number(payment.amount) / 1_000_000).toFixed(4) : "?"} USDC (${payment.network ?? "unknown"})`,
+        `  Payment: ${payment.amount ? (Number(payment.amount) / 1_000_000).toFixed(4) : "?"} USDC (${displayNetwork(payment.network ?? "unknown")})`,
       );
       if (txSig) dim(`  Tx: ${txSig}`);
     }

packages/x402-proxy/src/commands/mcp.ts

@@ -1,14 +1,15 @@
 declare const __VERSION__: string;
 
 import { buildCommand, type CommandContext } from "@stricli/core";
-import { appendHistory, type TxRecord } from "../history.js";
+import { appendHistory, displayNetwork, type TxRecord } from "../history.js";
 import { ensureConfigDir, getHistoryPath, loadConfig } from "../lib/config.js";
 import { dim, error, warn } from "../lib/output.js";
 import { buildX402Client, resolveWallet } from "../lib/resolve-wallet.js";
 
 type McpFlags = {
   evmKey: string | undefined;
   solanaKey: string | undefined;
+  network: string | undefined;
 };
 
 export const mcpCommand = buildCommand<McpFlags, [remoteUrl: string], CommandContext>({
@@ -35,6 +36,12 @@ Add to your MCP client config (Claude, Cursor, etc.):
         parse: String,
         optional: true,
       },
+      network: {
+        kind: "parsed",
+        brief: "Require specific network (base, solana)",
+        parse: String,
+        optional: true,
+      },
     },
     positional: {
       kind: "tuple",
@@ -66,8 +73,27 @@ Add to your MCP client config (Claude, Cursor, etc.):
     if (wallet.solanaAddress) dim(`  Solana: ${wallet.solanaAddress}`);
 
     const config = loadConfig();
+
+    // Auto-detect preferred network based on balance when not configured
+    let preferredNetwork = config?.defaultNetwork;
+    if (!preferredNetwork && wallet.evmAddress && wallet.solanaAddress) {
+      const { fetchEvmBalances, fetchSolanaBalances } = await import("./wallet.js");
+      const [evmBal, solBal] = await Promise.allSettled([
+        fetchEvmBalances(wallet.evmAddress),
+        fetchSolanaBalances(wallet.solanaAddress),
+      ]);
+      const evmUsdc = evmBal.status === "fulfilled" ? Number(evmBal.value?.usdc ?? 0) : 0;
+      const solUsdc = solBal.status === "fulfilled" ? Number(solBal.value?.usdc ?? 0) : 0;
+      if (evmUsdc > solUsdc) {
+        preferredNetwork = "base";
+      } else if (solUsdc > evmUsdc) {
+        preferredNetwork = "solana";
+      }
+    }
+
     const x402PaymentClient = await buildX402Client(wallet, {
-      preferredNetwork: config?.defaultNetwork,
+      preferredNetwork,
+      network: flags.network,
       spendLimitDaily: config?.spendLimitDaily,
       spendLimitPerTx: config?.spendLimitPerTx,
     });
@@ -89,7 +115,10 @@ Add to your MCP client config (Claude, Cursor, etc.):
       onPaymentRequested: (ctx) => {
         const accept = ctx.paymentRequired.accepts?.[0];
         if (accept) {
-          warn(`  Payment: ${accept.amount} on ${accept.network} for tool "${ctx.toolName}"`);
+          const amount = accept.amount ? (Number(accept.amount) / 1_000_000).toFixed(4) : "?";
+          warn(
+            `  Payment: ${amount} USDC on ${displayNetwork(accept.network)} for tool "${ctx.toolName}"`,
+          );
         }
         return true;
       },
@@ -98,15 +127,17 @@ Add to your MCP client config (Claude, Cursor, etc.):
     // Track payments
     x402Mcp.onAfterPayment(async (ctx) => {
       ensureConfigDir();
+      const accepted = ctx.paymentPayload.accepted;
       const tx = ctx.settleResponse?.transaction;
-      const accept = ctx.paymentPayload;
       const record: TxRecord = {
         t: Date.now(),
         ok: true,
         kind: "x402_payment",
-        net: (accept as { network?: string }).network ?? "unknown",
+        net: accepted?.network ?? "unknown",
         from: wallet.evmAddress ?? wallet.solanaAddress ?? "unknown",
+        to: accepted?.payTo,
         tx: typeof tx === "string" ? tx : undefined,
+        amount: accepted?.amount ? Number(accepted.amount) / 1_000_000 : undefined,
         token: "USDC",
         label: `mcp:${ctx.toolName}`,
       };

packages/x402-proxy/src/commands/wallet.ts

@@ -36,7 +36,7 @@ export async function fetchEvmBalances(address: string): Promise<{ eth: string;
   ])) as [RpcResult, RpcResult];
 
   const eth = ethRes.result ? (Number(BigInt(ethRes.result)) / 1e18).toFixed(6) : "?";
-  const usdc = usdcRes.result ? (Number(BigInt(usdcRes.result)) / 1e6).toFixed(2) : "?";
+  const usdc = usdcRes.result ? (Number(BigInt(usdcRes.result)) / 1e6).toFixed(4) : "?";
   return { eth, usdc };
 }
 
@@ -53,8 +53,8 @@ export async function fetchSolanaBalances(address: string): Promise<{ sol: strin
   const sol = solRes.result?.value != null ? (solRes.result.value / 1e9).toFixed(6) : "?";
   const accounts = usdcRes.result?.value;
   const usdc = accounts?.length
-    ? Number(accounts[0].account.data.parsed.info.tokenAmount.uiAmountString).toFixed(2)
-    : "0.00";
+    ? Number(accounts[0].account.data.parsed.info.tokenAmount.uiAmountString).toFixed(4)
+    : "0.0000";
   return { sol, usdc };
 }
 
@@ -112,8 +112,8 @@ export const walletInfoCommand = buildCommand<{ verbose: boolean }, [], CommandC
     }
 
     // Funding hint when both USDC balances are zero
-    const evmEmpty = !evm || evm.usdc === "0.00";
-    const solEmpty = !sol || sol.usdc === "0.00";
+    const evmEmpty = !evm || evm.usdc === "0.0000";
+    const solEmpty = !sol || sol.usdc === "0.0000";
     if (evmEmpty && solEmpty) {
       console.log();
       dim("  Send USDC to either address above to start using x402 APIs.");

packages/x402-proxy/src/handler.ts

@@ -57,7 +57,7 @@ export function createX402ProxyHandler(opts: X402ProxyOptions): X402ProxyHandler
     paymentQueue.push({
       network: hookCtx.selectedRequirements.network,
       payTo: hookCtx.selectedRequirements.payTo,
-      amount: raw?.startsWith("debug.") ? raw.slice(6) : raw,
+      amount: raw,
       asset: hookCtx.selectedRequirements.asset,
     });
   });