Docs·Public Data API
Public Data API
Freshness, coverage and boundaries
The asOfBlock envelope and the last database update time, why every endpoint reports PARTIAL coverage with a scope, and the bounds every figure inherits.
The freshness object#
| Field | Type | Meaning |
|---|---|---|
asOfBlock | integer string | The block every indexed figure in this response is true as of |
indexedAt | integer string | Unix seconds of that block. Every rolling window in this API ends here, not at the server clock |
lastDatabaseUpdateAt | ISO 8601 string, UTC | When our database was last updated: indexedAt as a timestamp |
headBlock | null | Always null. Chain head is not stored data, and this API never reads the chain |
lagBlocks | null | Always null, for the same reason |
lagSeconds | number | Age of the newest stored checkpoint: server clock minus indexedAt. The decision variable |
lagBasis | string | STORED_CHECKPOINT_AGE |
lagSecondsBasis | string | The same, with the block time the thresholds were converted at |
status | string | See the table below |
readiness.ready | boolean | null | The indexer’s /ready, which answers 503 during backfill. null means the probe could not be made — not that the indexer said no |
readiness.probeError | string | null | Why the probe could not be made, when it could not |
thresholdsBlocks | object | incident, degraded, critical, stateWindow, plus the provenance fields in blocks, not minutes |
thresholdsSeconds | object | null | incident, degraded, critical — the block thresholds at this chain’s measured block time. status is judged against these. null for a chain with no measured block time |
coverage | FULL | PARTIAL | PARTIAL means something was bounded. scope says what |
scope | string | null | Every reason the coverage is PARTIAL, joined. Null when it is FULL |
notice | object | null | A standing warning about what these figures are, independent of coverage. code, headline, detail, clearedBy. Null when none applies |
chainId | number | The chain that answered |
viewsSchema | string | The stable views the figures were read from |
| Question | Answer |
|---|---|
| Last database update | freshness.lastDatabaseUpdateAt on every response |
| Source | Our database only. This API never reads the chain on a request |
| Need fresher data | Run your own indexer against your own API or RPC provider; the contracts and addresses are public |
| Status | Condition | Effect on coverage |
|---|---|---|
FRESH | lagSeconds under thresholdsSeconds.incident (3,000 blocks) | None |
LAGGING | thresholdsSeconds.incident or more | None |
DEGRADED | thresholdsSeconds.degraded (4,370 blocks) or more | None |
BEHIND_STATE_WINDOW | thresholdsSeconds.critical (6,555 blocks) or more | Forces PARTIAL. Nothing in the gap can be cross-checked against the chain by anyone, including us |
UNJUDGED | No block time is measured for this chain | None |
Coverage and scope#
coverage: "PARTIAL" is the common case, and it is not a hedge. It means a specific, named bound applies to the figures in the response, and freshness.scope is that name. Read the scope; do not treat the flag as noise. Where two bounds apply, both reasons are joined into one scope.
freshness.notice is a different claim and is deliberately not folded into these two. Coverage says what was left out of a response; a notice says what the figures that are in it amount to. A response can be FULL and still carry one.
| Field | Value |
|---|---|
code | PLATFORM_NOT_PUBLIC — the only one that exists. Stable; branch on it |
headline | The Hood is not open to the public |
detail | Every figure here is from the operator’s own testing. It is not trading activity, adoption or revenue, and it does not represent the platform’s performance |
clearedBy | The deployment variable that removes it. notice becomes null on every endpoint the day the platform opens |
| Endpoint | Coverage | The bound |
|---|---|---|
/health, /metrics, /stats/daily | FULL | Unless freshness itself degrades it |
/stats | PARTIAL | Volume is bonding-curve trading only. Post-graduation pool volume is buy-side only and is never added into these totals |
/fees | PARTIAL | promotionRevenueWei is the launchpad slot line in wei only. A market’s featured cut is taken at settlement in that market’s own currency and has no accumulator, so no single marketing figure is derivable |
/thd/meter | PARTIAL when unlock is null | unlockUnavailableReason names which of the four causes applies |
/launches, /launches/{token} | PARTIAL | lastFdvWei is a poke, null until one exists; holdersDerived is not a census |
/launches/{token}/trades | PARTIAL | REDEEM rows are fee-free reserve outflows, not trades, and are never volume |
/launches/{token}/holders | PARTIAL | Either no census has ever completed, or the census carries no age bound and the derived count is a different quantity |
/markets, /markets/{id}, /markets/{id}/stakes | PARTIAL | Every amount is in that market’s own currency. No cross-currency total is published anywhere in this API |
/settlements | PARTIAL | A settlement is not the only end state. A market whose window closed unsettled is voided and appears in no settlement row |
/creators, /creators/{address} | PARTIAL | The derived figures and the registry snapshot are two measurements and are never reconciled into one |
/kols | PARTIAL | Two earnings figures from two authorities, plus the attestation boundary below |
/referrers | PARTIAL | Code-level aggregates only. The platform’s own exclusion list is applied downstream of the indexer and has not been applied to these rows |
/traders | PARTIAL, always | Bounded twice: the index starts at a floor block, and no exclusion list has been applied. The row also carries boardStatus and its own scope |
Boundaries every figure inherits#
Some figures are exactly what they say and some are an assertion by somebody. The difference is published on the response rather than left to be inferred, and the ones below are inherited by anything built on them.
| Figure | Boundary |
|---|---|
traders board | Bounded twice and never FULL: it starts at the index floor block rather than at genesis, and the platform’s own exclusion list is applied downstream of the indexer, so an address excluded from The Hood’s boards can appear here |
creators[].registry | A keeper-driven snapshot dated by the oldest page of a multi-page sync, and its staleness check only detects launches added since the sync — so a launch that graduated afterwards is invisible to it |
census on holders | null when no sweep has ever completed. A token with ten thousand holders and no census reads identically to one with none, so it is never rendered as a count of zero |
meterWei on the THD meter | Not revenue, and the gap never closes. Receipts above the daily counting ceiling are paid out in full and refused by the count for good, in refusedByCeilingWei; the revenue figure is revenueWei, their sum, labelled as such. pendingWei was dropped on 21-09-2026 with the carry it named |
unlock on the THD meter | null without its denominator, which is a per-deployment immutable. A testnet percentage is not comparable with a production one, so none is published without the denominator beside it |
feesProtocolWei on fees | Contains the trade fee’s treasury share and the launch fee and market fees. Adding it to tradeFeeWei double-counts, because one fee emits an event at each hop of the chain it passes through |
| Anything per market | Base units of that market’s own currency. There is no cross-currency total anywhere in this API, deliberately — adding an ETH pool to a USDC pool produces a number that is not any amount of anything |
Where a derivation lives#
| Form | Where | What it carries |
|---|---|---|
| Machine-readable | /api/v1/metrics | Every published figure’s id, unit, derivation, source, freshness, coverage, scope, caveats, servedBy and definedIn — plus notPublished, the figures that are derivable and wrong |
| Human-readable | Metrics reference | The same definitions in prose, grouped by subject, with the accumulators that exist on chain |
| The refusals | Figures we do not publish | Twelve figures that are derivable and wrong, with the reason each one is refused |
| Addresses and ABIs | The addresses file | Contract addresses per chain, the index floor block, and every prior factory still in scope — the same list /api/v1/health publishes as factories |
| What is enforced vs asserted | Trust model | The boundaries above, in full |