Market updates

This channel gives information about active markets. The main point of this channel is to provide more optimised way of live updates that happen to a market. When something in the market changes the update message will be sent to the channel. Content of the message is a JSON object containing mandatory market_id and ts (a unix timestamp) keys.

After joining this channel, you will receive “updated” events whenever a market changes. The set of fields returned are only those that have changed and will be further filtered by the output level (see below).

MarketInfo object

The MarketInfo object consists of 2 kind of properties, static that never change and dynamic that can change and when changed are pushed to the socket.

Fields reported in all events

These fields will be reported for all market update events

id : The id of the market.
ts : The unix timestamp of when this market change was made.

Static fields only sent for “created” event

These properties are set when the market is created. Because they never change, they will not be emitted on updates

dsc : The description of the market.
mp : The max price for orders and settlements in this market.
opr : a JSON object describing the rules how the order’s price should increment/decrement on the UI.
pos : The text to use in describing the position.
q : The question that the market is asking.
srt : A list of MarketInfo fields to use for the initial sorting of markets.
sttl : The human-readable short title for the market.
ttl : The human-readable title for the market.

Order Price Rules

A map describing how the order price can change in given price ranges. The structure is an array with elements like this:

{"from" => integer, "to" => integer,  "inc" => integer}}

Example:

[{"from": 1, "to": 100, "inc": 10},
 {"from": 101, "to": 9900, "inc": 100},
 {"from": 9901, "to": 9999, "inc": 10}]

Meaning that when the order’s price is between 1 and 100 cents (inclusive, note that 0 is not a valid order’s price) the +/- buttons on the UI should increment/decrement the price by 10 cents. When the price is between 101 and 9900 the buttons should increment by 100 cents. When the price is between 9901 and 9999 the buttons should increment by 10 cents (9999 is the max valid price for an order).

Fields that can be reported in the “watch” and “created” event

bds : The top bids on the market. An array with object containing the price and the accumulated quantity at that price.
clsd : The UTC time when the market was closed or cancelled.
db : The string that can be used for the detailed brief on the market’s event.
eb : The string that can be used for the brief on the market’s event.
estrt : The UTC start date and time of the event.
estat : The status of the event that the market is attached to (scheduled, in_progress, completed, cancelled).
fil : The list of filters to use when organizing markets.
hc : The category in which the market appears. It allows easily determine if the market is Upcoming, Live or without a category.
lprb : The time that the last probability was received by the server from the feed.
ltp : The price of the last executed trade.
mprb : Is the probability manual or from odds provider.
mstat : The status of the market (scheduled, pre_open, open, suspended, closed, cancelled).
ofrs : The top offers on the market. The structure is the same as for bids.
pc24 : The change in price over the last 24 hours.
prc : The market price that the market is trading at.
prb : The win probability for the market.
rslt : The result of the market (pending, won, lost, void).
rt : A list of the last 15 recent trades on the market.
tfil : The list of filters to use for organizing trades, settlements and related items.
v24 : The volume that has been traded on the market in the last 24 hours.

Joining the Channel

To start receiving “updated” events join the channel

["3","3","market_updates","phx_join", ""]

Event: “create”

Pushed whenever a market is created from the channel user perspective. In fact this is pushed when the market changes state from scheduled to pre_open.

Event:

[null, null, "market_updates", "created",
  {
    "bds": [],
    "db": "Aug 05 at 09:38 AM EDT",
    "dsc": "Contracts for this market settle into $100 if the montana beat the texas and settle into $0 if they do not.",
    "eb": "Aug 05 at 09:38 AM EDT",
    "estrt": "2022-08-05T13:38:00Z",
    "estat": "scheduled",
    "fil": [
        {
          "category": "tourney",
          "manual": false,
          "section": "Upcoming",
          "subcategory": "Games"
        }
    ],
    "hc": "Upcoming",
    "id": "db5a4f48-764c-4ae7-9b72-e0c23666f3e3",
    "mp": 10000,
    "mstat": "pre_open",
    "ofrs": [],
    "opr": [
        {
          "from": 1,
          "inc": 10,
          "to": 99
        },
        {
          "from": 100,
          "inc": 100,
          "to": 9899
        },
        {
          "from": 9900,
          "inc": 10,
          "to": 9999
        }
    ],
    "pos": "montana",
    "q": "Will the montana defeat the texas?",
    "rslt": "pending",
    "rt": [],
    "srt": [
        "event_start",
        "price",
        "short_title"
    ],
    "sttl": "tx @ mt",
    "sym": "SOCCER-tourney-2208050938-tx-mt-RG219M",
    "tfil": [
        {
          "category": "tourney",
          "manual": false,
          "section": "tx",
          "subcategory": "Teams"
        },
        {
          "category": "tourney",
          "manual": false,
          "section": "mt",
          "subcategory": "Teams"
        }
    ],
    "ttl": "tourney tx @ mt",
    "ts": 1659555562639479
  }
]

Event: “updated”

Pushed immediately when a market is updated.

Only changed fields will be included in the pushed message.
Packet will always have market_id and timestamp fields
Other possible fields that may be included: event_status, price, status, most recent bid price and quantity, most recent offer price and quantity
If the packet would only contain market_id and timestamp, the packet will not be sent.
Unlike the “created” and “watched” events the packet is not JSON. Due to the frequency of updates, the overhead of JSON exceeded the “real” data. Therefore the ‘updated’ event employs a simple field-substitution text “compression” schema.

Schema

The first line of the packet is the “schema” version number and newline Each line is “field identifier”, field data, newline “\n” (hex character ‘A’)

1\n
<single character fields identifier>data\n
<single character fields identifier>more data\n

Field substitutions

market_id -> “A”
timestamp -> “B”
price -> “C”
status -> “D”
event_status -> “E”
event_start -> “F”
first bid quantity from “bids” -> “G”
first bid price from “bids” -> “H”
first offer quantity from “offers” -> “I”
first offer bid price from “offers” -> “J”

Event:

Given a new bid on market d6ea3806-1b32-44b4-87f1-9edff2e41cb3, for 2 contracts at 10 dollars the packet will look something like this:

["3", null, "market_updates", "updated",
  "1\n\Ad6ea3806-1b32-44b4-87f1-9edff2e41cb3\nB1659555126239764\nH1000\nG2\n"
]

Command: “watch”

To get all changed fields for a given set of markets, use the “watch” command.

There-after all changed fields for those markets will be immediately reported via the “watch” event.

IMPORTANT NOTE! Should you need to re-connect for whatever reason, this command will have to be re-submitted after joining the channel to inform the server’s connection.

Request:

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

Response:

["3", "3", "market_updates", "phx_reply",
  {
    "response": {
      "subscription": {
        "updates": "level_1",
        "watch": [
            "017511eb-930b-492a-8933-2284067e3039"
        ]
      }
    },
    "status": "ok"
  }
]

Event:

Example “watch” event after user places a bid

["3", null, "market_updates", "watch",
  {
    "bids": [
      {
          "price": 1,
          "quantity": 2
      }
    ],
    "id": "d6ea3806-1b32-44b4-87f1-9edff2e41cb3",
    "ts": 1659555126239764
  }
]