How Developers Use Chainlist Network Data to Add Networks
Chainlist gives dApp developers EVM chain metadata to build wallet add and switch requests, then verify that the wallet reached the intended network. Its public registry supplies chain IDs, RPC endpoints, native currency details and explorers.
- Fetch and cache the registry, then look up records by chain ID.
- Convert the selected record into wallet add-network parameters.
- Validate RPC endpoints and handle wallet approval or rejection.
What does Chainlist offer developers building a dApp?
The EVM directory gives developers a reference for the network fields that wallets and Web3 tools need. The Chainlist directory is a concrete example because its chain IDs, RPC endpoints, native currency details and explorers map to a wallet’s network configuration.
The data comes from the open ethereum-lists/chains registry, also published as chainid.network/chains.json. A registry record uses a numeric chainId, an rpc array, a nativeCurrency object and explorer entries; a wallet add request uses related fields with different names and formats. That distinction matters when a dApp turns a record into JSON-RPC parameters.
How do developers fetch and use Chainlist network data?
Developers fetch chainid.network/chains.json, index its records by numeric chainId and cache the result. Registry metadata changes slowly enough to cache, so refresh it on a schedule instead of fetching the entire directory for every wallet request.
Say an illustrative dApp supports chain ID 137. Look up 137, take the network name and nativeCurrency fields, select usable HTTPS addresses from rpc, and map explorer URLs to blockExplorerUrls. Keep the app’s supported chain IDs explicit so a registry entry alone cannot make the dApp offer an unsupported network. Validate candidate endpoints before handing them to a wallet.
How do you add or switch a network in a dApp?
A dApp requests wallet_switchEthereumChain (EIP-3326) first and, when a wallet reports 4902 for an unknown chain, requests wallet_addEthereumChain. Both calls take chainId as a 0x-prefixed hexadecimal string: decimal 137 becomes 0x89, while the decimal number 137 makes the request fail. The 4902 response is wallet behavior to handle where supported.
A typical EIP-3085 add request supplies chainId, chainName, nativeCurrency with name, symbol and decimals, rpcUrls, and optional blockExplorerUrls. After approval, call eth_chainId and compare its hex result with the target: adding a chain can leave the previously selected chain active. If needed, request the switch again before sending a transaction. Error 4001 means the user rejected the request; stop and leave the choice with them. These requests can also pass through a WalletConnect-connected wallet when that wallet supports the methods.
How do I get my network listed on Chainlist?
Network operators submit chain metadata to ethereum-lists/chains, the registry that feeds the directory. Include the chain ID, name, native currency, usable public RPC URLs and explorer information, and follow the repository’s validation rules. Once a change is merged and published in chains.json, apps that refresh their cached data can find the record by chain ID.
Can I use Chainlist RPCs in production?
Public registry RPCs can serve wallet add requests, while production backends need a dedicated provider sized for their traffic. Community-submitted endpoints can hit rate limits, go offline or serve the wrong chain, so treat each URL as a candidate to test.
Send eth_chainId to every candidate HTTPS RPC and compare the returned hex value with the intended chain ID. Exclude endpoints that fail, time out, return a mismatch or still contain an unsubstituted API-key placeholder. Put an RPC you control first in rpcUrls, because some wallets use the first address. Recheck fallback URLs as their availability changes, and route backend reads through a dedicated provider with monitoring and capacity for your workload.