Skip to main content
PredictStreet groups one or more markets under an Event. A single match (Real Madrid vs Manchester City) typically maps to one event with one binary market. A tournament (UEFA Champions League winner) maps to one event with many per-team markets shown as a Polymarket-style accordion via groupItemTitle. Every public market response includes the parent event slug; every event response carries its full markets array. Most clients query GET /api/events for the home grid and fall back to GET /api/markets/{symbol} for the trading detail page.

​
Event shape

{
  "id": "e005f649-2d64-4e37-8513-5463c26f28c6",
  "slug": "m1v1-rma-mci-959311",
  "title": "Real Madrid (ESP) vs Manchester City (ENG) — UCL R16",
  "group": null,
  "stage": "r16",
  "teamA": "ESP",
  "teamB": "ENG",
  "tags": [
    { "slug": "soccer", "name": "Soccer" },
    { "slug": "champions-league", "name": "UEFA Champions League" },
    { "slug": "knockout", "name": "Knockout" },
    { "slug": "match", "name": "Single Match" }
  ],
  "eventStartTime": "2026-04-30T15:48:31Z",
  "createdAt": "2026-04-23T15:48:31Z",
  "updatedAt": "2026-04-23T15:50:37Z",
  "markets": [ { "...": "MarketSummary" } ]
}

​
Football metadata fields

FieldWhen populated
groupTournament group letter (A..L). Set on group-stage events only.
stagegroup / r32 / r16 / quarter_finals / semi_finals / third_place / final. Null for non-fixture events.
teamA / teamBFIFA 3-letter country codes. Both populated for 1-vs-1 fixtures; only teamA for tournament-winner markets in focus on a single team; both null for picker-style multi-outcome markets.
tagsCurated taxonomy from GET /api/tags. Use the slug as ?tag=<slug> to filter.
eventStartTimeReal-world fixture kickoff. Separate from createdAt.

​
Per-market fields driven by the event grouping

Field on MarketSummaryMeaning
groupItemTitlePer-market label inside the event accordion (e.g. "Real Madrid", "Liverpool", "Draw"). Equal to title for single-market events.
initialOutcomePricesPer-outcome seed price aligned to outcomeLabels. Equivalent to Polymarket’s outcomePrices.

​
Filtering

GET /api/events?stage=r16&tag=champions-league
GET /api/events?team=BRA
GET /api/events?group=A&from=2026-06-11T00:00:00Z&to=2026-06-26T00:00:00Z
GET /api/events?sort=trending
QueryBehaviour
stageExact match against the EventStage enum.
groupGroup letter; case-sensitive.
teamFIFA 3-letter code matched against teamA OR teamB.
tagSingle tag slug, exact match. Combine with other filters via repeated requests; the API does not support multi-tag in a single call.
from / toInclusive bounds on eventStartTime.
sorttrending (24h volume DESC) / ending_soon (non-past closesAt ASC) / starting_soon (future market kickoff ASC) / live (kickoff passed and a market is still OPEN; most-recently-started DESC). Default (no sort): earliest public-market kickoff ASC, then title ASC, then event id ASC — not createdAt. starting_soon / live use per-market kickoff as the source of truth; eventStartTime is a fallback used only when kickoff is NULL.
All filters AND together. Events with no public-status (OPEN / PRE_MARKET / PAUSED / PROPOSED) market are excluded from the response entirely — the public surface never returns “empty” events.

​
Tags

The tag taxonomy is admin-curated rather than free-form. Use GET /api/tags for the full active list and the slug as the value for ?tag=. 
GET /api/tags

{
  "tags": [
    { "slug": "soccer",        "name": "Soccer",                  "sortOrder": 1,  "isFeatured": true },
    { "slug": "world-cup-2026","name": "World Cup 2026",           "sortOrder": 5,  "isFeatured": true },
    { "slug": "premier-league","name": "Premier League",           "sortOrder": 10, "isFeatured": false },
    { "slug": "champions-league","name": "UEFA Champions League",  "sortOrder": 11, "isFeatured": false }
  ]
}
isFeatured tags are surfaced in the primary navigation strip; non-featured tags remain selectable through filter UI but are not pinned.