-
Notifications
You must be signed in to change notification settings - Fork 2
trader state API Reference
The trader-state webcomponent is the main frontend interface to the market. It allows players to enter orders, cancel orders and directly accept others' orders. It also emits events with information about entered orders, trades and errors. Additionally, it stores information about player's current state, as well as the state of the trading session as a whole. A reference for trader-state's properties, methods and events is provided below.
The trader-state component can be found at the following path:
/static/otree_markets/trader_state.js
You can import it directly into your template with this script tag:
<script type="module" src="/static/otree_markets/trader_state.js"></script>You can import it into a Polymer component with this import statement:
import '/static/otree_markets/trader_state.js';Orders and trades are stored in Javascript objects with the following structures. The notation for this section is that a value in `backticks` is a type. The ":=" means "is defined as". You can read this as "the Order/Trade type is defined as an object with these keys of these types".
For an explanation of the "making" and "taking" order fields on trade, see the Terminology page of this wiki.
`Order` := {
timestamp: `float`, // the time this order was entered
price: `int`, // this order's price
volume: `int`, // this order's volume
is_bid: `boolean`, // true if this order is a bid, false it it's an ask
pcode: `string`, // the participant code for the player that entered this order
traded_volume: `int`, // the volume of this order which was traded, or null if this order hasn't yet been traded
order_id: `int`, // this order's id
asset_name: `string`, // the name of the asset this order is for
}
`Trade` := {
timestamp: `float`, // the time this trade occurred
asset_name: `string`, // the name of the asset this trade occurred with
taking_order: `order`, // an order object representing the taking order for this trade
making_orders: [ // a list of order objects representing the making orders for this trade
`Order`,
...
]
}
bids: `Array`
This property is a list of Order objects representing all the currently active bids on the market. This array is sorted by the each order's priority. That is, it's sorted by descending price, then by ascending timestamp.
asks: `Array`
This property is a list of Order objects representing all the currently active asks on the market. This array is sorted by the each order's priority. That is, it's sorted by ascending price, then by ascending timestamp.
trades: `Array`
This property is a list of Trade objects representing all the trades which have occurred in the current round of trading. This array is sorted by ascending timestamp.
settledAssetsDict: `Object`
This property is an object mapping asset names to the current player's settled asset holdings. For a description of the distinction between settled and available holdings, see the Terminology page of this wiki.
availableAssetsDict: `Object`
This property is an object mapping asset names to the current player's available asset holdings. For a description of the distinction between settled and available holdings, see the Terminology page of this wiki.
settledAssets: `Number`
This property is only defined when oTree markets is configured for a single asset. When trading a single asset, this property contains the current player's holdings of that one asset. For a description of the distinction between settled and available holdings, see the Terminology page of this wiki.
settledCash: `Number`
This property contains the current player's settled cash holdings. For a description of the distinction between settled and available holdings, see the Terminology page of this wiki.
availableCash: `Number`
This property contains the current player's available cash holdings. For a description of the distinction between settled and available holdings, see the Terminology page of this wiki.
timeRemaining: `Number`
This property contains the number of seconds remaining in the round, rounded to the nearest second. Once the round starts, this number is updated once a second.
enter_order(price: `Number`, volume: `Number`, is_bid: `Boolean`, asset_name: `String`)
This method allows the current player to submit an order to the market. price is the price of the proposed order. volume is the volume of the proposed order. is_bid is true if the proposed order is a bid and false if it's an ask. asset_name is the name of the asset that the proposed order is for.
The asset_name argument should be omitted when trading with a single asset.
Price and volume should always be integers. See the Gotchas page for more information.
Calling this method does not guarantee that an order is successfully entered. The order may be rejected by the backend for some reason. To react to an order being successfully entered, you should use the confirm-order-entered event.
cancel_order(order: `Order`)
This method sends cancel request to the backend. The parameter order is an Order object representing the order that is to be canceled.
When canceling orders, make sure the player that is requesting the cancel is the same player that submitted the order. If this isn't true, an exception will be raised on the backend. Also ensure that the order being canceled is still active. If it isn't, again an exception will be raised.
Calling this method does not guarantee that the order is successfully canceled. To react to an order being successfully canceled, you should use the confirm-order-canceled event.
accept_order(order: `Order`)
This method sends an immediate accept message to the backend. The parameter order is an Order object representing the order that the player would like to accept.
An immediate accept order is a type of order where a player requests to trade directly with another named order. If the player has enough available holdings to complete the trade, the exchange will create a trade between the current player and the player that submitted the named order.
Calling this method does not guarantee that the named order is successfully traded with. To react to an order being successfully traded, you should use the confirm-trade event.
These are Javascript events that represent different events occurring in the market. These events can be caught with addEventListener. The information that each event is communicating is stored in the event's detail field.
The following Javascript snippet calls console.log on Order objects created by trader-state when a confirm-order-entered event occurs. It assumes the trader-state webcomponent is included in the page and has id="trader_state"
const trader_state = getElementById('trader_state');
trader_state.addEventListener('confirm-order-entered', function(event) {
const entered_order = event.detail;
console.log(entered_order);
});event.type = "confirm-order-enter"
event.detail = `Order`
This event signifies an order being accepted by the exchange. The detail field of this event is an Order object representing the order which was entered.
event.type = "confirm-order-cancel"
event.detail = `Order`
This event signifies an order being successfully canceled. The detail field of this event is an Order object representing the order which was canceled.
event.type = "confirm-trade"
event.detail = `Trade`
This event signifies a trade occurring. The detail field of this event is a Trade object representing the trade which just occurred.
event.type = "error"
event.detail = `String`
This event is emitted when the backend sends an error message to this player. The detail field of this event is the text of the error message.