Skip to main content
Blockfront

Crypto markets, protocols and policy

How to Add an ERC-20 Token to MetaMask After a Transfer

Add a custom token to MetaMask programmatically by switching to its chain, calling wallet_watchAsset from a button, and letting the user approve the prompt.

Blockfront Editorial

2 min read

How to Add an ERC-20 Token to MetaMask After a Transfer

Switch MetaMask to the token’s chain, then call wallet_watchAsset from a user-clicked button to request that the token be added. MetaMask only adds it on the selected network and after the user approves the prompt.

A Berachain bridge transfers assets across chains so they can be used in Berachain’s DeFi ecosystem. For context on that transfer route, the Berachain bridge topic explains how assets move across chains into Berachain’s DeFi ecosystem.

Have a connected MetaMask account, the token’s checksummed contract address, symbol and decimals, plus the target chain ID and RPC details. EIP-747 defines wallet_watchAsset; its ERC-20 options include address, symbol and decimals, with an optional HTTPS image URL. Keep the symbol to 11 characters or fewer, and use the value returned by the contract’s decimals() function.

Add the token from your dApp

  1. Read the selected network with ethereum.request({method: 'eth_chainId'}). Compare the result with the token’s target chain ID; the visible result is the network your dApp needs to switch to before requesting the token.
  2. When the IDs differ, request wallet_switchEthereumChain with the target chain ID. If MetaMask returns error 4902 because that chain has not been added, request wallet_addEthereumChain with its chain details, including the RPC URL. Once the user approves, request the switch again; MetaMask should show the target network as selected.
  3. Call wallet_watchAsset inside the button’s click handler, passing type: 'ERC20' and options containing address, symbol, decimals and, optionally, image. MetaMask displays its confirmation prompt; the user’s approval lets the wallet list the token. Do not call this automatically on page load: a dApp cannot read which tokens the user has already added, so automatic requests can prompt returning users again.
  4. Handle a true result as a successful request, and catch errors. Code 4001 means the user rejected the request; leave the token-add action available so they can try again. After a Berachain bridge transfer lands, for instance, the success screen can switch to chain 80094 (0x138de) and offer “Add HONEY to MetaMask” using the HONEY contract address. The task is done when the token appears in MetaMask’s assets on that network with a balance.