Provider configuration

Provider Configuration

Each provider is an entry in a chain’s providers list.

providers:
  - id: "ethereum_llamarpc"
    name: "LlamaRPC Ethereum"
    priority: 2
    url: "https://eth.llamarpc.com"
    ws_url: "wss://eth.llamarpc.com"
    archival: true
    subscribe_new_heads: true
    capabilities:
      limits:
        max_block_range: 1000

Field	Type	Required	Description
`id`	string	Yes	Unique provider identifier within the chain
`name`	string	No	Display name (defaults to `id`)
`priority`	integer	No	Lower = higher priority. Used by `:priority` strategy and as tiebreaker
`url`	string	Yes*	HTTP RPC endpoint URL
`ws_url`	string	No	WebSocket RPC endpoint URL. Required for subscriptions
`archival`	boolean	No	Whether this provider serves historical data (default: true)
`subscribe_new_heads`	boolean	No	Override chain-level `subscribe_new_heads` for this provider
`capabilities`	map	No	Provider capabilities (see Capabilities below)
`sharing_mode`	string	No	`auto` shares identical upstream runtime; `isolated` separates it by profile
`api_key`	string	No	Sends `Authorization: Bearer <value>`
`headers`	map	No	HTTP request and WebSocket handshake headers, overriding defaults
`auth_headers`	map	No	Headers with precedence over `headers` and `api_key`

*At least one of url or ws_url is required.

Environment Variable Substitution

Provider URLs support ${ENV_VAR} substitution. Unresolved variables reject a profile at startup or reload. Substitution also applies to api_key, headers, and auth_headers.

providers:
  - id: "alchemy_ethereum"
    url: "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
    ws_url: "wss://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"

Provider Credentials

Use your own provider API keys alongside public providers:

chains:
  ethereum:
    chain_id: 1
    providers:
      # Your own node (highest priority)
      - id: "my_erigon"
        url: "http://my-erigon:8545"
        priority: 1

      # Paid provider with your API key
      - id: "alchemy"
        url: "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
        priority: 2

      # Free public fallback
      - id: "publicnode"
        url: "https://ethereum-rpc.publicnode.com"
        priority: 10

In RPC Core v0.5.0, subscribe_new_heads controls automatic block tracking and client newHeads eligibility. Providers inherit the chain setting, which defaults to true; set a provider override to false when that upstream must not serve newHeads. A WebSocket URL is also required for subscriptions. See Profile configuration. Provider declarations describe intended support; validate the exact method, parameter shape, history, and plan you need against the upstream.

Get Started

Core Concepts

Configuration

Deployment

Observability

Advanced

Provider configuration