---
eip: 2015
title: wallet_updateEthereumChain RPC Method
description: Adds an RPC method to switch between EVM-compatible chains
author: Pedro Gomes (@pedrouid), Erik Marks (@rekmarks), Pandapip1 (@Pandapip1)
discussions-to: https://ethereum-magicians.org/t/eip-2015-wallet-update-chain-json-rpc-method-wallet-updatechain/3274
status: Stagnant
type: Standards Track
category: Interface
created: 2019-05-12
requires: 155
---

## Abstract

This EIP adds a wallet-namespaced RPC endpoint, `wallet_updateEthereumChain`, providing a standard interface for switching chains. The method takes the minimal parameters of `chainId`, `chainName`, `rpcUrl`, `nativeCurrency` and `blockExplorerUrl`.

## Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

This proposal adds a method to a wallet's web3 provider API: `wallet_updateEthereumChain`.

### `wallet_updateEthereumChain`

The `wallet_updateEthereumChain` method is used to switch to a network, and registering it with the wallet if it isn't already recognized.

The `wallet_updateEthereumChain` method takes one parameter, an `EthereumChainSwitchRequest` object, defined below:

```typescript
interface NativeCurrencyData {
  name: string;
  symbol: string;
  decimals: number;
}

interface EthereumChainSwitchRequest {
  chainId: string;
  chainName?: string;
  rpcUrls?: string[];
  nativeCurrency?: NativeCurrencyData;
  blockExplorerUrl?: string;
}
```

The `chainId` is the `0x`-prefixed [EIP-155](./eip-155.md)-compliant chain ID. The `chainName` is a suggested human-readable name of the chain, to be displayed to the user. The `rpcUrls` array is a list of RPC endpoints for the given `chainId`. The `nativeCurrency` object suggests how the native currency should be displayed. Its parameters, `name`, `symbol`, and `decimals`, should be interpreted like in [ERC-20](./eip-20.md). Finally, the `blockExplorerUrl` should link to a block explorer compatible with the given `chainId`.

All keys other than the `chainId` are optional. All keys other than `chainId` are suggestions to the wallet. Wallets can choose to ignore or display other data to users. Wallets should prompt the user before switching or adding chains. Wallets should also store a default list of data for commonly-used chains, in order to avoid phishing attacks. Wallets MUST sanitize each RPC url before using it to send other requests, including ensuring that it responds correctly to the `net_version` and `eth_chainId` methods.

The `wallet_updateEthereumChain` method returns `true` if the active chain matches the requested chain, regardless of whether the chain was already active or was added to the wallet previously. If the user rejects the request, it must return an error with code `4001`.

## Rationale

The `wallet_updateEthereumChain` method is designed to be as simple as possible, while still providing the necessary information for a wallet to switch to a new chain. The `chainId` is the only required parameter, as it is the only parameter that is guaranteed to be unique. The `chainName` is included to provide a human-readable name for the chain, and the `rpcUrls` array is included to provide a list of RPC endpoints for the chain. The `nativeCurrency` object is included to provide a suggestion for how the native currency should be displayed. Finally, the `blockExplorerUrl` is included to provide a link to a block explorer for the chain.

The `wallet_updateEthereumChain` method is namespaced under `wallet_` to avoid conflicts with other methods. The `wallet_` prefix is used by other methods that are wallet-specific, such as `wallet_addEthereumChain` and `wallet_switchEthereumChain`.

## Backwards Compatibility

This EIP is fully backwards compatible.

## Security Considerations

### Server-Side Request Forgery (SSRF)

The `rpcUrls` parameter is a list of RPC endpoints for the chain. Wallets should sanitize each RPC url before using it to send other requests, including ensuring that it responds correctly to the `net_version` and `eth_chainId` methods.

### Phishing

Wallets should store a default list of data for commonly-used chains, in order to avoid phishing attacks.

## Copyright

Copyright and related rights waived via [CC0](../LICENSE.md).