Prediction Reference Data

Prediction market instruments contain rich metadata from public/get-events and public/get-instruments response. This metadata enables partners to build flexible navigation hierarchies tailored to their application's needs.

Physical Instrument Hierarchy

The physical data model consists of two levels:

Event (underlying game/match/tournament)
  └─ Instrument (tradable contract)

Each Event groups related instruments under a common event_symbol. Event has metadata which allows you to extract League and Year information for higher level grouping, e.g. a Series.
Given an event_symbol, you can drill down for associated Instruments. Each Instrument represents a single tradable outcome with its own symbol and metadata.

You can try Prediction Instrument Hierarchy Explorer to visualise the instrument hierarchy.

Event

An Event represents a real-world occurrence that can have tradable outcomes — such as a sports match, tournament, election, or other predictable event. Events are returned by public/get-events and serve as the grouping level for related instruments.

Sample Event Response

{
  "symbol": "FIFA-00001-260629-M",
  "series_symbols": [],
  "name": "Japan @ Brazil",
  "description": "Japan @ Brazil",
  "event_date": 1782766800000000000,
  "last_updated_time": 1782443710514350000,
  "event_details": {
    "metaData": {
      "NAME": "Japan @ Brazil",
      "EVENT_DATE": "2026-06-29T17:00:00-04:00",
      "SPORTS_GROUPING": "SOCCER"
    },
    "eventName": "Japan @ Brazil"
  }
}

Key Event Fields

Field	Description	Example
`symbol`	Unique event identifier. The prefix indicates the league (e.g., `FIFA`, `MLB`, `UFC`). Use this to query instruments via `public/get-instruments?event_symbol=...`	`"FIFA-00001-260629-M"`
`event_details.metaData.SPORTS_GROUPING`	Sport category for grouping events. Specific to sports events.	`"SOCCER"`, `"MLB"`, `"ESPORT"`, `"MMA"`
`event_details.metaData.NAME`	Human-readable event name, typically in "Away @ Home" format for matches	`"Japan @ Brazil"`
`event_details.metaData.EVENT_DATE`	Event start time in ISO 8601 format. Extract the year component for season-based grouping.	`"2026-06-29T17:00:00-04:00"`

Instrument

An Instrument represents a single tradable option contract tied to a specific outcome of an event. Instruments are returned by public/get-instruments and contain rich metadata for building navigation hierarchies and displaying contract details.

Sample Instrument Response

{
  "id": -1,
  "method": "public/get-instruments",
  "code": 0,
  "result": {
    "data": [
      {
        "symbol": "NX.F.OPT.FIFA-00001-260714-M.O.1.67.20260830",
        "inst_type": "BINARY_OPTION",
        "display_name": "France vs Spain ; Spain (2-Way) ; AT&T Stadium ; 260714",
        "base_ccy": "USD",
        "quote_ccy": "USD",
        "tradable": true,
        "expiry_timestamp_ms": 1788127200000,
        "underlying_symbol": "FIFA-00001-260714-M",
        "event_details": {
          "metaData": {
            "NAME": "Spain @ France",
            "VENUE": "AT&T Stadium",
            "LEAGUE": "FIFA",
            "EVENT_DATE": "2026-07-14T19:00:00+00:00",
            "PARTICIPANT": "Spain",
            "SPORTS_GROUPING": "SOCCER",
            "AWAY_PARTICIPANT": "Spain",
            "HOME_PARTICIPANT": "France",
            "PREDICT_CATEGORY": "Sports",
            "PREDICT_EVENT_TYPE": "Game",
            "PREDICT_MARKET_TYPE": "Game Line",
            "PREDICT_PERIOD_TYPE": "90 Minutes and Stoppage Time",
            "PREDICT_OUTCOME_TYPE": "Away",
            "PREDICT_CONTRACT_TYPE": "Moneyline (2-Way)"
          },
          "eventName": "Spain to win"
        }
      },
      {
        "symbol": "NX.F.OPT.FIFA-00001-260714-M.O.1.68.20260830",
        "inst_type": "BINARY_OPTION",
        "display_name": "France vs Spain ; France (2-Way) ; AT&T Stadium ; 260714",
        "base_ccy": "USD",
        "quote_ccy": "USD",
        "tradable": true,
        "expiry_timestamp_ms": 1788127200000,
        "underlying_symbol": "FIFA-00001-260714-M",
        "event_details": {
          "metaData": {
            "NAME": "Spain @ France",
            "VENUE": "AT&T Stadium",
            "LEAGUE": "FIFA",
            "EVENT_DATE": "2026-07-14T19:00:00+00:00",
            "PARTICIPANT": "France",
            "SPORTS_GROUPING": "SOCCER",
            "AWAY_PARTICIPANT": "Spain",
            "HOME_PARTICIPANT": "France",
            "PREDICT_CATEGORY": "Sports",
            "PREDICT_EVENT_TYPE": "Game",
            "PREDICT_MARKET_TYPE": "Game Line",
            "PREDICT_PERIOD_TYPE": "90 Minutes and Stoppage Time",
            "PREDICT_OUTCOME_TYPE": "Home",
            "PREDICT_CONTRACT_TYPE": "Moneyline (2-Way)"
          },
          "eventName": "France to win"
        }
      }
    ]
  }
}

