Monitor freshness before use

Outcome

Classify one market-data window as fresh enough, stale, partial, delayed, or stopped before a downstream job uses it.

Prerequisites

Choose one venue family, symbol, data family, and bounded UTC window.
Define the application’s maximum acceptable lag before making the check.
Load the API key from the runtime environment for the authenticated quality and market-data calls.
Keep the downstream output path ready so the quality decision can be stored with it.

Inputs

Field	Example
Venue family	Hyperliquid core
Symbol	`BTC`
Data family	Trades
Window	`from=1773273600000&to=1773360000000`
Freshness policy	Application-defined maximum lag and incident rule
Completion condition	Quality response, decision, and data request metadata are saved together

Steps

Read service status

curl -sS "https://api.0xarchive.io/v1/data-quality/status" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Record status, updated_at, and active_incidents from this resource-specific response.

Read symbol freshness

curl -sS "https://api.0xarchive.io/v1/hyperliquid/freshness/BTC" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

For this core-market example, inspect data.measured_at and data.trades.lag_ms with its last_updated value.

Check the requested window

curl -sS "https://api.0xarchive.io/v1/data-quality/coverage/hyperliquid/BTC?from=1773273600000&to=1773360000000" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Check the selected data type and any returned gap or completeness information.

Make and save the decision

Proceed only when the freshness, coverage, and incident responses meet the application’s policy. Otherwise delay, narrow, mark, or stop the downstream job.

Expected state

A usable check has a measured timestamp, the selected data-family lag and last-updated value, a coverage response for the same symbol and window, and a named decision. The application owns the tolerance; the API supplies the observations.

Verification

Freshness describes how current a data family is. Coverage describes whether the selected family exists for the requested market and window. Incidents explain interruptions. Do not replace symbol-level coverage with the coarse /v1/status/coverage summary, and do not treat a service-level status as a signal that every route is current. Store the exact routes and numeric window. Capture any meta.request_id, x-request-id, or client request handle returned by each call, because the quality response may use a resource-specific shape.

Failure and recovery

A stale lag: delay the job, narrow the window, or mark the output stale.
A coverage gap or incident overlap: stop, narrow the window, or mark the output partial.
401: repair the key source or header.
404: check the family and symbol namespace.
A response without the expected field: stop at Data quality and OpenAPI before changing the parser.

Saved run metadata

{
  "run": "btc-trades-quality-001",
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "data_family": "trades",
  "window": {
    "from": 1773273600000,
    "to": 1773360000000
  },
  "status_route": "/v1/data-quality/status",
  "freshness_route": "/v1/hyperliquid/freshness/BTC",
  "coverage_route": "/v1/data-quality/coverage/hyperliquid/BTC",
  "request_ids": ["00000000-0000-0000-0000-000000000000"],
  "decision": "fresh enough | stale | partial | delayed | stopped",
  "output": "./artifacts/btc-trades-quality-001.json"
}

The zero UUID is a shape placeholder only. Replace it with the identifier returned by each route or client wrapper.

Next task

Use Reliability and data gaps to implement the decision states, or Historical market data after the selected window passes the quality check.

​Outcome

​Prerequisites

​Inputs

​Steps

​Expected state

​Verification

​Failure and recovery

​Saved run metadata

​Next task