Honeycluster Docs – Architecture

Architecture

How Honeycluster distributes XRP Ledger traffic across Clio and rippled nodes, applies fair-use rate limits, and routes HTTPS + WebSocket connections to the nearest healthy region.

Honeycluster is a distributed layer in front of the XRP Ledger's public node software. It exists so application developers don't have to run their own rippled or Clio instances to serve production traffic — you hit a single set of endpoints and we route to a healthy node near you.

The pieces

Component	Purpose
rippled	Reference XRP Ledger server. Serves the P2P protocol, validates ledgers, and exposes a WebSocket/HTTP API. We run rippled for consensus-sensitive paths.
Clio	Read-optimized XRP Ledger indexer. Stores full ledger history in Cassandra/ScyllaDB and answers history queries orders of magnitude faster than rippled. Most reads in Honeycluster hit Clio.
Edge proxy	The Honeycluster API server. Accepts HTTPS and WebSocket connections, applies shared-tier fair-use limits (or per-project credit accounting on private plans), then forwards to the closest healthy upstream.
Control plane	Prisma-backed service that stores projects, keys, credit allocations, and billing for private / enterprise plans. The edge proxy reads this synchronously via Redis.

Request flow (public)

•
Client POSTs a JSON-RPC body to https://honeycluster.io — for example {"method":"ledger","params":[{"ledger_index":85123456}]}.
•
The edge proxy checks the caller's IP against the shared-tier rate-limit ceiling.
•
The request is forwarded to the regional Clio cluster (for reads) or rippled (for submits).
•
The backend responds with the XRPL JSON-RPC envelope. The proxy streams it back.

WebSocket connections to wss://honeycluster.io follow the same flow minus the per-request body — the proxy holds the socket open and pipes frames in both directions for the lifetime of the connection.

Request flow (private / enterprise)

Same shape, plus:

•
The client sends X-API-Key: <key> on the HTTP upgrade / request.
•
The edge proxy resolves the key to a project in Redis (fallback to Prisma on miss).
•
Credit balance is decremented atomically; response headers (X-Credits-*) report the new balance.

See Authentication for the full details on when keys come into play.

Why Clio first?

Clio indexes the full ledger into a column store, so queries like "all transactions affecting account X between ledgers A and B" return in tens of milliseconds instead of seconds. rippled is still used for recent state and submit paths.

Regions and failover

Honeycluster runs in 15+ regions. Each region has at least one rippled and one Clio replica behind a local edge proxy. DNS-based GeoIP routing picks the nearest region for the caller; health checks drain a region in seconds if the upstream becomes unhealthy, and the client is transparently failed over to the next-closest region.

Because ledgers are globally consistent, regional replicas are interchangeable for reads — there's no "stale region" concern. Writes (transaction submission) always flow to a rippled that's validated against the live network.