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,
  "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: "pro" or "alpha". Determines which fields are included in results.

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.

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

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 filtering

Your API key tier determines which fields appear in the response. Higher-tier fields are simply absent from the JSON (not returned as null). This keeps payloads small.

Pro tier response (fewer fields)

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

Alpha tier response (all fields)

{
  "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.