Developer guide

    How to Add a Custom Network to MetaMask (and Actually Switch to It)

    Four fields decide whether a custom chain works: chain ID, RPC URL, native currency and block explorer. Here is what each one does, where to find trustworthy values, and why the switch prompt sometimes never appears.

    The Four Fields

    Chain ID

    The number signed into every transaction (EIP-155), which is what stops a transaction on one chain from being replayed on another. It must match the RPC exactly — the wallet calls eth_chainId and refuses to add the network if the answer differs. MetaMask wants it in decimal; explorers often quote hex.

    RPC URL

    An HTTPS JSON-RPC endpoint. It must be HTTPS (not HTTP), must allow browser origins via CORS, and should be one you trust — the endpoint sees every address you query. Public endpoints are rate-limited; a dedicated provider key is better for anything sustained.

    Native currency (name, symbol, decimals)

    Purely cosmetic to the protocol, but it is what your wallet shows on the confirmation screen. Get it wrong and you are approving "0.5 ETH" on a chain whose gas token is CORE. Decimals is 18 on virtually every EVM chain.

    Block explorer URL

    Optional, but without it your wallet cannot offer a "View on explorer" link and tools cannot build transaction links after a send. Use the origin only, e.g. https://scan.coredao.org.

    Never take these values from a random search result or a DM. Use the chain's official documentation, or a community registry such as chainlist — a malicious RPC can show you fabricated balances.

    Adding It

    In MetaMask directly

    1. Open the network dropdown, then "Add network" and "Add a network manually".
    2. Fill in name, RPC URL, chain ID (decimal), currency symbol and explorer URL.
    3. Save — MetaMask verifies the chain ID against the RPC before accepting.

    From ABI Page Builder

    1. On the create form, choose "Custom network" instead of a preset.
    2. Enter chain ID, RPC URL, and optionally the currency name/symbol/decimals and explorer URL.
    3. Generate the page and click switch. The app asks the wallet to switch, and if the chain is unknown it sends an add-network request (EIP-3085) first, so you approve one prompt and land on the right chain.
    4. The custom chain is remembered locally, so returning to the page reconnects without re-entering anything.

    When Switching Silently Fails

    • The wallet does not know the chain yet. Error 4902 means "unrecognized chain" — the app must send wallet_addEthereumChain before switching.
    • The RPC reports a different chain ID than the one you entered; the wallet rejects the add without much explanation.
    • The RPC blocks browser requests (no CORS headers) or is temporarily down.
    • HTTP instead of HTTPS — modern wallets refuse insecure endpoints.
    • On mobile, the switch prompt appears inside the wallet app, not the browser: reopen the wallet to find the pending request.
    • WalletConnect sessions only expose the chains negotiated at connect time; reconnecting after adding the chain resolves it.

    👉 Ready to use your chain?

    Build a contract page

    Related Guides