API reference

Endpoints

• GET /healthz Liveness + readiness probe

  Reports DB connectivity + RPC heartbeat freshness. Returns 200 with body `{status: "ok" | "degraded"}`. Used by k8s probes.

  https://whoearns.live/healthz Copy
• GET /v1/epoch/current Current Solana epoch snapshot

  First/last/current slot, `slotsElapsed`, and `isClosed` for the running epoch. Updated every `EPOCH_WATCH_INTERVAL_MS` tick.

  https://whoearns.live/v1/epoch/current Copy
• GET /v1/leaderboard Top-N validators by live, final, or Decade window

  Ranked list for a selected window. Default `window=live_trend&sort=income_per_slot`, combining current elapsed leader slots with the latest final epoch. Other windows: `current_only`, `stable_trend`, `final_epoch`, and `decade_epoch`.

  Query parameters (5)

  limit

  (integer)

  How many rows to return. Clamped server-side to 500. Default 100.

  epoch

  (integer)

  Override target closed epoch. Only valid with `window=final_epoch`.

  window

  (enum)

  `live_trend` | `current_only` | `stable_trend` | `final_epoch` | `decade_epoch`.

  minWindowSlots

  (integer)

  Minimum denominator slots required for a row. Default 4.

  sort

  (enum)

  `income_per_slot` | `total_income` | `mev_tips` | `fees` | `skip_rate`. Default `income_per_slot`.

  https://whoearns.live/v1/leaderboard?window=live_trend&limit=25&sort=income_per_slot Copy
• GET /v1/validators/search Search known validators

  DB-only search over validator name, vote pubkey prefix, identity pubkey prefix, and keybase username. Opted-out validators are excluded and the request never calls Solana RPC.

  Query parameters (2)

  q

  (string, required)

  Search text, minimum 2 characters.

  limit

  (integer)

  Result count clamped to 1-25. Default 10.

  https://whoearns.live/v1/validators/search?q=0base&limit=10 Copy
• GET /v1/validators/{idOrVote}/current-epoch A validator's running-epoch stats

  Same row as the history endpoint filtered to the current epoch. `idOrVote` accepts either a vote pubkey or an identity pubkey; the resolver picks whichever matches our `validators` table.

  https://whoearns.live/v1/validators/5BAi9YGCipHq4ZcXuen5vagRQqRTVTRszXNqBZC6uBPZ/current-epoch Copy
• GET /v1/validators/{idOrVote}/epochs/{epoch} A validator's stats for one epoch

  Same record shape as `current-epoch`, but pinned to the requested epoch. `idOrVote` accepts either a vote pubkey or an identity pubkey.

  https://whoearns.live/v1/validators/5BAi9YGCipHq4ZcXuen5vagRQqRTVTRszXNqBZC6uBPZ/epochs/963 Copy
• GET /v1/validators/{idOrVote}/epochs/{epoch}/leader-slots Leader-slot facts for one validator epoch

  Aggregates stored facts from watched validator leader slots only. The API call does not trigger Solana RPC; it returns slot quality fields plus block fee, tip, tx, CU, cost-unit, ComputeBudget, and income-per-1M-CU summaries.

  https://whoearns.live/v1/validators/9f7dqiYNBZbgPesAnLeWnKCtxYHSfMg5x1EMZCJwVwG7/epochs/966/leader-slots Copy
• GET /v1/validators/{idOrVote}/history Per-epoch history for a validator

  Rows returned newest-first. Each row carries `isFinal`, `hasSlots`, `hasIncome`, and `peerBenchmark` for indexed-validator average income per leader slot.

  Query parameters (1)

  limit

  (integer)

  Row count. Clamped server-side to 200. Default 50.

  https://whoearns.live/v1/validators/5BAi9YGCipHq4ZcXuen5vagRQqRTVTRszXNqBZC6uBPZ/history?limit=20 Copy