Key Instrument Fields

Use these metadata fields to build navigation hierarchies:

Field	Description	Example
`event_details.metaData.PREDICT_CATEGORY`	Top-level category for all prediction markets	`"Sports"`, `"Politics"`, `"Culture"`
`event_details.metaData.SPORTS_GROUPING`	Sport category (for sports events)	`"SOCCER"`, `"MLB"`, `"ESPORT"`, `"MMA"`
`event_details.metaData.LEAGUE`	Specific league within the sport	`"FIFA"`, `"EPL"`, `"UCL"`, `"MLS"`
`event_details.metaData.EVENT_DATE`	Event start time (ISO 8601). Extract year for season grouping.	`"2026-07-14T19:00:00+00:00"`
`event_details.metaData.NAME`	Human-readable event name in "Away @ Home" format	`"Spain @ France"`
`event_details.metaData.PREDICT_CONTRACT_TYPE`	Type of contract/market	`"Moneyline (2-Way)"`, `"Spread"`, `"Total Goals"`
`event_details.metaData.PREDICT_PERIOD_TYPE`	Time period the contract covers	`"90 Minutes and Stoppage Time"`, `"Full Game"`, `"1st Half"`

Example Hierarchy

Using the fields above, you can, for example, build a three-level navigation hierarchy:

Level	Fields	Example
Series	`PREDICT_CATEGORY` → `SPORTS_GROUPING` → `LEAGUE` → `YEAR(EVENT_DATE)`	Sports > SOCCER > FIFA > 2026
Event	`NAME` → `PREDICT_CONTRACT_TYPE` → `PREDICT_PERIOD_TYPE`	Spain @ France > Moneyline (2-Way) > 90 Minutes and Stoppage Time
Contract	The instrument record itself	`NX.F.OPT.FIFA-00001-260714-M.O.1.67.20260830`

Getting Continuous Updates

Both public/get-events and public/get-instruments support pagination and incremental updates using since and cursor parameters.

Initial Load

GET /dcm/v1/public/get-events?since=0
GET /dcm/v1/public/get-instruments?since=0

Use since=0 to fetch all available records from the beginning.

Pagination

When results exceed the page limit, the response includes a next_cursor field. Use it to fetch the next page:

GET /dcm/v1/public/get-events?since=0&cursor={next_cursor}
GET /dcm/v1/public/get-instruments?since=0&cursor={next_cursor}

Continue paginating until no next_cursor is returned.

Incremental Updates

After the initial load, use the last_updated_time from the most recent record as your since value to fetch only new or updated records:

GET /dcm/v1/public/get-events?since={last_updated_time}
GET /dcm/v1/public/get-instruments?since={last_updated_time}

This enables efficient polling for changes without re-fetching the entire dataset.

Example: Continuously Building a 3-Level Instrument Hierarchy

This example demonstrates how to build and maintain a Series > Event > Contract hierarchy using REST polling with since and cursor parameters.

Goal:

Build a 3-level navigation hierarchy: Series → Event → Contract
Keep data up-to-date via continuous REST polling

Procedure:

Initialize tracking variables:

events_last_modified = 0
instruments_last_modified = 0

Fetch events with changes:
```
GET /dcm/v1/public/get-events?since={events_last_modified}
```
Paginate using cursor until all pages are retrieved.
For each event, fetch associated instruments:
```
GET /dcm/v1/public/get-instruments?event_symbol={symbol}&since={instruments_last_modified}
```
This can be done in parallel for multiple events. Paginate each using cursor.
Build the hierarchy from instrument metadata:
- Series level: Group by PREDICT_CATEGORY → SPORTS_GROUPING → LEAGUE → YEAR(EVENT_DATE)
- Event level: Group by NAME → PREDICT_CONTRACT_TYPE → PREDICT_PERIOD_TYPE
- Contract level: Individual instrument records
Update tracking variables: Record the maximum last_updated_time from events and instruments for the next polling cycle.
Sleep and repeat: Wait for your desired polling interval, then return to step 2 with the updated since values.

This approach ensures you only fetch changed records on subsequent cycles, minimizing API calls and data transfer.

Full Meta Data Reference

For the complete metadata specification, please refer to FIX Document Pack > Prediction Market Appendix for details.

📄️ public/get-events

Returns a paginated list of prediction market events.

📄️ public/get-instruments

Provides information on all supported instruments (e.g. BTCUSD-PERP).