Watched markets (market_updates)

View Markdown Ask in ChatGPT Ask in Claude

Delivers live updates for markets you explicitly subscribe to: a bandwidth conscious alternative to the 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.

Payload fields

The fields below use full names; nothing here is abbreviated. They are a subset of the 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.

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:

[
  {"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.
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

["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:

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

Response:

[
  "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.

[
  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.

[
  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}]
  }
]

v1.5.9Changelog llms.txt llms-full.txt