# Watched markets (market_updates)


Source: https://docs.stxapp.io/websockets/channels/market-updates/

Delivers live updates for markets you explicitly subscribe to: a bandwidth
conscious alternative to the [`markets`](/websockets/channels/markets/) channel, which
broadcasts every market to every subscriber.

There's no snapshot on join: the full market list is available from
`GET /api/v1/markets`. This channel only pushes changes, and only for the
markets you [watch](#watching-markets).

## Payload fields

The fields below use full names; nothing here is abbreviated. They are a
subset of the [`markets`](/websockets/channels/markets/) channel's payload: `featured`,
`featured_home`, `stat_detail`, `event_title` and `event_short_title` are
sent there and not here. The market's id is sent under both `market_id` and
`id`, and the change time is sent as both an ISO 8601 `timestamp` and a
`unix_timestamp` in microseconds. Pick whichever pair suits your client.

:::caution[Prices on this channel are in cents]
As on [`markets`](/websockets/channels/markets/), `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 sends. A market whose `max_price` is `"1.0000"` over REST reads `100`
here, and `price` is sent with one decimal place (`53.0`). Divide by 100 before placing an
order with one of these values.
:::

### Fields set when the market is created

- `market_id` / `id` : The market's id, sent under both keys.
- `event_id` : The id of the event the market is attached to.
- `symbol` : A unique symbol string for the market.
- `description` : The market's description.
- `title` : The market's human-readable title.
- `short_title` : The market's human-readable short title.
- `group_title` : The market's human-readable title used for grouping in
  the UI.
- `grouping_id` : Identity of the set of mutually exclusive outcomes the market
  belongs to. Stable for the life of the market, and shared by its siblings.
  Sent when the full object is sent; absent from a change-only push, 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.
- `question` : The question the market is asking.
- `position` : The text used to describe the position.
- `event_type` : The type of event the market is attached to.
- `sport` : The sport the event is in, e.g. `Basketball`, `Tennis`.
- `competition` : The competition the event is in, e.g. `NFL`, `US Open`.
- `participants` : The market's participants (teams or opponents).
  Structure depends on the event type.
- `keywords` : Keywords associated with the market, such as team mascot
  names.
- `rules` : The rules that govern the market.
- `specifier` : The specifier for `rules`, used to determine the market's
  result and status. Null if the rule doesn't need one.
- `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 fields to use for the market's default sorting.
- `in_play_delay_sec` : The delay, in seconds, orders wait in queue while
  the event is `in_progress`.

#### Order Price Rules

An array describing how the order price can change within given price
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 never a valid price) a price steps by 1 cent.
Between 20 and 79 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. Any
whole-cent price below `max_price` is a valid order price.

### Fields that change as the market trades

- `timestamp` / `unix_timestamp` : When this change happened, sent as both
  an ISO 8601 string and a unix timestamp in microseconds.
- `status` : The market's status (`scheduled`, `pre_open`, `open`,
  `suspended`, `closed`, `resulted`, `cancelled`, `voided`). See
  [Market and order status](/concepts/market-status/).
- `result` : The market's result (`pending`, `won`, `lost`, `void`,
  `settled`, `push`).
- `settled_at` : When the market was resulted or voided, UTC.
- `archived` : Whether the market is archived.
- `trading` : Whether trading is enabled on the market.
- `filters` : The filters the market appears under.
- `trading_filters` : The filters used for organizing trades, settlements
  and related items.
- `home_category` : The category the market appears in. It lets a client
  tell `Upcoming`, `Live` and uncategorized markets apart.
- `event_status` : The status of the event the market is attached to
  (`scheduled`, `in_progress`, `completed`, `cancelled`).
- `event_start` : The event's start time, as an integer of Unix microseconds.
- `event_brief` : A brief string for the market's event.
- `detailed_event_brief` : A more detailed brief string for the market's
  event.
- `last_traded_price` : The price of the last executed trade, in cents.
- `volume_24h` : The volume traded on the market in the last 24 hours.
- `total_volume` : The total volume traded on the market: the sum of
  `quantity` across all of its trades.
- `price_change_24h` : The change in price over the last 24 hours.
- `recent_trades` : The market's last 15 trades. Each `price` is in cents.
- `bids` : The market's top bids, sorted by price descending, so the best bid
  is first. Each entry has a `price` in cents and the accumulated `quantity`
  at that price.
- `offers` : The market's top offers, also sorted by price descending, so the
  best offer is **last**. Same structure as `bids`.
