Configure RPC upstream pools

The platform reaches every EVM network through a pool of RPC upstreams: your own nodes, managed providers, or a mix. You manage that pool per network from the Console. The platform scores the upstreams on block-height lag, routes each call to a healthy and current one, retries transient failures, and fails over when an upstream goes down. When no upstream looks healthy for a moment, it keeps the network serving on the best upstream it can still reach rather than going dark.

You configure the same pool the platform uses internally and the one behind the authenticated JSON-RPC endpoint. One pool serves both.

Who can do this

Configuring upstream pools is an administrator task. The RPC control plane page sits in the admin area of the Console and is reachable only by users with the platform admin role. For how the admin role fits the wider access model, see admin operating model.

When you configure a pool

You set a network's upstream pool in two situations:

• During platform setup. The setup wizard includes an RPC endpoints step. The step is complete once you save at least one upstream for the network, so a deployment does not go live on chart defaults alone.
• During operations. Open the RPC control plane page from the admin area at any time to add a provider, rotate a credential, change failover order, or remove an upstream.

Both surfaces use the same editor and write to the same pool.

Set a network's upstream pool

A pool serves a network well when it has more than one healthy upstream: a primary the platform routes most traffic to, and at least one backup it can fail over to. Set that up per network.

1. Open the RPC control plane page from the admin area, or reach the RPC endpoints step during platform setup.
2. Select the network you want to configure from the network list.
3. Add one upstream for each node or provider the network should use. For each upstream, set the provider, the endpoint URL, the credential when the provider needs one, and a weight.
4. Order the upstreams. The order is the failover preference: the platform prefers the upstreams nearer the top while they stay healthy and current.
5. Save the pool. In the admin page, a confirmation panel lists the upstreams before you commit. In the setup wizard, the save is direct.

A saved pool becomes a stored override for that network. The override layers over the deployment configuration, so the network now follows what you saved in the Console rather than the chart defaults.

Choose a provider

Each upstream names a provider. The provider you pick sets which credential fields appear:

Selecting a provider preloads its usual credential type. You can still adjust the fields per upstream.

Set the endpoint URL

Enter the upstream's RPC URL. The platform validates the endpoint when you save: it calls the upstream and rejects the save if the endpoint is unreachable, returns an error, or reports a different chain than the network expects. A save that fails validation does not change the live pool, so a typo or a wrong URL cannot quietly take a network offline.

Store credentials

Enter a credential only for an upstream that needs one. An API-key provider takes a header name and the key value; a basic-auth provider takes a username and password.

The platform encrypts every stored credential and never shows the value again. When you reopen the editor, a saved credential shows a placeholder rather than the secret. The platform writes a credential only when you type a replacement value, so saving a pool without re-entering a secret keeps the stored one in place. After a save, the editor clears any secret you typed from the form.

Set weights and order

Each upstream carries a positive weight and a position in the list. The platform uses the order as failover preference and the weight to distribute traffic across upstreams it considers equally healthy. Put the upstream you want to serve most traffic near the top with a higher weight, and place backups below it.

Clear an override

To return a network to its deployment configuration, open the network in the editor and clear the override. The platform removes the stored pool, and the network falls back to the upstreams defined in the deployment configuration. Clearing is available only for a network whose pool currently comes from a saved override; a network already on deployment configuration has nothing to clear.

Read the health view

The RPC control plane page shows a health view for each network's upstreams. Use it to confirm which upstream is serving traffic and to spot an upstream that is lagging or failing.

Liveness reads as follows:

When scores are stale

The platform keeps upstream health scores in a shared store so every replica routes on the same view. If that store is unavailable, the page shows a banner that the scores are stale. While the banner is shown, treat the health view as informational: each replica falls back to its own local liveness checks rather than the shared scores, so the view is not authoritative until the store recovers.

When every upstream looks unhealthy

A network keeps serving even when no upstream passes the health gate. The platform picks the upstream to route to in order of preference:

1. A healthy, current upstream, the normal case.
2. If none qualify, the best reachable upstream that is excluded only for lag or a failing health check. The platform serves this one as a best effort instead of letting the network go dark.
3. If none are reachable either, any remaining upstream, as a last resort.

This matters most right after a node restarts or a brief network blip. The upstream can still carry a stale unhealthy score for up to a minute, but the platform tries it again on the very next request instead of waiting for the next health check. A request that succeeds clears the upstream's penalty and returns it to the healthy tier. The pool reports every upstream exhausted only when each fallback attempt actually fails, so a transient exclusion does not take the network offline.

While a network is serving in this degraded state, the health view still shows the upstreams as excluded or unhealthy. That is expected: the platform is serving the best option it has while the upstreams recover. Treat it as a signal to check why the upstreams dropped out, not as an outage on its own.

Verify the pool is working

After you save a pool:

1. Confirm the network shows its upstreams in the health view.
2. Watch the Serving column to see which upstream the platform routes to.
3. Check that backups read as healthy so failover has somewhere to go.
4. If an upstream stays excluded, check its tip lag: an upstream that trails the network tip is held out of routing while healthier upstreams exist. If every upstream is excluded at once, see when every upstream looks unhealthy.

For chain-level health signals alongside the pool view, see observability.

Related

• JSON-RPC endpoint for the authenticated read endpoint served by the same upstream pools.
• Admin operating model for the wider administration map.
• Supported networks for the EVM connectivity a network needs before it can serve RPC traffic.
• Observability for monitoring chain and platform health.