How do you use a Chainlist-style directory to find supported RPC networks and endpoints?

A Chainlist-style directory is a lookup table for two things developers constantly need: the chain ID of a network and one or more RPC endpoints that speak JSON-RPC for that chain. When you add a custom network to MetaMask, configure a viem client, or point a backend indexer at a new chain, you are really asking "what chain ID is this, and what URL do I call?" Directories answer that question in a browser instead of in scattered docs.

This page explains how those directories are organized, how to read the metadata they expose, how to verify an endpoint before you depend on it, and when a public directory entry is no longer the right tool for the job.

Quick recommendation: directory entry vs managed endpoint

Use a public directory entry when you are exploring a chain, testing a wallet integration, or writing a one-off script. Use a managed RPC API or dedicated node when the endpoint is on a request path that real users depend on.

The dividing line is not "mainnet vs testnet" — it is whether a failed request breaks something a user cares about. If a dropped connection means a failed transaction for a paying user, a directory listing is the wrong abstraction.

If you are already past the exploration stage, jump to supported RPC networks to see which chains are available through a managed endpoint, and RPC pricing to understand how usage is metered.

What a Chainlist-style directory actually stores

A directory entry is structured metadata, not just a URL. The fields that matter for integration are consistent across most directories because they map to the EIP-3085 wallet_addEthereumChain parameters that wallets already understand.

A directory is only as good as its last update. Endpoints get retired, rate limits change, and chains fork. Treat any listing as a starting point for verification, not a guarantee.

How to verify an endpoint before you trust it

Verification is a short sequence of JSON-RPC calls. Run these against any endpoint you pull from a directory before you wire it into an app.

# 1. Confirm the chain ID matches what the directory claims
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

# 2. Confirm the node is synced by comparing block height to a known source
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 3. Confirm the methods you actually need are supported
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{"fromBlock":"latest","toBlock":"latest"}]}'

Step 3 is the one people skip. An endpoint can return a valid eth_chainId and still reject eth_getLogs, debug_traceTransaction, or archive queries. Test the exact methods your app calls, not just the handshake.

If you are configuring a wallet rather than a backend, the same data goes into a network config object:

await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x38',
    chainName: 'BNB Smart Chain Mainnet',
    nativeCurrency: { name: 'BNB Chain Native Token', symbol: 'BNB', decimals: 18 },
    rpcUrls: ['https://bnb.api.onfinality.io/public'],
    blockExplorerUrls: ['https://bscscan.com'],
  }],
});

Keep the chain ID, symbol, decimals, and explorer URL consistent with the source you verified. Mixing values from two different directories is a common cause of "wrong network" bugs.

Reading a directory entry correctly

When you open a listing, work through it in this order:

1. Match the chain ID first. Names are ambiguous — several networks share similar names. The numeric ID is the source of truth.
2. Check the endpoint transport. Some entries are HTTP-only, some expose WebSocket, some expose both. If your app needs live subscriptions, confirm ws support before you commit.
3. Note how many endpoints are listed. A single endpoint is a single point of failure. If the directory lists several, that is a hint the maintainers expect rotation.
4. Check the explorer link. A working explorer is your fastest debugging tool when a transaction behaves unexpectedly.
5. Look for a testnet counterpart. If you are building, you want a testnet entry with the same structure so you can rehearse deploys.

For chains where you need a stable endpoint across environments, OnFinality exposes both mainnet and testnet endpoints through the same API surface, so your client code does not change between them. See BNB Chain and BNB Chain Testnet for an example of that pairing.

When a listed endpoint fails

Public endpoints fail in predictable ways. Match the symptom to the cause before you start changing code.

Most of these are not bugs in your code. They are signs that a shared public endpoint is being asked to do production work. The fix is usually to move that traffic to an endpoint with a defined capacity and a support path.

Public directory vs managed RPC API vs dedicated node

These three options sit on a spectrum from "free and shared" to "isolated and operated for you." The right choice depends on how much of your product depends on the endpoint.

OnFinality provides both a managed RPC API service and dedicated nodes, so you can start on shared infrastructure and move specific chains to isolated nodes as load grows. The provider selection guide walks through the evaluation criteria in more detail.

A practical migration path

You do not have to move everything at once. A staged approach keeps risk low:

1. Inventory. List every chain your app touches and the methods it calls. Note which ones need archive data, traces, or WebSocket.
2. Classify. Mark each chain as "exploration," "production read," or "production write." Only the last two need managed infrastructure.
3. Pilot one chain. Move a single production chain to a managed endpoint, keep the public one as a fallback, and compare error rates for a week.
4. Add failover. Configure a secondary endpoint so a single provider outage does not take down your app.
5. Expand. Move remaining production chains once the pilot pattern is proven.

Keep the directory entry around as documentation. It is useful for onboarding new developers even after you stop using its endpoints in production.

Key Takeaways

• A Chainlist-style directory maps chain IDs to RPC endpoints and the metadata wallets need to add a network.
• Always verify an endpoint with eth_chainId, eth_blockNumber, and the specific methods your app calls before trusting it.
• Public directory endpoints are fine for exploration and prototypes, but they lack capacity guarantees for production traffic.
• Match the symptom to the cause when an endpoint fails — most failures are capacity or method-support issues, not code bugs.
• Managed RPC APIs and dedicated nodes give you defined capacity, usage visibility, and a support path when the endpoint is on a critical request path.
• Keep chain ID, symbol, decimals, and explorer URL consistent across every config you write.

Frequently Asked Questions

Is a Chainlist-style directory the same as an RPC provider?

No. A directory is a reference list of endpoints contributed by various operators. An RPC provider operates the nodes behind an endpoint and offers capacity, monitoring, and support. Directories help you discover endpoints; providers help you run them in production.

Can I use a public endpoint from a directory in production?

Technically yes, but it is risky. Public endpoints are typically shared and rate-limited, with no guarantees about availability or method support. For anything user-facing, use a managed endpoint with a defined capacity and a fallback.

Why does an endpoint return a valid chain ID but fail on other calls?

Chain ID is a cheap call that almost any node can answer. Methods like eth_getLogs, debug_traceTransaction, or archive queries require more resources and may be disabled or limited on shared nodes. Always test the methods your app actually uses.

How do I add a network to a wallet using directory data?

Use the wallet_addEthereumChain method with the chain ID, chain name, native currency, RPC URL, and explorer URL from the directory entry. Verify the chain ID first, since names can be ambiguous.

What should I do when a listed endpoint starts returning 429 errors?

That usually means you have hit a shared rate limit. Reduce burst volume if possible, add a fallback endpoint, and consider moving that traffic to a managed RPC API or dedicated node where capacity is defined.

Does OnFinality support multiple chains through one API?

OnFinality provides RPC API access across a range of networks. Check the supported RPC networks page for the current list and RPC pricing for how usage is structured.