Provider Configuration

Configure RPC providers, API keys, and routing priorities

Providers are the upstream RPC endpoints that Lasso routes requests to. Each chain can have multiple providers with different priorities, capabilities, and access methods.

Provider Fields

Providers are defined in the providers list under each chain configuration.

id · string · required

Unique identifier for the provider within the chain. Used in metrics, logs, and provider-specific routing.

providers:
  - id: "ethereum_llamarpc"

name · string

Display name shown in the dashboard and logs. Defaults to id if omitted.

name: "LlamaRPC Ethereum"

url · string · required

HTTP RPC endpoint URL. Supports environment variable substitution.

url: "https://eth.llamarpc.com"

*At least one of url or ws_url is required.

ws_url · string

WebSocket RPC endpoint URL. Required for subscriptions and real-time block tracking.

ws_url: "wss://eth.llamarpc.com"

priority · integer

Routing priority. Lower values = higher priority. Used by the :priority strategy and as a tiebreaker in other strategies.

priority: 2

Common patterns:

• 1-5: Your own nodes and premium providers
• 10-20: Free public providers
• 100+: Last-resort fallbacks

archival · boolean · default: "true"

Whether this provider serves historical/archival data. Non-archival providers are excluded for requests older than selection.archival_threshold.

archival: true

subscribe_new_heads · boolean

Override chain-level websocket.subscribe_new_heads for this provider.

subscribe_new_heads: true

capabilities · object

Provider capabilities and limits. See Capabilities for details.

capabilities:
  limits:
    max_block_range: 1000

Basic Provider Example

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

Environment Variable Substitution

Provider URLs support ${ENV_VAR} substitution for API keys and secrets. Unresolved variables crash at startup to prevent silent misconfiguration.

Basic Substitution

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}"

Set the environment variable:

export ALCHEMY_API_KEY="your-key-here"

Multiple Variables

providers:
  - id: "custom_endpoint"
    url: "https://${RPC_HOST}:${RPC_PORT}/v1/${API_KEY}"

.env File Support

Lasso loads .env files from the project root if present:

# .env
ALCHEMY_API_KEY=your-key-here
DRPC_API_KEY=another-key
CHAINSTACK_API_KEY=third-key

System environment variables take precedence over .env values.

BYOK (Bring Your Own Keys)

Use your own provider API keys alongside public providers for better rate limits and reliability.

Example: Tiered Provider Setup

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

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

      # Tier 3: Free public fallback
      - id: "publicnode"
        url: "https://ethereum-rpc.publicnode.com"
        ws_url: "wss://ethereum-rpc.publicnode.com"
        priority: 10
        archival: false

Benefits of BYOK

Higher rate limits

Paid provider plans typically offer 10-100x higher rate limits than free public endpoints.

Better reliability

Your own nodes and paid providers have dedicated capacity and SLAs.

Cost control

Use free public providers for low-priority traffic and paid providers for critical requests.

Data sovereignty

Route sensitive requests to your own infrastructure while using public providers for general queries.

Provider Override

Bypass routing strategies and send requests directly to a specific provider:

POST /rpc/provider/:provider_id/:chain

Example:

curl -X POST http://localhost:4000/rpc/provider/ethereum_llamarpc/ethereum \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Use cases:

• Testing specific provider behavior
• Debugging provider issues
• Sending requests to providers with unique features

Common Provider Patterns

Archival + Pruned Combination

providers:
  # Archival provider for historical queries
  - id: "drpc_archival"
    url: "https://eth.drpc.org"
    priority: 2
    archival: true
    capabilities:
      limits:
        max_block_range: 10000

  # Pruned provider for recent data (faster, cheaper)
  - id: "publicnode_pruned"
    url: "https://ethereum-rpc.publicnode.com"
    priority: 3
    archival: false
    capabilities:
      limits:
        max_block_age: 1000
        block_age_methods:
          - eth_call
          - eth_getBalance

Lasso automatically routes historical requests to archival providers and recent requests to pruned providers.

WebSocket Fallback

providers:
  # Primary: WebSocket + HTTP
  - id: "drpc"
    url: "https://eth.drpc.org"
    ws_url: "wss://eth.drpc.org"
    priority: 2
    subscribe_new_heads: true

  # Fallback: HTTP only
  - id: "publicnode"
    url: "https://ethereum-rpc.publicnode.com"
    priority: 3
    subscribe_new_heads: false

Multi-Region Setup

providers:
  # US provider
  - id: "alchemy_us"
    url: "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
    priority: 2

  # EU provider
  - id: "chainstack_eu"
    url: "https://ethereum-mainnet.eu.chainstack.com/${CHAINSTACK_API_KEY}"
    priority: 2

  # Asia provider
  - id: "nodereal_asia"
    url: "https://eth-mainnet.asia.nodereal.io/v1/${NODEREAL_API_KEY}"
    priority: 2

Deploy Lasso nodes in each region and configure routing to prefer local providers.

Provider Configuration from default.yml

Here’s a real example from the included default.yml profile:

providers:
  - id: "ethereum_drpc"
    name: "dRPC Ethereum"
    priority: 2
    url: "https://eth.drpc.org"
    ws_url: "wss://eth.drpc.org"
    archival: true
    subscribe_new_heads: true
    capabilities:
      limits:
        max_block_range: 10000
      error_rules:
        - code: 30
          message_contains: "timeout on the free tier"
          category: rate_limit
        - code: 30
          category: rate_limit
        - code: 35
          category: capability_violation

  - id: "ethereum_publicnode"
    name: "PublicNode Ethereum"
    priority: 3
    url: "https://ethereum-rpc.publicnode.com"
    ws_url: "wss://ethereum-rpc.publicnode.com"
    subscribe_new_heads: true
    archival: false
    capabilities:
      unsupported_categories: [debug, trace, txpool, eip4844, filters]
      limits:
        max_block_age: 1000
        block_age_methods:
          - eth_call
          - eth_getBalance
          - eth_getCode
          - eth_getStorageAt
          - eth_getTransactionCount
      error_rules:
        - code: -32701
          category: capability_violation
        - message_contains: "pruned"
          category: requires_archival

Best Practices

Use descriptive provider IDs

Provider IDs appear in metrics and logs. Use names like ethereum_llamarpc or base_alchemy that include both chain and provider.

Set WebSocket URLs when available

WebSocket support enables real-time block tracking and reduces polling overhead.

Configure capabilities accurately

Incorrect capability configuration can cause request failures. Test providers and document their actual limits.

Layer providers by priority

Use priority tiers to control routing order: own nodes (1-5), paid providers (10-20), free providers (30-50), fallbacks (100+).

Document provider quirks

Use YAML comments to note rate limits, known issues, or special behavior.

Next Steps

Capabilities

Configure provider capabilities and error handling

Environment Variables

Learn about runtime configuration options