Prices and History

The Price API exposes the two data layers central to the protocol: constituent Market prices and derived Index levels. Every value is fixed-point, timestamped, provenance-tagged, and append-only so a consumer can reproduce what was known at a point in time.

Endpoint summary

All endpoints are public.

Index price observation

{
  "data": {
    "observation_id": "idxobs_demo_9001",
    "revision": 1,
    "supersedes_id": null,
    "index_id": "idx_demo_conflict_001",
    "index_version_id": "idxv_demo_003",
    "methodology_id": "meth_demo_weighted_001",
    "methodology_version": "2.1",
    "level": "128.4500000000",
    "unit": "index_points",
    "calculated_at": "2026-08-31T11:59:58.800Z",
    "source_cutoff_at": "2026-08-31T11:59:58.500Z",
    "published_at": "2026-08-31T11:59:59.000Z",
    "published_at_ts_ms": 1788350399000,
    "quality_state": "valid",
    "coverage_ratio": "0.9600",
    "confidence": "0.9100",
    "missing_constituent_ids": [],
    "excluded_inputs": [],
    "input_observation_ids": ["mktobs_demo_101", "mktobs_demo_102"],
    "calculation_run_id": "calc_demo_4401",
    "correction_reason": null
  },
  "meta": {
    "request_id": "req_demo_price_001",
    "published_at": "2026-08-31T12:00:00Z",
    "schema_version": "1.0",
    "max_age_ms": 2000
  }
}

Draft index quality states are valid, indicative, stale, degraded, suspended, and corrected. A response with an old timestamp MUST NOT be relabeled valid merely because the server is reachable.

GET /indexes/{index_id}/prices/{observation_id} additionally expands inputs on expand=inputs, including constituent ID, weight applied, Market/Outcome IDs, source observation, exclusion reason, normalization result, and contribution to the index level.

Market price view

{
  "data": {
    "market_id": "mkt_demo_001",
    "market_status": "open",
    "outcomes": [
      {
        "outcome_id": "out_demo_yes_001",
        "best_bid": "0.6300",
        "best_ask": "0.6500",
        "midpoint": "0.6400",
        "last_trade": "0.6420",
        "mark": "0.6410",
        "implied_probability": "0.6410",
        "spread": "0.0200",
        "bid_depth": "8400.00",
        "ask_depth": "7200.00",
        "derived": false
      }
    ],
    "venue_id": "ven_demo_001",
    "source_market_id": "source_mkt_demo_901",
    "source_sequence": 88120,
    "source_at": "2026-08-31T11:59:58.400Z",
    "received_at": "2026-08-31T11:59:58.520Z",
    "published_at": "2026-08-31T11:59:58.600Z",
    "freshness_ms": 200,
    "quality_state": "valid"
  },
  "meta": {
    "request_id": "req_demo_mprice_001",
    "published_at": "2026-08-31T11:59:58.600Z",
    "schema_version": "1.0",
    "max_age_ms": 2000
  }
}

mark is the methodology-defined reference value and is not necessarily midpoint or last_trade. The owning methodology MUST state its fallback order and stale/outlier treatment. Synthesized complementary binary prices MUST set derived: true and provide derivation_rule and source observation IDs.

Observation history

Index and Market history endpoints accept:

• inclusive start_time and exclusive end_time;
• cursor and limit;
• sampling=raw|latest_per_interval;
• interval when sampling (for example PT1M or PT1H);
• quality_state, outcome_id, and Market field=bid|ask|midpoint|last_trade|mark where applicable;
• include_corrections=true|false.

The default order is (published_at, observation_id) ascending. The cursor binds the complete filter and order set. Historical reads preserve source ID, schema/methodology version, all three time domains, and supersession fields.

Candles

Candles are derived views, not replacements for raw observations. start_time, end_time, and interval are required; index candles aggregate level, while Market candles require outcome_id and field.

{
  "bucket_start": "2026-08-31T11:00:00Z",
  "bucket_end": "2026-08-31T12:00:00Z",
  "open": "124.1000000000",
  "high": "129.0000000000",
  "low": "123.8000000000",
  "close": "128.4500000000",
  "observation_count": 60,
  "coverage_ratio_min": "0.8800",
  "quality_states": ["valid", "degraded"],
  "methodology_version": "2.1",
  "published_at": "2026-08-31T12:00:01Z"
}

Buckets are half-open [bucket_start, bucket_end). Empty buckets are omitted unless a future production policy explicitly supports gap filling; missing data MUST NOT be converted to zero.

Order-book snapshot

{
  "data": {
    "market_id": "mkt_demo_001",
    "outcome_id": "out_demo_yes_001",
    "sequence": 88120,
    "bids": [
      { "price": "0.6300", "quantity": "4200.00", "order_count": 12 }
    ],
    "asks": [
      { "price": "0.6500", "quantity": "3100.00", "order_count": 9 }
    ],
    "source_at": "2026-08-31T11:59:58.400Z",
    "published_at": "2026-08-31T11:59:58.600Z",
    "quality_state": "valid"
  },
  "meta": {
    "request_id": "req_demo_book_001",
    "published_at": "2026-08-31T11:59:58.600Z",
    "schema_version": "1.0"
  }
}

Clients use the REST snapshot as the recovery base for WebSocket deltas. Depth accepts outcome_id and a production-configured depth bounded by published capabilities.

Trade tape

GET /markets/{market_id}/trades returns immutable public trade records only where venue/licensing policy permits. Each trade includes trade_id, market_id, outcome_id, price, quantity, aggressor side if known, source venue/trade ID, source sequence/time, received time, publication time, and correction/void reference. It never exposes private account IDs.

Stale, missing, outlier, and venue outage handling

• Stale: retain the last known value with original timestamps and label it stale; never advance source_at.
• Missing: omit the value or set it null, record the missing input, and recalculate coverage.
• Outlier: preserve the raw source observation, record the rule/reason that excluded it, and publish any filtered value as derived.
• Venue outage/halt: surface source and Market status; an Index may become degraded, indicative, or suspended according to its immutable methodology.

Corrections and backfills

Published observations are append-only. A correction creates a new observation with a new ID, incremented revision, supersedes_id, correction_reason, corrected calculation/source/publication times, original input references, and the methodology/schema version used. Backfills set a later published_at while retaining the historical source_cutoff_at; consumers MUST order by the requested time domain rather than assuming publication order equals market time.