Orders
Orders interface is a facility to handle placing and managing trading orders. This interface can be used to place an order, look up an order, or retrieve a collection of orders.
Orders can be submitted in a synchronous or asynchronous fashion. It truly depends on the needs of your strategy which method is best suited for your strategy, but there are some caveats that you need to be aware of. Orders can be submitted either via a standalone Buy() or Sell() methods, or via ..buy() ..sell() methods of the Orders interface.
Asynchronous (non-blocking) orders#
Orders.buy and Orders.sell API methods of the Orders interface are asynchronous. They are non-blocking.When called in a script, the script execution will continue. The order will be submitted - as always - but the script will not wait to hear back from the broker. There will be no return value to query for order status, errors, etc. If you submit an order in a asynchronous way and wish to check up on its status, you will need to query other methods of Orders interface, for instance such as Orders.getOpenOrders(...)
WARNING: An asynchronously nature of things means that a condition (if any) set by a asynchronous task or a method, may not be read by the tasks that follow. Latency is a factor. I’ve once submitted unwanted orders because multiple tasks were triggered before a control flag was set.
Synchronous (blocking) orders#
On the other hand, standalone Buy(...) or Sell(...) API calls (as shown below) are executed synchronously. Those are blocking calls which means, the scripts execution will wait until there is a response from the broker. This allows us to inspect the result of the call.
The choice which method is suitable for your algo is up to you, the user, and it definitely depends on your needds and your algorithms.
Buy#
Place a buy order synchronously. It is a blocking method and script execution will halt until a response is received from a broker. The return value(s) is an instance of Order object (note plural vs. singular) which contains order details like status, fill quantity, etc. Typically a list of Orders is returned, even if it’d contain a single item.
| Parameter name | Type | Desription |
|---|---|---|
symbol | String | Symbol of the equity |
quantity | Number | Number of shares to buy |
inForce | String | Supported order types (for now) • “gtc” - good until cancelled • “day” - good until end of day • “ioc” - immediate or cancell • “fok” - fill or kill |
type | String | “limit” or “market” |
price | Number | Limit price in case type is “limit”, ignored for “market” orders |
• Return values
| Result | Return value |
|---|---|
| on success | An instance of an Order object |
| on error | An instance of an Order object with status code and error message (see: extendedInfo) |
- JavaScript
- Python
Sell#
Place a sell order synchronously. It is a blocking method and script execution will halt until a response is received from a broker. The returned value is an Order instance which can be inspected for the order status and additional information (extendedInfo).
| Parameter name | Type | Desription |
|---|---|---|
symbol | String | Symbol of the equity |
quantity | Number | Number of shares to buy |
inForce | String | Supported order types (for now) • “gtc” - good until cancelled • “day” - good until end of day • “ioc” - immediate or cancell • “fok” - fill or kill |
type | String | “limit” or “market” |
price | Number | Limit price in case type is “limit”, ignored for “market” orders |
• Return values
| Result | Return value |
|---|---|
| on success | An instance of an Order object |
| on error | An instance of an Order object with status code and error message (see: extendedInfo) |
- JavaScript
- Python