Data freshness

Every surface Polyrank serves is stamped with the exact chain block (or observation time) it reflects, in one registry. You never have to memorize per-widget staleness folklore: ask the endpoint, or read the X-Data-As-Of-Block / X-Data-As-Of-Time response headers on the leaderboard, trader, and market rails.

GET /v1/meta/freshness

Anonymous — no API key needed.

curl -s https://api.polyrank.app/v1/meta/freshness | jq '.surfaces[] | {surface, state, age_seconds, state_reason}'

{
  "surfaces": [
    {
      "surface": "pnl.resolved",
      "anchor": "block",
      "label": "Resolution re-marks in P&L",
      "status": "measured",
      "as_of_block": "93863361",
      "as_of_time": "2026-09-16T04:10:02.000Z",
      "age_seconds": 10800,
      "budget_seconds": 1800,
      "slo_class": "realtime",
      "slo_target": 0.995,
      "state": "paused",
      "state_reason": "paused for the position ledger recompute",
      "yield_since": "2026-09-16T04:05:00.000Z",
      "yield_ceiling_seconds": 28800,
      "provisional": null,
      "measured": { "within_slo": 0.9994997498749375, "within_budget": 0.8184092046023012, "p50_seconds": 39, "p99_seconds": 16997, "max_seconds": 22257, "method": "yield_proxy" }
    }
  ],
  "frontier_readable": true,
  "yields_readable": true,
  "slo_classes": [{ "slo_class": "realtime", "label": "Realtime P&L", "budget_seconds": 18000, "slo_target": 0.995, "has_yields": true, "provisional": false, "surfaces": ["pnl.realized", "pnl.resolved", "pnl.skill", "pnl.unrealized"] }],
  "slo_evidence": { "measured_from": "2026-09-01T19:00:00.000Z", "measured_through": "2026-09-15T19:00:00.000Z", "source": "…" },
  "as_of": "2026-09-16T07:10:02.000Z"
}

States

Every measured surface is in exactly one state. The age is always the real age — a state explains a number, it never replaces it.

• fresh — within its budget.
• paused — past its budget because its job is deliberately waiting behind a recompute (nightly, or a rare daytime repair: the position ledger, or the metrics chain) that needs the database to itself. state_reason names it and yield_since says when it began. Realtime P&L pauses most mornings (UTC) for a few hours; it resumes on its own the moment the recompute ends. Occasionally a repair run pauses P&L for about 40 minutes during the day; the freshness line keeps showing the real age, and affected wallets show “P&L under review” until it ends.
• stale — past its budget with no pause to explain it. This is a stall, and it alerts.
• overrun — paused for longer than any pause we have measured. Also alerts.
• unmeasured — no stamp yet. Absence never means fresh.

How the promises are set

Budgets and targets come from measurement, never from aspiration: each target is at or below the attainment we actually measured over the evidence window, and every budget change is recorded with its evidence. Surfaces marked provisional are about to change cadence (for example when a nightly job becomes incremental) and will be re-measured after the change. The class promise is always the loosest of its members, so it never promises more than every surface keeps.

The four anchor classes

Not everything can be block-aligned, and pretending otherwise would be its own confusion:

• block — truth lives on-chain (trades, P&L, positions, resolutions). as_of_block is the exact Polygon block the surface reflects.
• time — observations that exist only at the moment of capture (CLOB midpoints, market metadata). A mid has no block; a missed observation is gone, not "behind".
• slot — the prediction ledger's pre-registered 15-minute slots (a design property, not a staleness bug).
• cohort — ranks and percentiles are anchored to the vintage of the inputs they ranked: input_frontier carries the block of the metric snapshot that was ranked. Recomputing a rank per block is neither possible nor meaningful.

A registered surface with no stamp yet is status: "unmeasured" — absence never means fresh.

The registry

Promises by class

Every surface

Measured 2026-09-01 → 2026-09-15 (5-minute samples).