Events overview

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

Field	When populated
`group`	Tournament group letter (`A`..`L`). Set on group-stage events only.
`stage`	`group` / `r32` / `r16` / `quarter_finals` / `semi_finals` / `third_place` / `final`. Null for non-fixture events.
`teamA` / `teamB`	FIFA 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.
`tags`	Curated taxonomy from `GET /api/tags`. Use the slug as `?tag=<slug>` to filter.
`eventStartTime`	Real-world fixture kickoff. Separate from `createdAt`.

Crypto events

An event in the crypto vertical carries a cryptoSeries block when its markets belong to a recurring Up/Down series; every other event carries null. The factory creates one event per series per UTC day, so an Up/Down event is a day of windows (~96 at the 15-minute cadence) — navigate it through GET /api/crypto-series/{id}/windows rather than through markets[], which only nests the currently tradeable ones.

{
  "slug": "crypto-updown-btc15m-20260729",
  "vertical": "crypto",
  "cryptoSeries": {
    "id":             "04929134-5c9b-4d58-883e-1b669f286ac1",
    "symbolPrefix":   "BTC15M",
    "asset":          "BTC",
    "instrumentId":   "BTC-USD",
    "cadenceSeconds": 900,
    "windowSeconds":  900,
    "streamDecimals": 18,
    "titleTemplate":  "{asset} Up or Down: {windowStart}-{windowEnd} UTC"
  }
}

Long-dated crypto events (price thresholds, monthly closes) have cryptoSeries: null — their markets carry the rule in crypto.

Per-market fields driven by the event grouping

Field on `MarketSummary`	Meaning
`groupItemTitle`	Per-market label inside the event accordion (e.g. `"Real Madrid"`, `"Liverpool"`, `"Draw"`). Equal to `title` for single-market events.
`initialOutcomePrices`	Per-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

Query	Behaviour
`stage`	Exact match against the `EventStage` enum.
`group`	Group letter; case-sensitive.
`team`	FIFA 3-letter code matched against teamA OR teamB.
`tag`	Tag slug(s), exact match. An event matches when it carries at least one of the supplied tags.
`vertical`	Vertical slug — the category axis verbatim (`football`, `tennis`, `crypto`, `politics`, …); see `GET /api/verticals`. Open set: an unknown slug matches nothing. `soccer` is accepted and folded to `football`.
`asset`	Crypto coin slug (`btc`, `eth`, … or `others`). Open, data-driven set — a well-formed unknown slug matches nothing; a malformed one returns `400 invalid_asset`.
`cadence`	Crypto window cadence (`15-minute`, `hourly`, `daily`, `weekly`, `monthly`, `annual`). Closed set — an unknown value returns `400 invalid_cadence`.
`from` / `to`	Inclusive bounds on `eventStartTime`.
`sort`	`trending` (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.

Filters AND across fields and OR within a field. The multi-value fields (stage, group, team, tag, vertical, competition, scope, asset, cadence) accept repeated keys (?tag=a&tag=b) or CSV (?tag=a,b) — both forms can be mixed, up to 20 distinct values per field, duplicates collapsed. Events with no public-status (OPEN / PRE_MARKET / PAUSED / PROPOSED) market are excluded from the response entirely — the public surface never returns “empty” events.

Getting Started

Authentication

Vaults

Deposits

Trading

Events & Tags

Markets

Portfolio

Withdrawals

WebSocket

Settlement & Oracle

On-chain Contracts

Partners

Errors

Event shape

Football metadata fields

Crypto events

Per-market fields driven by the event grouping

Filtering

Tags

​Event shape

​Football metadata fields

​Crypto events

​Per-market fields driven by the event grouping

​Filtering

​Tags

Event shape

Football metadata fields

Crypto events

Per-market fields driven by the event grouping

Filtering

Tags