# All markets (markets)


Source: https://docs.stxapp.io/websockets/channels/markets/

Delivers live updates to market metadata as it changes: status transitions,
price and probability moves, top-of-book, filters, and similar. This channel
does not push the initial market list: get that from `GET /api/v1/markets`,
then join here for what changes afterward.

#### MarketPayload fields

Every push (`market_created` or `market_updated`) is a map from market UUID to
a payload object: a fixed set of fields, converted to wire types (UUIDs to
strings, prices to cents). `market_created` always includes every field below.

:::caution[Prices on this channel are in cents]
`max_price`, `price`, `last_traded_price` and the `price` inside `bids`, `offers` and
`recent_trades` are **JSON numbers in cents**, not the dollar strings the REST API and
the account channels send. On a market whose `max_price` is `"1.0000"` over REST,
`max_price` here is `100`, and a REST price of `"0.5300"` is `53`. Divide by 100
before placing an order with one of these values.
:::
`market_updated` includes only `market_id`, `timestamp`, `unix_timestamp` plus
whichever fields actually changed since the last push.

Nothing below is guaranteed to stay fixed for a market's lifetime. Every one
of these fields, including `title`, `description` and `symbol`, can be edited
by STX, and any such edit is what a later
`market_updated` diff reflects.

##### Always present

- `market_id` : The id of the market.
- `timestamp` : Server time when this payload was generated, as an ISO 8601 string.
- `unix_timestamp` : The same instant, as UNIX microseconds.

##### Identity and description

- `symbol` : The market's unique symbol, e.g. `STXNBA-26MAR250000CLECHI-GAMECHI`.
- `title` : The human readable title for the market.
- `short_title` : The human readable short title for the market.
- `group_title` : The human readable group title for the market; used in groupings in the app.
- `grouping_id` : Identity of the set of mutually exclusive outcomes this market
  belongs to. Stable for the life of the market, and shared by its siblings.
  Present on `market_created`; absent from `market_updated`, since it never changes.
- `grouping_name` : The same grouping in words, e.g. `Over/Under`. For display
  only: two different groupings can render the same name.
- `description` : The description of the market.
- `question` : The question that the market is asking.
- `position` : The text to use in describing the position.

##### Event linkage

- `event_id` : The id of the event that the market is attached to.
- `event_type` : The type of event associated with the market.
- `sport` : Sport that the event is in, e.g. `Basketball`, `Tennis`.
- `competition` : Competition that the event is in, e.g. `NFL`, `US Open`.
- `participants` : Market participants (teams or opponents), an array of
  `{name, role, short_name, abbreviation}`. Exact fields populated are event
  type dependent.
- `keywords` : Keywords associated with the market, such as team mascot names, used for search.

##### Rules and pricing

- `rules` : The rule that governs the market's result and status.
- `specifier` : Further specifies `rules` where needed (e.g. the spread line, or which player/stat for a player prop).
- `stat_detail` : Decoded detail for player-stat-line markets (player, stat, line); `null` for every other `rules` value.
- `max_price` : The settlement value of one winning contract, in cents, and the ceiling on order prices: an order must price strictly below it. `100` on a $1 market. Read it per market.
- `order_price_rules` : Price ranges, in cents, and the step a price display uses within each. See below.
- `sort` : A list of these field names, in priority order, for the client to use when sorting a market list.

###### Order Price Rules

An array of ranges:

```json
[{"from": 1, "to": 19, "inc": 1},
 {"from": 20, "to": 79, "inc": 10},
 {"from": 80, "to": 99, "inc": 1}]
```

This example is for a market whose `max_price` is `100` cents. Between 1 and 19 cents
(inclusive; 0 is not a valid order price) a price steps by 1 cent. Between 20 and 79 cents
it steps by 10 cents, and between 80 and 99 by 1 cent. The last range ends one cent below
`max_price`, the highest valid order price. The ranges are derived from `max_price`, so read
them per market rather than assuming these values. They describe the steps STX's own price
controls use; any whole-cent price below `max_price` is a valid order price.

##### Status and lifecycle

