# Scale chains & providers

> Source: https://docs.erpc.cloud/use-cases/scale-chains-and-providers
> One config line per provider, every chain they support — and the best upstream wins each request.
> Format: machine-readable markdown export of the docs page above.
> All collapsible AI sections are inlined and fully expanded.

# Scale chains & providers

Supporting a new chain shouldn't be a project. Give eRPC one provider API key and it
unlocks every chain that vendor supports — upstreams appear lazily the first time a
request needs them. Behind the scenes, a scoring engine continuously ranks all your
endpoints on real latency, errors, and how far behind the chain tip they are, so the
next request always goes to whoever deserves it most. Auditioning a brand-new provider?
Mirror live traffic to it in shadow mode before trusting it with a single real response.

- **[Providers](/config/projects/providers.llms.txt)** — 22 vendors built in — one key, all their chains.
- **[Networks](/config/projects/networks.llms.txt)** — Per-chain settings and friendly aliases like /main/arbitrum.
- **[Upstreams](/config/projects/upstreams.llms.txt)** — Fine-grained control over each endpoint when you need it.
- **[Selection & scoring](/config/projects/selection-policies.llms.txt)** — Live health metrics pick the best upstream, every time.
- **[Shadow upstreams](/config/projects/shadow-upstreams.llms.txt)** — Test new providers on real traffic with zero user impact.

All of the above in one place — illustrative, not a tuned production config:

**Config path:** `projects[]`

**YAML — `erpc.yaml`:**

```yaml
projects:
  - id: main
    # one key → every chain the vendor supports, upstreams appear lazily
    providers:
      - endpoint: alchemy://\${ALCHEMY_API_KEY}
      - endpoint: drpc://\${DRPC_API_KEY}
    upstreams:
      # mix in your own node alongside vendors
      - id: my-own-node
        endpoint: http://10.0.0.5:8545
      # audition a new provider on 20% of live traffic, zero user impact
      - id: candidate-provider
        endpoint: https://rpc.new-vendor.xyz
        shadow:
          enabled: true
          sampleRate: 0.2
    networks:
      - architecture: evm
        evm: { chainId: 1 }
        # /main/ethereum instead of /main/evm/1
        alias: ethereum
        # who deserves the next request, re-evaluated continuously
        selectionPolicy:
          evalFunc: |
            (upstreams, ctx) => upstreams
              .preferTag('!tier:fallback')
              .sortByScore()
```

**TypeScript — `erpc.ts`:**

```typescript
projects: [{
  id: "main",
  // one key → every chain the vendor supports, upstreams appear lazily
  providers: [
    { endpoint: \`alchemy://\${process.env.ALCHEMY_API_KEY}\` },
    { endpoint: \`drpc://\${process.env.DRPC_API_KEY}\` },
  ],
  upstreams: [
    // mix in your own node alongside vendors
    { id: "my-own-node", endpoint: "http://10.0.0.5:8545" },
    // audition a new provider on 20% of live traffic, zero user impact
    {
      id: "candidate-provider",
      endpoint: "https://rpc.new-vendor.xyz",
      shadow: { enabled: true, sampleRate: 0.2 },
    },
  ],
  networks: [{
    architecture: "evm",
    evm: { chainId: 1 },
    // /main/ethereum instead of /main/evm/1
    alias: "ethereum",
    // who deserves the next request, re-evaluated continuously
    selectionPolicy: {
      evalFunc: (upstreams, ctx) =>
        upstreams.preferTag("!tier:fallback").sortByScore(),
    },
  }],
}]
```

## Agent reference

Copy one of these prompts into your AI agent session (Claude Code, Cursor, …) — each one
points the agent at this page's machine-readable reference so it can do the work correctly:

**Prompt Example #1: add new chains and providers from scratch**

```text
I want to add Alchemy and dRPC to my eRPC config so every chain they support is
available automatically, with live scoring picking the best upstream per request.
Work with my existing eRPC config. Read the full reference first:
https://docs.erpc.cloud/use-cases/scale-chains-and-providers.llms.txt
```

**Prompt Example #2: shadow-test a new provider before trusting it**

```text
I want to audition a new RPC vendor on real traffic before giving it any production
requests. Configure a shadow upstream in my eRPC config that mirrors a sample of live
traffic to the candidate and logs mismatches, with zero user impact. Read the
reference first: https://docs.erpc.cloud/use-cases/scale-chains-and-providers.llms.txt
```

**Prompt Example #3: tune scoring so fallback providers stay idle unless needed**

```text
I have primary and fallback providers in my eRPC config and I want the selection policy
to always prefer primaries and only route to fallbacks when primaries are degraded.
Walk through the scoring and tag config to make this work. Reference:
https://docs.erpc.cloud/use-cases/scale-chains-and-providers.llms.txt
```

---

### Scale chains — agent starting points

This page sells the outcome; implementation lives in the feature pages. Fetch their
machine-readable companions:

- [Providers](/config/projects/providers.llms.txt) — every vendor's settings keys, URL shortcut schemes, lazy upstream generation.
- [Networks](/config/projects/networks.llms.txt) — network defaults inheritance, aliases, lazy bootstrap.
- [Upstreams](/config/projects/upstreams.llms.txt) — endpoint schemes, block availability gating, cordon reasons, defaults inheritance.
- [Selection & scoring](/config/projects/selection-policies.llms.txt) — score components, multipliers, custom eval functions, tags.
- [Shadow upstreams](/config/projects/shadow-upstreams.llms.txt) — mirroring, sampling, mismatch observability.

Resolution chain an agent must know: provider shortcut endpoints expand to vendor-specific
upstreams per network on first use; explicit `upstreams` and generated ones merge, with
`upstreamDefaults` then upstream-level overrides applied; the selection policy orders the
final set before every request. Full field tables live in each page's agent section.

---


## Navigation (machine-readable surface)

- Up: [All pages index](https://docs.erpc.cloud/llms.txt)
- Root index of every page: [llms.txt](https://docs.erpc.cloud/llms.txt) · everything in one file: [llms-full.txt](https://docs.erpc.cloud/llms-full.txt)

### Sibling pages

- [Cut RPC cost & latency](https://docs.erpc.cloud/use-cases/cut-costs-and-latency.llms.txt) — Serve repeated questions from cache, deduplicate identical requests, and stop paying providers for the same answer twice.
- [How eRPC works](https://docs.erpc.cloud/use-cases/how-it-works.llms.txt) — Every JSON-RPC call travels a battle-tested pipeline — auth, smart caching, parallel hedging, multi-upstream consensus — and arrives with full diagnostic headers. Zero glue code required.
- [Lock it down](https://docs.erpc.cloud/use-cases/lock-it-down.llms.txt) — Keys, JWTs, sign-in with Ethereum, per-user rate limits — your RPC endpoint stops being a free-for-all.
- [See everything](https://docs.erpc.cloud/use-cases/see-everything.llms.txt) — Per-request metrics, traces, and honest healthchecks — know about problems before your users do.
- [Survive provider outages](https://docs.erpc.cloud/use-cases/survive-provider-outages.llms.txt) — Keep serving traffic when an RPC provider slows down, rate-limits you, or disappears entirely.
- [Trust the data](https://docs.erpc.cloud/use-cases/trust-the-data.llms.txt) — Don't let one misbehaving node feed your app a wrong answer — verify, cross-check, and enforce integrity automatically.