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 event response carries the event’s markets in markets[], but not always the same market row: the list (GET /api/events) carries a slimmer list row per market, while GET /api/events/{slug} and GET /api/events/featured carry the full MarketSummaryDto — see List rows vs detail. Most clients query GET /api/events for the home grid, GET /api/events/{slug} for an event page and GET /api/markets/{slug} for the trading detail page.

Event shape

One row of GET /api/events (the event fields are the same on GET /api/events/{slug} and GET /api/events/featured). Every event-level key is always present; nullable ones are null, never missing. For the keys of each markets[] row, see List rows vs detail.

{
  "id": "e005f649-2d64-4e37-8513-5463c26f28c6",
  "slug": "m1v1-rma-mci-959311",
  "title": "Real Madrid vs Manchester City — UCL R16",
  "metaTitle": null,
  "imageUrl": "https://…/ucl.png",
  "homeCountry": null,
  "awayCountry": null,
  "sport": "soccer",
  "vertical": "football",
  "match": {
    "id": "b6e3f1a2-7c4d-4e8a-9f10-2a5c6d7e8f90",
    "slug": "rma-mci-r16",
    "title": "Real Madrid vs Manchester City",
    "group": null,
    "stage": "r16",
    "competition": { "name": "UEFA Champions League", "slug": "champions-league", "logo": "https://…/ucl.png" },
    "teamA": { "code": "RMA", "label": "Real Madrid", "logo": "https://…/rma.png" },
    "teamB": { "code": "MCI", "label": "Manchester City", "logo": "https://…/mci.png" },
    "kickoffAt": "2026-04-30T15:48:31Z",
    "state": "LIVE"
  },
  "teamA": { "code": "RMA", "label": "Real Madrid", "logo": "https://…/rma.png" },
  "teamB": { "code": "MCI", "label": "Manchester City", "logo": "https://…/mci.png" },
  "competition": { "name": "UEFA Champions League", "slug": "champions-league", "logo": "https://…/ucl.png" },
  "tags": [
    { "slug": "soccer", "name": "Soccer" },
    { "slug": "champions-league", "name": "UEFA Champions League" },
    { "slug": "knockout", "name": "Knockout" },
    { "slug": "match", "name": "Single Match" }
  ],
  "scheduledAt": "2026-04-30T15:48:31Z",
  "endedAt": null,
  "scheduleStatus": "SCHEDULED",
  "scheduleReason": null,
  "settlesByAt": null,
  "volume24h": "578.207202",
  "totalVolume": "1084.507287",
  "openMarketCount": 5,
  "totalMarketCount": 5,
  "createdAt": "2026-04-23T15:48:31Z",
  "updatedAt": "2026-04-23T15:50:37Z",
  "saved": false,
  "category": { "key": "GAME_LINES", "label": "Game Lines" },
  "live": null,
  "inPlay": false,
  "cryptoSeries": null,
  "cryptoLongSeries": null,
  "markets": [ { "...": "list market row on GET /api/events, full MarketSummaryDto on /{slug} and /featured" } ]
}

Football metadata fields

Field	When populated
`match`	Parent fixture of a match-bound event: `group`, `stage`, `competition`, `teamA`, `teamB`, `kickoffAt`, `state`. `null` for non-fixture events (outrights, tournament winners).
`match.group`	Tournament group letter (`A`..`L`). Set on group-stage fixtures only; otherwise `null`.
`match.stage`	`group` / `r32` / `r16` / `quarter_finals` / `semi_finals` / `third_place` / `final`, or a competition value (`fifa_friendlies` / `ucl` / `uefa_europa_conference_league`). Can be `null`.
`match.state`	The match’s publication state — always `LIVE` on the public API, including after the fixture has finished. Not an in-play flag — it does not tell you whether the match is under way.
`teamA` / `teamB`	Participant objects `{ code, label, logo }` on head-to-head events, match-bound or not; on a match-bound event they mirror `match.teamA` / `match.teamB`. On a fixture without a `match`, `code` can be `""` and `logo` `null` — render `label`. `logo` is a crest URL or `null` — normal for a national team, whose flag you draw from `code`. `null` on outrights and tournament events.
`competition`	Effective competition `{ name, slug, logo }` — the match’s, else the event’s own. Use the slug as `?competition=<slug>`.
`tags`	Curated taxonomy from `GET /api/tags`. Use the slug as `?tag=<slug>` to filter.
`scheduledAt`	Scheduled start of the event; on a match-bound event usually equal to `match.kickoffAt`. Separate from `createdAt`.

