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
##
ComponentPurpose
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)
##
  1. •
    Client POSTs a JSON-RPC body to https://honeycluster.io — for example {"method":"ledger","params":[{"ledger_index":85123456}]}.
  2. •
    The edge proxy checks the caller's IP against the shared-tier rate-limit ceiling.
  3. •
    The request is forwarded to the regional Clio cluster (for reads) or rippled (for submits).
  4. •
    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.