- `price` : The price the market is currently trading at, in cents.
- `probability` : The market's effective win probability, from the pricing
  feed or set manually.
- `manual_probability` : Whether `probability` was set manually rather
  than from the pricing feed.
- `last_probability_at` : When the last probability was received from the
  feed.

## Use Cases

| Use case | Message to send |
| --- | --- |
| Join the channel (no snapshot is pushed) | `["3","3","market_updates","phx_join",{}]` |
| Watch specific markets for updates | `["4","4","market_updates","watch",["017511eb-930b-492a-8933-2284067e3039"]]` |
| Check the connection and see your current watches | `["4","5","market_updates","ping",{}]` |

### Joining

```json
["3","3","market_updates","phx_join",{}]
```

### Watching markets

Joining alone gets you nothing; you have to tell the channel which
markets to watch. After that, `created` and `updated` events for those
markets are pushed to you as they happen. Should you reconnect for any
reason, `watch` needs to be re-submitted after joining.

Request:

```json
["4","4","market_updates","watch",["017511eb-930b-492a-8933-2284067e3039"]]
```

Response:

```json
[
  "4",
  "4",
  "market_updates",
  "phx_reply",
  {
    "response": {
      "subscriptions": {
        "updates": "level_1",
        "watches": ["017511eb-930b-492a-8933-2284067e3039"]
      }
    },
    "status": "ok"
  }
]
```

If `watch`'s payload isn't a list of market ids, you get an error reply
instead.

### Event: "created"

Pushed for a watched market when it changes state from `scheduled` to
`pre_open`, carrying every field listed under
[Payload fields](#payload-fields).

```json
[
  null,
  null,
  "market_updates",
  "created",
  {
    "market_id": "db5a4f48-764c-4ae7-9b72-e0c23666f3e3",
    "id": "db5a4f48-764c-4ae7-9b72-e0c23666f3e3",
    "event_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
    "symbol": "SOCCER-tourney-2208050938-tx-mt-RG219M",
    "description": "Contracts for this market settle into $1 if the montana beat the texas and settle into $0 if they do not.",
    "title": "tourney tx @ mt",
    "short_title": "tx @ mt",
    "group_title": "tx @ mt",
    "grouping_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301:moneyline:full",
    "grouping_name": "Moneyline",
    "question": "Will the montana defeat the texas?",
    "position": "montana",
    "event_type": "soccer_game",
    "sport": "Soccer",
    "competition": "tourney",
    "participants": ["tx", "mt"],
    "keywords": ["montana", "texas"],
    "rules": "home_winner",
    "specifier": 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"],
    "in_play_delay_sec": 5,
    "timestamp": "2022-08-05T13:39:22.639479Z",
    "unix_timestamp": 1659555562639479,
    "status": "pre_open",
    "result": "pending",
    "settled_at": null,
    "archived": false,
    "trading": true,
    "filters": [
      {"category": "tourney", "manual": false, "section": "Upcoming", "subcategory": "Games"}
    ],
    "trading_filters": [
      {"category": "tourney", "manual": false, "section": "tx", "subcategory": "Teams"},
      {"category": "tourney", "manual": false, "section": "mt", "subcategory": "Teams"}
    ],
    "home_category": "Upcoming",
    "event_status": "scheduled",
    "event_start": 1659706680000000,
    "event_brief": "Aug 05 at 09:38 AM EDT",
    "detailed_event_brief": "Aug 05 at 09:38 AM EDT",
    "last_traded_price": null,
    "volume_24h": null,
    "total_volume": null,
    "price_change_24h": null,
    "recent_trades": [],
    "bids": [],
    "offers": [],
    "price": null,
    "probability": 0.677168,
    "manual_probability": false,
    "last_probability_at": "2022-08-05T13:39:22.639637Z"
  }
]
```

### Event: "updated"

Pushed for a watched market whenever it changes. Only the fields that
changed are included, alongside the market's id and the change time:
`market_id`, `id`, `timestamp` and `unix_timestamp` are always present.

```json
[
  null,
  null,
  "market_updates",
  "updated",
  {
    "market_id": "d6ea3806-1b32-44b4-87f1-9edff2e41cb3",
    "id": "d6ea3806-1b32-44b4-87f1-9edff2e41cb3",
    "timestamp": "2022-08-03T21:32:06.239764Z",
    "unix_timestamp": 1659555126239764,
    "bids": [{"price": 10, "quantity": 2}]
  }
]
```