Skip to main content
Live in production, still flag-gated. Perpetuals are gated by PERPETUALS_PUBLIC_API_ENABLED, enabled in production and staging today; a deployment with the flag off returns 404 for every perpetual route. Read Overview before writing code.
What the market_state and funding blocks of the REST snapshot contain, and — more importantly — what each venue leaves out. The per-venue gaps here are the part that breaks integrations. Perp venues publish several prices and market measures that are related but not interchangeable. Kairos models them as typed observations rather than adding loosely named fields to a ticker.
Mixed status: the typed-observation model below is a design preview. Hyperliquid funding and market state are already being collected — see Hyperliquid today.

​
Market state

market_state.prices is a sparse array of {price_type, value, observed_time_ns}, and the available types differ by venue:
Select a price by type. Never use “best available.” An absent price is not copied from another price type, and a venue-provided mark is not replaced by a locally calculated mid. If you need mark and the venue omitted it, you do not have a mark.
next_funding_time_ns is populated only by Polymarket Perps. Do not build a countdown that assumes every venue supplies one.
The status vocabulary the validator accepts is exactly active, inactive, delisted, unknown. A snapshot carrying anything else returns 502. There is no premium, basis, rolling volume, or reduce-only state on the REST snapshot. Those fields exist on kairos.v2.MarketStateUpdate, which the beta does not publish.

​
The full canonical market-state model

A market-state update can contain sparse observations such as mark price, index price, oracle price, mid price, last trade price, open interest, rolling volume, premium or basis, and market status and reduce-only state. Every price has a type and source. Sparse updates merge only within the same instrument, source epoch, and state source. Fields are ordered by their own observation or revision identity; a newer message cursor does not make every field in an older snapshot obsolete.

​
Funding observations

On the REST snapshot a funding record is rate, phase, effective_time_ns, calculated_time_ns, rate_period_seconds, payment_interval_seconds, sign_convention, funding_price, and funding_price_type. What each venue actually fills in differs, and the gaps are the point:
Kalshi Margin’s funding rate cannot be normalized from the snapshot alone. It publishes an estimate with no declared rate period and no declared payment cadence. Do not assume 3600 seconds because the other two venues use it. Compare funding across venues only after aligning sign and interval.
All three declare positive_longs_pay. That is enforced, not observed: a funding record with any other sign convention, or a phase outside estimate / final, fails validation and the request returns 502.
effective_time_ns means different things by phase. It is the next funding time for Kalshi’s estimate and the settled interval time for the other two. An estimate is allowed up to 24 hours in the future; a final record is not.

​
The full canonical funding model

A funding update identifies: Rates are stored in their native interval. Kairos may additionally expose a normalized rate only when the conversion is mathematically and economically valid, with the target interval named. Clients must not compare an hourly rate with an eight-hour rate as if they were the same unit.
Predicted funding is not a payment, and a settled public funding observation is not an account ledger entry. These remain separate records. Do not derive account payments from public rates alone.

​
Funding sign

The venue’s sign convention is carried explicitly. A UI may render “longs pay” or “shorts pay,” but storage and transport never rely on an undocumented sign assumption.

​
Revisions and historical truth

Predictions can change repeatedly before settlement. The latest projection is useful for display; the revision history is useful for research and audit. Kairos therefore distinguishes:
  • the append-only observation history
  • the current projection for fast reads
  • the final venue settlement, when published
Preserve revisions for backtests that must avoid look-ahead.

​
Hyperliquid today

Hyperliquid funding and reference prices are collected by polling the venue’s public info endpoint — POST https://api.hyperliquid.xyz/info with {"type":"metaAndAssetCtxs"} — every 30 seconds. That response is a two-element tuple: the asset universe, then a positionally matching array of asset contexts, so a length mismatch is treated as a broken response rather than silently mispaired. Each polled asset context yields: A malformed or half-populated asset context is skipped individually — one delisted coin must not cost the funding observation for every other instrument. An asset the venue marks isDelisted is dropped before decoding: it keeps its slot in the universe, and recording funding for it would imply a live contract.
Same venue, two paths, two legitimate phases. This poller records estimate because Hyperliquid exposes only a current accruing value; the REST snapshot’s funding array reads fundingHistory and records final. The polled rows land in the perpetual fact tables, not in any public endpoint.

​
Consumer rules

  • Select a price by type; never use “best available.”
  • Compare funding only after aligning sign and interval.
  • Do not derive account payments from public rates alone.
  • Preserve revisions for backtests that must avoid look-ahead.
  • Treat market status as a trading prerequisite, not decorative metadata.
Next: Accounts and margin.