How to add a new network to the user's wallet using Ethers JS and JavaScript

In this tutorial, we are going to see how to add a new network to the list of networks in the user's wallet connected to your website using Ethers JS.

If your Web3 app is on a specific EVM blockchain that is not the Ethereum mainnet, you can't be sure that the user's wallet has that network in the list of available networks.

Some wallets don't have such a list but MetaMask which is the most popular wallet for Ethereum and EVM blockchains, allows users to select a different network to interact with applications on a specific blockchain and they allow them to add new networks.

It can be useful if your app is on a network like the Binance smart chain, Fantom, Avalanche, Polygon, Arbitrum or others from this list: https://chainlist.org/

Here is the full code to add the Binance smart chain to the user's wallet:

const ethers = require("ethers")

const provider = new ethers.providers.Web3Provider(YOUR_PROVIDER_HERE)

try {
    await provider.request({
        method: "wallet_addEthereumChain",
        params: [{
            chainId: ethers.utils.hexValue(56),
            chainName: 'Binance Smart Chain',
            nativeCurrency: {
                name: 'Binance Coin',
                symbol: 'BNB',
                decimals: 18
            },
            rpcUrls: ['https://bsc-dataseed.binance.org/'],
            blockExplorerUrls: ['https://bscscan.com']
        }]
    })
} catch (error) {
    console.log(error.code)
    console.log(error.message)
}

Now let's break it down.

For that code to work, your provider must be a wallet connected to your website like MetaMask. For example, the provider can be window.ethereum.

To add the network, we call the request function and in the parameters we pass "wallet_addEthereumChain" in the method and information about the blockchain in the params property.

In the params, you need to pass the following properties:

• chainId: an hexadecimal string containing the chain ID of the network to add. To convert a number into an hexadecimal string, we use ethers.utils.hexValue.
  You can find the full list of chain IDs here: https://chainlist.org/
• chainName: the name of the blockchain, it will be displayed in the list of networks in the user's wallet after they add it
• rpcUrls: an array containing URLs to interact with the blockchain you want to add. Those URLs are where the JSON-RPC API calls will be sent to interact with the blockchain. There must be at least one.
• blockExplorerUrls: an array containing the URL of at least one block explorer. Block explorers are websites where you can get information about the network, the transactions and the smart contracts on a specific blockchain.
• nativeCurrency: an object containing information about the native token of the blockchain. For example, for the Ethereum blockchain it's Ethereum and for the Binance smart chain it's BNB.

To find all this information about the blockchain you want to add, go to this official Github repo that lists all the EVM chains:

GitHub - ethereum-lists/chains: provides metadata for networkIDs and chainIDs

provides metadata for networkIDs and chainIDs. Contribute to ethereum-lists/chains development by creating an account on GitHub.

GitHubethereum-lists

Navigate to the data folder and then to the chains folder. From there, search for the chain ID of the blockchain you want to add.

There are a ton of blockchains in the repository so to find the chain ID of the blockchain you want to add, hit Cmd + F on Mac or Ctrl + F on Windows and search for your chain ID.

For example, the Binance Smart Chain ID is 56 so the file that contains information about that blockchain is eip155-56.json:

chains/eip155-56.json at master · ethereum-lists/chains

provides metadata for networkIDs and chainIDs. Contribute to ethereum-lists/chains development by creating an account on GitHub.

GitHubethereum-lists

Inside that file, you have all the information you need about your blockchain in order to add it to the user's wallet. Just copy and paste the values to your code in the params of the object you pass to the request function.

But be careful, the request function can fail so you need to handle errors properly.

If the user refuses to add the network on their wallet, it will throw an error and you have to catch it so your app doesn't break.

Check out this tutorial if you want to learn how to request the user to select a different network and also learn how to get the current selected network on the user's wallet:

How to switch the selected network on the connected wallet Ethers JS

In this tutorial, we are going to learn how to request switching the network of the wallet connected to your website using Ethers JS and JavaScript.

0xDev0xDev

And that's it 🎉

Thank you for reading this article