wallet_addEthereumChain

Request UKey Wallet to add a new EVM network. After the user confirms, the network will be saved to the wallet; if the network already exists, the wallet may switch directly to the chain.

---

Inputs

Pass an array whose first item is the chain configuration object:

Field	Variant	Need	Remarks
chainId	string	yes	Chain ID in 0x-prefixed hex
chainName	string	yes	Network name shown to the user
nativeCurrency	object	yes	Native asset metadata
nativeCurrency.name	string	yes	Native asset name
nativeCurrency.symbol	string	yes	Native asset ticker, usually 2-6 chars
nativeCurrency.decimals	number	yes	Native asset decimals, usually 18
rpcUrls	string[]	yes	RPC endpoints; provide at least one
blockExplorerUrls	string[]	no	Explorer URLs for the Network
iconUrls	string[]	no	Icon URLs for wallet display

---

return value

Returns null on success.

---

Demo

await window.$ukey.ethereum.request({
  method: "wallet_addEthereumChain",
  requestParams: [
    {
      chainId: "0x89",
      chainName: "Polygon Mainnet",
      nativeCurrency: {
        name: "MATIC",
        symbol: "MATIC",
        decimals: 18,
      },
      rpcUrls: ["https://polygon-rpc.com"],
      blockExplorerUrls: ["https://polygonscan.com"],
    },
  ],
});

Add Base

await window.$ukey.ethereum.request({
  method: "wallet_addEthereumChain",
  requestParams: [
    {
      chainId: "0x2105",
      chainName: "Base",
      nativeCurrency: {
        name: "Ethereum",
        symbol: "ETH",
        decimals: 18,
      },
      rpcUrls: ["https://mainnet.base.org"],
      blockExplorerUrls: ["https://basescan.org"],
    },
  ],
});

Add Arbitrum

await window.$ukey.ethereum.request({
  method: "wallet_addEthereumChain",
  requestParams: [
    {
      chainId: "0xa4b1",
      chainName: "Arbitrum One",
      nativeCurrency: {
        name: "Ethereum",
        symbol: "ETH",
        decimals: 18,
      },
      rpcUrls: ["https://arb1.arbitrum.io/rpc"],
      blockExplorerUrls: ["https://arbiscan.io"],
    },
  ],
});

---

error code

Code	Message	Details
4001	User rejected the request	Network addition was rejected by the user
-32602	Parameters failed validation	Network configuration is invalid

---

illustrate

• Wallets usually only use the first available address of rpcUrls and blockExplorerUrls.
• Please confirm that the source is trustworthy before incoming RPC to avoid directing users to connect to malicious nodes.
• The wallet may verify whether the RPC endpoint can respond normally to the corresponding Chain ID.
• Some wallets have limited support for native tokens with non-18-bit precision.
• Follows EIP-3085 specification.

Combination addition and switching

async function switchOrAddChain(chainConfig) {
  try {
    await window.$ukey.ethereum.request({
      method: "wallet_switchEthereumChain",
      requestParams: [{ chainId: chainConfig.chainId }],
    });
  } catch (error) {
    if (error.code === 4902) {
      await window.$ukey.ethereum.request({
        method: "wallet_addEthereumChain",
        requestParams: [chainConfig],
      });
    } else {
      throw error;
    }
  }
}