Skip to main content
aggKey gives prediction market apps a shared market identity across venues. Instead of building a custom matcher for every exchange, use one deterministic key to identify the same real-world event or contract across AGG-supported venues. This is the foundation for cross-venue discovery, price comparison, routing, arbitrage views, and market pages built on a single prediction market API.

​
What it is

aggKey is a deterministic, canonical identifier for a real-world market. The same market listed on multiple venues resolves to the same aggKey, so two rows from different venues that share an aggKey are the same market. It is computed at discovery time from each venue’s native data — no extra request needed. It appears on both objects in API responses:
  • VenueEvent.aggKey — the event (e.g. a game).
  • VenueMarket.aggKey — a specific market within the event (e.g. a spread line).

​
When it’s null

Not every market is canonicalizable. null means “no canonical key” — it is not an error. Fall back to other signals (title, venue ids) for those.
  • Events: free-form prose markets and some long-tail events return aggKey: null.
  • Markets: a market carries a key only when the key fully identifies the contract — moneylines, spreads and totals (the line is part of the key), and the single market of a one-market event. Markets whose terms are not encoded in a key — player props, exact-score / both-teams-to-score style markets, individual strikes of a multi-strike ladder — return aggKey: null even when their parent event has a key.
The flip side is the guarantee you can build on: when two markets from different venues share a non-null aggKey, they are the same contract — same line, same period, same window — not merely markets of the same event.

​
Using it

Read aggKey off any market or event, then fetch every venue’s row for it. Pass your app id with the x-app-id header, the same as every other discovery call. The aggKey param accepts a single key or several, and combines with the other filters (venue, status, …):
ResourceAPI Reference
Event-level keys, such as agg_nba_nyk_sas_260610List Venue Events
Market-level keys, such as agg_nba_nyk_sas_260610_sp_nyk_10p5List Venue Markets
Use the API Reference for request parameters, response schemas, and try-it-out examples.

​
Integration notes

  • Use event-level keys when you want every venue’s version of the same event.
  • Use market-level keys when you need the exact same contract, including line, period, and window.
  • Treat null as normal. Some free-form or long-tail markets cannot be keyed confidently.
  • Match on equality only. Do not parse the string to infer teams, assets, lines, or dates in app code.
  • Apply your normal app filters. Venue and category visibility still determine which rows your app can show.

​
Format

A key is the agg_ prefix followed by _-joined segments. Dates are YYMMDD (sports local date; daily markets) or a compact UTC instant (sub-daily intraday markets). Decimals use p (e.g. 2p5 = 2.5).
FamilyFormatExample
Sports head-to-headagg_{league}_{teamA}_{teamB}_{YYMMDD}[_{mkt}] — teams sorted, canonical per-league codes (NBA/MLB/NFL/NHL/WNBA tricodes; soccer uses country codes); moneyline → no suffix, spread → sp_{favored}_{line}, total → tot_{line}; non-full segments period-prefixed (e.g. _1h_sp_…)agg_nba_nyk_sas_260610, agg_nba_nyk_sas_260610_sp_nyk_10p5, agg_fifwc_bih_che_260618 (soccer)
Crypto up/downagg_ud_{asset}_{interval}_{startUTC} — sub-daily intervals carry the window-start instant; daily (1d) keys carry the day onlyagg_ud_btc_1h_260610T1500, agg_ud_btc_1d_260610
Crypto price / thresholdagg_px_{asset}_{kind}_{instantUTC}agg_px_btc_15m_260610T0600
FX over/underagg_fx_{pair}_{kind}_{instantUTC}see live responses
Index / equity thresholdagg_idx_{symbol}_{kind}_{instantUTC}see live responses
Dated outcomeagg_{normalized-subject}_{resolutionDate}agg_us-recession-2026_261231
Treat aggKey as an opaque equality token. Match on equality; do not parse the segments in your code. Keys for the same market are stable over time, and the segment grammar may evolve within a key version. A future format revision will use a new prefix (e.g. aggk2_), so the agg_ prefix is your version guard.

​
FAQ

​
What problem does aggKey solve?

Prediction markets are fragmented across venues, and each venue uses its own identifiers and market format. aggKey gives apps one equality token for the same real-world market so they can build cross-venue views without maintaining their own matching rules.

​
Should I use the event key or the market key?

Use VenueEvent.aggKey to group all venue rows for the same event. Use VenueMarket.aggKey when you need the same tradable contract, such as a specific spread, total, crypto window, or threshold.

​
Can I parse an aggKey?

No. The examples are readable for debugging, but partner integrations should treat aggKey as an opaque equality token. The only supported operation is matching non-null keys by exact equality.

Building Market Views

Compose discovery and orderbook endpoints into event grids and trading views.

Comparing Venue Prices

Fetch matched events and their midpoints to build a cross-venue price comparison.