Getting Started

Response Format

Every endpoint returns the same JSON structure. Understanding the envelope, timestamp format, and null semantics saves you from debugging surprises.

JSON envelope

All successful responses (200 OK) return a JSON object with these top-level fields:

200 OK response

{
  "tier": "pro",
  "coin": "BTC",
  "count": 142,
  "window_start": "2026-03-01T00:00:00+00:00",   // only when a history floor applied
  "history_clamped": true,                        // only when you asked for more
  "fields_omitted": 30,                           // only when your tier reads a subset
  "data_through": "2026-03-09T10:20:00+00:00",    // /v1/greeks/snapshot only
  "results": [
    { "timestamp": "2026-03-09T10:20:00+00:00", "coin": "BTC", ... },
    { "timestamp": "2026-03-09T10:10:00+00:00", "coin": "BTC", ... }
  ]
}

tierThe tier of your API key: "core", "pro" or "alpha". Governs sampling resolution, history depth and row cap. See Tiers & Limits.

coinThe coin you queried. Echoed back for confirmation.

countNumber of rows in this response. If count equals your limit, there may be more data available. A request that matches nothing returns 200 with count 0, not an error.

resultsArray of data rows, ordered by timestamp descending (newest first) unless otherwise noted.

Four more fields appear only when they apply. Their absence carries meaning: nohistory_clamped means nothing was truncated.

window_startThe oldest instant actually served, when your tier has a history floor. Present on Core and Pro whenever a floor applies. Alpha reads to inception, so Alpha rarely sees it.

history_clampedtrue when your from parameter reached further back than your tier allows. We serve from the floor and tell you, rather than refusing the request or silently truncating it. Absent when no clamping occurred.

fields_omittedHow many fields of this endpoint your tier does not read. The rows themselves are complete for your tier, never padded with nulls, so a missing key means "not included in your plan" and not "no value". The full per-endpoint breakdown is in the field matrix. Absent on Alpha, which reads everything.

data_throughOn /v1/greeks/snapshot only: the newest cycle your tier can actually receive. The Greeks are computed from the pricing table a cycle or two after it lands, so a request for data up to now returns data up to here. Read freshness off this rather than inferring it from the rows.

Timestamps

FormatISO 8601 with timezone offset: 2026-03-09T10:20:00+00:00

TimezoneAlways UTC (+00:00). No local time conversion. All from/to query params should also be UTC.

AlignmentSnapshot timestamps are aligned to 10-minute boundaries (:00, :10, :20, :30, :40, :50). Futures and spot marketdata: 1-minute boundaries.

OrderingResults are sorted by timestamp descending (newest first). The first row in the array is the most recent.

RenamingThe database column _timestamp is returned as timestamp (no underscore) in the API response.

Null values

Fields return null when the value cannot be computed, not when the value is zero. Always check for null before using a field in calculations.

Insufficient dataiv_percentile_30d is null for the first 30 days after inception.

Not applicableCross-asset relative value columns (iv_spread_vs_btc) are null for BTC itself (it is the benchmark).

Quality guardSkew metrics are null when the ATM cohort has no data for that expiry bucket.

Upstream missingSpot-vol asymmetry is null when fewer than 5 down-move observations exist.

Numeric precision

FloatsRounded to 6 decimal places in the response. Internal storage retains full precision (DECIMAL(10,4) to DECIMAL(22,8) depending on the field).

IntegersReturned as JSON integers (no decimal point). Examples: option_count, active_cohort_count.

PercentagesStored and returned as percentage points (e.g., 52.34 means 52.34 pct), not as decimals (0.5234). This applies to all IV, skew, VRP, and percentile fields.

USD valuesDollar amounts (e.g., net_gex_usd, trade_value_usd) are in actual USD, not thousands or millions. A value of 1234567.89 means $1,234,567.89.

Tier field entitlements

Each tier is licensed for a defined set of fields. Core covers the measured market, Pro adds everything derived from it, Alpha adds the proprietary layer. The Field Matrix is the authority on which tier reads which field, endpoint by endpoint.

A Core or Pro response is correspondingly narrower than an Alpha one:

Core: the measured market

{
  "timestamp": "2026-03-09T10:20:00+00:00",
  "coin": "BTC",
  "atm_iv_dte_30": 52.34
}

Alpha: the full surface

{
  "timestamp": "2026-03-09T10:20:00+00:00",
  "coin": "BTC",
  "atm_iv_dte_30": 52.34,
  "vrp_regime": "RICH",
  "vol_lifecycle_phase": "COMPRESSION",
  "phase_duration_cycles": 247,
  "phase_confidence": 82.5,
  "compression_duration_days": 17.1,
  "spot_vol_asymmetry_ratio": 2.31,
  "breach_sustainability_regime": "MEAN_REVERTING",
  ...
}

Error responses

Errors return a JSON object with a detail field. No results array is included.

400 Bad Request

{
  "detail": "Unsupported coin. Supported: AVAX, BTC, ETH, SOL, TRX, XRP"
}

See Error Codes for the full list.