This is a brief description some of the functionality in API V2. For further detail go to the API specification document here
Suspend-Unsuspend functionality:
This API supports suspending orders in addition to cancelling orders. Suspending orders allows a user a low processing cost way to set the status of an order so that will not be matched, as the order still exists and funds are still reserved for that order. Using the suspend and unsuspend orders calls is quicker and more efficient than cancelling orders and then placing new orders as the calculation to determine the new amount of funds to reserve does not need to be performed. If you intend to temporarily stop your trading but intend on put up those offer again, suspending and (updating and) unsuspending orders is the recommended approach. If you simply intend on cancelling the order then use the CancelOrders call directly. The reserved funds of a suspended order are automatically released when the bet is cancelled – on market reset or market close – where applicable. It is probable that at some stage a limit will be imposed on the number of orders that can be specified on PlaceOrdersNoReceipt, PlaceOrdersWithReceipt, UpdateOrdersNoReceipt and the CancelOrders API calls. No limit will be placed on the number or orders that can be specified on the SuspendOrders API calls. It is therefore recommended that robots use the SuspendOrders API calls to immediately ensure that none of their orders will get matched and to then determine update or cancel those orders in batches.
These are the API V2 suspend-unsuspend methods:
| Method | Description |
| SuspendFromTrading | Suspend any of your orders from being matched. This instantly prohibits any of your orders from getting matched subsequently. It is very quick and efficient to suspend your account in this way, but it can take considerable effort to unsuspend your account subsequently (all your open orders must be suspended or cancelled before you can be unsuspended). |
| UnsuspendFromTrading | Unsuspend yourself from being suspending from trading. This will allow orders to be placed and matched. You may not have any active orders when the attempt is made to Unsuspend yourself – all active orders at the time you were suspended must be cancelled or suspended before you can be unsuspended. |
| SuspendOrders | Suspends one or more orders. The amount of funds to be reserved is not re-calculated as a result of suspending orders. |
| SuspendOrdersOnMarket | Suspends all unmatched orders on a market. |
| SuspendAllOrders | Suspends all unmatched orders across all markets. |
| UnsuspendOrders | Unsuspends one or more suspended orders. |
Heartbeat functionality:
Heartbeat provides a mechanism through which all of a Punter’s orders will be cancelled, suspended (or the Punter itself suspended) automatically if connectivity is lost between the client application and the Exchange. This provides added protection to an application as it can be assured that its open orders will not get matched if it can no longer manage its position because it has lost connectivity with the Exchange.
The basic mechanism is that an application specifies that it wants to register for the Heartbeat and it specifies (i) the maximum threshold time after which an action is to be automatically performed if a Pulse is not received and (ii) the action that is to be performed (cancel all orders, suspend all orders or suspend the Punter). The application then sends Pulses (via the Pulse API) at least as frequently as the threshold specified. If a period of time greater than the threshold passes without the API having received a Pulse then the API automatically takes the action specified. This action will only be performed once for each threshold period exceeded. For example, if the threshold value is 6000 and a period of 20000 milli-seconds occurs between Pulses being received. The appropriate action will be taken by the system 6000 milli-seconds after the Pulse was received. No further action will be taken until a subsequent Pulse API call is received, after which the API will again take the appropriate action if a Pulse API is not received the threshold time.
Heartbeat registrations are not persisted by the system. In the unlikely event that a system component fails it discards all heartbeat registrations when re-started, and all applications must reregister their Heartbeats. The application is notified of this situation via the return code 462 PunterNotRegisteredForHeartbeat return code from the Pulse API. This could lead to exposure if both connectivity to the exchange is lost and the system component is restarted at exactly the same time, but this is an extremely remote possibility.
Note that this mechanism acts at the Punter account level. Only one registration can be active for a Punter at one time, and if a pulse is not received within that value the action specified will be performed. Although only one Heartbeat registration can be active at any time Pulse APIs can be issued from any source. Care must be taken if two applications are operating on the same Punter. At least two situations could arise:
- If connectivity from the application that is issuing the Pulse APIs is lost then the action automatically performed will affect orders issued from all other applications (or issued manually through the web site).
- If two applications are issuing Pulse APIs for the one Punter account and one of them lose connectivity the Pulse APIs being received from the other will have the effect that no action is taken for that Punter (as the system will keep received Pulse APIs for the relevant Punter).
These are the API V2 heartbeat methods:
| Method | Description |
| RegisterHeartbeat | Register the Punter as requiring a Heartbeat. To register a threshold and an action need to be specified. The HeartbeatAction values are CancelOrders(1), SuspendOrders(2), SuspendPunter(3). Note that if you are registering with Suspend or SuspendPunter actions you need to have unsuspend functionality already coded in you application to unsuspend APIs (unsuspendFromTrading, UnsuspenOrders). |
| ChangeHeartbeatRegistration | Update the Heartbeat parameters for the Punter. |
| DeregisterHeartbeat | Deregisters the Punter from requiring a Heartbeat. The effect of this is that no action will be automatically taken on the Punter, if a Pulse is not received within the applicable threshold. |
| Pulse | Notifies the system that the application is still active and still has connectivity. If a period of time greater than the threshold (specified on a previous RegisterHeartbeat or ChangeHeartbeatRegistration API) has elapsed since the last Pulse was received the relevant action will be automatically performed by the system (e.g. all orders will be cancelled or suspended or the punter will be suspended automatically). The effect of this Pulse API is that the absolute time by which the next Pulse API must be received will be extended by the threshold value. |
ListBlacklistInformation:
Lists the black-list status for the punter. This returns a list of every API from which the Punter is currently black-listed along with the remaining time (in milli-seconds) of the black-list period for that API. Punters can be black-listed for different periods for difference APIs..