fix(wallet): filter malformed payTo addresses in server payment options

Servers returning Solana payment options with EVM-format payTo addresses
(0x...) caused a base58 decode crash. Added address validation policy
that filters out network/address mismatches and falls back to valid
options. When all options are malformed, shows a clear error instead of
a cryptic codec failure.

Author: tenequm

packages/x402-proxy/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.4] - 2026-03-24
+
+### Fixed
+- Servers returning Solana payment options with EVM-format `payTo` addresses (e.g. `0x...`) no longer crash with a base58 decode error - malformed options are filtered out and valid options are used instead
+- When all payment options from a server have mismatched address formats, a clear error is shown instead of a cryptic codec failure
+
 ## [0.8.3] - 2026-03-24
 
 ### Added
@@ -230,7 +236,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.8.3...HEAD
+[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.8.4...HEAD
+[0.8.4]: https://github.com/cascade-protocol/x402-proxy/compare/v0.8.3...v0.8.4
 [0.8.3]: https://github.com/cascade-protocol/x402-proxy/compare/v0.8.2...v0.8.3
 [0.8.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.8.0...v0.8.1

packages/x402-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-proxy",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "curl for x402 paid APIs. Auto-pays any endpoint on Base, Solana, and Tempo. Also works as an OpenClaw plugin.",
   "type": "module",
   "sideEffects": false,

packages/x402-proxy/src/lib/resolve-wallet.test.ts

@@ -3,6 +3,7 @@ import type { PaymentRequirements } from "@x402/fetch";
 import { describe, expect, it } from "vitest";
 import { deriveSolanaKeypair } from "./derive.js";
 import {
+  createAddressValidationPolicy,
   createNetworkFilter,
   createNetworkPreference,
   networkToCaipPrefix,
@@ -123,6 +124,63 @@ describe("createNetworkPreference", () => {
   });
 });
 
+// --- createAddressValidationPolicy ---
+
+describe("createAddressValidationPolicy", () => {
+  const policy = createAddressValidationPolicy();
+
+  const validBaseReq = makeReq({
+    network: "eip155:8453",
+    payTo: "0x2cA6f53D5Fbc89d9a0658AEc0352a453ac991EC1",
+  });
+  const validSolanaReq = makeReq({
+    network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+    payTo: "AepWpq3GQwL8CeKMtZyKtKPa7W91Coygh3ropAJapVdU",
+  });
+  const malformedSolanaReq = makeReq({
+    network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+    payTo: "0x2cA6f53D5Fbc89d9a0658AEc0352a453ac991EC1",
+  });
+  const malformedEvmReq = makeReq({
+    network: "eip155:8453",
+    payTo: "AepWpq3GQwL8CeKMtZyKtKPa7W91Coygh3ropAJapVdU",
+  });
+
+  it("passes valid EVM and Solana options", () => {
+    expect(policy(2, [validBaseReq, validSolanaReq])).toEqual([validBaseReq, validSolanaReq]);
+  });
+
+  it("filters out Solana option with EVM payTo", () => {
+    expect(policy(2, [validBaseReq, malformedSolanaReq])).toEqual([validBaseReq]);
+  });
+
+  it("filters out EVM option with Solana payTo", () => {
+    expect(policy(2, [malformedEvmReq, validSolanaReq])).toEqual([validSolanaReq]);
+  });
+
+  it("falls back to valid option when first is malformed", () => {
+    expect(policy(2, [malformedSolanaReq, validBaseReq])).toEqual([validBaseReq]);
+  });
+
+  it("throws with clear message when all options are malformed", () => {
+    expect(() => policy(2, [malformedSolanaReq])).toThrow(
+      "Server returned only malformed payment options",
+    );
+    expect(() => policy(2, [malformedSolanaReq])).toThrow("Solana option has EVM-format payTo");
+  });
+
+  it("throws listing all malformed reasons when multiple bad options", () => {
+    expect(() => policy(2, [malformedSolanaReq, malformedEvmReq])).toThrow(
+      "payTo addresses don't match the advertised networks",
+    );
+  });
+
+  it("passes through unknown network types unchanged", () => {
+    const unknownReq = makeReq({ network: "cosmos:cosmoshub-4", payTo: "cosmos1xyz" });
+    expect(policy(2, [unknownReq])).toEqual([unknownReq]);
+  });
+});
+
 // --- resolveWallet with --solana-key ---
 
 describe("resolveWallet with solana key", () => {

packages/x402-proxy/src/lib/resolve-wallet.ts

@@ -125,6 +125,33 @@ export function networkToCaipPrefix(name: string): string {
   }
 }
 
+/**
+ * Validate that payTo addresses match the network format.
+ * Filters out malformed entries (e.g. EVM hex address on a Solana network).
+ */
+export function createAddressValidationPolicy(): PaymentPolicy {
+  return (_version, reqs) => {
+    const malformed: string[] = [];
+    const valid = reqs.filter((r) => {
+      if (r.network.startsWith("solana:") && r.payTo.startsWith("0x")) {
+        malformed.push(`Solana option has EVM-format payTo (${r.payTo})`);
+        return false;
+      }
+      if (r.network.startsWith("eip155:") && !r.payTo.startsWith("0x")) {
+        malformed.push(`EVM option has non-EVM payTo (${r.payTo})`);
+        return false;
+      }
+      return true;
+    });
+    if (valid.length === 0 && malformed.length > 0) {
+      throw new Error(
+        `Server returned only malformed payment options:\n  ${malformed.join("\n  ")}\nThe server's payTo addresses don't match the advertised networks.`,
+      );
+    }
+    return valid;
+  };
+}
+
 export function createNetworkFilter(network: string): PaymentPolicy {
   const prefix = networkToCaipPrefix(network);
   return (_version, reqs) => {
@@ -179,6 +206,8 @@ export async function buildX402Client(
     registerExactSvmScheme(client, { signer });
   }
 
+  client.registerPolicy(createAddressValidationPolicy());
+
   if (opts?.network) {
     client.registerPolicy(createNetworkFilter(opts.network));
   }