Skip to main content
MetaMask
Multichain API

wallet_addEthereumChain

Summary: Adds an Ethereum chain to the wallet.

Creates a confirmation asking the user to add the specified chain to the wallet application. The caller must specify a chain ID and some chain metadata. Specified by EIP-3085.

Parameters

Chain
object
required

Object containing information about the chain to add.

chainId
string

The chain ID as a 0x-prefixed hexadecimal string, per the eth_chainId method. MetaMask compares this chain ID value with the eth_chainId return value. If these values aren't identical, MetaMask rejects the request.

blockExplorerUrls
array

(Optional) An array of one or more URLs pointing to block explorer sites for the chain.

string

Block explorer URL.

chainName
string

A human-readable name for the chain.

iconUrls
array

(Optional) An array of one or more URLs pointing to icons that can be used to visually identify the chain. Note: MetaMask will not currently display these icons. You can still include icon URLs so they are used if MetaMask incorporates them into the display of custom networks in the future.

string

Icon URL.

nativeCurrency
object
required

An object containing information about the native currency of the chain.

decimals
integer

A non-negative integer representing the number of decimals the native currency uses.

name
string

A human-readable name of the native currency.

symbol
string

A human-readable symbol of the native currency.

rpcUrls
array

An array of one or more URLs pointing to RPC endpoints that can be used to communicate with the chain. At least one item is required, and only the first item is used.

string

RPC URL.

Returns

Null response
null

This method returns null if the chain is added.

Errors

Code
Message
-32602
Expected null or array with at least one valid string HTTPS URL 'blockExplorerUrl'. Received: ${blockExplorerUrls}
-32602
Expected 0x-prefixed, unpadded, non-zero hexadecimal string 'chainId'. Received: ${chainId}
-32602
Invalid chain ID "${_chainId}": numerical value greater than max safe value. Received: ${chainId}
-32602
May not specify default MetaMask chain.
-32602
Expected 2-6 character string 'nativeCurrency.symbol'. Received: ${ticker}
-32602
nativeCurrency.symbol does not match currency symbol for a network the user already has added with the same chainId. Received: ${ticker}
Customize request
Parameter
Value
string
[ "https://blockscout.com/poa/xdai/" ]
array
string
[ "https://xdaichain.com/fake/example/url/xdai.svg", "https://xdaichain.com/fake/example/url/xdai.png" ]
array
{ "nativeCurrency": { "decimals": 18, "name": "XDAI", "symbol": "XDAI" } }
object
integer
string
string
[ "https://rpc.gnosischain.com" ]
array

Connect your MetaMask wallet to run requests successfully.

Request

await window.ethereum.request({
 "method": "wallet_addEthereumChain",
 "params": [
  {
    chainId: "0x64",
    chainName: "Gnosis",
    rpcUrls: [
      "https://rpc.gnosischain.com"
    ],
    iconUrls: [
      "https://xdaichain.com/fake/example/url/xdai.svg",
      "https://xdaichain.com/fake/example/url/xdai.png"
    ],
    nativeCurrency: {
      name: "XDAI",
      symbol: "XDAI",
      decimals: 18
    },
    blockExplorerUrls: [
      "https://blockscout.com/poa/xdai/"
    ]
  }
],
});

Example response

null