Add ESC Network Programmatically

Asking users to copy RPC URLs, chain IDs, and explorer links into their wallet is error-prone and hurts conversion. Elastos Smart Chain (ESC) is a geth fork, so standard Ethereum provider APIs work in browsers and mobile dApp browsers. You can register the network in one click using EIP-3085 (wallet_addEthereumChain) and switch chains with wallet_switchEthereumChain.

EIP-3085 in brief

EIP-3085 defines wallet_addEthereumChain, which passes a chain metadata object to the wallet. If the chain is unknown, the wallet can prompt the user to add it. Combined with EIP-3326 (wallet_switchEthereumChain), you can move the user to the correct network and only show “add network” when needed (for example, when the wallet returns error code 4902, meaning the chain has not been added).

Provider availability

Call these methods only when window.ethereum (or your injected provider) is present. Gate UI behind a “Connect wallet” flow and handle users who reject the prompt.

Chain parameters

Use hex chainId strings (0x-prefixed). Below are ESC mainnet and testnet, plus EID mainnet for apps that need the identity chain.

const ESC_MAINNET_PARAMS = {
  chainId: "0x14", // 20
  chainName: "Elastos Smart Chain",
  nativeCurrency: { name: "ELA", symbol: "ELA", decimals: 18 },
  rpcUrls: ["https://api.elastos.io/esc"],
  blockExplorerUrls: ["https://esc.elastos.io/"],
};

const ESC_TESTNET_PARAMS = {
  chainId: "0x15", // 21
  chainName: "Elastos Smart Chain Testnet",
  nativeCurrency: { name: "ELA", symbol: "tELA", decimals: 18 },
  rpcUrls: ["https://api-testnet.elastos.io/esc"],
  blockExplorerUrls: ["https://esc-testnet.elastos.io/"],
};

const EID_MAINNET_PARAMS = {
  chainId: "0x16", // 22
  chainName: "Elastos Identity Chain",
  nativeCurrency: { name: "ELA", symbol: "ELA", decimals: 18 },
  rpcUrls: ["https://api.elastos.io/eid"],
  blockExplorerUrls: ["https://eid.elastos.io/"],
};

Add the network

async function addElastosNetwork(params) {
  try {
    await window.ethereum.request({
      method: "wallet_addEthereumChain",
      params: [params],
    });
  } catch (error) {
    console.error("Failed to add network:", error);
  }
}

Switch (and add if missing)

async function switchToElastos(chainId) {
  try {
    await window.ethereum.request({
      method: "wallet_switchEthereumChain",
      params: [{ chainId }],
    });
  } catch (error) {
    if (error.code === 4902) {
      await addElastosNetwork(ESC_MAINNET_PARAMS);
    }
  }
}

Extend the 4902 branch to pass ESC_TESTNET_PARAMS or EID_MAINNET_PARAMS when chainId matches that network, so users are not always prompted with ESC mainnet only.

React example

import { ESC_MAINNET_PARAMS } from "./chains";

export function AddEscButton() {
  const onClick = () => addElastosNetwork(ESC_MAINNET_PARAMS);

  return (
    <button type="button" onClick={onClick}>
      Add Elastos Smart Chain to MetaMask
    </button>
  );
}

Wire onClick to switchToElastos("0x14") if you only need to switch when the chain is already added.

Field reference

The object you pass to wallet_addEthereumChain should include:

• chainId: Required. Network ID as a hex string (e.g. 0x14 for decimal 20).
• chainName: Human-readable name shown in the wallet UI.
• nativeCurrency: name, symbol, and decimals for the gas token (ELA uses 18 decimals).
• rpcUrls: At least one HTTPS JSON-RPC endpoint. Wallets may use the first entry.
• blockExplorerUrls: Optional but recommended so “View on explorer” links work.

If any field is wrong, users may add a broken network; keep this config in one module and update it when endpoints change.

Errors and UX

• 4902: Chain not added; call wallet_addEthereumChain with the right params for the chainId you requested.
• 4001: User rejected the request; do not retry in a loop; show a short message instead.
• Missing provider: Detect typeof window !== "undefined" && window.ethereum before calling.

Mobile in-app browsers (e.g. MetaMask mobile) support the same RPC methods as desktop extensions when the dApp is opened inside the wallet’s browser.

Testing

Verify against MetaMask and other EIP-3085–capable wallets. Test both first-time add flows and switches when the chain already exists. Confirm that after approval, eth_chainId matches the chain you intended.

Summary

ESC behaves like any EVM chain from the wallet’s perspective: use EIP-3085 to add Elastos networks and EIP-3326 to switch, keep params in sync with official RPC and explorer URLs, and branch on 4902 so first-time visitors can onboard without manual network entry.