Chainlist: EVM Chain Metadata and Chain ID Registry
/chains
Chainlist is the dataset most EVM chain-ID lookups trace back to — a git repo storing one JSON file per chain, not a website. It holds that position through strict rules: whoever registers a chain ID first keeps it, and pull requests that try to reassign one get closed. The cost is friction — adding a chain means reading EIP-155 and passing gradle CI, not just filing a PR.
What the Chainlist repository contains
Chainlist is the base/chains GitHub repository holding metadata for EVM-compatible networks: one JSON file per chain, stored under _data/chains and named by its CAIP-2 identifier. Each file lists the chain's name, chainId, networkId, native currency, RPC endpoints, and explorers, plus an optional parent link for L2s. A separate _data/icons folder holds IPFS icon references shared across entries.
Metadata fields for each EVM chain
- ✓Each chain gets a single JSON file under _data/chains, named by its CAIP-2 identifier, holding chainId, networkId, name, and shortName.
- ✓nativeCurrency is a nested object (name, symbol, decimals) rather than a flat field, matching how wallets need to render balances.
- ✓explorers is an array, and each entry can declare a standard like EIP3091 so tooling knows the URL format to expect.
- ✓features lists EIP support per chain (the example entry shows EIP155 and EIP1559) rather than assuming every EVM chain implements the same set.
- ✓L2s and shards can declare a parent object pointing at an existing chain's CAIP-2 ID, with an optional bridges list.
- ✓A status field marks a chain active, incubating, or deprecated — deprecated entries stay in the repo instead of being deleted, so old IDs remain traceable.
- ✓Icons live in a separate _data/icons folder as IPFS references (url, width, height, format), reused across chain and explorer entries by name.
Rules and constraints for adding chains
- △Contribution has real friction: adding a chain needs a correctly formatted JSON file, a CI pass via `./gradlew run`, and any icon must resolve through `ipfs get` — Pinata-pinned icons are explicitly rejected for now.
- △No official web UI here — this is the raw metadata source; if you want a browsable list, you go to derivative sites like chainid.network or chainlist.org, not this repo.
- △Topics on the GitHub repo are empty, so discovery inside GitHub search relies on the repo name rather than topic labels.
- △Chain ID assignment is first-come, first-served with no appeals process — the README says PRs arguing a "better" claim to an existing chain ID get closed outright.
How Chainlist differs from eth-chains and chainid.network
Frequently asked questions
Ethereum mainnet's chain ID is 1 (its networkId is also 1), as recorded in Chainlist's own example entry for eip155-1 — the same ID defined by EIP-155.
Yes — base/chains is released under the MIT license, so pulling its chain metadata into a commercial wallet, explorer, or RPC product is permitted; the standard MIT terms, like keeping the copyright notice, still apply.
Add a JSON file for the chain under _data/chains, named with its CAIP-2 ID and following the documented schema (chainId, name, shortName, rpc, nativeCurrency, explorers), then run `./gradlew run` locally so the CI checks pass before opening a pull request.
Chainlist blocks duplicate chain IDs because a reused ID lets a transaction signed for one chain be replayed on another — the replay-attack risk EIP-155 was written to close. The repo assigns each ID to whoever registers it first and closes PRs that try to take over an existing one.
The aggregated file merging every chain entry in Chainlist is published at chainid.network/chains.json, with a smaller chains_mini.json version available when a reduced field set is enough.
A deprecated chain in Chainlist gets its status field set to "deprecated" instead of being deleted, and its chain ID isn't reassigned to a new chain by default — reusing it requires an explicit exception that triggers a "reusedChainId" red flag for wallets to display.
Best use cases
- •Populating a wallet's "add network" flow with a chain's RPC URLs, native currency, and explorer link instead of maintaining that list by hand.
- •Looking up a chain ID or networkId before signing a transaction, to avoid the exact cross-chain replay scenario EIP-155 addresses.
- •Pulling the pre-merged chains.json (or the smaller chains_mini.json) into a backend service that needs EVM network configuration without cloning the repo.
- •Registering a brand-new EVM chain and getting a chain ID that's checked against every existing one before it's accepted.
- •Resolving an explorer URL for a given chain by its declared standard (e.g. EIP3091) instead of guessing the URL pattern.
How to use
There's no package to install — Chainlist is consumed either by cloning base/chains and reading _data/chains/<chain-id>.json files directly, or by fetching the pre-built aggregates at chainid.network/chains.json (every chain, full schema) or chains_mini.json (fewer fields, smaller payload). Each per-chain file follows the documented JSON shape (chainId, name, shortName, nativeCurrency, rpc, explorers, and optional features/parent/status fields); icon references in _data/icons resolve to IPFS URLs rather than local image files.
Who should try it — and who should skip
Reach for Chainlist if you're building or maintaining a wallet, RPC client, or explorer and need a maintained, PR-reviewed source of chain IDs, RPC URLs, and explorer links instead of hardcoding your own list. It's also the right stop if you're registering a brand-new EVM chain and want an ID that won't collide with anyone else's. Skip it if you just want a webpage to click "add network to MetaMask" from — that's chainlist.org or chainid.network, not this repo — or if you need chain data with more fields than this schema documents (it's deliberately minimal: identity, currency, RPC, and explorer info, not gas prices or historical stats).
Still deciding about chains?
One click hands the question to an AI along with this page — see what it says about chains.