How to switch the selected network on the connected wallet using 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.
At the end, we will also learn how to get the network that the user's wallet is currently on.

Some wallets like MetaMask allow users to select different EVM blockchains like Ethereum, Binance Smart Chain, Fantom, Avalanche, Polygon and others.

To interact with the correct blockchain, you can request the user to switch to another network which will open a pop-up on the wallet browser extension or a new screen on the wallet mobile app for your user to select the right network.

Here is the full code to do that:

const ethers = require("ethers");

// provider must be a wallet connected to your website
// like window.ethereum
const provider = new ethers.providers.Web3Provider(YOUR_PROVIDER_HERE)

try {
    // send a request to the wallet to switch the network and select the Ethereum mainnet
    await provider.request({
        method: "wallet_switchEthereumChain",
        params: [{ chainId: ethers.utils.hexValue(1) }]
    })
} catch (error) {
    if (error.code === 4001) {
        console.log("the user doesn't want to change the network!")
    }
    else if (error.code === 4902) {
        console.log("this network is not in the user's wallet")
    }
    else {
        console.log(`Error ${error.code}: ${error.message}`)
    }
}

Now let's break down this code and see what it does

It's important to note that if you store the signer in a variable somewhere in your app, you need to update that variable after changing the network.

You need to call provider.getSigner() again after changing the selected network.

The request function in Ethers

First of all, to interact with the user's wallet we call the request function and pass an object in the arguments of that function.

That object needs to have 2 properties:

• method: the name of the method to call. To request changing the selected network, the method is "wallet_switchEthereumChain"
• params: the parameters to send to the method you're calling

The EIP-1193 standard and the request function

The methods you can call using the request function come from the EIP-1193 standard that defines how wallet APIs work.

This standard says that developers can call methods from the wallet using a request function that takes an object in arguments which contains options to send a JSON-RPC API call. In other words, this object contains the name of the method to call and the params to pass to that method.

The methods are defined in EIP-1193 but also other standards. This standard also defines events on the wallet and the error codes.

Fortunately, Ethers implements that standard so we can easily interact with wallets.

Not all wallets will support all methods defined in these standards but if they do, it works exactly as explained in the documentation. That's why it's extremely important to handle errors properly because not all wallets support all the methods.

For example, some wallets don't allow the user to select a network or select a different account like MetaMask does.

In our case, we call the "wallet_switchEthereumChain" method and in the parameters we need to pass the chain ID of the network we want to switch to.

The EVM chain IDs

You can see the full list of chain IDs for all EVM networks here: https://chainlist.org/

The chain ID you pass must be an hexadecimal string. To convert a number to an hexadecimal string, we use ethers.utils.hexValue() and pass the number to convert:

// The chain ID 1 is the Ethereum mainnet
const chainId = ethers.utils.hexValue(1)

The error codes

The request function throws an error depending on what caused the request function to fail.

You can see the error codes that all methods use here:

As you can see, the documentation also says that the error objects will have 3 properties:

• code: a unique identifier to know what was the error in the code
• message: a human-readable error message that you can display to your users
• data: extra information about the error that the method or the wallet gives you

For the "wallet_switchEthereumChain" function, the most common error codes are:

• 4001: it means the user didn't accept to change the network on their wallet
• 4902: it means the network is not available on the user's wallet. Either it's not supported or you can request the user to add it using the method "wallet_addEthereumChain" described here.

Check out this tutorial to learn how to add a new EVM blockchain to the user's wallet:

How to add a new network to the user’s wallet using Ethers JS

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.

0xDev0xDev

How to get the currently selected network on the user's wallet

Before requesting the user to select the right network, you might want to check if they are not already on the right network.

To get the chain ID of the currently selected network on the user's wallet, we use the getNetwork function:

const { chainId } = await provider.getNetwork()

The chain ID returned will be a number from this list: https://chainlist.org/

And that's it 🎉

Thank you for reading this article