Documentation
Prices
Price data shows current and historical trading activity in a Market.
Price Data
The purpose of Price data is to provide a view of trading activity in a Market. The trader then uses the Price data to decide how and when to enter Orders.
Price data shows the best available Buy and Sell price levels. Additional price levels on each side are also shown, up to the configured Market Depth. The last traded price and the last Transactional Tradeable amount executed are also shown.
The Market unique identifier (also referred to as the primary key) is included in each Price data packet. The data also has a timestamp field, in UTC, that holds the time that the matching loop created the Price data packet.
LIMIT Orders Only
Price data only shows LIMIT Orders that are working in the Market now (for current updates) or that were working at the time (for historical data).
MARKET Orders are hidden because they accept any price and could be picked off at extreme prices if other Users knew that they were working. STOP-type Orders and Effective Orders are held outside the Market and do not work until their trigger criteria are met.
Best Limit Orders
The best Buy Order is the Buy Order with the highest limit price. Conversely, the best Sell Order is that with the lowest limit price.
When multiple Orders have the same or similar limit prices, the price level shows the bucketed price and the total quantity of Transactional Tradeable Item available at that level.
"Similar" Limit Prices and Price Bucketing
In this system, the amounts of Tradeable Items on Orders are constrained to real-world increments by their Tick Sizes. The prices are not ticked, and are ratios of the Transactional and Settlement amounts, so prices can be decimal values up to a great many decimal places.
To avoid having many micro price levels, prices are "bucketed" to a given resolution. When the term "similar" price is used, it just means a price that is within the same price bucket, given the Market resolution.
Prices for Buys are bucketed down, and for Sells, bucketed up. For a Market priced in Dollars with a price resolution of 0.01, prices are bucketed into one-cent price levels. If a Buy Order has a high-precision price that falls between two cent values, it is bucketed into the lower of the two possible buckets. For a Sell Order, the reverse is true, prices are bucketed to the higher of the two possible buckets. This means that Orders in a price level are "at least as good" as the indicated level, and therefore likely to trade at that level or better.
The Transactional Tradeable amount shown for the bucket is the sum of the amounts across the Orders that fall into the same bucket. When matching occurs, the high precision prices are used to prioritise the best Orders first.
Depth of Market in Price Data
Depth of Market is the number of price levels displayed. The Owner of a Market can configure this, and it can be any number of levels from 1 to 20. The default value is 5.
A Depth of Market value of 5 is common. A value of at least 1 is required to show the best bid and offer. For Buy Orders, the next price level down is "behind" the best bid in matching priority, and each further level down is less likely to trade. Similarly for Sell Orders, the next price level above the best offer is behind the best offer in matching priority. Beyond a Depth of 5, the data becomes less useful, but there may be situations where showing many price levels has utility, so the facility is available if required.
Last Traded Price and Volume
If there was an execution in the Market, the last execution price and Transactional amount executed (termed volume) are included in the Price data.
If the matching loop reviewed the Market and could not find a match, the best bids and offers are still displayed as a new Price update, but the last traded price and volume are left empty.
Time Resolution
Each time the matching loop passes over the data, it pulls the best bid and best offer, tries to match them, and creates a Price data packet.
If a match occurs, the last traded price and volume are recorded in the Price data packet. If no match occurs, the last traded price and volume are omitted from the Price data packet, and that matching pass ends.
A Market matching pass continues through a series of loops while Orders can still be matched, with each execution producing a new Price data packet. Once no further Orders can be matched, a final Price data packet is produced without a last traded price or volume. As such, the sequential Price updates together form an extremely detailed "movie" of the trading activity, and every individual execution is recorded.
Price Resolution
As detailed above, prices are calculated as the ratio between amounts of Transactional and Settlement Tradeable Items. Because the Tradeable Item quantities are constrained by Tick Size, the resulting price is an unticked ratio and may contain many decimal places. Each Order could have a price with many decimal places that is specific to that Order and that would make Price data very difficult to display in a meaningful way.
To tackle this problem, prices are bucketed together into levels. The Market is configurable to control the size of the buckets used, and therefore how much detail is shown in the Price data.
The default precision for prices in a Market is determined by the tick-size of the Settlement Tradeable Item. This is referred to in the system as the "DecPlacesPx" value, short for "Decimal Places for Price".
The Settlement Tradeable Item is quite often a Currency. If we take the US Dollar as an example, the tick-size of the US Dollar is 0.01, or one-hundredth of a dollar, a Cent. The DecPlacesPx value is defaulted to 2 - two decimal places. That means that if you set up a Market and use the US Dollar as the Settlement Tradeable Item, prices will be expressed to two decimal places by default.
Buy Orders are bucketed together by rounding down their prices to the Cent, away from the Market. Sell Orders are bucketed together by rounding up their prices to the Cent, again, away from the Market. This means that Orders do not over-state their prices; they are at least as good as the bucket they are in.
This DecPlacesPx value is a setting that the Owner of a Market can change. You may want to set up a Market using US Dollars as the Currency, but the prices in the Market may be better rounded to whole dollars. For example, if you are trading big-ticket items like Cars, they have values in thousands of dollars, and the cents part is, to a certain extent, not useful. The Owner of a Market for Cars could still use US Dollars as the currency, but set the DecPlacesPx value to 0 (zero), and quote the prices in whole dollars. Remember that the actual Order prices may still contain cent or sub-cent values; only the Price data display is bucketed into whole-dollar levels.
Current and Historical Prices
Traders in Markets usually need to know where the Market is right now (current), and what the trends have been over time (historical).
Current Price Data
Current data is fast-moving, possibly at the sub-second rate. The design intention is for client applications to periodically poll the current Price data endpoint, at a rate that humans could sensibly review the data, i.e. once every two seconds or so.
Alternatively, Price data can be requested when a trader is preparing to place an Order. On an order ticket or website form, there might be a "Get the Current Price" button that presents the price right now.
Historical Price Data
Historical Price data is the set of Price data updates previously generated for a Market. This data could be extremely detailed, so data is provided by two possible endpoints.
One endpoint provides data in the raw form, so that every Price update is presented. This detail level allows the caller to see all of the executions sequentially. As matching may be sub-second, this data can be large, and the returned data set is paged.
The other Historical Price data endpoint provides trade data aggregated at a time resolution. The caller can provide a time resolution, and then trades are aggregated to that resolution. The intention is that this endpoint would be used if a website or application wanted to present "trade history" for prices over time, as a graph.
Conclusion
This documentation section covered...
- Order Basics: An Order is an instruction to buy or sell.
- Order Types: MARKET, LIMIT, STOPMARKET and STOPLIMIT Orders, together with time-triggered Effective Orders.
- Order Status and Lifespan: How an Order changes over the course of its existence.
- Order Routing: Orders can originate in external client systems and carry caller-supplied data.
- Average Limit Orders: Improvements can be used to increase the quantity an Order can execute.
- Prices: What Price data is, and how it is configurable for each Market.