Concepts
Coverage health
Why every response tells you whether we can see, and why "no matches" and "we cannot currently see" must never collapse into the same value in your code.
An empty result set has two very different causes. Nothing is wrong, or we cannot currently see. A monitoring product that cannot tell you which one you are looking at is worse than no monitoring product, because it converts a blind spot into a reassuring answer.
So coverage health is not an optional feature of this API. It is present on every path.
The three places it appears
| Where | Form |
|---|---|
GET /v1/exposure | coverage_health array in every response body, alongside matches. |
GET /v1/coverage | The same array, queryable on its own, scoped to your account. |
POST /v1/screen/address, POST /v1/decide/deposit | Foreshock-Coverage-Health: ok | degraded response header. |
The header is a pointer, not a report. On degraded, call GET /v1/coverage for the per-authority detail. It is a header rather than a body field so that coverage health is never absent from a response without altering the response shape.
What an entry says
Each CoverageHealthEntry describes one enforcement authority in scope for your account.
| Field | What it is |
|---|---|
authority_id | Opaque, stable identifier of one authority as it appears in your coverage. |
observable | Whether that authority is currently observable to Foreshock. |
verified_at | When that authority’s registry entry was last verified against the chain. |
collector_lag_s | Current lag, in seconds, between chain state and our view of that authority. |
Read observable: false, a verified_at outside its window, or an abnormal collector_lag_s as a blind spot. None of the three is an all-clear.
Scope is per customer
An authenticated caller sees the authorities that bear on the assets and addresses they have registered — not the full Foreshock registry.
Absence of an entry means that authority is out of scope for your account. It is not a statement about our registry as a whole, and it must not be read as one.
The live set of authorities, issuers, and chains is returned as data to authenticated customers. It is not enumerated in the public schema and is not published to unauthenticated parties, which is why chain, asset, and authority_id are plain strings in the contract rather than closed enumerations.
Observability is not a capability we provide
Whether an enforcement action is observable before it executes is a property of how the issuer governs itself. It is not something Foreshock adds, and it can change without notice when an issuer changes how it executes.
That is the honest framing, and it is also the operational one: design your fallback for the case where an authority you rely on stops being observable tomorrow. The coverage.health_changed webhook exists to tell you when that happens.