Other event fields

Field	Meaning
`vertical` / `sport`	`vertical` is the navigation axis (`football`, `tennis`, `crypto`, …) — the value `?vertical=` filters on. `sport` is the live-score vocabulary (`soccer` for football), the word `live.sport` carries; use it for live scores, not navigation. Either can be `null` on legacy events.
`category`	`{ key, label }` — the market-type tab the event belongs to: `GAME_LINES`, `TEAM_TO_ADVANCE`, `EXACT_SCORE` or `OTHER`.
`scheduleStatus`	`SCHEDULED` / `POSTPONED` / `CANCELLED` / `PLAYED` — read it for the status badge; `scheduleReason` explains a non-`SCHEDULED` state. On `POSTPONED`, `settlesByAt` is the instant after which positions settle at fair value if the fixture still has not been played.
`endedAt`	When the outcome was determined (full time, race end); `null` until known.
`volume24h` / `totalVolume`	Matched notional across the event’s markets in USDC, as decimal strings.
`openMarketCount` / `totalMarketCount`	Market counts for badges. `markets[]` is filtered by the view, so `markets.length` is not a count — see List rows vs detail.
`inPlay` / `live`	`inPlay` is `true` while the fixture is under way. `live` is the clock-and-score frame, `null` when no market has one (and on `POSTPONED` / `CANCELLED` events).
`saved`	Whether the signed-in user saved the event. Always `false` on anonymous and API-key requests.
`homeCountry` / `awayCountry`	ISO-3166 alpha-2 country of each participant (player flags on tennis), or `null`.
`metaTitle` / `imageUrl`	SEO title (fall back to `title`) and competition logo URL; both can be `null`.

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 nests only the windows around now: the tradeable ones on the list, plus the windows awaiting settlement and the three latest-ending settled (RESOLVED or VOIDED) windows on GET /api/events/{slug}. A finished day on the list’s ?status=closed view nests the same: every window still awaiting settlement and at most three settled ones. The one exception is a day whose windows were all VOIDED before they ended: the list nests all of them, and GET /api/events/{slug} returns 404 for it. For the whole day, settled windows included, call GET /api/crypto-series/{id}/windows?state=all&from=2026-07-29&to=2026-07-30. totalMarketCount counts every window of the day. Check each market’s status before trading.

