4. Orders - adharapayments/REST-API GitHub Wiki
General Information:
- Streaming order service provides a constant flow of events when there is a change in the status of any order or trade.
- Polling (non-streaming) order service provides a list with current pending orders and last executed trades.
- The first streaming response will be a message with all pending and executed orders (a snapshot), so user does not need to call previously the polling service.
- Trading strategies should open a single stream to receive all order events from different trading interfaces.
- Minimum latency is provided by this service to increase execution probability and cancel/modification latency of any order.
- While streaming, JSON heartbeat objects are sent if there are no changes on any order during a second.
- Typically a trading strategy will send new orders when a price change is detected, but also when an order is executed and more margin is available for trading.
- Typically a trading strategy will cancel a 'pending order' on a price change if order would be 'unexecutable' because of a far price.
- Cancelling pending orders will give more margin for trading.
Examples
Order status request, polling
$ curl -i --data '{"getOrder":{"user":"demo","token":"E79133C6902B63D2E5F5D9E9F1E658019F143675"}}' http://actfx.adhara.io:81/fcgi-bin/IHFTRestAPI/getOrder --header 'Content-Type: application/json'
HTTP/1.1 200 OK
Date: Thu, 02 Jul 2015 00:00:00 GMT
Server: Apache/2.4.7 (Ubuntu)
Transfer-Encoding: chunked
Content-Type: application/json;charset=iso-8859-1
{ "getOrderResponse": {
"order": [
{ "tempid": 189,
"orderid": "TRD_20151027132250498_0127",
"fixid": "TRD_20151027132250498_0127",
"account": "AC1",
"tinterface": "TI1",
"security": "EUR/USD",
"pips": 5,
"quantity": 100000,
"side": "buy",
"type": "limit",
"limitprice": 1.100000,
"maxshowquantity": 4045,
"timeinforce": "good till cancel",
"seconds": 4016,
"milliseconds": 0,
"priceatstart": 1.106150,
"userparam": 0,
"status": "pending" } ],
"timestamp": "1445952093.991207" }
}
Order status request, streaming (only changes)
$ curl -i --data '{"getOrder":{"user":"demo","token":"E79133C6902B63D2E5F5D9E9F1E658019F143675"}}' http://actfx.adhara.io:81/cgi-bin/IHFTRestStreamer/getOrder --header 'Content-Type: application/json'
HTTP/1.1 200 OK
Date: Thu, 02 Jul 2015 00:00:00 GMT
Server: Apache/2.4.7 (Ubuntu)
Transfer-Encoding: chunked
Content-Type: application/json;charset=iso-8859-1
{ "getOrderResponse": {
"heartbeat": {
"security": [ "AUD/CAD", ..., "ZAR/JPY" ],
"tinterface": [ "TI1", "TI2" ] },
"timestamp": "1445952272.783983" }
}
{ "getOrderResponse": {
"order": [
{ "tempid": 190,
"orderid": "TRD_20151027132551451_0126",
"fixid": "TRD_20151027132551451_0126",
"account": "AC1",
"tinterface": "TI1",
"security": "EUR/USD",
"pips": 5,
"quantity": 100000,
"side": "buy",
"type": "market",
"finishedprice": 1.105090,
"finishedquantity": 100000,
"commcurrency": "USD",
"commission": 15.000000,
"priceatstart": 1.105090,
"userparam": 0,
"status": "executed" } ],
"timestamp": "1445952273.659753" }
}
{ "getOrderResponse": {
"heartbeat": {
"security": [ "AUD/CAD", ..., "ZAR/JPY" ],
"tinterface": [ "TI1", "TI2" ] },
"timestamp": "1445952272.783983" }
}
... more responses ...
getOrder web-service:
Request: getOrder
getOrder takes the following input parameters:
- user: Required. Strategy login assigned by the backend administrator.
- token: Required. Token obtained during the authentication procedure.
- security: Optional. List of securities whose order changes will be streamed. Default value: All securities.
- tinterface: Optional. List of trading interfaces whose order changes will be streamed. Default value: All trading interfaces.
- type: Optional. List of types that will be streamed. It can be "pending", "indetermined", "executed", "canceled" and "rejected". For example: To stream only executed order, set 'type' to 'executed'. Default value: All defined types.
- interval: Optional. Inter-message time interval (in milliseconds). When defined streamed orders are sent at a given rate to prevent high throughputs and overkilling a mobile data plan. Default value: Orders are streamed in real-time (no interval is defined) when any change in an order is detected.
Response: getOrderResponse
getOrderResponse objects are continuously streamed. They may consist of a list of order changes or a heartbeat, both followed by a timestamp.
order: Object that includes a list of orders with the following fields:
- tempid: Temporary ID assigned to order when 'setOrder' web-service was invoked.
- orderid: ID assigned by Adharas's ACT system to identify this order. This ID is always the same after an order cancelation or modification ('cancelOrder' and 'modifyOrder' web services), so user can always identify uniquely each order.
- fixid: ID assined by the venue to this order. This ID must be used to cancel or replace this order (by 'cancelOrder' and 'modifyOrder' web services)
- account: Name of the account where settlement whill be done after order execution.
- tinterface: Name of the trading intarface used to route the order.
- security: Instrument name.
- pips: Number of decimals that defines the "pips" of the price.
- quantity: Amount of the order (of the security).
- side: "buy" or "sell".
- type: "market" or "limit".
- limitprice: Limit price assigned to a 'limit' order.
- timeinforce: "day", "good till cancel", "inmediate or cancel" or "fill or kill".
- finishedprice: Final negotiated price when an order has been executed.
- finishedquantity: Final negotiated quantity when an order has been executed.
- commcurrency: Asset to be used to apply the commission ("EUR", "USD", ...)
- commission: Commission amount to be applied to an executed order (at defined 'commcurrency' asset/currency).
- userparam: User-defined parameter (an integer) that user defined when order was placed (with 'setOrder' web service)
- status: Current status of the order: "invalid", "in flux", "pending", "indetermined", "executed", "canceled", "rejected", "error while sending", "replaced to a new order", "replaced to cancel status" or "cancelled by user".
- reason: (When defined) a descriptive message indicating why the order reached defined 'status'.
heartbeat: Keep alive object which is sent when there is no change in orders during 1000ms. It includes a list of all trading interfaces associated to the streaming with following fields:
- security: List of securitoes whose orders are being reported.
- tinterface: List of trading interface whose orders are being reported.
timestamp: Epoch time of the orders or heartbeat. Decimals define the number of micro-seconds. Integer part represents the seconds from "epoch" time.