Skip to main content

​
Introduction

Sol RPC Router uses TOML-based configuration files to define backends, routing rules, health checks, and proxy behavior. All configuration is validated on startup to ensure consistency and prevent runtime errors.

​
Configuration File Location

By default, the router loads configuration from config.toml in the current directory. You can specify a custom path using the --config flag: 
./sol-rpc-router --config /path/to/config.toml

​
File Structure

A complete configuration file contains the following sections: 
# Server Configuration
port = 28899
metrics_port = 28901
redis_url = "redis://127.0.0.1:6379/0"

# Backend Definitions
[[backends]]
label = "mainnet-primary"
url = "https://api.mainnet-beta.solana.com"
weight = 10
ws_url = "wss://api.mainnet-beta.solana.com"

# Proxy Settings
[proxy]
timeout_secs = 30

# Health Check Configuration
[health_check]
interval_secs = 30
timeout_secs = 5
method = "getSlot"
consecutive_failures_threshold = 3
consecutive_successes_threshold = 2
max_slot_lag = 50

# Method-Based Routing
[method_routes]
getSlot = "mainnet-primary"

​
Required vs Optional Sections

​
Required

​
port
integer
required
HTTP server port for incoming RPC requests
​
metrics_port
integer
required
Port for Prometheus metrics endpoint
Must be different from port and WebSocket port (port + 1)
​
redis_url
string
required
Redis connection URL for rate limiting and caching
Cannot be empty. Example: redis://127.0.0.1:6379/0
​
backends
array
required
Array of backend RPC nodes. At least one backend must be configured.See Backend Configuration for details.

​
Optional

​
proxy
object
Proxy behavior settings. Defaults to 30-second timeout if omitted.See Proxy Configuration for details.
​
health_check
object
Health check settings. Uses default values if omitted.See Health Check Configuration for details.
​
method_routes
object
Method-specific routing overrides. Optional.See Method Routing for details.

​
Validation Rules

The configuration is validated on startup with the following checks:
Configuration file must exist at the specified path
Redis URL must be non-empty
At least one backend must be configured
All backend labels must be unique
All backend weights must be greater than 0
All backend labels must be non-empty
Proxy timeout must be greater than 0
HTTP port and metrics port must be different
Metrics port cannot conflict with WebSocket port (HTTP port + 1)
Method routes must reference existing backend labels
If any validation fails, the router will exit with an error message indicating the specific issue.

​
Proxy Settings

​
proxy.timeout_secs
integer
default:"30"
Timeout in seconds for upstream backend requestsValidation: Must be greater than 0

​
Port Configuration

The router uses multiple ports:
  • HTTP Port: Main RPC endpoint (port)
  • WebSocket Port: Automatically set to port + 1
  • Metrics Port: Prometheus metrics (metrics_port)
Ensure your metrics port doesn’t conflict with the HTTP port or WebSocket port. For example, if port = 8080, the WebSocket will use 8081, so metrics_port cannot be 8080 or 8081.

​
Example Configurations

​
Minimal Configuration

port = 8081
metrics_port = 8082
redis_url = "redis://127.0.0.1:6379"

[[backends]]
label = "primary"
url = "https://api.mainnet-beta.solana.com"
weight = 1

​
Production Configuration

port = 28899
metrics_port = 28901
redis_url = "redis://127.0.0.1:6379/0"

[[backends]]
label = "mainnet-primary"
url = "https://api.mainnet-beta.solana.com"
weight = 10
ws_url = "wss://api.mainnet-beta.solana.com"

[[backends]]
label = "backup-rpc"
url = "https://solana-api.com"
weight = 5

[proxy]
timeout_secs = 30

[health_check]
interval_secs = 30
timeout_secs = 5
method = "getSlot"
consecutive_failures_threshold = 3
consecutive_successes_threshold = 2
max_slot_lag = 50

[method_routes]
getSlot = "mainnet-primary"

​
Next Steps

Backend Configuration

Configure RPC backends with weights and WebSocket support

Health Checks

Set up automatic health monitoring for backends

Rate Limiting

Configure per-API-key rate limits

Method Routing

Route specific RPC methods to designated backends

Build docs developers (and LLMs) love

Get started for freeTalk to us