Routing strategies

Configure with routing.strategy in your TOML config. The default is best_score.

---

best_score (default)

Reads go to the provider with the highest current health score. The full list sorted by score descending is used as the failover order.

[helius:0.91] → [quicknode:0.84] → [triton:0.72]
      ↑ first choice      retry 1       retry 2

[routing]
strategy = "best_score"

Good for: most production workloads. Always prefers the most reliable provider at the moment.

---

weighted_random

Each provider's selection probability is proportional to config_weight × health_score. The remaining providers sorted by score serve as the failover list.

[routing]
strategy = "weighted_random"

[[providers]]
name   = "helius"
url    = "..."
weight = 2   # twice as likely to be selected

[[providers]]
name   = "quicknode"
url    = "..."
weight = 1

Good for: distributing load across providers of similar quality, staying within per-provider rate limits, spreading costs.

---

failover_ordered

Providers are tried in the order they appear in the config file. Circuit-open providers are skipped. The first provider in config is always primary until its circuit opens.

[routing]
strategy = "failover_ordered"

[[providers]]
name = "helius"     # primary — always first
url  = "..."

[[providers]]
name = "quicknode"  # only used when helius is unavailable
url  = "..."

Good for: clear primary/secondary hierarchy, deterministic routing, cost control (cheap primary, expensive failover).

---

parallel_race

The request is sent to all healthy providers simultaneously. The first successful response wins; the others are cancelled.

[routing]
strategy = "parallel_race"

Good for: latency-critical reads where you can absorb N× the provider traffic cost.

---

Writes always broadcast

sendTransaction and simulateTransaction are always broadcast to all healthy providers, regardless of strategy. Duplicate submissions are harmless — Solana deduplicates by signature. Broadcasting maximises the probability that at least one provider relays the transaction to the current leader.

---

Retries

On a retryable error, the proxy tries the next provider in the ordered list up to routing.max_retries times (default: 2).

Category	Error codes	Behaviour
Retryable	HTTP 429, 500, 502, 503, 504	Try next provider
Retryable (RPC)	-32003, -32005, -32603	Try next provider
Non-retryable	HTTP 400, 401, 403, 404	Return immediately
Non-retryable (RPC)	-32700, -32600, -32601, -32602	Return immediately