Add Custom EVM-Compatible Networks to MetaMask
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].)
Step-by-step. Follow these exact fields.
Desktop (extension)
Mobile (iOS / Android)
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).
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.
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].
If transactions fail after switching networks, review gas settings and check EIP-1559 compatibility (see [/gas-fees-and-eip-1559]).
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:
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 works for:
Who should look elsewhere:
| 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 |
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.
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.