# EIP-3085: wallet_addEthereumChain Source: https://www.eipsfordesigners.com/standards/EIP-3085 Agent brief: https://www.eipsfordesigners.com/standards/EIP-3085/agent.md Machine-readable JSON: https://www.eipsfordesigners.com/api/standards/EIP-3085 Last reviewed: 2026-09-18 Last updated: 2026-09-18 | Field | Value | | --- | --- | | Status | Stagnant | | Chain | ethereum | | Category | Onboarding & Access | | Journey stages | Discovery & Connection, Executing Transactions | | Detailed guide | Yes | | Official specification | https://eips.ethereum.org/EIPS/eip-3085 | | Discussion search | https://ethereum-magicians.org/search?q=EIP-3085 | ## UX Impact EIP-3085 defines wallet_addEthereumChain, a request for a wallet to validate and add an EVM chain. The Stagnant specification requires chain-ID and RPC-URL validation and recommends explicit user consent. Wallets control additional metadata requirements and post-add selection; current implementations such as MetaMask Connect document their own confirmation and error behavior. ## Summary EIP-3085 defines wallet_addEthereumChain, a request for a wallet to validate and add an EVM chain. The Stagnant specification requires chain-ID and RPC-URL validation and recommends explicit user consent. Wallets control additional metadata requirements and post-add selection; current implementations such as MetaMask Connect document their own confirmation and error behavior. ## What does not work everywhere yet Treat this as an implementation-dependent wallet capability. MetaMask Connect documents the method, but support, required metadata, validation, and whether the newly added chain becomes active vary by wallet and release. An accepted request is not evidence that every wallet supports the chain or that the app switched to it. ## For Designers - Show the exact chain name, chain ID, native currency, RPC host, and explorer before asking the wallet to add a network. - Treat the wallet response as acknowledged or rejected; verify the active chain separately with eth_chainId and provider events. - Keep an explicit manual-network fallback when the wallet does not implement the method or rejects the request. ## Applicability ### When to Use - A dapp needs to guide a user to a known EVM network before an action can proceed. - The product owns or has verified the RPC and explorer metadata it is presenting. - The flow can explain that adding a chain changes wallet configuration and exposes activity to the selected RPC provider. ### When to Avoid - The target wallet or connection path does not expose wallet_addEthereumChain. - The app cannot verify the chain ID against the endpoint's eth_chainId response. - A network switch is enough and the chain is already known to the wallet. ## Problems It Solves ### Users mistake a network label for a verified chain Impact: critical Old way: Trust a name or icon supplied by an app without checking chain ID and endpoint. New way: Review the chain ID and endpoint identity before a wallet stores the chain. ### Users must configure a network by hand before using a dapp Impact: high Old way: Copy chain ID, RPC, currency, and explorer fields into wallet settings and hope they match. New way: A compatible wallet can review the dapp's chain metadata in one explicit add request. ### A dapp cannot explain why an action is blocked by network setup Impact: high Old way: Show a generic wrong-network error with no recovery path. New way: Request the known network, verify the result, and preserve a manual setup path when the wallet declines. ## Spec Constraints Quotes retain their source section and scope. Normative requirements, rationale, compatibility changes, and security recommendations are not interchangeable. Design implications are editorial guidance. ### A wallet may require, ignore, or reject fields in a wallet_addEthereumChain request, and must reject invalid fields when it does not ignore them. Applies to: wallet Source classification: normative > If a field does not meet the requirements of this specification and the wallet does not ignore the field, the wallet MUST reject the request. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Parameters](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-parameters) Design implication (editorial): Separate request validation from user consent and show the exact field that made a chain-add request invalid. ### Only chainId is required by the specification; a wallet may require, add requirements to, or ignore other fields. Applies to: wallet Source classification: normative > Only the `chainId` is required per this specification, but a wallet MAY require any other fields listed, impose additional requirements on them, or ignore them outright. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Parameters](https://eips.ethereum.org/EIPS/eip-3085#walletaddethereumchain-parameters) Design implication (editorial): Show wallet-specific metadata requirements before submission and distinguish omitted optional data from a validation failure. ### Validate chainId, URLs, native-currency metadata, and their formats before accepting a chain-add request. Applies to: wallet Source classification: normative > The `chainId` is the integer ID of the chain as a hexadecimal string, as per [EIP-155](./eip-155.md). The `blockExplorerUrls`, `iconUrls`, and `rpcUrls` fields are arrays of strings, each of which MUST be a valid URL. The `nativeCurrency` field is an object with `name`, `symbol`, and `decimals` fields, where `decimals` is a non-negative integer, and is to be interpreted like in [EIP-20](./eip-20.md). The `chainName` field is a string that is the human-readable name of the chain. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Parameters](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-parameters) Design implication (editorial): Use field-level validation and show the target chain identity, native currency, and endpoints in the confirmation review. ### RPC URLs must be present, valid, and agree with the submitted chainId through eth_chainId. Applies to: wallet Source classification: normative > The wallet MUST reject the request if the `rpcUrls` field is not provided, or if the `rpcUrls` field is an empty array. The wallet MUST reject the request if the `rpcUrls` contains any strings that are not valid URLs. The wallet must reject the request if the `chainId` does not match the value of the `eth_chainId` method for any of the RPC urls. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Parameters](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-parameters) Design implication (editorial): Do not allow a chain to be added on the basis of an endpoint that reports a different network; show an endpoint mismatch state. ### If nativeCurrency is supplied, name, symbol, and non-negative decimals are required. Applies to: wallet Source classification: normative > The wallet MUST reject the request if the `nativeCurrency` field is provided, and any of the `name`, `symbol`, or `decimals` fields are missing. The wallet MUST reject the request if the `decimals` field is a negative integer. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Parameters](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-parameters) Design implication (editorial): Validate the native asset metadata before rendering fee or balance copy and provide a corrective error for incomplete values. ### Optional block-explorer and icon URL arrays must contain valid URLs and icon URLs must point to valid images. Applies to: wallet Source classification: normative > The wallet MUST reject the request if the `iconUrls` field is provided, and any of the URLs are not valid URLs or do not point to a valid image. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Parameters](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-parameters) Design implication (editorial): Render metadata only after validation and keep a safe fallback when an explorer or icon cannot be loaded. ### Wallets must reject file and http URL schemes in chain-add request URLs. Applies to: wallet Source classification: normative > The wallet MUST reject any URLs that use the `file:` or `http:` schemes. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Parameters](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-parameters) Design implication (editorial): Show a blocked-resource state and do not turn an unsafe endpoint or asset URL into a clickable wallet surface. ### wallet_addEthereumChain returns null only for success and an error otherwise. Applies to: wallet Source classification: normative > The method MUST return `null` if the request was successful, and an error otherwise. The wallet MAY reject the request for any reason. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Returns](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-returns) Design implication (editorial): Keep request validation, user rejection, and successful addition as distinct result states; null does not mean the chain is selected. ### A successfully added chain must not be assumed to be automatically selected. Applies to: wallet Source classification: normative > The chain MUST NOT be assumed to be automatically selected by the wallet, even if the wallet does not reject the request. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Returns](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-returns) Design implication (editorial): Tell users whether the wallet merely added the chain or also switched the active network, and never imply a switch from a null result alone. ### The wallet must not add the same chainId multiple times. Applies to: wallet Source classification: normative > The wallet MUST NOT allow the same `chainId` to be added multiple times. See [Security Considerations](#security-considerations) for more information. Source: [Specification > walletaddEthereumChain > walletaddEthereumChain Returns](https://eips.ethereum.org/EIPS/3085#walletaddethereumchain-returns) Design implication (editorial): Resolve an existing chain entry instead of creating duplicates, while preserving the user’s ability to review the requester and metadata. ### Adding a chain is a powerful operation that requires request validation and clear chain differentiation. Applies to: wallet Source classification: security-considerations > ## Security Considerations > > `wallet_addEthereumChain` is a powerful method that exposes the end user to serious risks if implemented incorrectly. > Many of these risks can be avoided by validating the request data in the wallet, and clearly disambiguating different chains in the wallet UI. Source: [Security Considerations](https://eips.ethereum.org/EIPS/3085#security-considerations) Design implication (editorial): Use a high-salience confirmation that identifies requester, chain, and endpoints before changing wallet configuration. ### Use the submitted chainId as the signing identity and verify it against eth_chainId; never blindly trust an RPC-reported chain ID. Applies to: wallet Source classification: security-considerations > ### Chain IDs > > Since the chain ID used for transaction signing determines which chain the transaction is valid for, handling the chain ID correctly is of utmost importance. > The wallet should: > > - Ensure that a submitted chain ID is valid. > - It should be a `0x`-prefixed hexadecimal string per [EIP-695](./eip-695.md), and parse to an integer number. > - Prevent the same chain ID from being added multiple times. > - See the next section for how to handle multiple RPC endpoints. > - Only use the submitted chain ID to sign transactions, **never** a chain ID received from an RPC endpoint. > - A malicious or faulty endpoint could return arbitrary chain IDs, and potentially cause the user to sign transactions for unintended chains. > - Verify that the specified chain ID matches the return value of `eth_chainId` from the endpoint, as described above. Source: [Security Considerations > Chain IDs](https://eips.ethereum.org/EIPS/3085#chain-ids) Design implication (editorial): Show chain identity as a verified comparison, not as an RPC-provided label, and block mismatches before signing. ### RPC endpoints can expose activity and IP information and may be unknown or unsafe. Applies to: wallet Source classification: security-considerations > ### RPC Endpoints and RPC URLs > > Wallets generally interact with chains via an RPC endpoint, identified by some URL. > Most wallets ship with a set of chains and corresponding trusted RPC endpoints. > The endpoints identified by the `rpcUrls` parameter cannot be assumed to be honest, correct, or even pointing to the same chain. > Moreover, even trusted endpoints can expose users to privacy risks depending on their data collection practices. > > Therefore, the wallet should: > > - Inform users that their on-chain activity and IP address will be exposed to RPC endpoints. > - If an endpoint is unknown to the wallet, inform users that the endpoint may behave in unexpected ways. > - Observe good web security practices when interacting with the endpoint, such as require HTTPS. > - Clearly inform the user which RPC URL is being used to communicate with a chain at any given moment, and inform the user of the risks of using multiple RPC endpoints to interact with the same chain. Source: [Security Considerations > RPC Endpoints and RPC URLs](https://eips.ethereum.org/EIPS/3085#rpc-endpoints-and-rpc-urls) Design implication (editorial): Tell users which RPC is active, identify trusted versus requester-provided endpoints, and provide a privacy/security warning for unknown endpoints. ### Wallets should maintain known-chain metadata and verify unknown chain-add requests against it. Applies to: wallet Source classification: security-considerations > ### Validating Chain Data > > A wallet that implements `wallet_addEthereumChain` should expect to encounter requests for chains completely unknown to the wallet maintainers. > That said, community resources exist that can be leveraged to verify requests for many Ethereum chains. > The wallet should maintain a list of known chains, and verify requests to add chains against that list. > Indeed, a wallet may even prefer its own chain metadata over anything submitted with a `wallet_addEthereumChain` request. Source: [Security Considerations > Validating Chain Data](https://eips.ethereum.org/EIPS/3085#validating-chain-data) Design implication (editorial): Prefer verified wallet metadata over untrusted request fields and show when a chain is unknown or awaiting review. ### A chain must not be added without explicit user consent and different chains must be clearly differentiated. Applies to: wallet Source classification: security-considerations > ### UX > > Adding a new chain to the wallet can have significant implications for the wallet's functionality and the experience of the user. > A chain should never be added without the explicit consent of the user, and different chains should be clearly differentiated in the wallet UI. > In service of these goals, the wallet should: > > - When receiving a `wallet_addEthereumChain` request, display a confirmation informing the user that a specific requester has requested that the chain be added. > - Ensure that any chain metadata, such as `nativeCurrency` and `blockExplorerUrls`, are validated and used to maximum effect in the UI. > - If any images are provided via `iconUrls`, ensure that the user understands that the icons could misrepresent the actual chain added. > - If the wallet UI has a concept of a "currently selected" or "currently active" chain, ensure that the user understands when a chain added using `wallet_addEthereumChain` becomes selected. Source: [Security Considerations > UX](https://eips.ethereum.org/EIPS/3085#ux) Design implication (editorial): Require explicit confirmation and make chain name, ID, currency, endpoints, and selection effect visually distinct. ### Duplicate-chain requests should not automatically reveal which chains the user has added. Applies to: wallet Source classification: security-considerations > ### Preserving User Privacy > > Although a request to add a chain that was already added should generally be considered a success, treating such requests as _automatic_ successes leaks information to requesters about the chains a user has added to their wallet. > In the interest of preserving user privacy, implementers of `wallet_addEthereumChain` should consider displaying user confirmations even in these cases. > If the user denies the request, the wallet should return the same user rejection error as normal so that requesters cannot learn which chains are supported by the wallet without explicit permission to do so. Source: [Security Considerations > Preserving User Privacy](https://eips.ethereum.org/EIPS/3085#preserving-user-privacy) Design implication (editorial): Preserve a consent boundary even for already-known chains and return indistinguishable rejection behavior when the user denies. ## Anti-Patterns (editorial) ### Claiming that a successful add request also switched the wallet Severity: critical The EIP explicitly leaves active-chain selection to the wallet implementation. Instead: Verify the active chain separately and use EIP-3326 only when the wallet supports it. ### Using a chain name or icon as the only identity check Severity: critical Metadata can be misleading, and the same name can be used by multiple networks. Instead: Keep the hexadecimal chain ID and endpoint identity visible and validated. ### Silently retrying or substituting RPC endpoints Severity: high The endpoint receives user activity and may identify a different chain or privacy policy. Instead: Disclose the endpoint and stop on a chain-ID mismatch. ### Treating wallet rejection as proof that the chain is absent Severity: medium Wallets may reject for privacy or policy reasons without revealing their configured chains. Instead: Use an unknown or declined state and offer a user-controlled fallback. ## Design Decisions ### Which chain details belong in the app preview? Recommendation: Show the identity fields the wallet will validate, plus the RPC host and explorer that the app supplied. Rationale: A friendly chain name or icon is not enough to distinguish networks or communicate endpoint privacy and trust. ### When can the original action resume? Recommendation: Resume only after the provider reports the expected chain ID and the action is revalidated. Rationale: Adding a chain and switching the active chain are separate wallet behaviors. ### How should duplicate adds behave? Recommendation: Keep the same review and verification path for an already-known chain when the wallet does not reveal its state. Rationale: Automatic success can disclose wallet configuration and still does not prove the active network. ## States to Design ### Metadata being checked Trigger: The app has requested chain addition and the wallet confirmation is pending. User need: Know which network and endpoint they are about to trust. Design response: Keep the chain ID, network name, currency, explorer, and RPC host visible; do not let a spinner imply approval. ### Added, active state unknown Trigger: The wallet returns null or an implementation-specific success response. User need: Know whether the interrupted action can continue on the intended network. Design response: Read eth_chainId, listen for provider chain changes, and offer switch or retry if the active chain is unchanged. ### Rejected or unsupported Trigger: The wallet declines, validates out, or does not expose the method. User need: A way to proceed without guessing whether setup happened. Design response: Show a plain reason when available, keep the action paused, and provide manual network instructions or a supported-wallet path. ### Endpoint mismatch Trigger: The endpoint's eth_chainId does not match the requested chain ID. User need: Avoid signing for an unintended chain. Design response: Block the request and identify the mismatched endpoint; never silently substitute the returned chain ID. ## Vocabulary - Use "Add this network" instead of "Install chain": The wallet is storing a network configuration, not installing a protocol. - Use "RPC provider" instead of "Secure node": An RPC endpoint is a communication provider with its own trust and privacy properties. - Use "Network added; checking active network" instead of "Ready": The add response does not establish that the wallet selected the network. ## What to Prototype First ### Add network confirmation The user is deciding whether to trust new chain metadata and an RPC endpoint. Covers: Known chain, Unknown chain, Wallet rejection - Chain name and hexadecimal chain ID - Native currency and explorer - RPC host disclosure - Cancel and manual setup paths ### Return to interrupted action Adding a chain does not guarantee that the wallet selected it or that the original request can continue. Covers: Added but still on old chain, Added and selected, Request declined - Current chain indicator - Verify-and-continue step - Retry and manual switch ## Mental Model ### Request The dapp asks the wallet to consider adding a chain; it does not add the chain directly. ### Metadata review The wallet must validate the chain ID and required RPC endpoints. It can require additional metadata, use its own values, or ignore optional fields; accepted fields still need the specification's validation. ### User decision A wallet should obtain explicit consent and identify the requester, network, and RPC implications. ### Configured chain A successful response means the wallet accepted the add request. It does not mean the chain is active or that a transaction was sent. ## UI Components ### ChainIdentityCard Displays the chain ID and the metadata supplied to the wallet. Kind: card States: verified, checking, mismatch, unknown Props: chainId, chainName, nativeCurrency, rpcUrls, blockExplorerUrls ### NetworkHandoffStatus Tracks the add request, wallet response, active-chain verification, and return to the task. Kind: status States: waiting, accepted, rejected, unsupported, active Props: requestedChainId, activeChainId, error, onRetry ## Key Takeaways - EIP-3085 is Stagnant; support is wallet-specific. - Validate the chain ID against every RPC endpoint before handing the request to a wallet. - Adding a chain does not guarantee that it became active. - Keep manual setup and explicit active-chain verification available. ## UX Patterns ### Verified Add-Network Handoff Present the intended network, request wallet confirmation, then verify the active chain before returning to the task. Components: Chain identity card, RPC host disclosure, Wallet handoff state, Active-chain verifier User flow: - User starts an action on an unsupported network - App shows chain ID, currency, explorer, and RPC host - App requests wallet_addEthereumChain - User accepts or rejects in the wallet - App verifies eth_chainId and provider events - App resumes or gives manual setup guidance ### Manual Setup Fallback Give users a copyable, independently verifiable setup path when the wallet method is unavailable or declined. Components: Copyable chain fields, Endpoint verification note, Retry button, Unsupported-wallet message User flow: - Detect unsupported or rejected request - Explain what was not completed - Show exact fields and verification source - Let the user retry the wallet request - Recheck the active chain before continuing ## Related Standards - EIP-3326: Switch the active wallet chain after it is known to the wallet. - EIP-1193: Provider request and chain/account event transport. - EIP-155: Chain ID format and transaction replay domain. ## Technical Notes wallet_addEthereumChain takes an EthereumChainAddRequest with a required hexadecimal chainId and wallet-dependent metadata requirements. The wallet must reject invalid URLs and chain IDs, must require a non-empty rpcUrls array, must validate that each endpoint returns the requested eth_chainId, and must not add the same chain ID more than once. The specification rejects file: and http: URLs. The wallet may reject a valid request for any reason and must not be assumed to select the chain after returning null. Treat RPC URLs as user-visible trust and privacy inputs.