EIPs

EIP-3326 — wallet_switchEthereumChain

eips.ethereum.org/EIPS/eip-3326

Switches the wallet’s active chain.

import { wallet_switchEthereumChain } from "@ethernauta/eip/3326";
import type { Provider } from "@ethernauta/eip/1193";
import { create_provider, encode_chain_id } from "@ethernauta/transport";
import { eip155_1 } from "@ethernauta/chain/eip155-1";
import { UintSchema } from "@ethernauta/core";
import { parse } from "valibot";

const CHAIN_ID = encode_chain_id({ namespace: "eip155", reference: eip155_1.chainId });
declare const provider: Provider; // see /eips/6963 for discovery
const { signer } = create_provider(provider);

await wallet_switchEthereumChain([
  { chainId: parse(UintSchema, "0x2105") },  // Base
])(signer({ chain_id: CHAIN_ID }));

Surface

ExportTypePurpose
wallet_switchEthereumChainSignable<null>Request the switch.
SwitchEthereumChainParameter, SwitchEthereumChainParameterstypes
schemas

Error handling

If the chain isn’t recognized, the wallet returns error code 4902 (unrecognized_chain). The canonical pattern:

import { wallet_switchEthereumChain } from "@ethernauta/eip/3326";
import {
  wallet_addEthereumChain,
  type AddEthereumChainParameter,
} from "@ethernauta/eip/3085";
import type { Provider } from "@ethernauta/eip/1193";
import { create_provider, encode_chain_id } from "@ethernauta/transport";
import { eip155_1 } from "@ethernauta/chain/eip155-1";
import { UintSchema } from "@ethernauta/core";
import { parse } from "valibot";

const current = encode_chain_id({ namespace: "eip155", reference: eip155_1.chainId });
declare const provider: Provider; // see /eips/6963 for discovery
const { signer } = create_provider(provider);

const chainId = parse(UintSchema, "0x2105");
const chain_definition: AddEthereumChainParameter = {
  chainId,
  chainName: "Base",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: ["https://base-rpc.publicnode.com"],
};

try {
  await wallet_switchEthereumChain([{ chainId }])(signer({ chain_id: current }));
} catch (err) {
  if (err instanceof Error && "code" in err && err.code === 4902) {
    await wallet_addEthereumChain([chain_definition])(signer({ chain_id: current }));
    await wallet_switchEthereumChain([{ chainId }])(signer({ chain_id: current }));
  } else {
    throw err;
  }
}

Wallet behavior

The wallet may either auto-accept (chain previously authorized) or prompt the user. Auto-accept is the default for chains the user has used before; the Ethernauta wallet’s select-chain view shows up only on first switch to a given chain.

The chainChanged event (EIP-1193) fires after the switch settles.

See also