Add Custom EVM-Compatible Networks to MetaMask

Add Custom EVM-Compatible Networks to MetaMask

---

Why add a custom EVM-compatible network?

If you use MetaMask to interact with DeFi, testnets, Layer 2s, or private chains, adding a custom network is routine. You add a custom RPC so the wallet talks to the right node, understands the chain ID, and shows the correct native currency. Short version: without the right network settings the wallet can't sign or send transactions on that chain.

Use cases: connecting to an L2 for cheaper gas, pointing MetaMask at a private test node during development, or adding a public EVM-compatible chain that isn't preinstalled. I've been adding and switching networks for months while testing dApps; the workflow is simple once you know the gotchas.

(Yes, custom networks apply only to EVM-compatible chains—Solana and other non-EVM chains require other wallets. See the Solana/Tron/Near guide: [/solana-tron-near].)

Quick steps — add a network in MetaMask (desktop & mobile)

Step-by-step. Follow these exact fields.

Desktop (extension)

1. Open the MetaMask extension and click the network dropdown at the top (where it says “Ethereum Mainnet” or the current network).
2. Choose “Add network” or “Add a network” (UI wording varies by version).
3. Fill in the form:
   • Network name: any friendly label.
   • New RPC URL: an HTTPS endpoint (example placeholder: https://rpc.example).
   • Chain ID: enter the decimal chain ID (e.g., 137 for Polygon). Don’t use hex here.
   • Currency symbol: the native token symbol (optional but helpful).
   • Block explorer URL: optional. Adds a link to view transactions.
4. Save.

Mobile (iOS / Android)

1. Open the app, tap the hamburger menu → Settings → Networks.
2. Tap Add Network, then fill the same fields as above.
3. Save and switch to the new network using the network selector in the app.

Note: Some older UI versions may label the option “Custom RPC.” If you can’t find the form, see setup-desktop or setup-mobile for screenshots.

Caption: Screenshot placeholder — network form fields (Network name, RPC URL, Chain ID, Currency symbol, Block explorer URL).

Programmatic method: metamask addethereumchain and metamask switchethereumchain

dApps can request MetaMask to add or switch chains using the EIP methods. These are the calls you’ll see in developer docs and in browser console traces.

• metamask addethereumchain: the RPC method name is wallet_addEthereumChain (EIP-3085). A dApp sends full network parameters and MetaMask prompts the user to add the chain.
• metamask switchethereumchain: the RPC method name is wallet_switchEthereumChain (EIP-3326). It tells MetaMask to switch to a chain by chainId.

Important gotcha: programmatic calls expect the chainId as a hex string (for example 0x89 for decimal 137). Manual UI entry expects a decimal Chain ID. And yes, that mismatch will trip people up. And it has tripped me more than once.

Example pattern (simplified):

// Attempt switch
await window.ethereum.request({
  method: 'wallet_switchEthereumChain',
  params: [{ chainId: '0x89' }], // Polygon mainnet as hex
}).catch(async (err) => {
  // If chain not found (error code 4902), request add
  if (err.code === 4902) {
    await window.ethereum.request({
      method: 'wallet_addEthereumChain',
      params: [{
        chainId: '0x89',
        chainName: 'Polygon Mainnet',
        rpcUrls: ['https://rpc.example'],
        nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
        blockExplorerUrls: ['https://explorer.example']
      }]
    });
  }
});

In my experience the prompt is reliable but don’t blindly approve a chain add request. Check the parameters before you accept.

For a dedicated how‑to on this method see [/how-to-wallet-addethereumchain].

Common mistakes and quick fixes

• Wrong chain ID format: Entered hex in the UI or decimal in the dApp request. Fix: use decimal in the UI, hex (0x...) in wallet_addEthereumChain/wallet_switchEthereumChain.
• RPC URL errors: If MetaMask shows “Failed to fetch” the RPC is down or uses HTTP. Use an HTTPS RPC or a different endpoint.
• Balance shows zero: The wallet may be connected to the right chain but not tracking tokens. Add the token manually (see [/tokens-management]).
• dApp can’t switch network: The dApp may be requesting a chain that MetaMask doesn't trust or the user declined. Try adding manually and then retry the dApp.
• How to remove a custom network: Open Settings → Networks → Select the custom network → Remove (UI varies by platform).

If transactions fail after switching networks, review gas settings and check EIP-1559 compatibility (see [/gas-fees-and-eip-1559]).

Security and privacy considerations

A custom RPC is a node. It gives the node operator visibility into your requests (addresses queried, transactions broadcast). That doesn’t mean they control your private keys, but it affects privacy and reliability. Don’t add unknown RPC URLs pushed by random websites.

A malicious dApp can call metamask addethereumchain to register a network that hides transactions or shows fake balances. It cannot directly extract your seed phrase; however, it can create confusing UI conditions to trick you into signing unsafe transactions. But don't approve chain adds from unknown pages.

Best practices:

• Verify chain parameters against the chain’s official docs or a trusted source.
• Prefer reputable public RPCs or run your own node when privacy matters.
• Keep a secure note with any custom RPC URLs and decimal chain IDs—these settings are not guaranteed to be restored automatically from a seed phrase across devices.
• Use a hardware wallet for large balances and connect it via MetaMask (see [/connect-ledger] and [/connect-trezor]).

If you need to remove previously added networks after suspected compromise, remove the network and revoke any approvals on that chain (see [/revoke-approvals]).

Who this is for (and who should look elsewhere)

Who this works for:

• DeFi users who interact with multiple EVM-compatible chains and L2s.
• Developers testing contracts on private or public testnets.
• Users who want to connect a desktop dApp via WalletConnect or an injected provider.

Who should look elsewhere:

• People who need non-EVM chain support (see [/solana-tron-near]).
• Users who require node-level privacy and don't want to rely on public RPC providers—consider running your own full node.
• Users uncomfortable approving dApp prompts or adding unknown RPCs; a hardware wallet plus restricted workflows might be a better fit.

Reference table: manual vs programmatic add

Method	How to trigger	Chain ID format	Pros	Cons
Manual UI (desktop/mobile)	User fills Settings → Networks → Add	Decimal (e.g., 137)	Full control, safe for single adds	Slow for automation, manual entry errors
Programmatic (wallet_addEthereumChain / wallet_switchEthereumChain)	dApp calls window.ethereum.request	Hex string (e.g., 0x89)	Fast UX; dApp can auto-prompt	Risk of accidental adds if dApp is malicious

FAQ

Q: Is it safe to add a custom RPC to MetaMask? A: It’s safe if you trust the RPC source. The RPC can’t steal your private keys, but it can affect privacy and display. Verify endpoints and decline unknown requests.

Q: Why did my dApp fail to switch the network? A: Commonly the chain wasn't added yet (error code 4902). Either add it manually or allow the dApp to call wallet_addEthereumChain.

Q: Will custom networks be restored if I restore my wallet with a seed phrase? A: Not reliably. Network definitions are stored locally in the wallet UI; keep a copy of RPC URLs and chain IDs elsewhere.

Q: What happens if I enter the wrong chain ID? A: Transactions will not route correctly and the UI may show errors. Remove and re-add with the correct decimal chain ID.

Conclusion and next steps

Adding custom EVM-compatible networks to MetaMask is a routine but precise task: use the right chain ID format, validate RPC endpoints, and never approve unexpected prompts. I recommend keeping a secure list of any custom RPCs you use and testing a small transaction first when you switch to a new chain.

Want step-by-step examples for popular chains? See how-to guides for Polygon, BSC, Avalanche, and Layer 2s [/add-optimism-arbitrum]. For developer-focused details on programmatic adds, open [/how-to-wallet-addethereumchain].

If you run into errors, check troubleshooting pages: extension-troubleshooting and mobile-sync-troubleshooting.

And remember: if a site asks you to add a chain out of the blue, stop and verify. Safe crypto is careful crypto.