This is a hands-on walkthrough for adding a custom chain to MetaMask using the EIP-1193 method wallet_addEthereumChain, plus the manual fallback. I'll show the exact JSON payloads, common errors, and security checks I run before I approve any network add (I've made mistakes here — learned the hard way). If you want a focused walkthrough for Polygon specifically, see the step-by-step: [/how-to-add-polygon]. For developer-level notes check [/developer-integration].
wallet_addEthereumChain is a JavaScript RPC method that asks a software wallet (like MetaMask) to add a new EVM-compatible network to the user's list of networks. A dApp can call it so users don't have to copy/paste RPC URLs and chain IDs manually.
Under the hood the wallet checks the provided chain metadata (chainId, rpcUrls, nativeCurrency, blockExplorerUrls) and shows a permission prompt. The wallet does not get your private keys from this call — it only records the network details locally (and asks you to confirm).
But: even advanced users should verify RPC endpoints before approving anything. I once added an unreliable RPC that caused timeouts until I switched to a different endpoint. Learn from that.
General flow:
Code template (JS):
// Example helper: hexify a decimal chainId
function toHex(id) {
return '0x' + Number(id).toString(16);
}
async function ensureChain(provider, chainParams) {
const chainIdHex = toHex(chainParams.chainId);
try {
await provider.request({
method: 'wallet_switchEthereumChain',
params: [{ chainId: chainIdHex }]
});
return true; // switched successfully
} catch (switchError) {
// 4902 means chain is unknown/absent in the wallet
if (switchError.code === 4902) {
try {
await provider.request({
method: 'wallet_addEthereumChain',
params: [chainParams]
});
return true; // added and switched
} catch (addError) {
throw addError; // bubble up the add error
}
} else {
throw switchError; // other errors
}
}
}
Here's a practical payload for Polygon Mainnet (chainId 137). Always verify RPC URLs from the chain's official docs before using them in production.
const polygonParams = {
chainId: 137, // decimal
chainName: 'Polygon Mainnet',
nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
rpcUrls: ['https://polygon-rpc.com/'],
blockExplorerUrls: ['https://polygonscan.com/']
};
// call ensureChain(window.ethereum, polygonParams)
Note: the wallet_addEthereumChain payload above uses chainId as a decimal in our helper; MetaMask expects the chainId hex string when sent in the method params (the helper converts it). If you pass the wrong format you’ll get an invalid params error.
Error 4902 = chain not added. The pattern is: try switch -> catch 4902 -> call add -> user sees a confirmation. If the user rejects, the call throws error 4001. Catch and surface these to the user with a clear call-to-action.
If you prefer manual control (recommended for beginners):
Manual steps force you to read the RPC and explorer URLs before you hit Approve. For more on custom RPCs see [/custom-rpc] and this site’s specific guides like [/how-to-add-polygon] and [/add-bsc].
Mobile in-app browsers typically support wallet_addEthereumChain the same way the extension does. WalletConnect behaves differently depending on the connector version and the wallet on the other side.
And remember: UX differs. On mobile the confirmation modal can look slightly different and the RPC URL may be hidden behind a truncated string — read it carefully.
For mobile-specific tips see [/walletconnect-and-mobile-browser].
Adding a chain is not by itself dangerous. But attackers can abuse the flow:
Checklist before approving any add:
But don't stop there: only interact with tokens and approvals you understand. If a dApp asks for unlimited token allowance on a newly added chain, treat that as a red flag and review approvals later via [/revoke-approvals]. For broader safety reading see [/security-best-practices].
If the UI still behaves oddly, resetting the network list or reinstalling the extension (or reconnecting mobile) typically solves stale-state problems (see [/extension-troubleshooting] and [/mobile-sync-troubleshooting]).
Q: Is wallet_addEthereumChain safe? A: The call itself is safe (it doesn't expose private keys). The risk is in accepting untrusted RPCs. Verify chain metadata before approving.
Q: Will adding a custom network give the dApp access to my funds? A: No. Adding a network only stores metadata. A dApp still needs you to sign transactions to move funds.
Q: What happens if I lose my phone after adding a network on mobile? A: Network entries are part of the wallet state locally. If you restore your wallet using your seed phrase on a new device, you can re-add the custom network. See [/backup-and-recovery-options].
Q: How do I remove a network I added by mistake? A: Settings > Networks > select the network > Remove. If a dApp keeps prompting you, revoke site permissions in Settings.
Programmatic network addition (wallet_addEthereumChain) is a useful tool for developers and power users. It speeds onboarding for multi-chain dApps. But don't skip the verification steps—check chainId, RPC URL, and nativeCurrency before you approve. What I've found: a 30-second check prevents most headaches.
Want a guided walkthrough for a specific chain? See the Polygon guide: [/how-to-add-polygon]. If you're building a dApp that uses wallet_addEthereumChain, read the developer notes at [/developer-integration] and test WalletConnect behavior at [/walletconnect-and-mobile-browser].
If you found a buggy RPC or a malicious network call while testing, consider documenting the issue and revoke any suspicious approvals immediately (see [/revoke-approvals]).
Thanks for reading — test carefully, and double-check before you approve any network add.