Public Data API

The API#

Versioning#

The response envelope#

{
  "data": { ... },                 // the endpoint's own body
  "freshness": { ... },            // on every response, always
  "pagination": {                  // only on a paged endpoint
    "cursor": null,                // the cursor this page was read at
    "next": "eyJxIjoi..."          // the cursor for the next page, or null on the last
  }
}

data is an object rather than a bare array on every endpoint, including the list ones — a list endpoint puts its rows under a named key (launches, markets, trades, days, and so on) alongside the filters that produced them. On failure the body is the error shape instead, and no envelope is sent:

{
  "error": "The Hood's public data API cannot use `limit` = \"9000\". It must be a whole number between 1 and 500; the default is 50. …",
  "code": "API_V1_BAD_PARAMETER",
  "details": { "parameter": "limit", "received": "9000", "min": 1, "max": 500, "fallback": 50 }
}

error is the message to show a human, code is the stable string to branch on, and details carries the same subject and values as machine-readable fields. All three are sent verbatim — nothing between the failing layer and the response substitutes a generic string for a specific one, so a client that renders its own fallback over error is discarding the only useful part.

Amounts are decimal strings#

Every wei and token-base-unit quantity is a decimal string, never a JSON number. That is the entire reason the API returns strings: JSON.stringify throws on a bigint, and the obvious repair — Number(wei) — is silently lossy above 2⁵³, which is roughly 0.009 ETH. Every figure published here is larger than that.

// Right — exact, at any magnitude.
const raised = BigInt(launch.stats.netRaisedWei)          // 1234567890123456789012n

// Wrong — silently rounded, and unrecoverable afterwards.
const raised = Number(launch.stats.netRaisedWei)          // 1.2345678901234568e+21
const raised = parseFloat(launch.stats.netRaisedWei)      // the same loss, quieter

Convert to a display string at the edge, from the bigint, and never in between. A value that arrives from the database as a float is refused rather than published: precision was lost before this API saw it, and publishing it would state a quantity that is not any amount of anything. A bigint that reaches the serialiser throws for the mirror-image reason.

Counts (trades, holders, stakes) and basis-point fields are ordinary JSON numbers — they are bounded and safe. Timestamps are decimal strings of seconds, with an ISO rendering beside them.

Blocks, not minutes#

Every threshold in this API is defined as a block count. Because chain head is never read, status compares the stored checkpoint’s age with these counts at the chain’s measured block time — see freshness. The public RPC prunes state past a fixed number of blocks, and past that line an eth_call at the block in question fails outright — it is a cliff, not a slope, and a threshold in minutes hides that because block time differs between the two chains by a factor of 2.7 and moves under load.

CORS, caching and conditional requests#

# Everything an integration needs to start, in three requests.
curl -s <origin>/api/v1/health   | jq '{ chainId, environment, factories, indexed, readiness }'
curl -s <origin>/api/v1/metrics  | jq '.data.metrics[] | { id, unit, derivation }'
curl -s '<origin>/api/v1/launches?lifecycle=CURVE_TRADING&sort=VOLUME&limit=10' \
  | jq '{ asOf: .freshness.asOfBlock, coverage: .freshness.coverage, scope: .freshness.scope,
          launches: [.data.launches[] | { token, forceName, raised: .stats.netRaisedWei }] }'