# Agent instructions

You are advising on UX and product design for **EIP-3326: wallet_switchEthereumChain**.
This document is editorial design guidance from EIPs for Designers. Official specifications control protocol facts.

- **Spec Constraints** quote the official specification. Preserve the stated audience, conditions, and source classification. Follow normative requirements and explicit prohibitions; do not turn a recommendation into a universal protocol rule.
- **Anti-Patterns** and design implications are editorial UX guidance. Apply judgment and resolve factual conflicts in favor of the official specification.
- Use the **Vocabulary** section as editorial copy guidance without hiding permissions, risks, or account authority.
- Cite the canonical source URL when giving recommendations.
- Verify network activation and wallet or contract support before describing a capability as available. Specification status alone does not establish deployment.

---

# EIP-3326: wallet_switchEthereumChain

Source: https://www.eipsfordesigners.com/standards/EIP-3326
Agent brief: https://www.eipsfordesigners.com/standards/EIP-3326/agent.md
Machine-readable JSON: https://www.eipsfordesigners.com/api/standards/EIP-3326
Last reviewed: 2026-09-18
Last updated: 2026-09-18

| Field | Value |
| --- | --- |
| Status | Stagnant |
| Chain | ethereum |
| Category | Transaction Friction |
| Journey stages | Discovery & Connection, Executing Transactions |
| Detailed guide | Yes |
| Official specification | https://eips.ethereum.org/EIPS/eip-3326 |
| Discussion search | https://ethereum-magicians.org/search?q=EIP-3326 |

## UX Impact

EIP-3326 defines wallet_switchEthereumChain, a request for a wallet with an active-chain concept to switch to a known chain. The specification is Stagnant and recommends explicit confirmation and cancellation of chain-specific pending work; implementation details, supported chains, and error handling remain wallet-specific.

## Summary

EIP-3326 defines wallet_switchEthereumChain, a request for a wallet with an active-chain concept to switch to a known chain. The specification is Stagnant and recommends explicit confirmation and cancellation of chain-specific pending work; implementation details, supported chains, and error handling remain wallet-specific.

## What does not work everywhere yet

MetaMask Connect documents a current implementation, including error 4902 for an unrecognized chain. That documentation does not establish support in every wallet or connection type. Feature-detect the method, handle rejection and unknown-chain errors, and verify the active chain after the request.

## For Designers

- Name the requester and destination network in the handoff, then verify the provider's active chain before resuming an action.
- Cancel or invalidate pending network-specific quotes, signatures, and transaction requests when the chain changes.
- Treat an unknown-chain response as a separate add-network step rather than repeatedly prompting the user to switch.

## Applicability

### When to Use

- A dapp has a verified network requirement and the wallet exposes one active chain.
- The product can safely pause and revalidate the current action after a chain change.
- The user benefits from returning to the same task after a wallet network handoff.

### When to Avoid

- The connection model supports multiple active chains or the wallet does not implement the method.
- The app would continue using a quote, signature, or pending request created for the previous chain.
- The target chain is not already known to the wallet and no explicit add-network flow is available.

## Problems It Solves

### A dapp continues using stale data after the network changes

Impact: critical

Old way: Keep the previous quote, contract address, or signature request alive across the switch.

New way: Invalidate chain-specific work and rebuild it after provider verification.

### Users must open wallet settings to reach a known network

Impact: high

Old way: Leave the dapp, search for the network, switch manually, then find the task again.

New way: A compatible wallet can request a switch to a known chain from the dapp.

### Users cannot tell whether the handoff completed

Impact: high

Old way: Dismiss the error or spinner and hope the wallet changed networks.

New way: Listen for the provider chain change and show a verified return state.

## Spec Constraints

Quotes retain their source section and scope. Normative requirements, rationale, compatibility changes, and security recommendations are not interchangeable. Design implications are editorial guidance.

### A wallet rejects a chain-switch request when its fields are invalid, the chain is unknown, or the wallet cannot service the chain.

Applies to: wallet
Source classification: normative

> If a field does not meet the requirements of this specification, the wallet **MUST** reject the request.