- `status` : The market's status. See [Market and order status](/concepts/market-status/).
- `result` : The market's result once known: `pending`, `won`, `lost`, `void`, `settled` or `push`.
- `settled_at` : The UTC time when the market was resulted or voided.
- `trading` : Whether the market is accepting orders right now; see the `suspended` derivation in [Market and order status](/concepts/market-status/#suspended-is-not-one-of-them).
- `in_play_delay_sec` : The delay, in seconds, orders wait in queue while the market's event is `in_progress`.
- `archived` : Whether the market is archived.

##### Categorization

- `featured` : Whether the market is featured (shown first in the UI).
- `featured_home` : Whether the market is featured on the home page.
- `filters` : The list of filters the market appears under, for browsing/organizing markets.
- `trading_filters` : The list of filters used for organizing trades, settlements and related items.
- `home_category` : `Upcoming`, `Live`, or `null` if the market fits neither.

##### Event display

- `event_status` : The status of the event this market is attached to. See [Market and order status](/concepts/market-status/#events-have-their-own-statuses).
- `event_start` : The start time of the event, as an integer of Unix microseconds.
- `event_title` : The title of the event associated with the market.
- `event_short_title` : The short title of the event associated with the market.
- `event_brief` : A short string describing the current state of the market's event.
- `detailed_event_brief` : A longer version of `event_brief`.

##### Trading activity

- `last_traded_price` : The price of the last executed trade, in cents.
- `volume_24h` : Contracts traded on this market in the last 24 hours.
- `total_volume` : Contracts traded on this market across its lifetime.
- `price_change_24h` : The change in price over the last 24 hours.
- `recent_trades` : The last 15 trades on the market. Each `price` is in cents.
- `bids` : The top bids on the market: an array of `{price, quantity}`, price in cents and quantity accumulated at that price. Sorted by price descending, so the best bid is first.
- `offers` : The top offers on the market. Same structure as `bids`, also sorted by price descending, so the best offer is **last**.
- `price` : The price the market is currently trading at, in cents.

##### Probability

- `probability` : The market's effective win probability, whether manual or feed-derived.
- `manual_probability` : Whether `probability` was set manually rather than from the pricing feed.
- `last_probability_at` : When the server last received a probability update from the feed.

#### Joining the Channel

Clients join the topic `markets`. An optional join payload controls filtering:

```json
{
  "rule_filters": ["home_winner", "spread"],
  "message_types": ["market_updated", "market_created"]
}
```

- `rule_filters` : Only markets whose `rules` field matches one of these values
  are delivered. Omit or pass `null` to receive every market. Unknown values
  are silently ignored; if nothing valid is left, filtering is disabled.
- `message_types` : Which broadcast types to receive: `market_updated`,
  `market_created`, or both. Defaults to both when omitted, invalid, or `null`.

The join reply echoes back the resolved configuration:

```json
{
  "available_rules": ["home_winner", "spread", "..."],
  "selected_rule_filters": ["spread"],
  "selected_message_types": ["market_updated", "market_created"]
}
```

`available_rules` is the full set of rule identifiers you can filter on.

#### Changing filters after joining

Send `select_rule_filters` or `select_message_types` on the channel at any
time to change what you receive, without rejoining.

- `select_rule_filters` : `{"rule_filters": [...]}`, or `{"rule_filters": null}`
  to disable rule filtering. Replies with
  `{"selected_rule_filters": [...] | null}`.
- `select_message_types` : `{"message_types": [...]}`, or
  `{"message_types": null}` to reset to both types. Replies with
  `{"selected_message_types": [...]}`.

#### Use Cases

| Use case | Message to send |
| --- | --- |
| Join and receive every market, both event types | `["0","1","markets","phx_join",{}]` |
| Join filtered to `spread` markets only | `["0","1","markets","phx_join",{"rule_filters":["spread"]}]` |
| Join receiving only `market_updated` events | `["0","1","markets","phx_join",{"message_types":["market_updated"]}]` |
| Narrow the rule filter after joining | `["0","2","markets","select_rule_filters",{"rule_filters":["home_winner"]}]` |
| Disable rule filtering after joining | `["0","3","markets","select_rule_filters",{"rule_filters":null}]` |
| Switch to only `market_created` events after joining | `["0","4","markets","select_message_types",{"message_types":["market_created"]}]` |
| Reset to receiving both event types after joining | `["0","5","markets","select_message_types",{"message_types":null}]` |

#### Delta updates to markets

`market_updated` carries only the fields that changed, plus the mandatory
`market_id`, `timestamp` and `unix_timestamp`.

A **status change is pushed immediately** when it happens. Every other field
change is coalesced and pushed at most once per broadcast interval (2 seconds by
default), but only while the market is `pre_open` or `open`;
outside that window there's nothing left to coalesce on a timer, so the next
change rides along with the next status-change push instead.

##### Status change

```
[null,null,"markets","market_updated",{"017511eb-930b-492a-8933-2284067e3039": {"market_id":"017511eb-930b-492a-8933-2284067e3039","status":"pre_open","timestamp":"2021-03-24T13:11:42.113364Z","unix_timestamp":1616591502113364}}]
```

##### Game starts

```
[null,null,"markets","market_updated",{"256910ed-213c-44bb-8b9b-66d48689e42b": {"event_brief":"PHX 0 - 0 ORL : Q1 12:00","event_status":"in_progress","market_id":"256910ed-213c-44bb-8b9b-66d48689e42b","timestamp":"2021-03-24T13:24:51.138859Z","unix_timestamp":1616592291138859}}]
```

##### Game closes

```
[null,null,"markets","market_updated",{"256910ed-213c-44bb-8b9b-66d48689e42b": {"settled_at":"2021-03-24T13:26:57.791844Z","market_id":"256910ed-213c-44bb-8b9b-66d48689e42b","price":100,"result":"won","status":"resulted","timestamp":"2021-03-24T13:26:57.802121Z","unix_timestamp":1616592417802121}}]
```

##### Probability changed

```
[null,null,"markets","market_updated",{"fcab0df4-2c78-462c-a52e-9e859467bd29": {"last_probability_at":"2021-03-24T13:12:01.979223Z","market_id":"fcab0df4-2c78-462c-a52e-9e859467bd29","probability":0.319857,"timestamp":"2021-03-24T13:12:01.979329Z","unix_timestamp":1616591521979329}}]
```

#### Newly created market push

`market_created` fires when a market first becomes tradeable: on the
transition to `pre_open`, or (for a market with no pre-open phase) on the
transition straight from `scheduled` to `open`. Unlike `market_updated`, it
always carries every field listed under [MarketPayload fields](#marketpayload-fields).

```json
[null,null,"markets","market_created",{
  "017511eb-930b-492a-8933-2284067e3039": {
    "market_id": "017511eb-930b-492a-8933-2284067e3039",
    "event_id": "86c9d896-62ab-4c59-8f1c-4cc7850c19c3",
    "timestamp": "2026-03-24T12:58:30.869725Z",
    "unix_timestamp": 1774360710869725,
    "symbol": "STXNBA-26MAR250000CLECHI-GAMECHI",
    "title": "NBA - Week 14  CLE @ CHI",
    "short_title": "Bulls to win",
    "group_title": "Chicago Bulls @ Cleveland Cavaliers",
    "grouping_id": "86c9d896-62ab-4c59-8f1c-4cc7850c19c3:moneyline:full",
    "grouping_name": "Moneyline",
    "description": "Contracts for this market settle into $1 if the Chicago Bulls beat the Cleveland Cavaliers and settle into $0 if they do not.",
    "question": "Will the Chicago Bulls defeat the Cleveland Cavaliers?",
    "position": "Chicago Bulls",
    "event_type": "basketball_game",
    "sport": "Basketball",
    "competition": "NBA",
    "participants": [
      {"name": "Chicago Bulls", "role": "home", "short_name": "Bulls", "abbreviation": "CHI"},
      {"name": "Cleveland Cavaliers", "role": "away", "short_name": "Cavaliers", "abbreviation": "CLE"}
    ],
    "keywords": ["Bulls", "Cavaliers"],
    "rules": "home_winner",
    "specifier": null,
    "stat_detail": null,
    "max_price": 100,
    "order_price_rules": [
      {"from": 1, "to": 19, "inc": 1},
      {"from": 20, "to": 79, "inc": 10},
      {"from": 80, "to": 99, "inc": 1}
    ],
    "sort": ["event_start", "price", "short_title"],
    "status": "pre_open",
    "result": "pending",
    "settled_at": null,
    "trading": true,
    "in_play_delay_sec": 5,
    "archived": false,
    "featured": false,
    "featured_home": false,
    "filters": [{"category": "NBA", "section": "Week 14", "subcategory": "Game"}],
    "trading_filters": [],
    "home_category": "Upcoming",
    "event_status": "scheduled",
    "event_start": 1774396800000000,
    "event_title": "Chicago Bulls @ Cleveland Cavaliers",
    "event_short_title": "CHI @ CLE",
    "event_brief": "Starts March 25, 00:00",
    "detailed_event_brief": "",
    "last_traded_price": null,
    "volume_24h": null,
    "total_volume": 0,
    "price_change_24h": null,
    "recent_trades": [],
    "bids": [],
    "offers": [],
    "price": null,
    "probability": 0.677168,
    "manual_probability": false,
    "last_probability_at": "2026-03-24T12:58:30.869637Z"
  }
}]
```