Skip to main content

​
Overview

This guide will walk you through setting up Sol RPC Router from scratch. You’ll learn how to build the router, configure Redis, set up backend endpoints, create API keys, and make your first authenticated request.
Prerequisites: Make sure you have Rust (2021 edition) and Redis installed. See the Installation guide for detailed setup instructions.

​
Quick Setup

1

Clone and Build

Build Sol RPC Router from source:
git clone https://github.com/glamsystems/sol-rpc-router
cd sol-rpc-router
cargo build --release
This will create two binaries:
  • ./target/release/sol-rpc-router - The main proxy server
  • ./target/release/rpc-admin - The API key management CLI
The release build is optimized for production use. For development, you can use cargo build (without --release) for faster compilation.
2

Start Redis

Sol RPC Router requires Redis for API key storage and rate limiting:
# Using Docker
docker run -d -p 6379:6379 redis:7-alpine

# Or using a local Redis installation
redis-server
Verify Redis is running:
redis-cli ping
# Should return: PONG
3

Configure the Router

Create a config.toml file based on the example:
cp config.example.toml config.toml
Here’s a minimal configuration to get started:
config.toml
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

[method_routes]
getSlot = "mainnet-primary"
Configuration Details:
  • port: HTTP server listens here. WebSocket automatically uses port + 1
  • weight: Higher values receive more traffic (10:5 = 2:1 distribution)
  • ws_url: Optional WebSocket endpoint for subscriptions
  • method_routes: Pin specific RPC methods to backends
4

Start the Router

Launch the router with your configuration:
./target/release/sol-rpc-router --config config.toml
You should see output like:
Loaded configuration from: config.toml
Redis URL configured (host redacted)
Loaded 2 backends
  - [mainnet-primary] https://api.mainnet-beta.solana.com (weight: 10)
  - [backup-rpc] https://solana-api.com (weight: 5)
Method routing overrides:
  - getSlot -> mainnet-primary
HTTP server listening on http://0.0.0.0:28899
WebSocket server listening on ws://0.0.0.0:28900
Metrics server listening on http://0.0.0.0:28901
Health monitoring endpoint: http://0.0.0.0:28899/health
Starting health check loop
5

Create an API Key

Use the rpc-admin CLI to create your first API key:
./target/release/rpc-admin create my-client --rate-limit 50
Output:
Created API key for my-client:
a7f3K9mN2pQ5sT8vX1wY4zB6cD0eF3gH
The API key is automatically generated as a 32-character alphanumeric string. You can also specify a custom key using --key your-custom-key.
Common rpc-admin commands:
./target/release/rpc-admin list
6

Make Your First Request

Test the router with a JSON-RPC request:
curl -X POST http://localhost:28899/?api-key=a7f3K9mN2pQ5sT8vX1wY4zB6cD0eF3gH \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSlot"
  }'
Expected response:
{
  "jsonrpc": "2.0",
  "result": 123456789,
  "id": 1
}
Authentication Required: All requests must include ?api-key= as a query parameter. Requests without a valid API key will receive a 401 Unauthorized response.

​
Test WebSocket Connections

Sol RPC Router supports WebSocket subscriptions on both the main HTTP port (via upgrade) and a dedicated WebSocket port: 
wscat -c "ws://localhost:28899/?api-key=a7f3K9mN2pQ5sT8vX1wY4zB6cD0eF3gH"
Send a subscription request: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "slotSubscribe"
}

​
Monitor Health and Metrics

Check backend health status: 
curl http://localhost:28899/health
Response: 
{
  "backends": [
    {
      "label": "mainnet-primary",
      "healthy": true,
      "consecutive_failures": 0,
      "consecutive_successes": 5,
      "last_check": "2026-03-03T10:30:45Z",
      "last_error": null
    },
    {
      "label": "backup-rpc",
      "healthy": true,
      "consecutive_failures": 0,
      "consecutive_successes": 5,
      "last_check": "2026-03-03T10:30:45Z",
      "last_error": null
    }
  ]
}
View Prometheus metrics: 
curl http://localhost:28901/metrics

​
Rate Limiting in Action

Test the rate limiter by exceeding your configured limit: 
# Create a key with a very low limit
./target/release/rpc-admin create test-client --rate-limit 2

# Make 3 rapid requests (the 3rd should be rate limited)
for i in {1..3}; do
  curl -X POST "http://localhost:28899/?api-key=<your-key>" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
  echo ""
done
The third request will return: 
{
  "error": "Rate limit exceeded"
}
with HTTP status 429 Too Many Requests.

​
Next Steps

Configuration Guide

Learn about advanced configuration options, method routing, and health checks

API Reference

Complete endpoint documentation and request/response examples

Deployment

Production deployment strategies, monitoring, and best practices

Metrics & Monitoring

Set up Prometheus and Grafana dashboards for your router

​
Troubleshooting

Error: Failed to initialize Redis KeyStoreSolutions:
  • Verify Redis is running: redis-cli ping
  • Check the redis_url in your config.toml
  • Ensure Redis is accessible on the configured port
  • Check firewall rules if Redis is on a remote host
Error: All requests return 401 UnauthorizedSolutions:
  • Ensure you’re passing ?api-key= as a query parameter
  • Verify the API key exists: ./target/release/rpc-admin inspect <key>
  • Check that the key is active: active should be true
  • Confirm Redis is running and accessible
Error: Failed to connect to backendSolutions:
  • Verify backend URLs are correct in config.toml
  • Test backend connectivity: curl <backend_url>
  • Check the /health endpoint for backend status
  • Review health_check.method - ensure the RPC method is supported
Solutions:
  • Check /health endpoint for error details
  • Verify health_check.method is a valid RPC method (e.g., getSlot)
  • Increase health_check.timeout_secs if backends are slow
  • Review backend logs for errors
  • Test backends directly with curl

Build docs developers (and LLMs) love

Get started for freeTalk to us