Source: [Specification — walletswitchEthereumChain — Parameters](https://eips.ethereum.org/EIPS/eip-3326#parameters)

Design implication (editorial): Show a clear unsupported or unavailable network state before asking the user to confirm a switch.

### A successful chain switch returns `null`; an unsupported active-chain concept or other failure returns an error.

Applies to: application
Source classification: normative

> The method **MUST** return `null` if the request was successful, and an error otherwise.

Source: [Specification — walletswitchEthereumChain — Returns](https://eips.ethereum.org/EIPS/eip-3326#returns)

Design implication (editorial): Wait for the wallet result and then refresh network-specific data. Do not treat a request dispatch as a completed switch.

### Wallets should confirm the requester and target chain, then cancel pending chain-specific requests and confirmations after a switch.

Applies to: wallet
Source classification: security-considerations

> ## Security Considerations
> 
> For wallets with a concept of an active chain, switching the active chain has significant implications for pending RPC requests and the user's experience.
> If the active chain switches without the user's awareness, a dapp could induce the user to take actions for unintended chains.
> 
> In light of this, the wallet should:
> 
> - Display a confirmation whenever a `wallet_switchEthereumChain` is received, clearly identifying the requester and the chain that will be switched to.
>   - The confirmation used in [EIP-1102](./eip-1102.md) may serve as a point of reference.
> - When switching the active chain, cancel all pending RPC requests and chain-specific user confirmations.

Source: [Security Considerations](https://eips.ethereum.org/EIPS/eip-3326#security-considerations)

Design implication (editorial): Name the requesting app and target chain in the confirmation. Clear stale network-specific forms and pending confirmations after the switch.

### Automatically rejecting unsupported chains can reveal which chains a wallet supports.

Applies to: wallet
Source classification: security-considerations

> ### Preserving User Privacy
> 
> Automatically rejecting requests for chains that aren't supported or have yet to be added by the wallet allows requesters to infer which chains are supported by the wallet.
> Wallet implementers should consider whether this communication channel violates any security properties of the wallet, and if so, take appropriate steps to mitigate it.

Source: [Security Considerations — Preserving User Privacy](https://eips.ethereum.org/EIPS/eip-3326#preserving-user-privacy)

Design implication (editorial): Treat unsupported-chain responses as a privacy decision and avoid exposing the wallet’s full supported-chain inventory unnecessarily.

## Anti-Patterns (editorial)

- **Switching silently in the background** (critical)
  - Why: A dapp could cause a user to take a sensitive action on an unintended chain.
  - Instead: Name the requester and destination chain and rely on wallet confirmation.

- **Continuing with a quote or signature from the old chain** (critical)
  - Why: Chain-bound data can point to the wrong contract, asset, or replay domain.
  - Instead: Invalidate and refresh chain-specific work after chainChanged.

- **Treating error 4902 as a generic transaction failure** (high)
  - Why: The user needs a network-add recovery path, not a retry loop.
  - Instead: Offer EIP-3085 setup when the wallet supports it and otherwise explain manual setup.

- **Calling the switch method without feature detection** (medium)
  - Why: Provider implementations differ and may reject unknown methods.
  - Instead: Detect support, handle user rejection, and keep manual switching available.

## Design Decisions

### What should the user see before a switch?

Recommendation: Show the current chain, destination chain ID and name, requester, and which pending work will be refreshed.

Rationale: A silent chain switch can make a familiar action target a different contract or asset.

### What happens to a pending signature?

Recommendation: Cancel or discard chain-specific confirmations and rebuild the request after the switch.

Rationale: The EIP calls for cancelling pending RPC requests and confirmations tied to the old chain.

### When should add-network appear?

Recommendation: Use an explicit add step after a recognized unknown-chain response, with the same metadata review as EIP-3085.

Rationale: Switching does not define how an unknown chain becomes known to the wallet.

## States to Design

### Switch pending

Trigger: The wallet confirmation is open.

User need: Know why the wallet is asking to change networks.

Design response: Show current and destination chains and hold the action in a paused state.

### Switched, action revalidating

Trigger: The provider emits the expected chain change.

User need: Know whether the original action is still valid.

Design response: Refresh chain-bound reads and quotes before restoring the primary action.

### Unknown chain

Trigger: The wallet does not know the requested chain; MetaMask documents error code 4902 for this case.

User need: Understand why switching stopped and what setup is required.

Design response: Offer an add-network handoff using verified metadata, then retry switching only after the add result is known.

### Rejected or unsupported

Trigger: The user declines or the provider does not implement the method.

User need: A clear way to remain safe on the current chain.

Design response: Keep the current context explicit, preserve the action where safe, and show manual switching instructions.

### Wrong chain after request

Trigger: The request returned but eth_chainId does not match the destination.

User need: Avoid signing or submitting to the wrong network.

Design response: Block the chain-specific action and ask the user to recheck the wallet network.

## Vocabulary

- Use "Switch network" instead of "Move funds": The method changes the wallet's active RPC context; it does not transfer assets.

- Use "Refreshing for [network]" instead of "Transaction pending": A chain switch is a provider context change, not an on-chain transaction.

- Use "This network is not added yet" instead of "Network unavailable": The chain may be healthy; the wallet simply may not know its configuration.

## UX Patterns

### Safe Network Handoff

Pause the current task, request a wallet switch, then revalidate and continue on the selected chain.

Components: Current-network badge, Destination-network card, Pending-work notice, Revalidation status

User flow:

- Detect the required chain
- Show current and destination network
- Request wallet_switchEthereumChain
- Listen for chainChanged and verify eth_chainId
- Refresh chain-specific data
- Resume or show a recovery action

### Add Then Switch

Handle an unknown destination as a verified add-network step before retrying the switch.

Components: Add-network handoff, Unknown-chain explanation, Retry switch, Manual fallback

User flow:

- Request a switch to a known chain ID
- Receive an unknown-chain response
- Review verified add-network metadata
- Request wallet_addEthereumChain
- Retry switch and verify active chain

## What to Prototype First

### Switch-network confirmation

A chain switch changes where subsequent reads, signatures, and transactions are directed.

Covers: Supported chain, User rejection, Unknown chain

- Requester identity
- Current and destination chain
- Pending-work cancellation notice
- Back-to-task behavior

### Stale action recovery

A switch can invalidate the assumptions behind the action that triggered it.

Covers: Quote expired, Wrong-chain signature, Action revalidated

- Fresh quote marker
- Network-bound data refresh
- Retry and cancel

## Mental Model

### Active chain

The wallet forwards chain-specific RPC requests to one selected network for this connection.

### Switch request

The dapp asks the wallet to select a known chain by hexadecimal chain ID; the wallet decides whether to approve it.

### Pending-work boundary

A switch changes the context for reads and confirmations, so pending chain-specific work must be cancelled or rechecked.

### Verified return

The app resumes only after the provider reports the expected chain ID and the current action has been rebuilt for that chain.

## UI Components

### NetworkSwitchStatus

Shows the current chain, requested destination, wallet response, and active-chain verification.
Kind: status
States: ready, waiting, switched, unknown-chain, rejected, mismatch
Props: currentChainId, requestedChainId, error, onRetry, onCancel

### StaleActionNotice

Explains which quote, signature, or request was invalidated by the chain change.
Kind: status
States: refreshing, refreshed, blocked
Props: resourceType, oldChainId, newChainId, onRefresh

## Key Takeaways

- EIP-3326 is Stagnant; current support is wallet-specific.
- A switch must be visible and must invalidate chain-specific pending work.
- Error 4902 can lead to EIP-3085 add-network recovery in supported wallets.
- Verify the active chain before signing or submitting the resumed action.

## Related Standards

- EIP-3085: Request a wallet to add the destination chain when it is not known. — https://www.eipsfordesigners.com/standards/EIP-3085/agent.md

- EIP-1193: Provider request and chainChanged event transport. — https://www.eipsfordesigners.com/standards/EIP-1193/agent.md

- EIP-155: Chain ID used to distinguish transaction domains. — https://www.eipsfordesigners.com/standards/EIP-155/agent.md

## Technical Notes

wallet_switchEthereumChain accepts an object with a hexadecimal chainId and returns null if the wallet switched its active chain. The wallet must reject malformed or unknown chain IDs and may reject a valid request. If the wallet has no active-chain concept it must reject the request. Wallets should show confirmation, identify the requester and destination, and cancel pending chain-specific RPC requests and confirmations. MetaMask documents error 4902 for an unrecognized chain.

## Official specification (reference only)

https://eips.ethereum.org/EIPS/eip-3326