> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agg.market/llms.txt
> Use this file to discover all available pages before exploring further.
# Canonical Market Key (aggKey)
> Identify and fetch the same market across venues with a single deterministic key
`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`, …):
| Resource | API Reference |
| --------------------------------------------------------------- | --------------------------------------------------------------- |
| Event-level keys, such as `agg_nba_nyk_sas_260610` | [List Venue Events](/api-reference/discovery/listvenueevents) |
| Market-level keys, such as `agg_nba_nyk_sas_260610_sp_nyk_10p5` | [List Venue Markets](/api-reference/discovery/listvenuemarkets) |
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).
| Family | Format | Example |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Sports head-to-head | `agg_{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/down | `agg_ud_{asset}_{interval}_{startUTC}` — sub-daily intervals carry the window-start instant; daily (`1d`) keys carry the day only | `agg_ud_btc_1h_260610T1500`, `agg_ud_btc_1d_260610` |
| Crypto price / threshold | `agg_px_{asset}_{kind}_{instantUTC}` | `agg_px_btc_15m_260610T0600` |
| FX over/under | `agg_fx_{pair}_{kind}_{instantUTC}` | see live responses |
| Index / equity threshold | `agg_idx_{symbol}_{kind}_{instantUTC}` | see live responses |
| Dated outcome | `agg_{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.
## Related
Compose discovery and orderbook endpoints into event grids and trading views.
Fetch matched events and their midpoints to build a cross-venue price comparison.