WHAT WEB METHODS ARE AVAILABLE?
The BETDAQ API has two levels of interface: “Read-only” methods which only require your username and “Secure” methods which require user and password information.
All calls and their returncodes are detailed in the API V2 specification document, which is available here.
Read-only methods
Currently, the following Read-Only methods are available:
GetCurrentSelectionSequenceNumber
Returns the maximum selection sequence number
Get Event Sub Tree No Selections
Returns the tree of events and markets
Get Event Sub Tree With Selections
Returns the tree of events, markets and selections
Get Market Information
Returns detailed information about given markets(up to a maximum of 50), including the selections and prices
Get Prices
Returns the prices for the specified markets(up to a maximum of 50) – this is more optimized than GetMarketInformation
List Market Withdrawal History
Returns history of withdrawals for a given market
List Selections Changed Since
Returns the selections with a sequence number greater than the sequence number provided
List Top Level Events
Returns the set of top level events that are currently active
Get Odds Ladder
Obtain the current odds ladder
Get Selection Trades
Returns the history of trades ojn the selection(s) specified
Get Enabled Market Information
Gets information definining which markets are enabled starting price-orders
Secure methods
These ar secure methods that are available. The information protection is provided using SSL.
GetAccountBalances
Returns a summary of your account balances
GetOrderDetails
Returns detailed information about a given Order
CancelAllOrders
Cancels all unmatched orders across all markets
CancelAllOrdersOnMarket
Cancels all unmatched orders on a market
CancelOrders
Cancels 1 or more Orders on the exchange
ChangePassword
Change password on the current account
ListAccountPostings
Returns an account summary and details of orders placed for the current punter
ListAccountPostingsById
Returns an account summary and details of orders placed for the current punter
ListBlacklistInformation
List blacklist information for the current punter
ListBootstrapOrders
Returns bootstrap orders that have a sequence number greater than the sequence number specified
ListOrdersChangedSince
Returns a list of orders that have changed since a given sequence number exchange
PlaceOrderNoReceipt
Places one or more orders(up to a maximum of 50) on the exchange and does not wait for response from exchange
PlaceOrdersWithReceipt
Places one or more orders(up to a maximum of 10) on the exchange and waits for response from exchange<
UpdateOrdersNoReceipt
Updates one or more orders(up to a maximum of 50) on the exchange without waiting for a response UpdateOrdersNoReceipt
SuspendFromTrading
Suspend any of your orders from being matched
UnsuspendFromTrading
Unsuspend yourself from being suspending from trading
SuspendOrders
Suspends one or more orders
SuspendAllOrdersOnMarket
Suspends all unmatched orders on a market
SuspendAllOrders
Suspends all unmatched orders across all markets
UnsuspendOrders
Unsuspends one or more suspended orders
RegisterHeartbeat
Register the Punter as requiring a Heartbeat
ChangeHeartbeatRegistration
Update the Heartbeat parameters for the Punter
DeregisterHeartbeat
Deregister the Punter from requiring a Heartbeat
Pulse
Notify the system that the application is still active and still has connectivity
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 |
| Register Heartbeat | 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). |
| Change Heartbeat Registration | Update the Heartbeat parameters for the Punter. |
| De-register Heartbeat | 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. |
List BlackList Information
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..
Details Page Functionality
The UI for the sample application is broken into three pages, however the Details page offers most of the functionality. In order to connect and use the Global Betting Exchange API v2.0 you will need to start by setting the connection details found in the first panel of the page. The Secure and Readonly fields should never need to be changed, and are both joined with the Base URL field to construct the full URL for the API. The Username, Password and Base URL fields should be provided to you in an email. Pressing the Connect button simply instantiates the SecureServiceAgent and ReadonlyServiceAgent objects, which in turn creates private instances of the SecureService and ReadOnlyService proxy objects as defined in the API’s WSDL. So now every API call must go through the two agents, which in turn calls the relevant method on their private instance of the proxy.
Because simply setting up the API proxies won’t necessarily tell us if we have a problem, the Connect button finishes off by calling a web method to test the connection, in this case by calling the Get Details button’s event handler. Note: the form’s load event sets up the proxies as well, so typically you will only need to actually press the Connect button if you change the connection settings and so need to establish a new connection.
The second panel (Account Details) provides the Get Details button that simply calls the GetAccountBalances web method. As is the usual pattern, the agent object is called which in turn makes the actual web method call and receives a GetAccountBalancesResponse object in reply. This is then used to populate the five fields in the panel.
The third panel contains an Events TreeView control for displaying the event hierarchy. This control is first populated by pressing the Get Top Level Events button, which uses the ListTopLevelEvents web method to get the high level events, e.g. Soccer, Horse Racing, etc. When the plus symbol beside an event is clicked, the agent calls the GetEventSubTreeNoSelections web method to fetch the full event tree for that sport. Once the event sub-tree is fetched it is then stored in memory, this means the first time the sub-tree is expanded a significant delay may be encountered, however all subsequent expansions will be quick. Clicking on a market within the tree uses the GetPrices web method to populate the Selections DataGrid below it. This grid displays the top three back and lay prices for each selection.
The fourth panel displays details about the selected event, market and selection. You may then specify the amount, odds and polarity for a bet then add it to the list of orders waiting to be placed by clicking the Add Bets button. The Clear List button obviously removes all pending Bets to place, while the Place Bet button results in the PlaceOrdersNoReceipt web method being called. The order ids for each of the placed bets are then displayed below in the Bet Id(s) listbox. A number of these bet ids can be selected from the list at the same time and the Cancel Bets button pressed, resulting in the CancelOrders web method being called.
My Bets Page Functionality
This page demonstrates the use of two web methods that work hand in hand, ListBootstrapOrders and ListOrdersChangedSince. The typical way to use these functions is by starting with a bootstrapping cycle, this will give you all the existing bets up to the current time. Both these methods return a set number of bets per call, which means that multiple calls may need to be made in order to get all the bets. The basic rule to follow is that you should keep calling the method until no bets are returned or the sequence number of the last returned bet is equal to the maximum sequence number.
Once you’ve finished the bootstrapping cycle you should make a call to the ListOrdersChangedSince web method, passing in the MaximumSequenceNumber as a parameter, just in case a bet may have changed since the time you started the bootstrapping cycle.
Typically, in a real world scenario you would set up a timer to call the ListOrdersChangedSince web method regularly, however in this sample application you must press the ListOrdersChangedSince button yourself to make the call. If you don’t pass in the maximum sequence number from the bootstrapping cycle when you call the ListOrdersChangedSince web method then you will get back the full bet history again. To test the application is working as expected, complete the bootstrapping cycle, place a new bet then press the ListOrdersChangedSince button, this should result in the new bet being listed in the second DataGrid control.
Log Page Functionality
The function of this page is pretty obvious, each call to the web service results in information being written to this page. Presently, the only information displayed is the name of the web method call and the time taken. As you’ll see this logging functionality is too simple for a real world situation, results simply disappear of the bottom of the list, however this could easily be extended to output to a file of your choice.