{
  "slug": "crypto-updown-btc15m-20260729",
  "vertical": "crypto",
  "cryptoSeries": {
    "id":             "04929134-5c9b-4d58-883e-1b669f286ac1",
    "symbolPrefix":   "BTC15M",
    "asset":          "BTC",
    "instrumentId":   "BTC-USD",
    "cadence":        "15-minute",
    "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, and an event that is one period of a recurring long-dated series carries a cryptoLongSeries block.

Per-market fields driven by the event grouping

Market field (list row and full row)	Meaning
`groupItemTitle`	Per-market label inside the event accordion (e.g. `"Real Madrid"`, `"Liverpool"`, `"Draw"`). `null` when not set — typically on single-market events; fall back to `title`.
`outcomePrices` / `chances`	Per-outcome cost to buy and implied probability, aligned to `outcomeLabels` — see Markets overview.

List rows vs detail

Endpoint	`markets[]` rows	Which markets
`GET /api/events`	List row (below)	Default view: markets that are `PRE_MARKET` (once launched), `OPEN`, `PAUSED` or `POSTPONED`; on an event in play or postponed, also its markets that have already closed. With `?status=closed`: markets in `SUSPENDED`, `CLOSED`, `PENDING_RESOLUTION`, `DELAYED`, `DISPUTED`, `RESOLVED` or `VOIDED`; on an Up/Down day, `RESOLVED` and `VOIDED` windows are capped at the three that ended last, as on the detail, unless every window was voided before it ended (see Crypto events).
`GET /api/events/{slug}`	Full `MarketSummaryDto`	Every public market of the event in any status, settled ones included (Up/Down days: see Crypto events).
`GET /api/events/featured`	Full `MarketSummaryDto`	The same markets as the list’s default view; the finished-event fallback (with `team`) carries its closed markets, as on `?status=closed`.

The event fields are the same on all three. Because markets[] depends on the view, render counts from openMarketCount / totalMarketCount, never from markets.length. The order of markets[] is stable but not part of the contract.

Fields the list row leaves out

Slimmer list rows. A market row on GET /api/events is the full MarketSummaryDto without the fields below. Everything else — ids and token ids, outcomes, outcomePrices, chances, status, tradable, tradingWindow, lifecycle, resolution, crypto, cryptoWindow, marketType, vertical, volumes — is the same as on the full row. Migration notes: Changelog.

Field	Where to read it
`eventSlug`	The event row’s own `slug`.
`tags`	The event row’s `tags` — the same list.
`homeCountry` / `awayCountry`	The event row’s `homeCountry` / `awayCountry`.
`sport`	The event row’s `sport`. The market’s own `vertical` stays.
`tradingMode` / `notTradableReason`	Derive them from `status` (it stays, as does `tradable`) with the table below; full rows carry them.
`resolutionCriteria`	Kept on long-dated crypto markets (`crypto` set, not an Up/Down window, `cryptoWindow` `null`), where a `RANGE_BAND`’s bounds and a period product’s window appear only in this text. On every other market the key is absent: read it from `GET /api/events/{slug}`, `GET /api/markets/{slug}`, or a `GET /api/markets` page for full rows in bulk.

`status`	`tradingMode`	`notTradableReason`
`PRE_MARKET`	`pre_market_post_only`	`null`
`OPEN`	`open`	`null`
`PAUSED`	`paused`	`paused`
`SUSPENDED`	`paused`	`suspended`
`POSTPONED`	`paused`	`postponed`
`CLOSED`	`closed`	`closed_at_cutoff`
`PENDING_RESOLUTION`	`awaiting_settlement`	`awaiting_settlement`
`DELAYED`	`delayed`	`awaiting_data`
`DISPUTED`	`under_review`	`under_review`
`RESOLVED`	`resolved`	`resolved`
`VOIDED`	`voided`	`voided`

Two blocks are trimmed rather than removed:

Block	On the list row	Only on the full row
`prediction`	`version`, `kind`, `line`, `threshold`, `endsAt`	`provider`, `questionId`, `question`, `rulesText`, `capturedAt`
`probabilityChange`	`window`, `unit`, `outcomes[].outcomeIndex`, `outcomes[].change`	`asOf`, `outcomes[].baselineAt`

prediction is null except on markets listed from a vendor prediction question (for example politics).
probabilityChange is the 24-hour move of each outcome’s implied probability, in percentage points (0.27 → 0.32 is 5), rounded to two decimals. change is null when there is no price to compare with; the block itself can be null or absent.

For full rows in bulk, page GET /api/markets?limit=500&offset=… (up to 500 full rows per request, with hasMore; PRE_MARKET, OPEN, PAUSED and POSTPONED by default, closed=true or status= for the others) instead of calling GET /api/events/{slug} once per event — detail calls share the /api/events* rate-limit bucket with your list walk. For one event’s markets in any status, call GET /api/events/{slug}; for one market, GET /api/markets/{slug} (no probabilityChange).

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 fixture stage — one of the `match.stage` values above. Any other value returns `400 invalid_stage`.
`group`	Group letter; case-sensitive.
`team`	3-letter team code (case-insensitive: national FIFA codes and club short codes), matched against the parent `match`’s `teamA` or `teamB`. Events without a `match` — tennis or baseball head-to-heads, for example — never match, even though they carry `teamA` / `teamB`.
`competition`	Competition slug, as in `competition.slug`. An unknown slug matches nothing.
`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 Up/Down series grid step (`5-minute`, `15-minute`, `30-minute`, `hourly`, `6-hour`, `daily`, `weekly`). Closed set — any other value (including `monthly` / `annual`) returns `400 invalid_cadence`.
`frequency`	How often a crypto market recurs: the cadence values above plus `monthly`, `annual` and `one-time`. Closed set — an unknown value returns `400 invalid_frequency`.
`from` / `to`	ISO-8601 dates: inclusive bounds on the event’s scheduled start, compared in UTC — send `Z` or an explicit offset. An event with no stored start time never matches a date bound, even when `scheduledAt` shows a fallback. A date `from` replaces the default cut-off for events already under way, so a past `from` also returns events that have started, are not in play and still have open markets. Digits-only values are list positions, not dates — see Paging. Beside `page` / `limit`, a date must start `YYYY-MM-DD` (`2026-10-01`, read as 00:00 UTC, or `2026-10-01T00:00:00Z`); any other value there is `400 ambiguous_pagination`.
`kind`	`match` — events bound to a fixture (`match` is not `null`). `tournament` — every event without a `match`, which includes match-less fixtures such as tennis head-to-heads, not only outrights.
`q`	Free-text search, up to 64 characters. Results are ordered by relevance unless you pass `sort`. Every page of the response then carries `total` (the size of the whole matched set, independent of paging), `openMarketCount` / `totalMarketCount` and `facets.competition` (`[{ slug, name, count }]`, counted without the `competition` filter itself). Without `q`, `facets` is never present, and `total` and the two counts come on the first page only — see Paging.
`sort`	`trending` (24h volume DESC) / `coming_soon` (future market `opensAt` ASC; hides events already open) / `ending_soon` (non-past `closesAt` ASC) / `starting_soon` (future market `kickoff` ASC) / `live` (fixture currently in play — kickoff passed and not yet over, its markets possibly already `CLOSED`; most-recently-started DESC). Default (no `sort`): earliest public-market `kickoff` ASC, then `title` ASC, then event `id` ASC — not `createdAt`. On `?status=closed` there is no such kickoff, so the default order is effectively `title` ASC. `starting_soon` / `live` use per-market `kickoff` as the source of truth; the event’s scheduled start (`scheduledAt`) 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, subcategory, scope, asset, cadence, frequency, predictionType) 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. More is 400 too_many_<field>, for example too_many_tag (predictionType uses too_many_prediction_type). By default the list holds events with at least one tradeable market (PRE_MARKET / OPEN / PAUSED / POSTPONED), plus fixtures currently in play, whose markets may already be CLOSED. ?status=closed (or the legacy ?closed=true) returns the settled / finished set instead: events with no tradeable market and at least one closed market, excluding fixtures in play.

Paging

GET /api/events returns at most 100 events per response. Page with page / limit: a limit above 100 is served as 100, not rejected, and without page / limit you get the first 100 events. Walk page=1, 2, … with limit=100 and stop at the first empty page. The first page (page=1, from=0, or no page and no digits-only from) also carries total, the number of events matching every filter, independent of paging, and openMarketCount / totalMarketCount, the per-event counters summed over those events — so on status=closed the open sum is 0; show totalMarketCount. With scope, both hold the same number instead: the markets of those scopes that the filter admits on the view, not the sum of the rows’ counters. Later pages carry none of the three unless the request has q. Treat them as optional: when they cannot be computed in time, the first page comes without them. Full rules, including the numeric from / to positions: Pagination.

List data can be up to a minute or two old. Which events a page holds, their order, volumes and each market’s status / tradable come from a list slice shared by every caller that can be up to about 20 seconds old. Anonymous requests — API-key requests included, since the key is ignored on this endpoint — are then served from a short cache on top: usually a few seconds, up to about 30 seconds for a full page of 100 events, 60 seconds for a full status=closed page, and 2 minutes on a closed page where every market is settled. A first page’s total, openMarketCount and totalMarketCount are cached with it. Do not use GET /api/events as a price feed; read the orderbook or the WebSocket instead.

Getting Started

Authentication

Vaults

Deposits

Trading

Events & Tags

Markets

Portfolio

Withdrawals

WebSocket

Settlement & Oracle

On-chain Contracts

Partners

Errors

Event shape

Football metadata fields

Other event fields

Crypto events

Per-market fields driven by the event grouping

List rows vs detail

Fields the list row leaves out

Filtering

Paging

Tags

​Event shape

​Football metadata fields

​Other event fields

​Crypto events

​Per-market fields driven by the event grouping

​List rows vs detail

​Fields the list row leaves out

​Filtering

​Paging

​Tags

Event shape

Football metadata fields

Other event fields

Crypto events

Per-market fields driven by the event grouping

List rows vs detail

Fields the list row leaves out

Filtering

Paging

Tags