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. The wallet application may refuse or accept the request. null is returned if the chain is added, and an error otherwise. Introduced by EIP-3085.

Parameters

AddEthereumChainParameter object
required

AddEthereumChainParameter

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) One or more URLs pointing to block explorer sites for the chain.

string

chainName string

A human-readable name for the chain.

iconUrls array

(Optional) One or more URLs pointing to reasonably sized images that can be used to visually identify the chain. NOTE: MetaMask will not currently display these images. Values can still be included so that they are utilized if MetaMask incorporates them into the display of custom networks in the future.

string

nativeCurrency object
required

Describes the native currency of the chain using the name, symbol, and decimals fields.

decimals integer

A non-negative integer.

name string

A human-readable name.

symbol string

A human-readable symbol.

rpcUrls array

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

Returns

AddEthereumChainResult null

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": { "name": "XDAI", "symbol": "XDAI", "decimals": 18 } }
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