Skip to content
All documentation chapters
On this page

Supra Core API — Public Client Documentation

Chapter 07 — Health Endpoint

1. Purpose

The health endpoint provides basic API availability and selected data-state indicators. It is useful for connection tests and lightweight monitoring.

It passes through the same authentication layer as every other /api/v1/* route.

It is not proof that every market, candle, swap, or liquidity row is fully current.

2. Endpoint

GET /api/v1/health

Authentication:

X-API-Key: <api-key>

Optional query parameter:

Parameter Required? Default Description
network No mainnet Selects the documented public network

3. Curl Example

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/health?network=mainnet'

4. Illustrative Response

{
  "ok": true,
  "data": {
    "status": "<status>",
    "network": "mainnet",
    "fa_cursor_block": 0,
    "legacy_cursor_block": 0,
    "fa_cursor_updated_at": "<utc-timestamp-or-null>",
    "legacy_cursor_updated_at": "<utc-timestamp-or-null>",
    "market_stats_as_of_utc": "<utc-timestamp-or-null>",
    "market_stats_rows": 0,
    "server_time_utc": "<utc-timestamp>"
  },
  "meta": {
    "api_version": "v1",
    "endpoint": "health"
  }
}

The example is illustrative. Use the current endpoint contract when defining strict client models.

5. Public Field Guide

Field Meaning
status High-level public service status
network Network represented by the response
fa_cursor_block Latest reported FA progress block when available
legacy_cursor_block Latest reported LEGACY progress block when available
fa_cursor_updated_at Last reported FA progress update time
legacy_cursor_updated_at Last reported LEGACY progress update time
market_stats_as_of_utc Network-wide market stats calculation clock when available
market_stats_rows Count of currently represented market snapshot rows
server_time_utc Server UTC time used as a comparison point

Fields can be nullable when no corresponding state is available.

6. Availability Versus Freshness

HTTP 200 with ok=true means the health request succeeded.

It does not guarantee:

  • every endpoint has rows;
  • every source family advanced recently;
  • every derived dataset has the same update time;
  • historical coverage is complete;
  • a token or pair requested elsewhere is available.

Clients should compare relevant timestamps with server_time_utc and apply use-case-specific freshness thresholds.

  • Poll at a moderate interval.
  • Cache the latest successful response briefly.
  • Avoid one health request per UI component.
  • Back off on 429.
  • Use bounded retry on temporary 500 or network failures.
  • Keep the last known health state clearly labeled with its observation time.

8. Error Handling

Status Client action
400 Correct the network parameter
401 Fix API key configuration
404 Verify /api/v1/health
405 Use GET
429 Back off
500 Retry cautiously and show temporary-error state

9. Scope and Data Exposure

The authenticated health response exposes only the documented availability and data-state fields. It must not be treated as proof that every dataset is current.

10. Chapter Summary

Use GET /api/v1/health for basic availability and selected freshness indicators. Interpret its timestamps carefully, poll responsibly, and verify endpoint-specific data separately.