You can offer an EVM network to a user’s wallet with one wallet_addEthereumChain request, replacing manual entry of its chain ID, RPC endpoint and currency. The dApp supplies the details; the wallet checks them and asks the user to approve the addition.
Think of a user opening a Polygon dApp while their wallet is set to Ethereum. The dApp can ask the wallet to save Polygon’s network settings. Adding Polygon and making Polygon the active network are separate actions.
The wallet checks the network before saving it
A wallet_addEthereumChain call sends one object in the params array of a wallet JSON-RPC request. Its fields have distinct jobs:
- chainId identifies the chain as a hexadecimal string. Polygon’s decimal ID, 137, is 0x89.
- chainName gives the wallet a readable name for its network menu.
- nativeCurrency supplies the currency’s name, symbol and decimals for wallet displays.
- rpcUrls supplies endpoints the wallet can use to communicate with the chain.
- blockExplorerUrls supplies links for viewing transactions and addresses.
Here is an illustrative complete Polygon call using one RPC endpoint: ethereum.request({ method: 'wallet_addEthereumChain', params: [{ chainId: '0x89', chainName: 'Polygon Mainnet', nativeCurrency: { name: 'POL', symbol: 'POL', decimals: 18 }, rpcUrls: ['https://polygon-bor-rpc.publicnode.com'], blockExplorerUrls: ['https://polygonscan.com'] }] });
Under EIP-3085, the wallet checks the fields and must reject an RPC URL whose eth_chainId response differs from the requested chainId. MetaMask performs this check, so an endpoint serving another chain will fail the add request. The wallet then presents its approval prompt. A successful request returns null; a refusal or validation failure returns an error.
Before that illustrative call, the user’s MetaMask has no saved Polygon entry. After approval, it has Polygon’s network details, while the user’s account remains the same. The active network may also remain Ethereum: EIP-3085 does not require a switch after adding.
Chainlist’s add buttons send this same request to a connected wallet. Before committing network settings to your app, compare the chain ID, currency and candidate RPC on Chainlist, then verify the endpoint’s eth_chainId response yourself.
For a reliable flow, request wallet_switchEthereumChain with { chainId: '0x89' } first. If the wallet already knows Polygon, it can switch without an add prompt. If MetaMask returns 4902, meaning the chain is unrecognized, send the add request and then request the switch again. Surface other errors, including a user rejection, instead of treating every failed switch as a missing network. MetaMask documents this 4902 fallback; wallet error behavior can vary.
Keep the Polygon object in one versioned configuration shared by every app entry point. Review changes to its RPC URL, explorer and currency fields before release, so each flow sends identical values. Next, test both a wallet that already knows Polygon and a fresh wallet; those two cases confirm that your switch and add paths reach the intended chain.
Related terms clarify what the request adds
These terms distinguish a network entry from an asset entry and explain the ID the wallet verifies.
What is wallet_watchAsset (EIP-747)?
wallet_watchAsset asks a wallet to track an asset, such as a token identified by its contract address. wallet_addEthereumChain asks it to add a network configuration. A dApp may need both requests, but adding Polygon does not add a token to the wallet’s asset display.
What is an EIP-155 chain ID?
An EIP-155 chain ID is a number used in transaction signing to distinguish chains and prevent a transaction signed for one chain from being replayed on another. wallet_addEthereumChain represents that number as a hexadecimal string; for Polygon, 137 becomes 0x89.
Questions teams ask after adding a network
Adding a network changes the wallet’s saved configuration; later requests still depend on the wallet and connection in use.
Can a dApp remove a network from a user's wallet?
No standard counterpart to wallet_addEthereumChain lets a dApp remove a saved network. The user manages saved networks in their wallet. Your app can stop offering a network and remove it from its own configuration, but that does not delete the user’s wallet entry.
Does wallet_addEthereumChain work through WalletConnect sessions?
It can, when the wallet supports the method and the approved session permits it. Inspect the session’s methods before sending the request. Adding a network to the wallet does not automatically add that chain to the session’s approved chains; the session may need an update before the dApp can use it. WalletConnect session namespaces define those permissions.
Top comments (0)