rpcgate

rpcgate

rpcgate — self-hosted open-source proxy and load balancer for EVM RPC providers.

rpcgate lets you run your own lightweight gateway that connects to multiple Ethereum-compatible RPC providers.
It increases reliability, provides unified access across chains, and exposes metrics for observability.

Features

• Multi-chain configuration — define gateways for several networks in a single file.
• Multi-provider setup — balance requests across public RPCs or private nodes for high availability.
• Metrics — observe provider latency, error rates and usage.
• Client tracking — per-application statistics.

Quick start

1. Clone repo.

   git clone https://github.com/BinaryArchaism/rpcgate.git
   cd rpcgate
   

2. Create config file.
3. Build an image.

   docker build -t rpcgate .
   

4. Run it.

   docker run -p port:8080 -v your-config-path:/config.yaml [-d] rpcgate
   

Config placeholders

rpcgate supports environment variable placeholders in the config. Use the ${VAR_NAME} format — rpcgate will substitute the value from the environment and panic on missing variables.

rpcs:
  - name: mainnet
    chain_id: 1
    balancer_type: round-robin
    providers:
      - name: ankr
        conn_url: https://rpc.ankr.com/eth/${ANKR_MAINNET_TOKEN}

Placeholders can be used anywhere in the YAML file.

Load balancing options

• p2cewma Adaptive algorithm based on Exponentially Weighted Moving Average (EWMA) latency, in-flight load, and penalties for providers errors.
• round-robin Simple rotation of requests across providers.
• least-connection Distributes requests based on the number of active in-flight calls per provider. It always prefers providers that are currently less loaded.

p2cewma is a default option for http. The p2cewma algorithm automatically adapts to provider latency and reliability, giving higher throughput under variable RPC conditions. p2cewma is not available for websocket.

To configure a balancing strategy, specify it per-chain in your config:

rpcs:
  - name: mainnet
    balancer_type: p2cewma # [p2cewma, round-robin, least-connection]
  - name: base
    # omit balancer_type to use default (p2cewma)

You can define global defaults or override them per-RPC when using this load-balancing algorithm:

p2cewma: # global
  smooth: 0.3
  load_normalizer: 8
  penalty_decay: 0.8
  cooldown_timeout: 10s

rpcs:
  - name: base
    chain_id: 8453
    p2cewma: # local
      smooth: 0.5
      load_normalizer: 16
      penalty_decay: 0.5
      cooldown_timeout: 5s
    providers:
      ...

Option explained:

• smooth - [0;1] controls how quickly latency changes affect the score. Higher values → faster adaptation, lower values → smoother response.
• load_normalizer - >0 reduces load on already busy providers. Smaller values make the balancer avoid heavily loaded RPCs more aggressively.
• penalty_decay - [0;1] defines how quickly an error penalty fades. Lower values mean a provider stays “punished” for longer after a failure.
• cooldown_timeout - duration for which a provider stays inactive after an error. Example: 10s, 30s, 1m.

Client tracking options

rpcgate can identify requests by client using either Basic Auth or a query parameter, so you can track metrics per application without changing any code.

• Basic Auth

  clients:
    auth_required: false # default
    type: basic          # default
    clients: 
      - login: admin
        password: test   # optional
  

  Connection string examples:

  • https://admin:test@rpcgate-url/1
  • https://admin:@rpcgate-url/1
  • https://admin@rpcgate-url/1

  If you don’t need a password, omit it.

  Note: Some SDKs (like Web3.py) require a colon : after username even if no password is set.

• Query parameter

  clients:
    type: query 
  

  Connection string example:

  • https://rpcgate-url/1?client=admin

Grafana Dashboard

An official Grafana dashboard is available for rpcgate.

The dashboard visualizes key rpcgate metrics — RPS, latency (p50/p95/p99), error rates, load distribution across providers, and response sizes.

🪪 License

MIT — see LICENSE