1. API-NG Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3
1.1 Getting Started with API-NG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.1 Application Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.1.2 API-NG Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.1.2.1 Non-Interactive (bot) login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.1.2.1.1 Certificate Generation With XCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.1.2.2 Interactive Login from a Desktop Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
1.1.2.3 Interactive Login - API Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
1.1.2.4 Login FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
1.1.2.5 Keep Alive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
1.1.2.6 Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.1.3 API-NG - Visualiser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
1.1.4 Example Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
1.1.5 How Do I? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
1.1.6 Market Data Request Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
1.1.7 Understanding Market Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
1.2 API-NG Roadmap - to September 2014 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
1.3 API 6.0 > API-NG Operations Comparison Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
1.4 API-NG Reference Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
1.4.1 Betting API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
1.4.1.1 Betting on Australian Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
1.4.1.2 Betting On Italian Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
1.4.1.3 Betting Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
1.4.1.3.1 listCompetitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
1.4.1.3.2 listCountries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
1.4.1.3.3 listCurrentOrders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
1.4.1.3.4 listClearedOrders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
1.4.1.3.5 listEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
1.4.1.3.6 listEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
1.4.1.3.7 listMarketBook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
1.4.1.3.8 listMarketCatalogue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
1.4.1.3.9 listMarketProfitAndLoss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
1.4.1.3.10 listMarketTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
1.4.1.3.11 listTimeRanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
1.4.1.3.12 listVenues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
1.4.1.3.13 placeOrders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
1.4.1.3.14 cancelOrders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
1.4.1.3.15 replaceOrders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
1.4.1.3.16 updateOrders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
1.4.1.4 Betting Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
1.4.1.5 Betting Enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
1.4.1.6 Betting Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
1.4.2 Accounts API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
1.4.2.1 Accounts Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
1.4.2.1.1 createDeveloperAppKeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
1.4.2.1.2 getAccountDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
1.4.2.1.3 getAccountFunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
1.4.2.1.4 getDeveloperAppKeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
1.4.2.1.5 getAccountStatement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
1.4.2.1.6 listCurrencyRates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
1.4.2.2 Account Operations (Vendor API) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
1.4.2.2.1 activateApplicationSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
1.4.2.2.2 cancelApplicationSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
1.4.2.2.3 getApplicationSubscriptionHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
1.4.2.2.4 getApplicationSubscriptionToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
1.4.2.2.5 getVendorClientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
1.4.2.2.6 listAccountSubscriptionTokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
1.4.2.2.7 listApplicationSubscriptionTokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
1.4.2.3 Accounts Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
1.4.2.4 Accounts Enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
1.4.2.5 Accounts TypeDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
1.4.3 Vendor Services in API-NG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
1.4.4 Interface Definition Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
1.4.5 Heartbeat API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
1.4.6 Navigation Data For Applications (beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
1.5 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
1.5.1 Betfair Price Increments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
1.5.2 Currency Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
1.5.3 Racecourse Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
1.5.4 Runner Metadata Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
1.5.5 Time Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
1.5.6 Common Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
1.5.7 Virtual Bets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
1.6 Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
about an hour ago ( ) view change updated by Neil Thomas Interface Definition Documents
44 minutes ago ( ) view change updated by Neil Thomas Additional Information
API-NG Overview
API-NG is Betfair's next generation API for developers looking to create automated betting systems or custom
interfaces for themselves or for Betfair customers.
API-NG contains a powerful set of features that allow advanced market navigation, search, odds retrieval and bet
placement and is split into between three separate components:
Betting API - Contains navigation, odds retrieval and bet placement operations.
I Accounts AP - Contains account related operations such as the ability to retrieve your available account
balance.
Vendor API - available for who want to provide Betfair customers access to their licensed software vendors
certified software
Documentation
Please see the page for an introduction to the new Betting API Getting Started with API-NG
There is a to all of the API-NG operations. Reference Guide
Benefits & Features
The main benefits and features of the new API include:
Free access - Access to API-NG is free of charge* to all developers until at least 12th January 2015
No data request charges for requests made via API-NG.
Lightweight protocol (JSON/JSON-RPC).
Configure the depth of the best prices returned to you.
Rollup available prices - you can configure the rollup amount and type.
Retrieve data from multiple markets in one request.
Retrieve matched and unmatched bets and prices available via a single request.
Search by MarketType (MATCH_ODDS, WIN, PLACE etc.) flags which remain the same, regardless of
language.
Search for in-play markets.
View result by selection after settlement.
View virtual prices.
* does not apply to commercial access.
Please see for details of commercial licensing Commercial Opportunities

Recently Updated
Jul 15, 2014 ( ) view change updated by Neil Thomas New API-NG Release - 14th July 2014
Jul 17, 2014 ( ) view change updated by Neil Thomas Navigation Data For Applications (beta)
Jul 17, 2014 ( ) view change updated by Neil Thomas Getting Started with API-NG
Jul 17, 2014 ( ) view change updated by Neil Thomas Betting API
Jul 18, 2014 ( ) view change updated by Neil Thomas Runner Metadata Description
Jul 22, 2014 ( ) view change updated by Neil Thomas Betfair Price Increments
Jul 24, 2014 ( ) view change updated by Neil Thomas Keep Alive
Jul 24, 2014 ( ) view change updated by Neil Thomas Logout
about 8 hours ago ( ) view change updated by Neil Thomas Betting Type Definitions
about 8 hours ago ( ) view change updated by Neil Thomas Non-Interactive (bot) login
about an hour ago attached by Neil Thomas SportsAPING.xml
about an hour ago attached by Neil Thomas HeartbeatAPING.xml
about an hour ago attached by Neil Thomas AccountAPING.xml
1.
2.
3.
Navigate space

Getting Started with API-NG

This section contains information to help you get started with API-NG.
To use API-NG you require the following:
A . you can open a Betfair account Betfair account here
An - you can create an application by following the instructions Application Key here
A you can create a session token by using either of the methods or by sessionToken - API-NG login
following the instructions here
Making a Request to the API
All requests must include a HTTP header named containing the "X-Application" Applicati
assigned to you. on Key
All requests must include a HTTP header containing your "X-Authentication" sessionTok
en.
Please note: The only exceptions to the above are some of the ( Account Operations Vendor API
) which require the X-Authentication HTTP header only.
You can call the API at one of two endpoints, depending on which style of request you want to use.
JSON
You can POST a request to the API at:
https://api.betfair.com/exchange/betting/rest/v1.0/<operation name>. So, to call the listEventTypes method, you
would POST to: https://api.betfair.com/exchange/betting/rest/v1.0/listEventTypes/
The POST data contains the request parameters. For listEventTypes, the only required parameter is a filter to select
markets. You can pass an empty filter to select all markets, in which case listEventTypes returns the EventTypes
associated with all available markets.
JSON POST Data
{
"filter" : { }
}
Python Example JSON Request
import requests
import json
endpoint = "https://api.betfair.com/exchange/betting/rest/v1.0/"
header = { 'X-Application' : 'APP_KEY_HERE', 'X-Authentication' :
'SESSION_TOKEN_HERE' ,'content-type' : 'application/json' }
json_req='{"filter":{ }}'
url = endpoint + "listEventTypes/"
response = requests.post(url, data=json_req, headers=header)
print json.dumps(json.loads(response.text), indent=3)
JSON-RPC
You can POST a request to the API using at: JSON-RPC
https://api.betfair.com/exchange/betting/json-rpc/v1
The POST data should contain a valid JSON-RPC formatted request where the "params" field contains the request
parameters and the "method" field contains the API method you are calling, specified like
"SportsAPING/v1.0/<operation name>.
For example, if you were calling the operation and passing in a filter to find all markets with a listCompetitions
corresponding event type id of 1 (i.e., all Football markets), the POST data for the JSON-RPC endpoint would be:
Example JSON-RPC POST data
{
"params": {
"filter": {
"eventTypeIds": [1]
}
},
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listCompetitions",
"id": 1
}

Here's a quick example Python program that uses JSON-RPC and returns the list of EventTypes (Sports) available:
JSON-RPC Python Example
import requests
import json
url="https://api.betfair.com/exchange/betting/json-rpc/v1"
header = { 'X-Application' : 'APP_KEY_HERE', 'X-Authentication' : 'SESSION_TOKEN'
,'content-type' : 'application/json' }
jsonrpc_req='{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listEventTypes",
"params": {"filter":{ }}, "id": 1}'
response = requests.post(url, data=jsonrpc_req, headers=header)
print json.dumps(json.loads(response.text), indent=3)
And the response from the above:
EventTypeResult
{
"jsonrpc": "2.0",
"result": [
{
"eventType": {
"id": "468328",
"name": "Handball"
},
"marketCount": 59
},
{
"eventType": {
"id": "1",
"name": "Soccer"
},
"marketCount": 14792
},
{
"eventType": {
"id": "2",
"name": "Tennis"
},
"marketCount": 51
},
{
"eventType": {
"id": "3",
"name": "Golf"
},
"marketCount": 12
},
{
"eventType": {
"id": "4",
"name": "Cricket"
},
"marketCount": 139
},
{
"eventType": {
"id": "5",
"name": "Rugby Union"
},
"marketCount": 100
},
{
"eventType": {
"id": "6",
"name": "Boxing"
},
"marketCount": 12
},
{
"eventType": {
"id": "7",
"name": "Horse Racing"
},
"marketCount": 187
},
{
"eventType": {
"id": "8",
"name": "Motor Sport"
},
"marketCount": 3
},
{
"eventType": {
"id": "7524",
"name": "Ice Hockey"
},
"marketCount": 8
},
{
"eventType": {
"id": "10",
"name": "Special Bets"
},
"marketCount": 30
},
{
"eventType": {
"id": "451485",
"name": "Winter Sports"
},
"marketCount": 7
},
{
"eventType": {
"id": "7522",
"name": "Basketball"
},
"marketCount": 559
},
{
"eventType": {
"id": "1477",
"name": "Rugby League"
},
"marketCount": 3
},
{
"eventType": {
"id": "4339",
"name": "Greyhound Racing"
},
"marketCount": 269
},
{
"eventType": {
"id": "2378961",
"name": "Politics"
},
"marketCount": 19
},
{
"eventType": {
"id": "6231",
"name": "Financial Bets"
},
"marketCount": 51
},
{
"eventType": {
"id": "998917",
"name": "Volleyball"
},
"marketCount": 69
},
{
"eventType": {
"id": "998919",
"name": "Bandy"
},
"marketCount": 2
},
{
"eventType": {
"id": "998918",
"name": "Bowls"
},
"marketCount": 10
},
{
"eventType": {
"id": "3503",
"name": "Darts"
},
"marketCount": 446
},
{
"eventType": {
"id": "72382",
"name": "Pool"
},
"marketCount": 1
},
{
"eventType": {
"id": "6422",
"name": "Snooker"
},
"marketCount": 3
},
{
"eventType": {
"id": "6423",
"name": "American Football"
},
"marketCount": 86
},
{
"eventType": {
"id": "7511",
"name": "Baseball"
},
"marketCount": 1
}
1.
2.
3.
4.
5.
],
"id": 1
}
Application Keys
In order to use the Betting API, you need to have an Application Key. The Application Key identifies your API client.
Two App Keys are assigned to a single Betfair account, one App Key and one . live App Key delayed
You must pass the Application Key with every HTTP request. You do this by setting the HTTP header with the value
of the key assigned by Betfair.
X-Application: APP_KEY_ASSIGNED
How to Create An Application Key
You can create an Application Key for your Betfair account using the and Accounts API Visualiser createDeveloper
operation AppKeys
Click on the link. Accounts API Visualiser
Select the operation from the list of Operations on the top left hand side of the createDeveloperAppKeys
visualiser.
Enter a in the 'Session Token (ssoid)' text box. You can find instructions on how to find your sessionToken
sessionToken via your browser . here
Enter your e in the 'Request' column. Application Nam
Press at the bottom of the 'Request' column. Execute
Two Application Keys will then be created and displayed in the column of the Visualiser, one of Developer Apps
which will be a Delayed Application Key (see details below)
Please note: the X-Application header is not required when using the or the createDeveloperAppKeys getDevelo
service. perAppKeys
Delayed Application Keys
The service will assign two Application Keys (App Keys) to your Betfair account. createDeveloperAppKeys
One 'live' App Key and one 'delayed' App Key. A delayed App Key is displayed as 'Version 1.0-DELAY' via createDe
/ veloperAppKeys getDeveloperAppKeys
The delayed App Key returns data and to be performed delayed price does not allow betting transactions
( , ) Attempting to use these operations with a placeOrders replaceOrders,updateOrders,cancelOrders
delayed App Key will result in the PERMISSION_DENIED error.
The delayed App Key should be used for development and any functional testing that doesn't require the use
of live data and betting functionality.
The delayed App Key should also be used in simulation/practice applications where the facility to bet into live
Betfair markets is not available.
The delayed App Key does not return traded volume data 'EX_TRADED' via listMarketBook.
1.
2.
API-NG Login
API-NG offers 2 login flows for developers, depending on the use case of your
application:.
Non-Interactive login - if you are building an application which will run autonomously, there
is a separate login flow to follow to ensure your account remains secure.
Interactive login - if you are building an application which will be used interactively, then
this is the flow for you.This flow has two variants:
Interactive login - Embedded method - This login flow makes use of Betfair's login
pages and allows your app to gracefully handle all indirection points that can be
handled.
Interactive login - API method - This flow makes use of a JSON API Endpoint and
is the simplest way to get started.
If you're looking for the quickest way to get started, try the curl example in the Interactive login - API Method.
Non-Interactive (bot) login
The non-interactive login method for API-NG requires that you create and upload a self signed certificate which will
be used, alongside your username and password, to authenticate your credentials and generate a session token.
For the purposes of this guide, we have used openssl to generate this client, details of which can be found athttp://
www.openssl.org/
Getting Started
There are a couple of steps required before we can actually log in:
Create a self-signed certificate
Linking the certificate to your Betfair account
Creating a Self Signed Certificate
API-NG requires that a 1024-bit or 2048-bit RSA certificate be used. There are various tutorials available on the
Internet, but be aware that the certificate needs to be for client authentication (most tutorials only cover server
authentication).

Create a public/private RSA key pair using openssl

openssl genrsa -out client-2048.key 2048

Update or Create the openssl configuration file (openssl.cnf) for OpenSSL to override some of the default
settings:
[ ssl_client ]
basicConstraints = CA:FALSE
nsCertType = client
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth
In Windows, the config file is located in the installation directory of OpenSSL
In Linux distributions, the config file is located at /usr/lib/ssl/openssl.cnf or/etc/ssl/openssl.cnf
Create a certificate signing request (CSR).
openssl req -new -config openssl.cnf -key client-2048.key -out client-2048.csr
Country Name (2 letter code) [AU]:GB
State or Province Name (full name) [Some-State]:London
Locality Name (eg, city) []:London
Organization Name (eg, company) [Internet Widgits Pty Ltd]:yourcompany.com
Organizational Unit Name (eg, section) []:Security Team
Common Name (e.g. server FQDN or YOUR name) []:Test API-NG Certificate
Email Address []:[email protected]
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Self-sign the certificate request to create a certificate

openssl x509 -req -days 365 -in client-2048.csr -signkey client-2048.key -out
client-2048.crt -extfile openssl.cnf -extensions ssl_client
In Windows, using any text editor, copy the contents of the .crt file and the .key file into a new
file. Save this new file as client-2048.pem.
Linking the Certificate to Your Betfair Account
The previous steps should have created the following files:
File name Description
1.
2.
3.
4.
5.
1.
client-2048.key The private key. This file is needed in order to use the
certificate and should be protected and shouldnt be
shared with anyone.
client-2048.csr A certificate signing request. This file is no longer
needed and can be deleted.
client-2048.crt The certificate. This file is not sensitive in security
terms and can be shared with anyone.
Before you login using the certificate, it must be attached to your Betfair account, as follows:
Log in to your Betfair account through betfair.comPaste the following URL into the address bar of your
browser
https://myaccount.betfair.com/accountdetails/mysecurity?showAPI=1
Scroll to the section at the bottom, titled API-NG Configuration
Click on Browse and then locate and select the file client-2048.crt (client-2048.pem if applicable) created
above.
Click on the Upload Certificate button.
Scroll down to the API-NG Configuration section if required and the certificate details should be shown. You
should now be able to log in to your Betfair account using the API-NG endpoint.
Note on File Formats
Some systems require that client certificates are in a different format to the ones weve created. The two most
common formats are (a) PEM format key and certificate in a single file and (b) PKCS#12 format file.
To create a PEM format file that contains both the private key and the certificate you can use the following
command:
Linux
cat client-2048.crt client-2048.key > client-2048.pem
Create the PKCS#12 format using crt and key
openssl pkcs12 -export -in client-2048.crt -inkey client-2048.key -out
client-2048.p12
Don't circulate the key, PEM file or PCKS#12 format files as these files are security sensitive
Details of a Login Request
A login request can now be made as follows:
1.
2.
3.
4.
5.
Submit a HTTP POST request to: https://identitysso.betfair.com/api/certlogin
As part of the SSL connection, the certificate created previously must be supplied.
Include a custom Header called X-Application with a value that identifies your application. The value is not
validated and is only used to help with troubleshooting and diagnosing any problems.
Ensure the POSTs Content-Type is application/x-www-form-urlencoded rather than MIME attachment
encoded.
As part of the POST body include two parameters username and password which should have the
relevant username/password for your account.
Certificate Login Interface Details
URL Definition
Certificate Endpoint
https://identitysso.betfair.com/api/certlogin
This endpoint is also available under:
identitysso.betfair.com
identitysso.betfair.es
identitysso.betfair.it
identitysso.w-con.betfair.com
identitysso.betfaironline.eu
Request headers
X-Application - You must set the X-Application header to your application key.
Request Parameters
username (mandatory) - The username of the user logging in.
password (mandatory) - The password of the user logging in.
Please note: The username and password values should be encoded when making the login
request. All method names are case sensitive, this includes login, keepAlive and logout.
Response
The response returned is a json string. If the response is successful then the loginStatus key will contain SUCCESS,
for example:
{
sessionToken: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx;
loginStatus: SUCCESS;
}
Should a failure or exception be returned, the response will be structured as below and loginStatus will contain a
failure reason:
{
loginStatus: INVALID_USERNAME_OR_PASSWORD;
}
The possible failure and exceptional return codes are:
loginStatus
INVALID_USERNAME_OR_PASSWORD the username or password are invalid
ACCOUNT_NOW_LOCKED the account was just locked
ACCOUNT_ALREADY_LOCKED the account is already locked
PENDING_AUTH pending authentication
TELBET_TERMS_CONDITIONS_NA Telbet terms and conditions rejected
DUPLICATE_CARDS duplicate cards
SECURITY_QUESTION_WRONG_3X the user has entered wrong the security question 3
times
KYC_SUSPEND KYC suspended
SUSPENDED the account is suspended
CLOSED the account is closed
SELF_EXCLUDED the account has been self excluded
INVALID_CONNECTIVITY_TO_REGULATOR_DK the DK regulator cannot be accessed due to some
internal problems in the system behind or in at
regulator; timeout cases included.
NOT_AUTHORIZED_BY_REGULATOR_DK the user identified by the given credentials is not
authorized in the DK's jurisdictions due to the
regulators' policies. Ex: the user for which this session
should be created is not allowed to act(play, bet) in the
DK's jurisdiction.
INVALID_CONNECTIVITY_TO_REGULATOR_IT the IT regulator cannot be accessed due to some
internal problems in the system behind or in at
regulator; timeout cases included.
NOT_AUTHORIZED_BY_REGULATOR_IT the user identified by the given credentials is not
authorized in the IT's jurisdictions due to the regulators'
policies. Ex: the user for which this session should be
created is not allowed to act(play, bet) in the IT's
jurisdiction.
SECURITY_RESTRICTED_LOCATION the account is restricted due to security concerns
BETTING_RESTRICTED_LOCATION the account is accessed from a location where betting
is restricted
TRADING_MASTER Trading Master Account
TRADING_MASTER_SUSPENDED Suspended Trading Master Account
AGENT_CLIENT_MASTER Agent Client Master
AGENT_CLIENT_MASTER_SUSPENDED Suspended Agent Client Master
DANISH_AUTHORIZATION_REQUIRED Danish authorization required
SPAIN_MIGRATION_REQUIRED Spain migration required
DENMARK_MIGRATION_REQUIRED Denmark migration required
SPANISH_TERMS_ACCEPTANCE_REQUIRED The latest spanish terms and conditions version must
be accepted
ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED The latest Italian contract version must be accepted
CERT_AUTH_REQUIRED Certificate required or certificate present but could not
authenticate with it
CHANGE_PASSWORD_REQUIRED change password required
PERSONAL_MESSAGE_REQUIRED personal message required for the user

Sample curl command to quickly check the certificate based login

curl -q -k --cert client-2048.crt --key client-2048.key
https://identitysso.betfair.com/api/certlogin -d
"username=testuser&password=testpassword" -H "X-Application: curlCommandLineTest"
Response should be
{"sessionToken":"Zx8i4oigut5nc+l4L8qFb0DSxG+mwLn2t0AMGFxjrMJI=","loginStatus":"SUCCE
SS"}

Sample Java code using Apache http client library and PKCS#12 key store
Java API-NG login
package com.test.aping.client;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.conn.ClientConnectionManager;
import org.apache.http.conn.scheme.Scheme;
import org.apache.http.conn.ssl.SSLSocketFactory;
import org.apache.http.conn.ssl.StrictHostnameVerifier;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;
import javax.net.ssl.KeyManager;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.SSLContext;
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.security.KeyStore;
import java.security.SecureRandom;
import java.util.ArrayList;
import java.util.List;
public class HttpClientSSO {
private static int port = 443;
public static void main(String[] args) throws Exception {
DefaultHttpClient httpClient = new DefaultHttpClient();
try {
SSLContext ctx = SSLContext.getInstance("TLS");
KeyManager[] keyManagers = getKeyManagers("pkcs12", new
FileInputStream(new File("C:\\sslcerts\\client-2048.p12")), "password");
ctx.init(keyManagers, null, new SecureRandom());
SSLSocketFactory factory = new SSLSocketFactory(ctx, new
StrictHostnameVerifier());
ClientConnectionManager manager = httpClient.getConnectionManager();
manager.getSchemeRegistry().register(new Scheme("https", port,
factory));
HttpPost httpPost = new
HttpPost("https://identitysso.betfair.com/api/certlogin");
List<NameValuePair> nvps = new ArrayList<NameValuePair>();
nvps.add(new BasicNameValuePair("username", "testuser"));
nvps.add(new BasicNameValuePair("password", "testpassword"));
httpPost.setEntity(new UrlEncodedFormEntity(nvps));
httpPost.setHeader("X-Application","appkey");
System.out.println("executing request" + httpPost.getRequestLine());
HttpResponse response = httpClient.execute(httpPost);
HttpEntity entity = response.getEntity();
System.out.println("----------------------------------------");
System.out.println(response.getStatusLine());
if (entity != null) {
String responseString = EntityUtils.toString(entity);
//extract the session token from responsestring
System.out.println("responseString" + responseString);
}
} finally {
httpClient.getConnectionManager().shutdown();
}
}
private static KeyManager[] getKeyManagers(String keyStoreType, InputStream
keyStoreFile, String keyStorePassword) throws Exception {
KeyStore keyStore = KeyStore.getInstance(keyStoreType);
keyStore.load(keyStoreFile, keyStorePassword.toCharArray());
KeyManagerFactory kmf =
KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
kmf.init(keyStore, keyStorePassword.toCharArray());
1.
2.
3.
4.
return kmf.getKeyManagers();
}
}
Sample Python code
#!/usr/bin/env python
import requests
#openssl x509 -x509toreq -in certificate.crt -out CSR.csr -signkey privateKey.key
payload = 'username=myusername&password=password'
headers = {'X-Application': 'SomeKey', 'Content-Type':
'application/x-www-form-urlencoded'}
resp = requests.post('https://identitysso.betfair.com/api/certlogin', data=payload,
cert=('client-2048.crt', 'client-2048.key'), headers=headers)
if resp.status_code == 200:
resp_json = resp.json()
print resp_json['loginStatus']
print resp_json['sessionToken']
else:
print "Request failed."
Certificate Generation With XCA
If you aren't able (or willing) to setup openssl on your windows machine, there are various GUI wrappers around the
toolset which you might be able to use instead. XCA is an open source wrapper around the OpenSSL toolset which
allows you to create keys, csrs and certificates via a GUI and stores all of the generated items in a database file.
First you need to download XCA, which is an open source wrapper around the openssl toolset from:
http://sourceforge.net/projects/xca/
Step by Step Guide
Install XCA and run it.
Create a new Database,
Name it something sensible
Save it somewhere appropriate.
This proprietary database is useful for the xca tool only and helps you store your keys, csrs, and certificates, the
database file is not used in any part of the process with Betfair.
Equivalent Open SSL Command - Create a public/private RSA key pair using openssl
openssl genrsa -out client-2048.key 2048

Create a public/private RSA key pair using xca:

Equivalent Open SSL Command - Create a certificate signing request (CSR).

openssl req -new -config openssl.cnf -key client-2048.key -out client-2048.csr

Select the Certificate signing requests tab and click New Request
Select the CA template and click the button. Apply Extensions

Click on the tab and enter the name etc. Subject

The key that you generated in the first step must be selected (if the key doesn't appear, check the "Used keys
tool" box)

Click on the tab Extensions

Ensure that is selected as the type. Certification Authority
Click OK.
Equivalent Open SSL Command - Self-sign the certificate request to create a certificate
openssl x509 -req -days 365 -in client-2048.csr -signkey client-2048.key -out client-2048.crt -extfile openssl.cnf
-extensions ssl_client
We will now create and sign a certificate from the first two steps:
Click the Certificates Tab and click New Certificate
Click on the tab and enter the name etc. Subject
The key that you generated in the first step must be selected (if the key doesn't appear, check the "Used keys
tool" box)

Click on the tab and select the parameters shown below: Source

You should make sure that your CSR is selected but that Copy extensions from the request is unticked and
that you have selected the [default] HTTPS_client and pressed the Apply extensions button.
You can then press OK to create the self-signed certificate.
Next we need to export the key and the certificate for use in our application.
Export the private key and Certificate. These files should be used in the authentication process and should be
referred to in your code where the private key (the .pem file) and certificate file (the .crt file) are mentioned.
You can also export to other formats such as PKCS 12 depending upon the format expected by your
language/library of choice.
You should upload the .crt file exported to the My Security page on Betfair.com to allow this
certificate access to your account.
Interactive Login from a Desktop Application
Overview
Interactive login is to be used when the user is present to login (for example, 3rd Party Desktop Applications) and
will manage any additional information required at login depending upon a customer's account (such as 2 Factor
Authentication codes or National Identifiers).
This is achieved by embedding the Betfair IdentitySSO login page in your application and then obtaining a
successful session token upon login. The keep alive operation should be called within the 20 minute session expiry
time if the user is still actively using your application. The embedded login page initially looks like this:
The interactive login sequence looks like this:
Once a login has been successfully made, the javascript in the page will POST the session token to the URL
provided as a redirect URL. For a desktop application, this is not required to be a real page as the Desktop
application can intercept the POST request as it happens via the embedded browser container. A windows based
application can embed a Web Browser into the application and use the event to catch the post BeforeNavigate2
data sent to the redirect URL and there are platform specific alternatives. The POST request body will contain two
URL encoded parameters (which you will need to URL Decode):
- A code which will either be 'SUCCESS' or an error code from the table below. loginStatus
productToken - This is your session token and should be attached to requests made to API-NG in the
X-Authentication header.
This flow protects the implementing application from user login complexities, such as 2 factor
auth, requiring national identifiers or jurisdictional migrations.

Interactive Login White-listing

Use of the Interactive Login requires your App Key to be white-listed. To get your App Key
white-listed you should raise a Support Ticket via Support > Create A Support Ticket and provide
details of your intended use of the interactive login (i.e. whether this is for personal use or for an
application that you intend to distribute to Betfair customers).
loginStatus
ACCOUNT_ALREADY_LOCKED the account is already locked
ACCOUNT_NOW_LOCKED the account was just locked
AGENT_CLIENT_MASTER Agent Client Master
AGENT_CLIENT_MASTER_SUSPENDED Suspended Agent Client Master
BETTING_RESTRICTED_LOCATION the account is accessed from a location where betting
is restricted
CERT_AUTH_REQUIRED Certificate required or certificate present but could not
authenticate with it
CHANGE_PASSWORD_REQUIRED change password required
CLOSED the account is closed
DANISH_AUTHORIZATION_REQUIRED danish authorization required
DENMARK_MIGRATION_REQUIRED denmark migration required
DUPLICATE_CARDS duplicate cards
INVALID_CONNECTIVITY_TO_REGULATOR_DK the DK regulator cannot be accessed due to some
internal problems in the system behind or in at
regulator; timeout cases included.
INVALID_CONNECTIVITY_TO_REGULATOR_IT the IT regulator cannot be accessed due to some
internal problems in the system behind or in at
regulator; timeout cases included.
INVALID_USERNAME_OR_PASSWORD the username or password are invalid
ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED The latest italian contract version must be accepted
KYC_SUSPEND KYC suspended
NOT_AUTHORIZED_BY_REGULATOR_DK the user identified by the given credentials is not
authorized in the DK's jurisdictions due to the
regulators' policies. Ex: the user for which this session
should be created is not allowed to act(play, bet) in the
DK's jurisdiction.
NOT_AUTHORIZED_BY_REGULATOR_IT the user identified by the given credentials is not
authorized in the IT's jurisdictions due to the regulators'
policies. Ex: the user for which this session should be
created is not allowed to act(play, bet) in the IT's
jurisdiction.
PENDING_AUTH pending authentication
PERSONAL_MESSAGE_REQUIRED personal message required for the user
SECURITY_QUESTION_WRONG_3X the user has entered wrong the security question 3
times
SECURITY_RESTRICTED_LOCATION the account is restricted due to security concerns
SELF_EXCLUDED the account has been self excluded
SPAIN_MIGRATION_REQUIRED spain migration required
SPANISH_TERMS_ACCEPTANCE_REQUIRED The latest spanish terms and conditions version must
be accepted
SUSPENDED the account is suspended
TELBET_TERMS_CONDITIONS_NA Telbet terms and conditions rejected
TRADING_MASTER Trading Master Account
TRADING_MASTER_SUSPENDED Suspended Trading Master Account

Interface
Login
URL definition
International users:
Spanish jurisdiction users:
Italian jurisdiction users:

https:// <theProductDescriptor>&url=<theRedirectUrl> identitysso.betfair.com/view/login?product=

https:// <theProductDescriptor>&url=<theRedirectUrl> identitysso.betfair.es/view/login?product=

https:// <theProductDescriptor>&url=<theRedirectUrl> identitysso.betfair.it/view/login?product=

Please note that all method names are case
sensitive, this includes login, keepAlive and
logout.

Parameters
Name Description Sample
product(mandatory) The product for which the login
page is used and on which the user
will do the login; This should be
your application key.
"IhDSui3ODdsdwo"
url(mandatory) The url to which the the browser
should be redirected in case of a
successful login.
By default, https://www.betfair.com
will be allowed but further URLs can
be added upon agreement with
Betfair.
https://www.betfair.com
Interactive Login - API Endpoint
Overview and limitations
The API login endpoint is the simplest method of integration for most applications in terms of development time
expected to be required, but comes at the cost of being less flexible to edge cases than the embedded Betfair
. It will allow a user to provide a username and password or a username and (password + 2 embedded login page
factor auth code) if they have strong authentication enabled.
Customers who writing bots are for their own use are to use the strongly recommended non-interactive
with an SSL certificate. endpoint
We that which will be exposed to a wide range of users use the recommend 3rd party applications
Interactive login method of embedding the as this will allow your application to Betfair embedded login page
handle additional workflows, such as terms and conditions updates as well as additional jurisdictional specific
identifiers.
The and methods remain the same with this method of login. Keep alive logout

Endpoint
API Login Endpoint
https://identitysso.betfair.com/api/login
The presence of the "Accept: application/json" will signal SSO that it should responde with JSON and not with a
HTML page.

Parameters (POST)
Name Description Sample
username(mandatory) The username to be used for the
login

password(mandatory) The password to be used for the

login. For strong auth customers,
this should be their password with a
2 factor auth code appended to the
password string.

Headers
Name Description Sample
Accept(mandatory) Signals that the response should be
returned as JSON
application/json
X-Application(mandatory) AppKey used by the customer to
identify the product.

Response structure

Error values (mappings for statuses to possible error values LIMITED_ACCESS / LOGIN_RESTRICTED / FAIL)
Business error codes:
LIMITED_ACCESS - Access is limited (eg. accounts that can login but can't bet), product session will be provided:

{
"token":"<token_passed_as_header>",
"product":"product_passed_as_header",
"status":"<status>",
"error":"<error>"
}
Status values

SUCCESS
LIMITED_ACCESS
LOGIN_RESTRICTED
FAIL

LOGIN_RESTRICTED - Login is restricted (in case of indirection point this is what will be returned), product session
will not be provided:
FAIL - All other cases are treeted as errors, product session will not be provided:
{
"token": product_token,
"product": product,
"status": LIMITED_ACCESS,
"error": error
}

error = {PENDING_AUTH | SECURITY_QUESTION_WRONG_3X | KYC_SUSPEND | SUSPENDED}

{
"token": "",
"product": product,
"status": LOGIN_RESTRICTED,
"error": error
}

error = {STRONG_AUTH_CODE_REQUIRED | DENMARK_MIGRATION_REQUIRED | DANISH_AUTHORIZATION_REQUIRED
| SPAIN_MIGRATION_REQUIRED | SPANISH_TERMS_ACCEPTANCE_REQUIRED | ITALY_MIGRATION_REQUIRED |
ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED | CHANGE_PASSWORD_REQUIRED | PERSONAL_MESSAGE_REQUIRED}

{
"token": "",
"product": product,
"status": FAIL,
"error": error
}

error = {TRADING_MASTER | TRADING_MASTER_SUSPENDED | AGENT_CLIENT_MASTER |
AGENT_CLIENT_MASTER_SUSPENDED | DENMARK_MIGRATION_REQUIRED | INVALID_PIN |
INVALID_USERNAME_OR_PASSWORD | PIN_DELETED_ON_FAILED_COUNT_EXCEEDED | UNRECOGNIZED_DEVICE |
DUPLICATE_CARDS | ACCOUNT_NOW_LOCKED | ACCOUNT_ALREADY_LOCKED | SECURITY_RESTRICTED_LOCATION |
BETTING_RESTRICTED_LOCATION | INVALID_CONNECTIVITY_TO_REGULATOR |
INVALID_CONNECTIVITY_TO_REGULATOR | INVALID_CONNECTIVITY_TO_REGULATOR_IT |
INVALID_CONNECTIVITY_TO_REGULATOR_DK| NOT_AUTHORIZED_BY_REGULATOR | NOT_AUTHORIZED_BY_REGULATOR
| NOT_AUTHORIZED_BY_REGULATOR_DK | NOT_AUTHORIZED_BY_REGULATOR_IT | TELBET_TERMS_CONDITIONS_NA
| CLOSED | SELF_EXCLUDED | NOT_AUTHORIZED_FOR_DOMAIN_ES | NOT_AUTHORIZED_FOR_DOMAIN_IT |
NOT_AUTHORIZED_FOR_DOMAIN_COM | AUTHORIZED_ONLY_FOR_DOMAIN_ES}

Please note that master account access is restricted for API/JSON requests.
Curl call sample
Example of a successful login:

{
"token": "",
"product": "APP_KEY",
"status": FAIL,
"error": error
}

error = {INPUT_VALIDATION_ERROR | FORBIDDEN | INVALID_USERNAME_OR_PASSWORD | NO_SESSION |
INVALID_PIN | INVALID_PIN_LOGIN_REQUEST | INVALID_PIN_LOGIN_REQUEST}

curl -k -i -H "Accept: application/json" -H "X-Application: <AppKey>" -X POST -d

'username=<username>&password=<password>' https://identitysso.betfair.com/api/login

curl -k -i -H "Accept: application/json" -H "X-Application: <AppKey>" -X POST -d

'username=<username>&password=<password>' https://identitysso.betfair.com/api/login

{
"token":"SESSION_TOKEN",
"product":"APP_KEY",
"status":"SUCCESS",
"error":""
}

The possible failure and exceptional return codes are:

loginStatus Description
TRADING_MASTER_SUSPENDE
D
Suspended Trading
Master Account
TRADING_MASTER Trading Master Account
TELBET_TERMS_CONDITIONS
_NA
Telbet terms and
conditions rejected
SUSPENDED the account is
suspended
SPANISH_TERMS_ACCEPTANC
E_REQUIRED
The latest spanish
terms and conditions
version must be
accepted
SPAIN_MIGRATION_REQUIRE
D
Spain migration
required
SELF_EXCLUDED the account has been
self excluded
SECURITY_RESTRICTED_LOC
ATION
the account is
restricted due to
security concerns
SECURITY_QUESTION_WRONG
_3X
the user has entered
wrong the security
question 3 times
PERSONAL_MESSAGE_REQUIR
ED
personal message
required for the user
PENDING_AUTH pending authentication
NOT_AUTHORIZED_BY_REGUL
ATOR_IT
the user identified by
the given credentials
is not authorized in
the IT's jurisdictions
due to the regulators'
policies. Ex: the user
for which this session
should be created is
not allowed to
act(play, bet) in the
IT's jurisdiction.
NOT_AUTHORIZED_BY_REGUL
ATOR_DK
the user identified by
the given credentials
is not authorized in
the DK's jurisdictions
due to the regulators'
policies. Ex: the user
for which this session
should be created is
not allowed to
act(play, bet) in the
DK's jurisdiction.
KYC_SUSPEND KYC suspended
ITALIAN_CONTRACT_ACCEPT
ANCE_REQUIRED
The latest Italian
contract version must
be accepted
INVALID_USERNAME_OR_PAS
SWORD
the username or
password are invalid
INVALID_CONNECTIVITY_TO
_REGULATOR_IT
the IT regulator
cannot be accessed due
to some internal
problems in the system
behind or in at
regulator; timeout
cases included.
INVALID_CONNECTIVITY_TO
_REGULATOR_DK
the DK regulator cannot
be accessed due to some
internal problems in
the system behind or in
at regulator; timeout
cases included.
DUPLICATE_CARDS duplicate cards
Login FAQs
When should I use the non-interactive login?
You should use the non-interactive login when the user will not be present to log into the application themselves. An
example of this are automated bots that might need to login without the user triggering a login. 3 Party interfaces to
rd
Betfair, used by multiple users, and which act as a direct proxy of a user request should use the interactive login
instead.
Why is the redirect URL required for the interactive login?
DENMARK_MIGRATION_REQUI
RED
Denmark migration
required
DANISH_AUTHORIZATION_RE
QUIRED
Danish authorization
required
CLOSED the account is closed
CHANGE_PASSWORD_REQUIRE
D
change password
required
CERT_AUTH_REQUIRED Certificate required
or certificate present
but could not
authenticate with it
BETTING_RESTRICTED_LOCA
TION
the account is
accessed from a
location where betting
is restricted
AGENT_CLIENT_MASTER_SUS
PENDED
Suspended Agent Client
Master
AGENT_CLIENT_MASTER Agent Client Master
ACCOUNT_NOW_LOCKED the account was just
locked
ACCOUNT_ALREADY_LOCKED

the account is already

locked

The redirect URL is required in order to post the session token to the application at the end of the login process.
This is required to be a URL which is white-listed by Betfair although additional https based URLs can be added with
approval.
? Why isnt there a non-interactive endpoint that accepts only a username and a password
Betfair take user security very seriously and have made many recent enhancements to the login process alongside
additional changes which have been made at the request of some of our regulators. This means that you cannot rely
upon a username and password being the only pieces of information that may be required at login. Some examples
of workflows currently in use are 2 factor authorisation codes, Additional National Identifiers for a region or requests
for additional account information or account migration.
? Why does my session time out, even though Ive been retrieving prices
For security reasons, we require that the application using the API explicitly calls the keep-alive operation no more
than once every 7 minutes in a response to user activity. In the case of non-interactive applications, these should
call the keep-alive operation every 7 minutes whilst they are active.
Why is the certificate upload form in the My Security page not visible by default?
We plan to make this visible by default in the near future.
Why is my interactive login/logout request failing with errorCode=FORBIDDEN?
Your Application Key App Key & redirect URL has not yet been white-listed by Betfair. To get your App Key
white-listed you should raise a Support Ticket via Support > Create A Support Ticket and provide details of your
intended use of the interactive login (i.e. whether this is for personal use or for an application that you intend to
distribute to Betfair customers).

Keep Alive
You can use Keep Alive to extend the session timeout period. The minimum session time is
currently 20 minutes (Italian Exchange). On the international (.com) Exchange the current
session time is 12 hours.. Therefore, you should request Keep Alive within this time to prevent
session expiry. If you don't call Keep Alive within the specified timeout period, the session will
expire. Session times aren't determined or extended based on API activity.
URL Definition
https://identitysso.betfair.com/api/keepAlive

The presence of the "Accept: application/json" header will signal that the service should respond with JSON and not
an HTML page
Headers

Name Description Sample

Accept (mandatory) Header that signals that the
response should be returned as
JSON
application/json
X-Authentication (mandatory) Header that represents the session
token that needs to be keep alive
Session Token
X-Application (optional) Header the Application Key used by
the customer to identify the product.
App Key

Response structure

Status values
{
"token":"<token_passed_as_header>",
"product":"product_passed_as_header",
"status":"<status>",
"error":"<error>"
}

SUCCESS
FAIL

Error values

INPUT_VALIDATION_ERROR
INTERNAL_ERROR
NO_SESSION

Call sample
Keep Alive success:
Logout
You can use Logout to terminate your existing session.
URL Definition
https://identitysso.betfair.com/api/logout
The presence of the "Accept: application/json" header will signal that the service should respond with JSON and not
an HTML page
Headers

# full request
curl -k -i -H "Accept: application/json" -H "X
-Application: AppKey" -H "X-Authentication:
<token>" https://identitysso.betfair.com/api/k
eepAlive

curl -k -i -H "Accept: application/json" -H "X

-Application: AppKey" -H "X-Authentication:
SESSIONTOKEN" https://identitysso.betfair.com/
api/keepAlive

{
"token":"SESSIONTOKEN",
"product":"AppKey",
"status":"SUCCESS",
"error":""
}

Name Description Sample

Accept (mandatory) Header that signals that the
response should be returned as
JSON
application/json
X-Authentication (mandatory) Header that represents the session
token created at login.
Session Token
X-Application (optional) Header the Application Key used by
the customer to identify the product.
App Key

Response structure
Error values

Status values
{
"token":"<token_passed_as_header>",
"product":"product_passed_as_header",
"status":"<status>",
"error":"<error>"
}

SUCCESS
FAIL

Call sample
API-NG - Visualiser
Visualisers
Visualiser tools are available for the new Betfair API (API-NG) for both the Betting and Accounts API.
You can access the tools via the following links:
Betting API - https://developer.betfair.com/visualisers/api-ng-sports-operations/
Accounts API - https://developer.betfair.com/visualisers/api-ng-account-operations/
Heartbeat API -https://developer.betfair.com//visualisers/api-ng-heartbeat-operations/
This visualiser is used by the API developers to allow quick experimentation with the API. As new features become
available in API-NG, our aim is to extend the visualiser to support these new features to help with rapid adoption of
the added functionality.
INPUT_VALIDATION_ERROR
INTERNAL_ERROR
NO_SESSION

# full request
curl -k -i -H "Accept: application/json" -H "X
-Application: AppKey" -H "X-Authentication:
<token>" https://identitysso.betfair.com/api/l
ogout
Please note that the visualiser's are provided as-is, and is intended solely as a testing
resource.
There are a number of useful features to the visualiser:
All existing API-NG operations are available
You can easily experiment with the parameters for your query.
You can build sample requests and interact with the API directly (requests and responses are
output to the JavaScript debug console) see attached. For example, using Google Chrome ,you
can open the Javascript console using the shortcut . The same shortcut can also be Ctrl+Shift+J
used with Mozilla Firefox.
Obtaining a session token for the visualiser
There are several ways that you can obtain a session token for the visualiser:
1. Borrowing a website session ssoid cookie
a. Visit in your browser and log into the website as you would to use the website. http://www.betfair.com
Please note that for other regions, please substitute betfair.com with your equivalent domain. e.g. betfair.it or
betfair.es.
b. Once logged in, retrieve the value of the ssoid cookie using the method for your browser:
Google Chrome:
Visit and search for betfair.com. There should be a large number of cookies for chrome://settings/cookies
betfair.com, select the "ssoid" cookie and copy the conte, which is your session token.
Mozilla Firefox:
Right click to the left of the betfair.com header logo on the betfair.com page and select "View Page Info" from the
context menu. Then select the "Security" tab, then select "View Cookies". You can sort this list alphabetically by
clicking on the Cookie Name header. You can view the content of the "ssoid" cookie, this is your session token.
Internet Explorer:
Paste the following into the browser url bar when you have logged into the Betfair site and have the Betfair page
open:javascript:alert(document.cookie)
Copy the contents of the box with CTRL+C and then paste into an editor with CTRL+V. Look for the
ssoid=SOME_VALUE; definition. The session token is the token between "ssoid=" and ";" and does not include the
equals sign immediately after ssoid or the semi-colon at the end.
Other Browsers:
Please search for the specific instructions for viewing the cookies of your browser on the internet. The Session token
is always under the betfair.com domain (or your regional equivalent) and is named ssoid.
2. Using the API-NG Interactive login sample
If you already have an application key, downloadSampleAPI.exe, which is a compiled version of the sample
interactive login code which is described in the documentation , with the source from the here API-NG Sample code
. github repo
Enter your application key and follow the login instructions, your session token with be extracted from your session
and presented to you via the application.
Example Requests
This section shows how you might call the Betting API to retrieve information.
This section includes examples of how to request the following information:
Request a List Of Available Event Types
Request a List of Events for an Event Type
Request the Market Information for an Event
Football Competitions
List Football Markets 'In-Play Now'
Horse Racing - Today's Win & Place Markets
Market Prices
Placing a Bet
Placing a SP Bet
Retrieving the Result of a Settled Market
Request A List Of Available Event Types
You can make a request using the service which will return a response containing the eventTypes listEventTypes
(e.g. Soccer, Horse Racing etc.) that are currently available on Betfair.
listEventTypes Request
[
{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listEventTypes",
"params": {
"filter": {}
},
"id": 1
}
]
listEventTypes Response
[
{
"jsonrpc": "2.0",
"result": [
{
"eventType": {
"id": "468328",
"name": "Handball"
},
"marketCount": 11
},
{
"eventType": {
"id": "1",
"name": "Soccer"
},
"marketCount": 25388
},
{
"eventType": {
"id": "2",
"name": "Tennis"
},
"marketCount": 402
},
{
"eventType": {
"id": "3",
"name": "Golf"
},
"marketCount": 79
},
{
"eventType": {
"id": "4",
"name": "Cricket"
},
"marketCount": 192
},
{
"eventType": {
"id": "5",
"name": "Rugby Union"
},
"marketCount": 233
},
{
"eventType": {
"id": "6",
"name": "Boxing"
},
"marketCount": 18
},
{
"eventType": {
"id": "7",
"name": "Horse Racing"
},
"marketCount": 398
},
{
"eventType": {
"id": "8",
"name": "Motor Sport"
},
"marketCount": 50
},
{
"eventType": {
"id": "7524",
"name": "Ice Hockey"
},
"marketCount": 521
},
{
"eventType": {
"id": "10",
"name": "Special Bets"
},
"marketCount": 39
},
{
"eventType": {
"id": "451485",
"name": "Winter Sports"
},
"marketCount": 7
},
{
"eventType": {
"id": "11",
"name": "Cycling"
},
"marketCount": 1
},
{
"eventType": {
"id": "136332",
"name": "Chess"
},
"marketCount": 1
},
{
"eventType": {
"id": "7522",
"name": "Basketball"
},
"marketCount": 617
},
{
"eventType": {
"id": "1477",
"name": "Rugby League"
},
"marketCount": 91
},
{
"eventType": {
"id": "4339",
"name": "Greyhound Racing"
},
"marketCount": 298
},
{
"eventType": {
"id": "6231",
"name": "Financial Bets"
},
"marketCount": 44
},
{
"eventType": {
"id": "2378961",
"name": "Politics"
},
"marketCount": 23
},
{
"eventType": {
"id": "998917",
"name": "Volleyball"
},
"marketCount": 66
},
{
"eventType": {
"id": "998919",
"name": "Bandy"
},
"marketCount": 4
},
{
"eventType": {
"id": "998918",
"name": "Bowls"
},
"marketCount": 17
},
{
"eventType": {
"id": "26420387",
"name": "Mixed Martial Arts"
},
"marketCount": 52
},
{
"eventType": {
"id": "3503",
"name": "Darts"
},
"marketCount": 21
},
{
"eventType": {
"id": "2152880",
"name": "Gaelic Games"
},
"marketCount": 2
},
{
"eventType": {
"id": "6422",
"name": "Snooker"
},
"marketCount": 22
},
{
"eventType": {
"id": "6423",
"name": "American Football"
},
"marketCount": 171
},
{
"eventType": {
"id": "315220",
"name": "Poker"
},
"marketCount": 2
},
{
"eventType": {
"id": "7511",
"name": "Baseball"
},
"marketCount": 7
}
],
"id": 1
}
]
Request a List of Events for an Event Type
The below example demonstrates how to retrieve a list of events (eventIds) for a specific event type. The request
shows how to retrieve all Soccer events that are taking place in a single day.
listEvents Request
[
{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listEvents",
"params": {
"filter": {
"eventTypeIds": [
"1"
],
"marketStartTime": {
"from": "2014-03-13T00:00:00Z",
"to": "2014-03-13T23:59:00Z"
}
}
},
"id": 1
}
]
listEvents Response
[
{
"jsonrpc": "2.0",
"result": [
{
"event": {
"id": "27165668",
"name": "Al-Wahda (KSA) v Hajer (KSA)",
"countryCode": "SA",
"timezone": "GMT",
"openDate": "2014-03-13T13:30:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165665",
"name": "Al Hussein v Mansheyat Bani Hasan",
"countryCode": "JO",
"timezone": "GMT",
"openDate": "2014-03-13T15:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165425",
"name": "Daily Goals",
"countryCode": "GB",
"timezone": "Europe/London",
"openDate": "2014-03-13T18:00:00.000Z"
},
"marketCount": 1
},
{
"event": {
"id": "27165667",
"name": "Al Jeel v Al Draih",
"countryCode": "SA",
"timezone": "GMT",
"openDate": "2014-03-13T12:45:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165677",
"name": "Daventry Town v Kettering",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T19:45:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27160160",
"name": "Porto v Napoli",
"countryCode": "PT",
"timezone": "GMT",
"openDate": "2014-03-13T18:00:00.000Z"
},
"marketCount": 84
},
{
"event": {
"id": "27162435",
"name": "Bishops Stortford v Hayes And Yeading",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T19:45:00.000Z"
},
"marketCount": 2
},
{
"event": {
"id": "27166333",
"name": "Bosnia U19 v Serbia U19",
"timezone": "GMT",
"openDate": "2014-03-13T12:30:00.000Z"
},
"marketCount": 25
},
{
"event": {
"id": "27162436",
"name": "Maidenhead v Gosport Borough",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T19:45:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165673",
"name": "ASA Tel Aviv Uni (W) v FC Ramat Hasharon (W)",
"countryCode": "IL",
"timezone": "GMT",
"openDate": "2014-03-13T17:15:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27164435",
"name": "Forest Green v Braintree",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T19:45:00.000Z"
},
"marketCount": 15
},
{
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165684",
"name": "FC Lokomotivi Tbilisi v FC Saburtalo Tbilisi",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165686",
"name": "FC Sasco Tbilisi v Matchak Khelvachauri",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
},
"marketCount": 18
},
{
"event": {
"id": "27165680",
"name": "FAR Rabat v Maghreb Fes",
"countryCode": "MA",
"timezone": "GMT",
"openDate": "2014-03-13T15:30:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165683",
"name": "FC Kolkheti Khobi v Samgurali Tskaltubo",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165682",
"name": "FC Dila Gori II v FC Dinamo Batumi",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165693",
"name": "Tilbury FC v Redbridge",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T19:45:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165688",
"name": "HUJK Emmaste v Kohtla-Jarve JK Jarve",
"countryCode": "EE",
"timezone": "GMT",
"openDate": "2014-03-13T17:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165690",
"name": "M Kishronot Hadera (W) v Maccabi Holon FC (W)",
"countryCode": "IL",
"timezone": "GMT",
"openDate": "2014-03-13T17:30:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27166225",
"name": "Litex Lovech v Cherno More",
"countryCode": "BG",
"timezone": "GMT",
"openDate": "2014-03-13T15:30:00.000Z"
},
"marketCount": 27
},
{
"event": {
"id": "27162412",
"name": "KR Reykjavik v IA Akranes",
"countryCode": "IS",
"timezone": "GMT",
"openDate": "2014-03-13T19:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27162473",
"name": "Atletico Huila v Tolima",
"countryCode": "CO",
"timezone": "GMT",
"openDate": "2014-03-13T23:00:00.000Z"
},
"marketCount": 27
},
{
"event": {
"id": "27162413",
"name": "KV v Selfoss",
"countryCode": "IS",
"timezone": "GMT",
"openDate": "2014-03-13T21:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165159",
"name": "August Town FC v Boys Town FC",
"countryCode": "JM",
"timezone": "GMT",
"openDate": "2014-03-13T20:30:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27165161",
"name": "Bogota v CD Barranquilla",
"countryCode": "CO",
"timezone": "GMT",
"openDate": "2014-03-13T20:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27166474",
"name": "Brasilia FC v Formosa",
"countryCode": "BR",
"timezone": "GMT",
"openDate": "2014-03-13T19:00:00.000Z"
},
"marketCount": 15
},
{
"event": {
"id": "27162538",
"name": "Arsenal FC v Penarol",
"countryCode": "AR",
"timezone": "GMT",
"openDate": "2014-03-13T22:00:00.000Z"
},
"marketCount": 40
},
{
"event": {
"id": "27166478",
"name": "Ware FC v AFC Sudbury",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T19:45:00.000Z"
},
"marketCount": 15
},
{
"event": {
"id": "27165505",
"name": "Tomsk v Tyumen",
"countryCode": "RU",
"timezone": "GMT",
"openDate": "2014-03-13T11:30:00.000Z"
},
"marketCount": 28
},
{
"event": {
"id": "27166477",
"name": "Needham Market FC v Thurrock",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T19:45:00.000Z"
},
"marketCount": 15
},
{
"event": {
"id": "27160154",
"name": "Lyon v Plzen",
"countryCode": "FR",
"timezone": "GMT",
"openDate": "2014-03-13T20:05:00.000Z"
},
"marketCount": 41
},
{
"event": {
"id": "27160155",
"name": "Ludogorets v Valencia",
"countryCode": "BG",
"timezone": "GMT",
"openDate": "2014-03-13T18:00:00.000Z"
},
"marketCount": 84
},
{
"event": {
"id": "27160152",
"name": "Tottenham v Benfica",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T20:05:00.000Z"
},
"marketCount": 84
},
{
"event": {
"id": "27162428",
"name": "Wadi Degla v El Shorta",
"countryCode": "EG",
"timezone": "GMT",
"openDate": "2014-03-13T13:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27160158",
"name": "FC Basel v Red Bull Salzburg",
"countryCode": "CH",
"timezone": "GMT",
"openDate": "2014-03-13T18:00:00.000Z"
},
"marketCount": 84
},
{
"event": {
"id": "27162427",
"name": "Ismaily v El Qanah",
"countryCode": "EG",
"timezone": "GMT",
"openDate": "2014-03-13T13:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27160159",
"name": "AZ Alkmaar v Anzhi Makhachkala",
"countryCode": "NL",
"timezone": "GMT",
"openDate": "2014-03-13T20:05:00.000Z"
},
"marketCount": 41
},
{
"event": {
"id": "27162426",
"name": "Al Ahly v El Entag El Harby",
"countryCode": "EG",
"timezone": "GMT",
"openDate": "2014-03-13T15:30:00.000Z"
},
"marketCount": 15
},
{
"event": {
"id": "27160156",
"name": "Sevilla v Betis",
"countryCode": "ES",
"timezone": "GMT",
"openDate": "2014-03-13T20:05:00.000Z"
},
"marketCount": 84
},
{
"event": {
"id": "27160157",
"name": "Juventus v Fiorentina",
"countryCode": "IT",
"timezone": "GMT",
"openDate": "2014-03-13T20:05:00.000Z"
},
"marketCount": 84
},
{
"event": {
"id": "27166336",
"name": "Becamex Binh Duong U19 v Khanh Hoa U19",
"countryCode": "VN",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
},
"marketCount": 15
},
{
"event": {
"id": "27163800",
"name": "Lokomotiv Sofia v Chernomorets Burgas",
"countryCode": "BG",
"timezone": "GMT",
"openDate": "2014-03-13T12:00:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27162481",
"name": "Ljungskile v Torslanda",
"countryCode": "SE",
"timezone": "GMT",
"openDate": "2014-03-13T18:00:00.000Z"
},
"marketCount": 27
},
{
"event": {
"id": "27166338",
"name": "H Ironi Petah Tikva (W) v Maccabi Beer Sheva (W)",
"countryCode": "IL",
"timezone": "GMT",
"openDate": "2014-03-13T18:15:00.000Z"
},
"marketCount": 15
},
{
"event": {
"id": "27163801",
"name": "Concord Rangers v Havant and W",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2014-03-13T19:45:00.000Z"
},
"marketCount": 2
},
{
"event": {
"id": "27166340",
"name": "Maccabi Ironi Bat Yam v Hapoel Mahane Yehuda",
"countryCode": "IL",
"timezone": "GMT",
"openDate": "2014-03-13T17:00:00.000Z"
},
"marketCount": 15
},
{
"event": {
"id": "27162418",
"name": "Courts Young Lions v Woodlands Wellington",
"countryCode": "SG",
"timezone": "GMT",
"openDate": "2014-03-13T11:30:00.000Z"
},
"marketCount": 20
},
{
"event": {
"id": "27162417",
"name": "Balestier Khalsa v Tanjong Pagar Utd",
"countryCode": "SG",
"timezone": "GMT",
"openDate": "2014-03-13T11:30:00.000Z"
},
"marketCount": 20
}
],
"id": 1
}
]
Request the Market Information for an Event
The below example demonstrates how to retrieve all the market information that belongs to an event (excluding
price data) . You can include one or more eventId's in the requests provide that you stay within the Market Data
Limits
listMarketCatalogue Request
[
{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listMarketCatalogue",
"params": {
"filter": {
"eventIds": [
"27165685"
]
},
"maxResults": "200",
"marketProjection": [
"COMPETITION",
"EVENT",
"EVENT_TYPE",
"RUNNER_DESCRIPTION",
"RUNNER_METADATA",
"MARKET_START_TIME"
]
},
"id": 1
}
]
listMarketCatalogue Response
[
{
"jsonrpc": "2.0",
"result": [
{
"marketId": "1.113197547",
"marketName": "FC Betlemi Keda +1",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 12,
"runners": [
{
"selectionId": 6843871,
"runnerName": "FC Betlemi Keda +1",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123618"
}
},
{
"selectionId": 6830600,
"runnerName": "FC Samtredia -1",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123619"
}
},
{
"selectionId": 151478,
"runnerName": "Draw",
"handicap": 0,
"sortPriority": 3,
"metadata": {
"runnerId": "63123620"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197546",
"marketName": "FC Samtredia +1",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 0,
"runners": [
{
"selectionId": 6830597,
"runnerName": "FC Samtredia +1",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123615"
}
},
{
"selectionId": 6843874,
"runnerName": "FC Betlemi Keda -1",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123616"
}
},
{
"selectionId": 151478,
"runnerName": "Draw",
"handicap": 0,
"sortPriority": 3,
"metadata": {
"runnerId": "63123617"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197492",
"marketName": "Total Goals",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 246.82,
"runners": [
{
"selectionId": 285469,
"runnerName": "1 goals or more",
"handicap": -1,
"sortPriority": 1,
"metadata": {
"runnerId": "63123486"
}
},
{
"selectionId": 285470,
"runnerName": "2 goals or more",
"handicap": -2,
"sortPriority": 2,
"metadata": {
"runnerId": "63123487"
}
},
{
"selectionId": 285471,
"runnerName": "3 goals or more",
"handicap": -3,
"sortPriority": 3,
"metadata": {
"runnerId": "63123488"
}
},
{
"selectionId": 2795170,
"runnerName": "4 goals or more",
"handicap": -4,
"sortPriority": 4,
"metadata": {
"runnerId": "63123489"
}
},
{
"selectionId": 285473,
"runnerName": "5 goals or more",
"handicap": -5,
"sortPriority": 5,
"metadata": {
"runnerId": "63123490"
}
},
{
"selectionId": 285474,
"runnerName": "6 goals or more",
"handicap": -6,
"sortPriority": 6,
"metadata": {
"runnerId": "63123491"
}
},
{
"selectionId": 8215951,
"runnerName": "7 goals or more",
"handicap": -7,
"sortPriority": 7,
"metadata": {
"runnerId": "63123492"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197491",
"marketName": "Match Odds",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 7707.52,
"runners": [
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123483"
}
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123484"
}
},
{
"selectionId": 58805,
"runnerName": "The Draw",
"handicap": 0,
"sortPriority": 3,
"metadata": {
"runnerId": "63123485"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197550",
"marketName": "Both teams to Score?",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 14.78,
"runners": [
{
"selectionId": 30246,
"runnerName": "Yes",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123625"
}
},
{
"selectionId": 30247,
"runnerName": "No",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123626"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197501",
"marketName": "Next Goal",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 3.34,
"runners": [
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123495"
}
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123496"
}
},
{
"selectionId": 69852,
"runnerName": "No Goal",
"handicap": 0,
"sortPriority": 3,
"metadata": {
"runnerId": "63123497"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197502",
"marketName": "Over/Under 6.5 Goals",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 1255.79,
"runners": [
{
"selectionId": 2542448,
"runnerName": "Under 6.5 Goals",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123498"
}
},
{
"selectionId": 2542449,
"runnerName": "Over 6.5 Goals",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123499"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197505",
"marketName": "Correct Score",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 2380.92,
"runners": [
{
"selectionId": 1,
"runnerName": "0 - 0",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123505"
}
},
{
"selectionId": 4,
"runnerName": "0 - 1",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123506"
}
},
{
"selectionId": 9,
"runnerName": "0 - 2",
"handicap": 0,
"sortPriority": 3,
"metadata": {
"runnerId": "63123507"
}
},
{
"selectionId": 16,
"runnerName": "0 - 3",
"handicap": 0,
"sortPriority": 4,
"metadata": {
"runnerId": "63123508"
}
},
{
"selectionId": 2,
"runnerName": "1 - 0",
"handicap": 0,
"sortPriority": 5,
"metadata": {
"runnerId": "63123509"
}
},
{
"selectionId": 3,
"runnerName": "1 - 1",
"handicap": 0,
"sortPriority": 6,
"metadata": {
"runnerId": "63123510"
}
},
{
"selectionId": 8,
"runnerName": "1 - 2",
"handicap": 0,
"sortPriority": 7,
"metadata": {
"runnerId": "63123511"
}
},
{
"selectionId": 15,
"runnerName": "1 - 3",
"handicap": 0,
"sortPriority": 8,
"metadata": {
"runnerId": "63123512"
}
},
{
"selectionId": 5,
"runnerName": "2 - 0",
"handicap": 0,
"sortPriority": 9,
"metadata": {
"runnerId": "63123513"
}
},
{
"selectionId": 6,
"runnerName": "2 - 1",
"handicap": 0,
"sortPriority": 10,
"metadata": {
"runnerId": "63123514"
}
},
{
"selectionId": 7,
"runnerName": "2 - 2",
"handicap": 0,
"sortPriority": 11,
"metadata": {
"runnerId": "63123515"
}
},
{
"selectionId": 14,
"runnerName": "2 - 3",
"handicap": 0,
"sortPriority": 12,
"metadata": {
"runnerId": "63123516"
}
},
{
"selectionId": 10,
"runnerName": "3 - 0",
"handicap": 0,
"sortPriority": 13,
"metadata": {
"runnerId": "63123517"
}
},
{
"selectionId": 11,
"runnerName": "3 - 1",
"handicap": 0,
"sortPriority": 14,
"metadata": {
"runnerId": "63123518"
}
},
{
"selectionId": 12,
"runnerName": "3 - 2",
"handicap": 0,
"sortPriority": 15,
"metadata": {
"runnerId": "63123519"
}
},
{
"selectionId": 13,
"runnerName": "3 - 3",
"handicap": 0,
"sortPriority": 16,
"metadata": {
"runnerId": "63123520"
}
},
{
"selectionId": 4506345,
"runnerName": "Any Unquoted ",
"handicap": 0,
"sortPriority": 17,
"metadata": {
"runnerId": "63123521"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197506",
"marketName": "Over/Under 2.5 Goals",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 4149.36,
"runners": [
{
"selectionId": 47972,
"runnerName": "Under 2.5 Goals",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123522"
}
},
{
"selectionId": 47973,
"runnerName": "Over 2.5 Goals",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123523"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197504",
"marketName": "Over/Under 5.5 Goals",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 2216.24,
"runners": [
{
"selectionId": 1485567,
"runnerName": "Under 5.5 Goals",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123503"
}
},
{
"selectionId": 1485568,
"runnerName": "Over 5.5 Goals",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123504"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197509",
"marketName": "Half Time/Full Time",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 97.3,
"runners": [
{
"selectionId": 6830596,
"runnerName": "FC Samtredia/FC Samtredia",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123536"
}
},
{
"selectionId": 6830599,
"runnerName": "FC Samtredia/Draw",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123537"
}
},
{
"selectionId": 8380726,
"runnerName": "FC Samtredia/FC Betlemi Ked",
"handicap": 0,
"sortPriority": 3,
"metadata": {
"runnerId": "63123538"
}
},
{
"selectionId": 6830595,
"runnerName": "Draw/FC Samtredia",
"handicap": 0,
"sortPriority": 4,
"metadata": {
"runnerId": "63123539"
}
},
{
"selectionId": 3710152,
"runnerName": "Draw/Draw",
"handicap": 0,
"sortPriority": 5,
"metadata": {
"runnerId": "63123540"
}
},
{
"selectionId": 6843869,
"runnerName": "Draw/FC Betlemi Ked",
"handicap": 0,
"sortPriority": 6,
"metadata": {
"runnerId": "63123541"
}
},
{
"selectionId": 8380727,
"runnerName": "FC Betlemi Ked/FC Samtredia",
"handicap": 0,
"sortPriority": 7,
"metadata": {
"runnerId": "63123542"
}
},
{
"selectionId": 6843873,
"runnerName": "FC Betlemi Ked/Draw",
"handicap": 0,
"sortPriority": 8,
"metadata": {
"runnerId": "63123543"
}
},
{
"selectionId": 6843870,
"runnerName": "FC Betlemi Ked/FC Betlemi Ked",
"handicap": 0,
"sortPriority": 9,
"metadata": {
"runnerId": "63123544"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197510",
"marketName": "Over/Under 1.5 Goals",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 1879.69,
"runners": [
{
"selectionId": 1221385,
"runnerName": "Under 1.5 Goals",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123545"
}
},
{
"selectionId": 1221386,
"runnerName": "Over 1.5 Goals",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123546"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197507",
"marketName": "Over/Under 4.5 Goals",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 3189.28,
"runners": [
{
"selectionId": 1222347,
"runnerName": "Under 4.5 Goals",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123524"
}
},
{
"selectionId": 1222346,
"runnerName": "Over 4.5 Goals",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123525"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197511",
"marketName": "Over/Under 3.5 Goals",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 3934.41,
"runners": [
{
"selectionId": 1222344,
"runnerName": "Under 3.5 Goals",
"handicap": 0,
"sortPriority": 1,
"metadata": {
"runnerId": "63123547"
}
},
{
"selectionId": 1222345,
"runnerName": "Over 3.5 Goals",
"handicap": 0,
"sortPriority": 2,
"metadata": {
"runnerId": "63123548"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
},
{
"marketId": "1.113197512",
"marketName": "Asian Handicap",
"marketStartTime": "2014-03-13T11:00:00.000Z",
"totalMatched": 1599.38,
"runners": [
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -4,
"sortPriority": 1
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 4,
"sortPriority": 2
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -3.75,
"sortPriority": 3
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 3.75,
"sortPriority": 4
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -3.5,
"sortPriority": 5
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 3.5,
"sortPriority": 6
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -3.25,
"sortPriority": 7
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 3.25,
"sortPriority": 8
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -3,
"sortPriority": 9
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 3,
"sortPriority": 10
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -2.75,
"sortPriority": 11
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 2.75,
"sortPriority": 12
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -2.5,
"sortPriority": 13
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 2.5,
"sortPriority": 14
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -2.25,
"sortPriority": 15
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 2.25,
"sortPriority": 16
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -2,
"sortPriority": 17
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 2,
"sortPriority": 18
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -1.75,
"sortPriority": 19
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 1.75,
"sortPriority": 20
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -1.5,
"sortPriority": 21
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 1.5,
"sortPriority": 22
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -1.25,
"sortPriority": 23
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 1.25,
"sortPriority": 24
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -1,
"sortPriority": 25
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 1,
"sortPriority": 26
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -0.75,
"sortPriority": 27
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 0.75,
"sortPriority": 28
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -0.5,
"sortPriority": 29
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 0.5,
"sortPriority": 30
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": -0.25,
"sortPriority": 31
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 0.25,
"sortPriority": 32
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 0,
"sortPriority": 33
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": 0,
"sortPriority": 34
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 0.25,
"sortPriority": 35
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -0.25,
"sortPriority": 36
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 0.5,
"sortPriority": 37
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -0.5,
"sortPriority": 38
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 0.75,
"sortPriority": 39
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -0.75,
"sortPriority": 40
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 1,
"sortPriority": 41
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -1,
"sortPriority": 42
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 1.25,
"sortPriority": 43
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -1.25,
"sortPriority": 44
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 1.5,
"sortPriority": 45
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -1.5,
"sortPriority": 46
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 1.75,
"sortPriority": 47
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -1.75,
"sortPriority": 48
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 2,
"sortPriority": 49
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -2,
"sortPriority": 50
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 2.25,
"sortPriority": 51
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -2.25,
"sortPriority": 52
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 2.5,
"sortPriority": 53
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -2.5,
"sortPriority": 54
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 2.75,
"sortPriority": 55
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -2.75,
"sortPriority": 56
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 3,
"sortPriority": 57
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -3,
"sortPriority": 58
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 3.25,
"sortPriority": 59
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -3.25,
"sortPriority": 60
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 3.5,
"sortPriority": 61
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -3.5,
"sortPriority": 62
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 3.75,
"sortPriority": 63
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -3.75,
"sortPriority": 64
},
{
"selectionId": 6830593,
"runnerName": "FC Samtredia",
"handicap": 4,
"sortPriority": 65,
"metadata": {
"runnerId": "63123613"
}
},
{
"selectionId": 6843866,
"runnerName": "FC Betlemi Keda",
"handicap": -4,
"sortPriority": 66,
"metadata": {
"runnerId": "63123614"
}
}
],
"eventType": {
"id": "1",
"name": "Soccer"
},
"competition": {
"id": "2356065",
"name": "Pirveli Liga"
},
"event": {
"id": "27165685",
"name": "FC Samtredia v FC Betlemi Keda",
"countryCode": "GE",
"timezone": "GMT",
"openDate": "2014-03-13T11:00:00.000Z"
}
}
],
"id": 1
}
]
Horse Racing - Today's Win & Place Markets
The below request is an example of retrieving the available win/place horse racing markets for a specific day.
ThemarketStartTime (from & to) should be updated accordingly.
listMarketCatalogue Request
[
{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listMarketCatalogue",
"params": {
"filter": {
"eventTypeIds": [
"7"
],
"marketTypeCodes": [
"WIN",
"PLACE"
],
"marketStartTime": {
"from": "2013-10-16T00:00:00Z",
"to": "2013-10-16T23:59:00Z"
}
},
"maxResults": "200",
"marketProjection": [
"MARKET_START_TIME",
"RUNNER_METADATA",
"RUNNER_DESCRIPTION",
"EVENT_TYPE",
"EVENT",
"COMPETITION"
]
},
"id": 1
}
]
Football Competitions
To retrieve all football competitions, you call the eventTypeId; operation with the following market filter:
listCompetitions Request
{
"params": {
"filter": {
"eventTypeIds": [1]
}
},
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listCompetitions",
"id": 1
}
The "filter" selects all markets that have an eventTypeId of 1 (which is the event type for Football).
Then returns a list of Competitions and their Ids and how many markets are in each competition which are
associated with those markets:
listCompetitions Response
{
"jsonrpc": "2.0",
"result": [
{
"marketCount": 16,
"competition": {
"id": "833222",
"name": "Turkish Division 2"
}
},
{
"marketCount": 127,
"competition": {
"id": "5",
"name": "A-League 2012/13"
}
},
{
"marketCount": 212,
"competition": {
"id": "7",
"name": "Austrian Bundesliga"
}
},
{
"marketCount": 243,
"competition": {
"id": "11",
"name": "Dutch Jupiler League"
}
},
{
"marketCount": 206,
"competition": {
"id": "26207",
"name": "Greek Cup"
}
},
{
"marketCount": 117,
"competition": {
"id": "2129602",
"name": "Professional Development League"
}
},
{
"marketCount": 68,
"competition": {
"id": "803237",
"name": "Argentinian Primera B"
}
},
{
"marketCount": 1,
"competition": {
"id": "1842928",
"name": "OTB Bank Liga"
}
}
],
"id": 1
}
Python Example
import requests
import json

url="https://api.betfair.com/betting/json-rpc"
header = { 'X-Application' : "APP_KEY_HERE", 'X-Authentication : 'SESSION_TOKEN',
'content-type' : 'application/json' }
jsonrpc_req='{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listCompetitions",
"params": {"filter":{ "eventTypeIds" : [1] }}, "id": 1}'

print json.dumps(json.loads(jsonrpc_req), indent=3)
print " "

response = requests.post(url, data=jsonrpc_req, headers=header)

print json.dumps(json.loads(response.text), indent=3)
List Football Markets 'In-Play Now'
The below request will return information on the marketId's that are in-play at the time the request was made.
listMarketCatalogue Request
[
{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listMarketCatalogue",
"params": {
"filter": {
"eventTypeIds": [
"1"
],
"inPlayOnly": true
},
"maxResults": "200",
"marketProjection": [
"COMPETITION",
"EVENT",
"EVENT_TYPE",
"RUNNER_DESCRIPTION",
"RUNNER_METADATA",
"MARKET_START_TIME"
]
},
"id": 1
}
]
Market Prices
Once you have identified the market (marketId) that you are interested in using the service, you listMarketCatalogue
can request prices for that market using the API call. listMarketBook
This is an example showing a request for the best prices for two markets

listMarketBook Request
import requests
import json
url="https://api.betfair.com/betting/json-rpc"
header = { 'X-Application' : 'APP_KEY_HERE', 'X-Authentication' :
'SESSION_TOKEN_HERE' ,'content-type' : 'application/json' }
jsonrpc_req='{"jsonrpc": "2.0", ' \
'"method": "SportsAPING/v1.0/listMarketBook", ' \
'"params": { "marketIds" : ["1.107514698" , "1.107702438"],
"priceProjection" : ["EX_BEST_OFFERS"] }, ' \
'"id": 1}'
response = requests.post(url, data=jsonrpc_req, headers=header)
print json.dumps(json.loads(response.text), indent=3)
listMarketBook Response
{
"jsonrpc": "2.0",
"result": [
{
"status": "OPEN",
"isMarketDataDelayed": false,
"numberOfRunners": 2,
"complete": true,
"bspReconciled": false,
"runnersVoidable": false,
"betDelay": 0,
"marketId": "1.107514698",
"crossMatching": false,
"totalMatched": 31.82079480940795,
"version": 424118705,
"lastMatchTime": "2012-12-08T10:29:16.000Z",
"numberOfWinners": 1,
"inplay": false,
"numberOfActiveRunners": 2,
"totalAvailable": 597.3932815826607,
"runners": [
{
"status": "ACTIVE",
"handicap": 0.0,
"selectionId": 36223,
"totalMatched": 31.82079480940795,
"ex": {
"availableToBack": [
{
"price": 4.0,
"size": 12.165450121654498
},
{
"price": 2.12,
"size": 3.7193156459211507
},
{
"price": 2.1,
"size": 16.220600162206
}
],
"availableToLay": [
{
"price": 9.6,
"size": 1.6220600162206
},
{
"price": 1000.0,
"size": 1.6220600162206
}
]
},
"lastPriceTraded": 3.75
},
{
"handicap": 0.0,
"status": "ACTIVE",
"selectionId": 36224,
"totalMatched": 0.0,
"ex": {
"availableToBack": [
{
"price": 1.02,
"size": 450.1216545012165
},
{
"price": 1.01,
"size": 8.110300081103
}
],
"availableToLay": [
{
"price": 1.25,
"size": 4.0551500405515
},
{
"price": 1000.0,
"size": 1.6220600162206
}
]
}
}
]
},
{
"status": "OPEN",
"isMarketDataDelayed": false,
"numberOfRunners": 5,
"complete": true,
"bspReconciled": false,
"runnersVoidable": false,
"betDelay": 0,
"marketId": "1.107702438",
"crossMatching": false,
"totalMatched": 0.0,
"version": 435265564,
"numberOfWinners": 1,
"inplay": false,
"numberOfActiveRunners": 5,
"totalAvailable": 70.551500405515,
"runners": [
{
"handicap": 0.0,
"status": "ACTIVE",
"selectionId": 2267624,
"totalMatched": 0.0,
"ex": {
"availableToBack": [
{
"price": 6.4,
"size": 2.0
},
{
"price": 6.2,
"size": 2.0
},
{
"price": 6.0,
"size": 2.0
}
]
}
},
{
"handicap": 0.0,
"status": "ACTIVE",
"selectionId": 314518,
"totalMatched": 0.0,
"ex": {
"availableToBack": [
{
"price": 4.3,
"size": 2.0
},
{
"price": 4.2,
"size": 2.0
},
{
"price": 4.1,
"size": 2.0
}
]
}
},
{
"handicap": 0.0,
"status": "ACTIVE",
"selectionId": 1356011,
"totalMatched": 0.0,
"ex": {
"availableToBack": [
{
"price": 1.77,
"size": 2.0
},
{
"price": 1.76,
"size": 2.0
},
{
"price": 1.75,
"size": 2.0
}
]
}
},
{
"handicap": 0.0,
"status": "ACTIVE",
"selectionId": 2776952,
"totalMatched": 0.0,
"ex": {
"availableToBack": [
{
"price": 2.04,
"size": 2.0
},
{
"price": 2.02,
"size": 2.0
},
{
"price": 2.0,
"size": 2.0
}
]
}
},
{
"handicap": 0.0,
"status": "ACTIVE",
"selectionId": 4491706,
"totalMatched": 0.0,
"ex": {
"availableToBack": [
{
"price": 22.0,
"size": 2.0
},
{
"price": 21.0,
"size": 2.0
},
{
"price": 20.0,
"size": 2.0
}
]
}
}
]
}
],
"id": 1
}
Placing a Bet
To place a bet you require the marketId and selectionId parameters from the API call. The listMarketCatalogue
below parameters will place a normal Exchange bet at odds of 3.0 for a stake of 2.0.
If the bet is placed successfully, a betId is returned in the response placeOrders
placeOrders Request
[
{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/placeOrders",
"params": {
"marketId": "1.109850906",
"instructions": [
{
"selectionId": "237486",
"handicap": "0",
"side": "LAY",
"orderType": "LIMIT",
"limitOrder": {
"size": "2",
"price": "3",
"persistenceType": "LAPSE"
}
}
]
},
"id": 1
}
]
placeOrder Response
[
{
"jsonrpc": "2.0",
"result": {
"marketId": "1.109850906",
"instructionReports": [
{
"instruction": {
"selectionId": 237486,
"handicap": 0,
"limitOrder": {
"size": 2,
"price": 3,
"persistenceType": "LAPSE"
},
"orderType": "LIMIT",
"side": "LAY"
},
"betId": "31242604945",
"placedDate": "2013-10-30T14:22:47.000Z",
"averagePriceMatched": 0,
"sizeMatched": 0,
"status": "SUCCESS"
}
],
"status": "SUCCESS"
},
"id": 1
}
]
Placing a Betfair SP Bet
To place a bet on a selection at Betfair SP, you need to specify the parameters below in the request. placeOrders
The below example would place a Betfair SP back bet on the required selection for a stake of 2.00.
Request
placeOrders Request
[
{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/placeOrders",
"params": {
"marketId": "1.111836557",
"instructions": [
{
"selectionId": "5404312",
"handicap": "0",
"side": "BACK",
"orderType": "MARKET_ON_CLOSE",
"marketOnCloseOrder": {
"liability": "2"
}
}
]
},
"id": 1
}
]
placeOrders Response
[
{
"jsonrpc": "2.0",
"result": {
"marketId": "1.111836557",
"instructionReports": [
{
"instruction": {
"selectionId": 5404312,
"handicap": 0,
"marketOnCloseOrder": {
"liability": 2
},
"orderType": "MARKET_ON_CLOSE",
"side": "BACK"
},
"betId": "31645233727",
"placedDate": "2013-11-12T12:07:29.000Z",
"status": "SUCCESS"
}
],
"status": "SUCCESS"
},
"id": 1
}
]
Retrieving the Result of a Settled Market

To retrieve the result of a settled market simply make a

request to listMarketBook after the market has been settled.
The response will indicate whether the selection was
settled as a 'WINNER' or 'LOSER' in the runners 'status'
field. Settled market information is available for 90 days
after settlement.
listMarketBook Request to a Settled market
[{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listMarketBook", "params":
{"marketIds":["1.114363660"],"priceProjection":{"priceData":["EX_BEST_OFFERS"]}},
"id": 1}]
listMarketBook Response
[
{
"jsonrpc": "2.0",
"result": [
{
"marketId": "1.114363660",
"isMarketDataDelayed": false,
"status": "CLOSED",
"betDelay": 0,
"bspReconciled": false,
"complete": true,
"inplay": false,
"numberOfWinners": 1,
"numberOfRunners": 14,
"numberOfActiveRunners": 0,
"totalMatched": 0,
"totalAvailable": 0,
"crossMatching": false,
"runnersVoidable": false,
"version": 767398001,
"runners": [
{
"selectionId": 8611526,
"handicap": 0,
"status": "REMOVED",
"adjustmentFactor": 9.1,
"removalDate": "2014-06-13T08:44:17.000Z",
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 8611527,
"handicap": 0,
"status": "REMOVED",
"adjustmentFactor": 3.5,
"removalDate": "2014-06-13T08:44:29.000Z",
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 7920154,
"handicap": 0,
"status": "WINNER",
"adjustmentFactor": 17.5,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 1231425,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 4.3,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 7533866,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 11.4,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 8220841,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 5.4,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 7533883,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 8.7,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 8476712,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 8.7,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 7012263,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 5.4,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 7374225,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 8.7,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 8611525,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 0.7,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 7659121,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 26.8,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 6996332,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 0.7,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
},
{
"selectionId": 7137541,
"handicap": 0,
"status": "LOSER",
"adjustmentFactor": 1.7,
"ex": {
"availableToBack": [],
"availableToLay": [],
"tradedVolume": []
}
}
]
}
],
"id": 1
}
]
How Do I?
The table below shows the most appropriate API service for each task.
To: Use:
Login Login (Interactive and non-interactive logins are
available)
Logout Logout
Keep session alive Keep Alive
Request a list of available events listEvents

Request the market information for a specific event

listMarketCatalogue
Request market details (excluding prices) listMarketCatalogue

Place a bet

placeOrders
Cancel a bet before its matched cancelOrders
Retrieve a list of Matched/Unmatched bets listCurrentOrders/listMarketBook

Edit an Unmatched bet updateOrders/replaceOrders

Place a Betfair SP bet placeOrders
Retrieve a list of markets that are in-play now listMarketCatalogue
Retrieve a list of markets that are due to be turned
in-play
listMarketCatalogue

Retrieve a list of Settled, Void, Cancelled or Lapsed

bets
listClearedOrders
Market Data Request Limits
Although you can request multiple markets from , and , listMarketBook listMarketCatalogue listMarketProfitandLoss
there are limits on the amount of data requested in one request.
The following table explains the "weighting" of data for each or . If you exceed MarketProjection PriceProjection
the maximum weighting of 200 points, the API will return a TOO_MUCH_DATA error.
sum(Weight) * number market ids must not exceed 200 points
listMarketCatalogue
MarketProjection Weight
MARKET_DESCRIPTION 1
RUNNER_DESCRIPTION 0
EVENT 0
EVENT_TYPE 0
COMPETITION 0
RUNNER_METADATA 1
MARKET_START_TIME 0
listMarketBook
PriceProjection Weight
Null (No PriceProjection set) 2
SP_AVAILABLE 3
SP_TRADED 7
EX_BEST_OFFERS 5
EX_ALL_OFFERS 17
EX_TRADED 17
listMarketProfitandLoss
PriceProjection Weight
Not applicable 4

Understanding Market Navigation

In the new API, navigating markets uses the concepts of faceted search. You've probably seen faceted search used
on sites like eBay or Amazon where you pick a category, for example "Shoes" and then you see a list of shoes.
Then, you can narrow your search by facets. For example, by colour or price. In a similar way, the new Sports API
lets you find markets you're interested in and then get data back about a facet of those markets.
The way to think of the API Navigation operations is to imagine a single table that lists every market, along with
various metadata about the market. The columns of the table are the Facets (and the Nav Operations in API return
some of them in combination):
As you can see, the table has four markets along with some of the metadata associated with that market. Of course,
the actual table would have tens of thousands of markets and more columns.
Along the top, you can see three of the navigation operations. Each of those operations takes a "MarketFilter". The
MarketFilter filters the table of markets and selects the ones that match. The MarketFilter can contain things like
"going in play" or "eventId 7", etc. So, if you called "listCompetitions" and passed in a filter that looked like:
Code:
{ "filter": {"turnsInPlay" : true }}
The selected markets would look like:
In the example, the 1001, 2355, and the 5621 market are the ones that match the filter. As you called
"listCompetitions" with that filter, then the data returned is the columns containing competition information:
In this example, you'd get a list of competitions like so:
Code:
{"competitionId" : "23", "competitionName" :
"World Cup 2013"}
Notice that the competition "Final 2013" was not returned. This is because the market was not selected by the
MarketFilter. Also, notice that although the market 2355 was selected by the MarketFilter, it is not associated with a
competition, so no competition id and name were returned for that market.
As a further example, suppose that you used the same MarketFilter as before while calling listEvents. In that case,
the data returned is the columns containing eventId and eventName for the markets that match the filter (i.e.,
turnsInPlay = True):
In this example, you'd get a list of events like so:
Code:
[{"eventId" : "24", "eventName" : "Arsenal Vs.
Reading"}, {"eventId" : "124", "eventName" :
"Ascot 16th September"}, {"eventId" : "23",
"eventName" : "Cheltenham 17th September"}]
Again, notice that the event "Celtics vs Nicks" was not returned because it was not selected by the MarketFilter.
One further example. Suppose you were only interested in Line markets and you want to find all of the Sports
(EventTypes) that contain Line markets. You would create a MarketFilter like this:
Code:
{ "filter": {"MarketBettingType" : "LINE" }}
And call listEventTypes with that filter. The markets selected by that MarketFilter would be:
and the data returned would be:
Code:
{"eventTypeId" : "4", "EventTypeName" :
"Basketball"}
Using the set of navigation operations, you can easily create a menu tree of markets in whatever hierarchy you
want. You can can listEventTypes to get the Sports as the top of your menu. Or, you could call "listCountries" and
use markets in a country as the root of the tree.
There is also so if you didn't care about creating a visual navigation, you could simply call listMarketCatalogue listMa
with a defining the markets you're interested in and get back information about those rketCatalogue MarketFilter
markets.

API-NG Roadmap - to September 2014

Please see details below for the API-NG road map until September 2014.
API-NG Roadmap
Estimated Release
Date*
Feature Description Status
3rd February Add listMarketProfitAn
dLoss operation
New operation to return
the profit and loss
value per selection.

Released
24th February listCurrentOrders
add a dateRange
parameter
Allows the user to
specify a date and time
to start from for the list
of returned bets.
Released
9th April

Heartbeat service Heartbeat functionality

that allows the
automatic cancellation
of a users bets in the
event of a loss of
connectivity to the
Exchange.
Released
24th April Convert currency
operation
The service will provide
details of the current
foreign exchange rates
that are being used by
the Betfair Exchange
Released
24th April Account Statement Provides the Account
Statement items
.
Released
16th June Navigation data for
applications (Beta)
Beta endpoint to
expose Betfair
"Left-Hand Menu"
navigation data for
developers to use
when creating
navigation menu in
their apps.
Released
16th June getApplicationSubscr
iptionHistory - option
to call this from
vendor's app client
Software vendor will be
able to obtain a user's
application subscription
history entirely from the
client side
Released
16th June getAccountFunds - ex
tended to include
discount rate and
points balance
Simplifies access to
dynamic account data,
as this is now all
available in a single
operation
getAccountFunds
Released
28th July Navigation data for
applications
(Production)
Production release of
earlier beta
Pending
11th August Scores API - Tennis A new API service
available to Betfair
customers** providing
live tennis scores and
incidents for ATP &
WTA matches
(excludes Grand Slam
tournaments).
Pending
1st September Australian Wallet
operations -
getAccountFunds &
Transfer Funds
Read Australian wallet
balance & transfer
funds between UK and
AUS wallets
Pending
8th September Scores API - Cricket
(subscription only)
Ball-by-ball cricket
match coverage,
together with incidents
(e.g. weather stopping
play)
Pending
TBD getAccountStatement Market type and start
date are no longer
returned
Pending
*The release dates are estimates and are subject to change. Please see the New API - Release Announcements
for live update
**not available to commercial data licensees

API 6.0 > API-NG Operations Comparison Table

The below table compares API-NG operations with their API 6.0 equivalent for those looking to migrate their
applications.

API6 Operation API-NG Operation Notes

cancelBets cancelOrders
cancelBetsByMarket cancelOrders All bets can be cancelled using cancelOrders if a marketId is not supplied
convertCurrency listCurrencyRates
getAccountFunds getAccountFunds
getAccountStatement getAccountStatement
getActiveEventTypes listEventTypes
getAllCurrenciesV2 To Be Added See convertCurrency
getAllEventTypes listEventTypes
getAllMarkets listMarketCatalogue
getBet listCurrentOrders
getBetHistory listClearedOrders
getBetLite listCurrentOrders
getBetMatchesLite listCurrentOrders
getCompleteMarketPricesCompressed listMarketBook Requires EX_ALL_OFFERS set as the PriceProjection
getCurrentBets listCurrentOrders
getCurrentBetsLite listCurrentOrders
getDetailAvailableMktDepth listMarketBook Requires both EX_ALL_OFFERS and EX_TRADED set as the PriceProjection
getEvents listEvents
getInPlayMarkets listMarketCatalogue Requires 'turnInPlayEnabled = true' in the MarketFilter
getMarket listMarketCatalogue
getMarketInfo listMarketCatalogue
getMarketPrices listMarketBook Requires EX_BEST_OFFERS set as the PriceProjection
getMarketPricesCompressed listMarketBook Requires EX_BEST_OFFERS set as the PriceProjection
getMarketProfitAndLoss listMarketProfitAndLoss
getMarketTradedVolume listMarketBook Requires EX_TRADED set as the PriceProjection
getMarketTradedVolumeCompressed listMarketBook Requires EX_TRADED set as the PriceProjection
getMUBets listCurrentOrders
getMUBetsLite listCurrentOrders
getSilks listMarketCatalogue Available when the MarketProjection RUNNER_METADATA is specified for a horse racing market
getSilksV2 listMarketCatalogue Available when the MarketProjection RUNNER_METADATA is specified for a horse racing market
Heartbeat heartbeat
keepAlive Keep Alive
login Login Interactive and non-interactive login methods are available.
logout Logout
placeBets placeOrders
transferFunds To Be Added
updateBets updateOrders/replaceOr
ders

viewProfile getAccountDetails
viewProfileV2 getAccountDetails
Deprecated API 6.0 Operations
The following operations are deprecated and won't be provided via API-NG:
addPaymentCard
createAccount
deletePaymentCard
depositFromPaymentCard
forgotPassword
getCoupon
getPaymentCard
getPrivateMarkets
modifyPassword
modifyProfile
retrieveLIMBMessage
selfExclude
setChatName
submitLIMBMessage
updatePaymentCard
viewReferAndEarn
withdrawByBankTransfer
withdrawToPaymentCard

API-NG Reference Guide

Version Description Date
V.1.7 Updated to include changes to
getAccountFunds & Vendor
Services API
16-06-2014
V.1.6 Updated to include
getAccountStatement and
listCurrencyRates
29-04-2014
V.1.5 Updated to include the Heartbeat
API
09-04-2014
V.1.4 Updated to include changes to
listClearedOrders and
listMarketCatalogue.
24-02-2014
V.1.3 Introduced the
listMarketProfitAndLoss
functionality to the Betting API.
03-02-2014
V.1.2 Introduced the listClearedOrders
functionality to the Betting API.
17-12-2013
V.1.1 Updates to the Vendor API,
listCurrentOrders and addition of
endpoint for Australian Exchange
07-10-2013
V1.0 Introduced login and vendor
services functionality, moved to final
endpoints.
29-07-2013
V0.4 Introduced additional Account
functionality (getAccountFunds and
getAccountDetails)
01-07-2013
V0.3 Introduced Account API-NG 03-06-2013
V0.2 Introduced betting functionality and
listCurrentOrders
20-05-2013
V0.1 Initial release 09-12-2012
Quick Navigation

Betting API
Please find the details for the current Betting API endpoints:
You can make requests and place bets on UK & international markets by accessing the UK Exchange via the
following endpoints.
UK Exchange
Interface Endpoint JSON-RPC Prefix <methodname>
Example
JSON-RPC https://api.betfair.com/exc
hange/betting/json-rpc/v1
<methodname> SportsAPING/v1.0/listMar
ketBook
JSON REST https://api.betfair.com/exc
hange/betting/rest/v1.0/

You can make requests and place bets on Australian markets by accessing the Australian exchange server via the
following endpoints.
Australian Exchange
Interface Endpoint JSON-RPC Prefix <methodname>
Example
JSON-RPC https://api-au.betfair.com/
exchange/betting/json-rpc
/v1
<methodname> SportsAPING/v1.0/listMar
ketBook
JSON REST https://api-au.betfair.com/
exchange/betting/rest/v1.0
/

Betting on Australian Events
API-NG supports betting on events within Australia and/or under the jurisdiction of the Tasmanian Gaming
Commission (TGC).
The main requirements of are that:
1. Betting markets for sporting events that take place in Australia must be operated under an Australian licence
from the Tasmanian Gaming Commission (the body that regulates on-line gambling in Australia).
2.Bets placed in a betting market that operates under an Australian licence must be matched and settled on
equipment residing physically in Australia.
3.No performance degradation may be suffered by customers (in their placement and management of bets) as a
result of the requirement for bets to be matched and settled in Australia.
4.Providers of on-line gambling services must formally verify the name and address of every customer who wishes
to bet on an Australian sporting event.
Until this verification has taken place for a customer, that customer is not permitted to:
Deposit more than $300 (USD) in a single month into his or her betting account
Use the funds in the betting account to place bets whose cumulative cost in a single month exceeds $300
(USD)
Remove any funds from the account.
Finally, the name and address verification process must be completed within three months of the first
deposit into the account, otherwise the account will be suspended until verification has taken place.
To meet the first and second of the TGCs requirements,you can only bet on Australian events by accessing the
Australian exchange server via a separate endpoint. You need to make sure that your client software sends its
requests to the correct endpoint URL for the Australian exchange server.
You must also explicitly specify the correct endpoint URL.
You can make requests for and place bets on Australian markets by accessing the Australian exchange server via
the following endpoints.
Betting API
Interface Endpoint JSON-RPC Prefix <methodname>
Example
JSON-RPC https://api-au.betfair.com/
exchange/betting/json-rpc
/v1
<methodname> SportsAPING/v1.0/listMar
ketBook
JSON REST https://api-au.betfair.com/
exchange/betting/rest/v1.0

You can make requests for your Aus Exchange wallet information by accessing the Aus Exchange via the following
endpoints.
Account API
Interface Endpoint JSON-RPC Prefix <methodname>
Example
JSON-RPC https://api-au.betfair.com/
exchange/account/json-rp
c/v1
<methodname> AccountAPING/v1.0/getA
ccountFunds
JSON REST https://api-au.betfair.com/
exchange/account/rest/v1.
0

*Please note the getAccountFunds operations for the Australian Exchange doesnt currently return details
from the Australian wallet. This is due to be rectified in a future release.
Betting On Italian Exchange
Italian residents who have registered an Italian Exchange account can access the Betfair Exchange API. Italian
residents can register an account viahttps://register.betfair.it/account/italy/registration
To use the Italian Exchange with API-NG you need to create an Application Key for your Italian Exchange account
by following the process outlined viahttps://api.developer.betfair.com/services/webapps/docs/display/1smk3cen4v3l
u3yomq5qye0ni/Application+Keys
Once you have done created an App Key, you will need to login to API-NG using the Italian Exchange endpoint
which is as follows:
Non-interactive Login
https://identitysso.betfair.it/api/certlogin
1.
2.
3.
Interactive Login
https:// <AppKey>&url= it identitysso.betfair.it/view/login?product= https://www.betfair.

Italian Exchange Specific Bet Rules

To use the interactive login with the Italian Exchange your App Key will need to be white-listed by Betfair.
White-listing is not required to use the non-interactive login method.
There are several additional regulatory rules which apply specifically and only to accounts betting on the Italian
Exchange (https://www.betfair.it/exchange):
The stake for each back offer is a minimum of 200 Euro Cents and can only be incremented in multiples of 50
Euro Cents.
Any lay offers placed by the customer, must be placed in such a way as to ensure that the stake for any
corresponding back offer amounts to a minimum of 50 Euro Cents.
We cannot accept betting offers with potential winnings, calculated on the basis of the pre-selected odds, that
exceed the amount envisaged by article 12, paragraph 4, of Finance Minister Decree no. 111 of 1 March
2006 (10,000 Euros). N.B. This does not include stake.
The Italian Exchange isn't available for betting between 0100and 0500 GMT
Betting Operations
Operation summary
List< > EventTypeResult listEventTypes ,Stringlocale ( filter MarketFilter )
List< > CompetitionResult listCompetitions ,Stringlocale ( filter MarketFilter )
List< > TimeRangeResult listTimeRanges , ( filter MarketFilter TimeGranularit
granularity y )
List< > EventResult listEvents ,Stringlocale ( filter MarketFilter )
List< > MarketTypeResult listMarketTypes ,Stringlocale ( filter MarketFilter )
List< > CountryCodeResult listCountries ,Stringlocale ( filter MarketFilter )
List< > VenueResult listVenues ,Stringlocale ( filter MarketFilter )
List< > MarketCatalogue listMarketCatalogue ,Set< ( filter MarketFilter Market
>marketProjection, sort, int Projection MarketSort
maxResults, Stringlocale )
List< > MarketBook listMarketBook , ( List<String>marketIds PriceProjec
priceProjection, orderProjection, tion OrderProjection M
matchProjection,StringcurrencyCode,Str atchProjection
inglocale )
List< > MarketProfitAndLoss listMarketProfitAndLoss , ( Set< > marketIds MarketId
boolean includeSettledBets, boolean includeBspBets,
boolean netOfCommission )
CurrentOrderSummaryReport listCurrentOrders ,Set<String>m ( Set<String>betIds
arketIds, orderProjection, OrderProjection TimeRange
placedDateRange, orderBy, sortDir,intf OrderBy SortDir
romRecord,intrecordCount )
ClearedOrderSummaryReport , Set< listClearedOrders ( betStatus BetStatus Event
> eventTypeIds, Set< > eventIds, Set< TypeId EventId Ma
> marketIds, Set< > runnerIds, Set< rketId RunnerId BetId
> betIds, side, settledDateRange, Side TimeRange Gro
groupBy, boolean includeItemDescription, String upBy
locale, int fromRecord, int recordCount )
PlaceExecutionReport placeOrders , ( StringmarketId List<PlaceInstruction
, StringcustomerRef > instructions )
CancelExecutionReport cancelOrders , ( StringmarketId List<CancelInstructi
, StringcustomerRef >instructions on )
ReplaceExecutionReport replaceOrders , ( StringmarketId List< ReplaceInstru
, StringcustomerRef > instructions ction )
UpdateExecutionReport updateOrders , ( StringmarketId List< UpdateInstruc
, StringcustomerRef > instructions tion )
listCompetitions
Operation
listCompetitions
,Stringlocale List< > CompetitionResult listCompetitions ( filter MarketFilter ) throws APINGExcep
tion
Returns a list of Competitions (i.e., World Cup 2013) associated with the markets selected by the
MarketFilter. Currently only Football markets have an associated competition.
Parameter name Type Required Description
filter MarketFilter The filter to select
desired markets. All
markets that match the
criteria in the filter are
selected.
locale String The language used for
the response. If not
specified, the default is
returned.
Return type Description
List< > CompetitionResult output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listCountries
Operation
listCountries
,Stringlocale List< > CountryCodeResult listCountries ( filter MarketFilter ) throws APINGExceptio
n
Returns a list of Countries associated with the markets selected by the MarketFilter.
Parameter name Type Required Description
filter MarketFilter The filter to select
desired markets. All
markets that match the
criteria in the filter are
selected.
locale String The language used for
the response. If not
specified, the default is
returned.
Return type Description
List< > CountryCodeResult output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listCurrentOrders
Operation
listCurrentOrders
Set<String>betIds,Set<String>marketIds, CurrentOrderSummaryReport listCurrentOrders ( Order
orderProjection, placedDateRange, dateRange, order Projection TimeRange TimeRange OrderBy
By, sortDir,intfromRecord,intrecordCount SortDir ) throws APINGException
Returns a list of your current orders. Optionally you can filter and sort your current orders using the
various parameters, setting none of the parameters will return all of your current orders, up to a
maximum of 1000 bets, ordered BY_BET and sorted EARLIEST_TO_LATEST. To retrieve more than
1000 orders, you need to make use of the fromRecord and recordCount parameters.
Parameter name Type Required Description
betIds Set<String> Optionally restricts the
results to the specified
bet IDs. A maximum of
250 betId's, or a
combination of 250
betId's & marketId's are
permitted.
marketIds Set<String> Optionally restricts the
results to the specified
market IDs. A
maximum of 250
marketId's, or a
combination of 250
marketId's & are betId's
permitted.
orderProjection OrderProjection Optionally restricts the
results to the specified
order status.
placedDateRange TimeRange Deprecated use
dateRange instead.
Optionally restricts the
results to be from/to the
specified placed date.
This date is inclusive,
i.e. if an order was
placed on exactly this
date (to the
millisecond) then it will
be included in the
results. If the from is
later than the to, no
results will be returned.
dateRange TimeRange Replacement for
placedDateRange to
allow filtering by other
date fields rather than
just placedDate.
Optionally restricts the
results to be from/to the
specified date, these
dates are contextual to
the orders being
returned and therefore
the dates used to filter
on will change to
placed, matched,
voided or settled dates
depending on the
orderBy. This date is
inclusive, i.e. if an order
was placed on exactly
this date (to the
millisecond) then it will
be included in the
results. If the from is
later than the to, no
results will be returned.
orderBy OrderBy Specifies how the
results will be ordered.
If no value is passed in,
it defaults to BY_BET.
Also acts as a filter
such that only orders
with a valid value in the
field being ordered by
will be returned (i.e.
BY_VOID_TIME
returns only voided
orders,
BY_SETTLED_TIME
returns only settled
orders and
BY_MATCH_TIME
returns only orders with
a matched date
(voided, settled,
matched orders)). Note
that specifying an
orderBy parameter
defines the context of
the date filter applied
by the dateRange
parameter (placed,
matched, voided or
) - see the settled date
dateRange parameter
description (above) for
more information. See
also the OrderBy type
definition.
sortDir SortDir Specifies the direction
the results will be
sorted in. If no value is
passed in, it defaults to
EARLIEST_TO_LATE
ST.
fromRecord int Specifies the first
record that will be
returned. Records start
at index zero, not at
index one.
recordCount int Specifies how many
records will be
returned, from the
index position
'fromRecord'. Note that
there is a page size
limit of 1000. A value of
zero indicates that you
would like all records
(including and from
'fromRecord') up to the
limit.
Return type Description
CurrentOrderSummaryReport
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listClearedOrders
Operation
listClearedOrders
ClearedOrderSummaryReport , Set< > listClearedOrders ( betStatus BetStatus EventTypeId
eventTypeIds, Set< > eventIds, Set< > marketIds, Set< > runnerIds, Set< > EventId MarketId RunnerId BetId
betIds, side, settledDateRange, groupBy, boolean includeItemDescription, Side TimeRange GroupBy
String locale, int fromRecord, int recordCount ) throwsAPINGException
Returns a list of settled bets based on the bet status, ordered by settled date. To retrieve more than 1000
records, you need to make use of the fromRecord and recordCount parameters. The fields available at
each roll-up are available here
Parameter name Type Required Description
betStatus BetStatus Restricts the results to
the specified status.
eventTypeIds Set< > EventTypeId Optionally restricts the
results to the specified
Event Type IDs.
eventIds Set< > EventId Optionally restricts the
results to the specified
Event IDs.
marketIds Set< > Market Id Optionally restricts the
results to the specified
market IDs.
runnerIds Set< > RunnerId Optionally restricts the
results to the specified
Runners.
betIds Set< > BetId Optionally restricts the
results to the specified
bet IDs.
side Side Optionally restricts the
results to the specified
side.
settledDateRange TimeRange Optionally restricts the
results to be from/to the
specified settled date.
This date is inclusive,
i.e. if an order was
placed on exactly this
date (to the
millisecond) then it will
be included in the
results. If the from is
later than the to, no
results will be returned.
groupBy GroupBy How to aggregate the
lines, if not supplied
then the lowest level is
returned, i.e. bet by bet
This is only applicable
to SETTLED BetStatus.
includeItemDescription boolean If true then an
ItemDescription object
is included in the
response.
locale String The language used for
the itemDescription. If
not specified, the
customer account
default is returned.
fromRecord int Specifies the first
record that will be
returned. Records start
at index zero.
recordCount int Specifies how many
records will be
returned, from the
index position
'fromRecord'. Note that
there is a page size
limit of 1000. A value of
zero indicates that you
would like all records
(including and from
'fromRecord') up to the
limit.
Return type Description
ClearedOrderSummary
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0

listClearedOrders - Roll-up Fields Available

The below table indicates fields will be available at each roll-up when making requests to listClearedOrders
Rollup level: BET SIDE MARKET EVENT EVENT_TYP
E
EXCHANGE
Settled As Y Y Y Y Y Y
Settled Date Y MAX MAX MAX MAX MAX
Bet Count Y Y Y Y Y Y
Profit Y SUM SUM SUM SUM SUM
Exchange Id Y Y Y Y Y Y
Event Type Id Y Y Y Y Y N
Event Id Y Y Y Y N N
Market Id Y Y Y N N N
Selection Id Y Y N N N N
Handicap Y Y N N N N
Side Y Y N N N N
Price
Requested
Y AVG
N
(AVG)
N N N
Price
Matched
Y AVG
N
(AVG)
N N N
Size Settled Y SUM
N
(SUM)
N N N
Price
Reduced
Y Y Y N N N
Commission N N Y SUM SUM SUM
Bet Id Y N N N N N
Placed Date Y MAX MAX N N N
Persistence
Type
Y Y Y N N N
Order Type Y Y Y N N N
Regulator
Code
Y Y Y N N N
Regulator
Auth Code
Y Y Y N N N
Voided Date(
where
applicable)
Y MAX MAX N N N

listEvents
Operation
listEvents
,Stringlocale List< > EventResult listEvents ( filter MarketFilter ) throws APINGException
Returns a list of Events (i.e, Reading vs. Man United) associated with the markets selected by the
MarketFilter.
Parameter name Type Required Description
filter MarketFilter The filter to select
desired markets. All
markets that match the
criteria in the filter are
selected.
locale String The language used for
the response. If not
specified, the default is
returned.
Return type Description
List< > EventResult output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listEventTypes
Operation
listEventTypes
,Stringlocale List< > EventTypeResult listEventTypes ( filter MarketFilter ) throws APINGExceptio
n
Returns a list of Event Types (i.e. Sports) associated with the markets selected by the MarketFilter.
Parameter name Type Required Description
filter MarketFilter The filter to select
desired markets. All
markets that match the
criteria in the filter are
selected.
locale String The language used for
the response. If not
specified, the default is
returned.
Return type Description
List< > EventTypeResult output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listMarketBook
Operation
listMarketBook
, priceProjection, List< > MarketBook listMarketBook ( List<String>marketIds PriceProjection Ord
orderProjection, matchProjection,StringcurrencyCode,Stringlocale erProjection MatchProjection )
throws APINGException
Returns a list of dynamic data about markets. Dynamic data includes prices, the status of the market, the
status of selections, the traded volume, and the status of any orders you have placed in the market.

: Please note Market Data Request Limits apply to requests made to listMarketBook
that include price or order projections.
Calls to should be made up to a maximum of 5 times per second to a listMarketBook
single marketId.
Parameter name Type Required Description
marketIds List<String> One or more market
ids. The number of
markets returned
depends on the amount
of data you request via
the price projection.
priceProjection PriceProjection The projection of price
data you want to
receive in the
response.
orderProjection OrderProjection The orders you want to
receive in the
response.
matchProjection MatchProjection If you ask for orders,
specifies the
representation of
matches.
currencyCode String A Betfair standard
currency code. If not
specified, the default
currency code is used.
locale String The language used for
the response. If not
specified, the default is
returned.
Return type Description
List< > MarketBook output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listMarketCatalogue
Operation
listMarketCatalogue
,Set< >marketP List< > MarketCatalogue listMarketCatalogue ( filter MarketFilter MarketProjection
rojection, sort, ,Stringlocale MarketSort intmaxResults ) throws APINGException
Returns a list of information about markets that does not change (or changes very rarely). You use
listMarketCatalogue to retrieve the name of the market, the names of selections and other information
about markets. apply to requests made to listMarketCatalogue. Market Data Request Limits
Parameter name Type Required Description
filter MarketFilter The filter to select
desired markets. All
markets that match the
criteria in the filter are
selected.
marketProjection Set< MarketProjection
>
The type and amount
of data returned about
the market.
sort MarketSort The order of the
results. Will default to
RANK if not passed
maxResults int limit on the total
number of results
returned, must be
greater than 0 and less
than or equal to 1000
locale String The language used for
the response. If not
specified, the default is
returned.
Return type Description
List< > MarketCatalogue output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listMarketProfitAndLoss

listMarketProfitAndLoss
List< > MarketProfitAndLoss , boolean listMarketProfitAndLoss ( Set< > marketIds MarketId
includeSettledBets, boolean includeBspBets, boolean netOfCommission ) throws APINGException
Retrieve profit and loss for a given list of markets. The values are calculated using matched
bets and optionally settled bets. Only odds ( = ODDS) markets are MarketBettingType
implemented, markets of other types are silently ignored.
: Please note Market Data Request Limitsapply to requests made tolistMarketProfitAndLoss
Parameter name Type Required Description
marketIds Set< > MarketId List of markets to
calculate profit and loss
includeSettledBets boolean Option to include
settled bets (partially
settled markets only).
Defaults to false if not
specified.
includeBspBets boolean Option to include BSP
bets. Defaults to false if
not specified.
netOfCommission boolean Option to return profit
and loss net of users
current commission
rate for this market
including any special
tariffs. Defaults to false
if not specified.
Return type Description
List< > MarketProfitAndLoss
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listMarketTypes
Operation
listMarketTypes
,Stringlocale List< > MarketTypeResult listMarketTypes ( filter MarketFilter ) throws APINGExcepti
on
Returns a list of market types (i.e. MATCH_ODDS, NEXT_GOAL) associated with the markets selected
by the MarketFilter. The market types are always the same, regardless of locale.
Parameter name Type Required Description
filter MarketFilter The filter to select
desired markets. All
markets that match the
criteria in the filter are
selected.
locale String The language used for
the response. If not
specified, the default is
returned.
Return type Description
List< > MarketTypeResult output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listTimeRanges
Operation
listTimeRanges
, List< > TimeRangeResult listTimeRanges ( filter MarketFilter granularity TimeGranularity ) throw
s APINGException
Returns a list of time ranges in the granularity specified in the request (i.e. 3PM to 4PM, Aug 14th to Aug
15th) associated with the markets selected by the MarketFilter.
Parameter name Type Required Description
filter MarketFilter The filter to select
desired markets. All
markets that match the
criteria in the filter are
selected.
granularity TimeGranularity The granularity of time
periods that correspond
to markets selected by
the market filter.
Return type Description
List< > TimeRangeResult output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listVenues
Operation
listVenues
,Stringlocale List< > VenueResult listVenues ( filter MarketFilter ) throws APINGException
Returns a list of Venues (i.e. Cheltenham, Ascot) associated with the markets selected by the
MarketFilter. Currently, only Horse Racing markets are associated with a Venue.
Parameter name Type Required Description
filter MarketFilter The filter to select
desired markets. All
markets that match the
criteria in the filter are
selected.
locale String The language used for
the response. If not
specified, the default is
returned.
Return type Description
List< > VenueResult output data
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
placeOrders
Operation
1.
2.
placeOrders
, ,Stringc PlaceExecutionReport placeOrders ( StringmarketId List< >instructions PlaceInstruction
ustomerRef ) throws APINGException
Place new orders into market. This operation is atomic in that all orders will be placed or none will be
placed. Please note that additional apply to bets placed into the Italian Exchange. bet sizing rules
Parameter name Type Required Description
marketId String The market id these
orders are to be placed
on
instructions List< > PlaceInstruction The number of place
instructions. The limit
of place instructions
per request is 200.
customerRef String Optional parameter
allowing the client to
pass a unique string
(up to 32 chars) that is
used to de-dupe
mistaken
re-submissions.
CustomerRef can
contain: upper/lower
chars, digits, chars : - .
_ + * : ; ~ only.
Return type Description
PlaceExecutionReport
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
Italian Exchange Specific Bet Rules
There are several additional regulatory rules which apply specifically and only to accounts betting on the Italian
Exchange (https://www.betfair.it/exchange):
The stake for each back offer is a minimum of 200 Euro Cents and can only be incremented in multiples of 50
Euro Cents.
Any lay offers placed by the customer, must be placed in such a way as to ensure that the stake for any
2.
3.
corresponding back offer amounts to a minimum of 50 Euro Cents.
We cannot accept betting offers with potential winnings, calculated on the basis of the pre-selected odds, that
exceed the amount envisaged by article 12, paragraph 4, of Finance Minister Decree no. 111 of 1 March
2006 (10,000 Euros). N.B. This does not include stake.
The Italian Exchange isn't available for betting between 0100and 0500 GMT
cancelOrders
Operation
cancelOrders
StringmarketId,List< >instructions,Strin CancelExecutionReport cancelOrders ( CancelInstruction
gcustomerRef ) throws APINGException
Cancel all bets OR cancel all bets on a market OR fully or partially cancel particular orders on a market.
Only LIMIT orders can be cancelled or partially cancelled once placed.
Parameter name Type Required Description
marketId String If not supplied all bets
are cancelled
instructions List< CancelInstruction
>
All instructions need to
be on the same market.
If not supplied all bets
on the market (if
market id is passed)
are fully cancelled.
The limit of cancel
instructions per request
is 60
customerRef String Optional parameter
allowing the client to
pass a unique string
(up to 32 chars) that is
used to de-dupe
mistaken
re-submissions.
Return type Description
CancelExecutionReport
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
replaceOrders
Operation
replaceOrders
, , ReplaceExecutionReport replaceOrders ( StringmarketId List< >instructions ReplaceInstruction
StringcustomerRef ) throws APINGException
This operation is logically a bulk cancel followed by a bulk place. The cancel is completed first then the
new orders are placed. The new orders will be placed atomically in that they will all be placed or none will
be placed. In the case where the new orders cannot be placed the cancellations will not be rolled back.
See ReplaceInstruction.
Parameter name Type Required Description
marketId String The market id these
orders are to be placed
on
instructions List< ReplaceInstructio
> n
The number of replace
instructions. The limit
of replace instructions
per request is 60.
customerRef String Optional parameter
allowing the client to
pass a unique string
(up to 32 chars) that is
used to de-dupe
mistaken
re-submissions.
Return type Description
ReplaceExecutionReport
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
updateOrders
Operation
updateOrders
, ,St UpdateExecutionReport updateOrders ( StringmarketId List< >instructions UpdateInstruction
ringcustomerRef ) throws APINGException
Update non-exposure changing fields
Parameter name Type Required Description
marketId String The market id these
orders are to be placed
on
instructions List< UpdateInstruction
>
The number of update
instructions. The limit
of update instructions
per request is 60
customerRef String Optional parameter
allowing the client to
pass a unique string
(up to 32 chars) that is
used to de-dupe
mistaken
re-submissions.
Return type Description
UpdateExecutionReport
Throws Description
APINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
Betting Exceptions
Exceptions
APINGException
This exception is thrown when an operation fails
Error code Description
TOO_MUCH_DATA The operation requested too much data,
exceeding the Market Data Request Limits.
INVALID_INPUT_DATA Invalid input data
INVALID_SESSION_INFORMATION The session token hasn't been provided, is invalid
or has expired.
NO_APP_KEY An application key header ('X-Application') has
not been provided in the request
NO_SESSION A session token header ('X-Authentication') has
not been provided in the request
UNEXPECTED_ERROR An unexpected internal error occurred that
prevented successful request processing.
INVALID_APP_KEY The application key passed is invalid or is not
present
TOO_MANY_REQUESTS There are too many pending requests e.g. a listM
with Order/Match projections is limited arketBook
to 3 concurrent requests. The error also applies to
, and listCurrentOrders listMarketProfitAndLoss list
if you have 3 or more requests ClearedOrders
currently in execution
SERVICE_BUSY The service is currently too busy to service this
request
TIMEOUT_ERROR Internal call to downstream service timed out
REQUEST_SIZE_EXCEEDS_LIMIT The request exceeds the request size limit.
Requests are limited to a total of 250
betIds/marketIds (or a combination of both)
ACCESS_DENIED The calling client is not permitted to perform the
specific action e.g. the using a Delayed App Key
when placing bets or attempting to place a bet
from a restricted jurisdiction.
Other parameters Type Required Description
errorDetails String the stack trace of the
error
requestUUID String
Generic JSON-RPC Exceptions
Error Code Description
-32700 Invalid JSON was received by the server. An
error occurred on the server while parsing the
JSON text.
-32601 Method not found
-32602 Problem parsing the parameters, or a mandatory
parameter was not found
-32603 Internal JSON-RPC error
Betting Enums
Enums
MarketProjection
Value Description
COMPETITION If not selected then the competition will not be
returned with marketCatalogue
EVENT If not selected then the event will not be returned
with marketCatalogue
EVENT_TYPE If not selected then the eventType will not be
returned with marketCatalogue
MARKET_START_TIME If not selected then the start time will not be
returned with marketCatalogue
MARKET_DESCRIPTION If not selected then the description will not be
returned with marketCatalogue
RUNNER_DESCRIPTION If not selected then the runners will not be
returned with marketCatalogue
RUNNER_METADATA If not selected then the runner metadata will not
be returned with marketCatalogue. If selected
then RUNNER_DESCRIPTION will also be
returned regardless of whether it is included as a
market projection.
PriceData
Value Description
SP_AVAILABLE Amount available for the BSP auction.
SP_TRADED Amount traded in the BSP auction.
EX_BEST_OFFERS Only the best prices available for each runner, to
requested price depth.
EX_ALL_OFFERS EX_ALL_OFFERS trumps EX_BEST_OFFERS if
both settings are present
EX_TRADED Amount traded on the exchange.
MatchProjection
Value Description
NO_ROLLUP No rollup, return raw fragments
ROLLED_UP_BY_PRICE Rollup matched amounts by distinct matched
prices per side.
ROLLED_UP_BY_AVG_PRICE Rollup matched amounts by average matched
price per side
OrderProjection
Value Description
ALL EXECUTABLE and EXECUTION_COMPLETE
orders
EXECUTABLE An order that has a remaining unmatched portion
EXECUTION_COMPLETE An order that does not have any remaining
unmatched portion
MarketStatus
Value Description
INACTIVE Inactive Market
OPEN Open Market
SUSPENDED Suspended Market
CLOSED Closed Market
RunnerStatus
Value Description
ACTIVE ACTIVE
WINNER WINNER
LOSER LOSER
REMOVED_VACANT REMOVED_VACANT applies to Greyhounds.
Greyhound markets always return a fixed number
of runners (traps). If a dog has been removed, the
trap is shown as vacant.
REMOVED REMOVED
HIDDEN The selection is hidden from the market. This
occurs in Horse Racing markets were runners is
hidden when it is doesnt hold an official entry
following an entry stage. This could be because
the horse was never entered or because they
have been scratched from a race at a declaration
stage.
TimeGranularity
Value Description
DAYS
HOURS
MINUTES
Side
Value Description
BACK To back a team, horse or outcome is to bet on the
selection to win.
LAY To lay a team, horse, or outcome is to bet on the
selection to lose.
OrderStatus
Value Description
EXECUTION_COMPLETE An order that does not have any remaining
unmatched portion.
EXECUTABLE An order that has a remaining unmatched portion.
OrderBy
Value Description
BY_BET @Deprecated Use BY_PLACE_TIME instead.
Order by placed time, then bet id.
BY_MARKET Order by market id, then placed time, then bet id.
BY_MATCH_TIME Order by time of last matched fragment (if any),
then placed time, then bet id. Filters out orders
which have no matched date. The dateRange
filter (if specified) is applied to the matched date.
BY_PLACE_TIME Order by placed time, then bet id. This is an alias
of to be deprecated BY_BET. The dateRange
filter (if specified) is applied to the placed date.
BY_SETTLED_TIME Order by time of last settled fragment (if any),
then by last match time, then placed time, then
bet id. Filters out orders which have not been
settled. The dateRange filter (if specified) is
applied to the settled date.
BY_VOID_TIME Order by time of last voided fragment (if any),
then by last match time, then placed time, then
bet id. Filters out orders which have not been
voided. The dateRange filter (if specified) is
applied to the voided date.

SortDir
Value Description
EARLIEST_TO_LATEST Order from earliest value to latest e.g. lowest
betId is first in the results.
LATEST_TO_EARLIEST Order from the latest value to the earliest e.g.
highest betId is first in the results.
OrderType
Value Description
LIMIT A normal exchange limit order for immediate
execution
LIMIT_ON_CLOSE Limit order for the auction (SP)
MARKET_ON_CLOSE Market order for the auction (SP)
MarketSort
Value Description
MINIMUM_TRADED Minimum traded volume
MAXIMUM_TRADED Maximum traded volume
MINIMUM_AVAILABLE Minimum available to match
MAXIMUM_AVAILABLE Maximum available to match
FIRST_TO_START The closest markets based on their expected start
time
LAST_TO_START The most distant markets based on their
expected start time
MarketBettingType
Value Description
ODDS Odds Market
LINE Line Market
RANGE Range Market
ASIAN_HANDICAP_DOUBLE_LINE Asian Handicap Market
ASIAN_HANDICAP_SINGLE_LINE Asian Single Line Market
FIXED_ODDS Sportsbook Odds Market. This type is deprecated
and will be removed in future releases, when
Sportsbook markets will be represented as ODDS
market but with a different product type.
ExecutionReportStatus
Value Description
SUCCESS Order processed successfully
FAILURE Order failed.
PROCESSED_WITH_ERRORS The order itself has been accepted, but at least
one (possibly all) actions have generated errors.
This error only occurs for , replaceOrders cancel
and operations. The Orders updateOrders place
operation will not return Orders
PROCESSED_WITH_ERRORS status as it is an
atomic operation.
TIMEOUT Order timed out.
ExecutionReportErrorCode
Value Description
ERROR_IN_MATCHER The matcher is not healthy
PROCESSED_WITH_ERRORS The order itself has been accepted, but at least
one (possibly all) actions have generated errors
BET_ACTION_ERROR There is an error with an action that has caused
the entire order to be rejected
INVALID_ACCOUNT_STATE Order rejected due to the account's status
(suspended, inactive, dup cards)
INVALID_WALLET_STATUS Order rejected due to the account's wallet's status
INSUFFICIENT_FUNDS Account has exceeded its exposure limit or
available to bet limit
LOSS_LIMIT_EXCEEDED The account has exceed the self imposed loss
limit
MARKET_SUSPENDED Market is suspended
MARKET_NOT_OPEN_FOR_BETTING Market is not open for betting, either inactive,
suspended or closed
DUPLICATE_TRANSACTION duplicate customer referece data submitted
INVALID_ORDER Order cannot be accepted by the matcher due to
the combination of actions. For example, bets
being edited are not on the same market, or order
includes both edits and placement
INVALID_MARKET_ID Market doesn't exist
PERMISSION_DENIED Business rules do not allow order to be placed
DUPLICATE_BETIDS duplicate bet ids found
NO_ACTION_REQUIRED Order hasn't been passed to matcher as system
detected there will be no state change
SERVICE_UNAVAILABLE The requested service is unavailable
REJECTED_BY_REGULATOR The regulator rejected the order. On the Italian
this error will occur if more than 50 Exchange
bets are sent in a single placeOrders request.
PersistenceType
Value Description
LAPSE Lapse the order when the market is turned in-play
PERSIST Persist the order to in-play. The bet will be place
automatically into the in-play market at the start of
the event.
MARKET_ON_CLOSE Put the order into the auction (SP) at turn-in-play
InstructionReportStatus
Value Description
SUCCESS
FAILURE
TIMEOUT
InstructionReportErrorCode
Value Description
INVALID_BET_SIZE bet size is invalid for your currency or your
regulator
INVALID_RUNNER Runner does not exist, includes vacant traps in
greyhound racing
BET_TAKEN_OR_LAPSED Bet cannot be cancelled or modified as it has
already been taken or has lapsed Includes
attempts to cancel/modify market on close BSP
bets and cancelling limit on close BSP bets
BET_IN_PROGRESS No result was received from the matcher in a
timeout configured for the system
RUNNER_REMOVED Runner has been removed from the event
MARKET_NOT_OPEN_FOR_BETTING Attempt to edit a bet on a market that has closed.
LOSS_LIMIT_EXCEEDED The action has caused the account to exceed the
self imposed loss limit
MARKET_NOT_OPEN_FOR_BSP_BETTING Market now closed to bsp betting. Turned in-play
or has been reconciled
INVALID_PRICE_EDIT Attempt to edit down the price of a bsp limit on
close lay bet, or edit up the price of a limit on
close back bet
INVALID_ODDS Odds not on price ladder - either edit or
placement
INSUFFICIENT_FUNDS Insufficient funds available to cover the bet action.
Either the exposure limit or available to bet limit
would be exceeded
INVALID_PERSISTENCE_TYPE Invalid persistence type for this market, e.g.
KEEP for a non bsp market
ERROR_IN_MATCHER A problem with the matcher prevented this action
completing successfully
INVALID_BACK_LAY_COMBINATION The order contains a back and a lay for the same
runner at overlapping prices. This would
guarantee a self match. This also applies to BSP
limit on close bets
ERROR_IN_ORDER The action failed because the parent order failed
INVALID_BID_TYPE Bid type is mandatory
INVALID_BET_ID Bet for id supplied has not been found
CANCELLED_NOT_PLACED Bet cancelled but replacement bet was not placed
RELATED_ACTION_FAILED Action failed due to the failure of a action on
which this action is dependent
NO_ACTION_REQUIRED the action does not result in any state change. eg
changing a persistence to it's current value
RollupModel
Value Description
STAKE The volumes will be rolled up to the minimum
value which is >= rollupLimit.
PAYOUT The volumes will be rolled up to the minimum
value where the payout( price * volume ) is >=
rollupLimit.
MANAGED_LIABILITY The volumes will be rolled up to the minimum
value which is >= rollupLimit, until a lay price
threshold. There after, the volumes will be rolled
up to the minimum value such that the liability >=
a minimum liability. Not supported as yet.
NONE No rollup will be applied. However the volumes
will be filtered by currency specific minimum stake
unless overridden specifically for the channel.
GroupBy
Value Description
EVENT_TYPE A roll up of settled P&L, commission paid and
number of bet orders, on a specified event type
EVENT A roll up of settled P&L, commission paid and
number of bet orders, on a specified event
MARKET A roll up of settled P&L, commission paid and
number of bet orders, on a specified market
SIDE An averaged roll up of settled P&L, and number
of bets, on the specified side of a specified
selection within a specified market, that are either
settled or voided
BET The P&L, commission paid, side and regulatory
information etc, about each individual bet order
BetStatus
Value Description
SETTLED A matched bet that was settled normally
VOIDED A matched bet that was subsequently voided by
Betfair, before, during or after settlement
LAPSED Unmatched bet that was cancelled by Betfair (for
example at turn in play).
CANCELLED Unmatched bet that was cancelled by an explicit
customer action.
Betting Type Definitions
Type definitions
MarketFilter
Field name Type Required Description
textQuery String Restrict markets by any
text associated with the
market such as the
Name, Event,
Competition, etc. You
can include a wildcard
(*) character as long as
it is not the first
character.
exchangeIds Set<String> Restrict markets by the
Exchange where the
market operates. Not
currently in use,
requests for
Australian markets
should be sent to the
Aus Exchange
endpoint.
eventTypeIds Set<String> Restrict markets by
event type associated
with the market. (i.e.,
Football, Hockey, etc)
eventIds Set<String> Restrict markets by the
event id associated
with the market.
competitionIds Set<String> Restrict markets by the
competitions
associated with the
market.
marketIds Set<String> Restrict markets by the
market id associated
with the market.
venues Set<String> Restrict markets by the
venue associated with
the market. Currently
only Horse Racing
markets have venues.
bspOnly boolean Restrict to bsp markets
only, if True or non-bsp
markets if False. If not
specified then returns
both BSP and non-BSP
markets
turnInPlayEnabled boolean Restrict to markets that
will turn in play if True
or will not turn in play if
false. If not specified,
returns both.
inPlayOnly boolean Restrict to markets that
are currently in play if
True or are not
currently in play if false.
If not specified, returns
both.
marketBettingTypes Set< MarketBettingTyp
> e
Restrict to markets that
match the betting type
of the market (i.e.
Odds, Asian Handicap
Singles, or Asian
Handicap Doubles
marketCountries Set<String> Restrict to markets that
are in the specified
country or countries
marketTypeCodes Set<String> Restrict to markets that
match the type of the
market (i.e.,
MATCH_ODDS,
HALF_TIME_SCORE).
You should use this
instead of relying on
the market name as the
market type codes are
the same in all locales
marketStartTime TimeRange Restrict to markets with
a market start time
before or after the
specified date
withOrders Set< > OrderStatus Restrict to markets that
I have one or more
orders in these status.
MarketCatalogue
Information about a market
Field name Type Required Description
marketId String The unique identifier for
the market
marketName String The name of the
market
marketStartTime Date The time this market
starts at, only returned
when the
MARKET_START_TIM
E enum is passed in
the marketProjections
description MarketDescription Details about the
market
totalMatched Double The total amount of
money matched on the
market
runners List< > RunnerCatalog The runners
(selections) contained
in the market
eventType EventType The Event Type the
market is contained
within
competition Competition The competition the
market is contained
within. Usually only
applies to Football
competitions
event Event The event the market is
contained within
MarketBook
The dynamic data in a market
Field name Type Required Description
marketId String The unique identifier for
the market. MarketId's
are prefixed with '1.' or
'2.' 1. = UK Exchange
2. = AUS Exchange.
isMarketDataDelayed boolean True if the data
returned by
listMarketBook will be
delayed. The data may
be delayed because
you are not logged in
with a funded account
or you are using an
Application Key that
does not allow up to
date data.
status MarketStatus The status of the
market, for example
ACTIVE,
SUSPENDED,
SETTLED, etc.
betDelay int The number of seconds
an order is held until it
is submitted into the
market. Orders are
usually delayed when
the market is in-play
bspReconciled boolean True if the market
starting price has been
reconciled
complete boolean If false, runners may be
added to the market
inplay boolean True if the market is
currently in play
numberOfWinners int The number of
selections that could be
settled as winners
numberOfRunners int The number of runners
in the market
numberOfActiveRunner
s
int The number of runners
that are currently
active. An active runner
is a selection available
for betting
lastMatchTime Date The most recent time
an order was executed
totalMatched double The total amount
matched
totalAvailable double The total amount of
orders that remain
unmatched
crossMatching boolean True if cross matching
is enabled for this
market.
runnersVoidable boolean True if runners in the
market can be voided
version long The version of the
market. The version
increments whenever
the market status
changes, for example,
turning in-play, or
suspended when a
goal score.
runners List< > Runner Information about the
runners (selections) in
the market.
RunnerCatalog
Information about the Runners (selections) in a market
Field name Type Required Description
selectionId long The unique id for the
selection.
runnerName String The name of the runner
handicap double The handicap
sortPriority int The sort priority of this
runner
metadata Map<String,String> Metadata associated
with the runner. For a
description of this data
for Horse Racing,
please see Runner
Metadata Description
Runner
The dynamic data about runners in a market
Field name Type Required Description
selectionId long The unique id of the
runner (selection)
handicap double The handicap. Enter
the specific handicap
value (returned by
RUNNER in listMaketB
) if the market is an ook
Asian handicap market.
status RunnerStatus The status of the
selection (i.e., ACTIVE,
REMOVED, WINNER,
LOSER, HIDDEN)
Runner status
information is available
for 90 days following
market settlement.
adjustmentFactor double The adjustment factor
applied if the selection
is removed
lastPriceTraded double The price of the most
recent bet matched on
this selection
totalMatched double The total amount
matched on this runner
removalDate Date If date and time the
runner was removed
sp StartingPrices The BSP related prices
for this runner
ex ExchangePrices The Exchange prices
available for this runner
orders List< > Order List of orders in the
market
matches List< > Match List of matches (i.e,
orders that have been
fully or partially
executed)
RunnerDescription
Field name Type Required Description
runnerName String The name of the runner
metadata Map<String,String> The for this metadata
runner, such as horse
racing silks.
StartingPrices
Information about the Betfair Starting Price. Only available in BSP markets
Field name Type Required Description
nearPrice double What the starting price
would be if the market
was reconciled now
taking into account the
SP bets as well as
unmatched exchange
bets on the same
selection in the
exchange.
farPrice double What the starting price
would be if the market
was reconciled now
taking into account only
the currently place SP
bets. The Far Price is
not as complicated but
not as accurate and
only accounts for
money on the
exchange at SP.
backStakeTaken List< > PriceSize The back bets matched
at the actual Betfair
Starting Price
layLiabilityTaken List< > PriceSize The lay amount
matched at the actual
Betfair Starting Price
actualSP double The final BSP price for
this runner. Only
available for a BSP
market that has been
reconciled.
ExchangePrices
Field name Type Required Description
availableToBack List< > PriceSize
availableToLay List< > PriceSize
tradedVolume List< > PriceSize
Event
Event
Field name Type Required Description
id String The unique id for the
event
name String The name of the event
countryCode String The ISO-2 code for the
event. A list of ISO-2
codes is available via h
ttp://en.wikipedia.org/wi
ki/ISO_3166-1_alpha-2
timezone String The timezone in which
the event is taking
place
venue String venue
openDate Date The scheduled start
date and time of the
event.
EventResult
Event Result
Field name Type Required Description
event Event Event
marketCount int Count of markets
associated with this
event
Competition
Competition
Field name Type Required Description
id String id
name String name
CompetitionResult
Competition Result
Field name Type Required Description
competition Competition Competition
marketCount int Count of markets
associated with this
competition
competitionRegion String Region in which this
competition is
happening
EventType
EventType
Field name Type Required Description
id String id
name String name
EventTypeResult
EventType Result
Field name Type Required Description
eventType EventType The ID identifying the
Event Type
marketCount int Count of markets
associated with this
eventType
MarketTypeResult
MarketType Result
Field name Type Required Description
marketType String Market Type
marketCount int Count of markets
associated with this
marketType
CountryCodeResult
CountryCode Result
Field name Type Required Description
countryCode String The ISO-2 code for the
event. A list of ISO-2
codes is available via h
ttp://en.wikipedia.org/wi
ki/ISO_3166-1_alpha-2
marketCount int Count of markets
associated with this
Country Code
VenueResult
Venue Result
Field name Type Required Description
venue String Venue
marketCount int Count of markets
associated with this
Venue
TimeRange
TimeRange
Field name Type Required Description
from Date from
to Date to
TimeRangeResult
TimeRange Result
Field name Type Required Description
timeRange TimeRange TimeRange
marketCount int Count of markets
associated with this
TimeRange
Order
Field name Type Required Description
betId String
orderType OrderType BSP Order type.
status OrderStatus Either EXECUTABLE
(an unmatched amount
remains) or
EXECUTION_COMPL
ETE (no unmatched
amount remains).
persistenceType PersistenceType What to do with the
order at turn-in-play
side Side Indicates if the bet is a
Back or a LAY
price double The price of the bet.
size double The size of the bet.
bspLiability double Not to be confused with
size. This is the liability
of a given BSP bet.
placedDate Date The date, to the
second, the bet was
placed.
avgPriceMatched double The average price
matched at. Voided
match fragments are
removed from this
average calculation.
sizeMatched double The current amount of
this bet that was
matched.
sizeRemaining double The current amount of
this bet that is
unmatched.
sizeLapsed double The current amount of
this bet that was
lapsed.
sizeCancelled double The current amount of
this bet that was
cancelled.
sizeVoided double The current amount of
this bet that was
voided.
Match
An individual bet Match, or rollup by price or avg price. Rollup depends on the requested MatchProjection
Field name Type Required Description
betId String Only present if no
rollup
matchId String Only present if no
rollup
side Side Indicates if the bet is a
Back or a LAY
price double Either actual match
price or avg match
price depending on
rollup.
size double Size matched at in this
fragment, or at this
price or avg price
depending on rollup
matchDate Date Only present if no
rollup

MarketDescription
Market definition
Field name Type Required Description
persistenceEnabled boolean If 'true' the market
supports 'Keep' bets if
the market is to be
turned in-play
bspMarket boolean If 'true' the market
supports Betfair SP
betting
marketTime Date The market start time
suspendTime Date The market suspend
time
settleTime Date settled time
bettingType MarketBettingType See MarketBettingType
turnInPlayEnabled boolean If 'true' the market is
set to turn in-play
marketType String Market base type
regulator String The market regulator
marketBaseRate double The commission rate
applicable to the
market
discountAllowed boolean Indicates whether or
not the user's discount
rate is taken into
account on this market.
If false all users will be
charged the same
commission rate,
regardless of discount
rate.
wallet String The wallet to which the
market belongs
(UK/AUS)
rules String The market rules.
rulesHasDate boolean
clarifications String Any additional
information regarding
the market
MarketRates
Market Rates
Field name Type Required Description
marketBaseRate double marketBaseRate
discountAllowed boolean discountAllowed
MarketLicence
Market Licence
Field name Type Required Description
wallet String The wallet from which
funds will be taken
when betting on this
market
rules String The rules for this
market
rulesHasDate boolean The market's start date
and time are relevant to
the rules.
clarifications String Clarifications to the
rules for the market
MarketLineRangeInfo
Market Line and Range Info
Field name Type Required Description
maxUnitValue double maxPrice
minUnitValue double minPrice
interval double interval
marketUnit String unit
PriceSize
Field name Type Required Description
price double
size double
ClearedOrderSummary
Summary of a cleared order.
Field name Type Required Description
eventTypeId EventTypeId The id of the event type
bet on. Available at
EVENT_TYPE groupBy
level or lower.
eventId EventId The id of the event bet
on. Available at EVENT
groupBy level or lower.
marketId MarketId The id of the market
bet on. Available at
MARKET groupBy level
or lower.
selectionId SelectionId The id of the selection
bet on. Available at
RUNNER groupBy
level or lower.
handicap Handicap The id of the market
bet on. Available at
MARKET groupBy level
or lower.
betId BetId The id of the bet.
Available at BET
groupBy level.
placedDate Date The date the bet order
was placed by the
customer. Only
available at BET
groupBy level.
persistenceType PersistenceType The turn in play
persistence state of the
order at bet placement
time. This field will be
empty or omitted on
true SP bets. Only
available at BET
groupBy level.
orderType OrderType The type of bet (e.g
standard limited-liability
Exchange bet (LIMIT),
a standard BSP bet
(MARKET_ON_CLOS
E), or a
minimum-accepted-pric
e BSP bet
(LIMIT_ON_CLOSE)).
If the bet has a
OrderType of
MARKET_ON_CLOSE
and a persistenceType
of
MARKET_ON_CLOSE
then it is a bet which
has transitioned from
LIMIT to
MARKET_ON_CLOSE.
Only available at BET
groupBy level.
side Side Whether the bet was a
back or lay bet.
Available at SIDE
groupBy level or lower.
itemDescription ItemDescription A container for all the
ancillary data and
localised text valid for
this Item
priceRequested Price The average requested
price across all settled
bet orders under this
Item. Available at SIDE
groupBy level or lower.
settledDate Date The date and time the
bet order was settled
by Betfair. Available at
SIDE groupBy level or
lower.
betCount int The number of actual
bets within this
grouping (will be 1 for
BET groupBy)
commission Size The cumulative amount
of commission paid by
the customer across all
bets under this Item, in
the account currency.
Available at
EXCHANGE,
EVENT_TYPE, EVENT
and MARKET level
groupings only.
priceMatched Price The average matched
price across all settled
bets or bet fragments
under this Item.
Available at SIDE
groupBy level or lower.
priceReduced boolean If true, then the
matched price was
affected by a reduction
factor due to of a
runner removal from
this Horse Racing
market.
sizeSettled Size The cumulative bet size
that was settled as
matched or voided
under this Item, in the
account currency.
Available at SIDE
groupBy level or lower.
profit Size The profit or loss
(negative profit) gained
on this line, in the
account currency
sizeCancelled Size The amount of the bet
that was available to be
matched, before
cancellation or lapsing,
in the account currency
ClearedOrderSummaryReport
A container representing search results.
Field name Type Required Description
clearedOrders List<ClearedOrderSum
> mary
The list of cleared
orders returned by your
query. This will be a
valid list (i.e. empty or
non-empty but never
'null').
moreAvailable boolean Indicates whether there
are further result items
beyond this page. Note
that underlying data is
highly time-dependent
and the subsequent
search orders query
might return an empty
result.
ItemDescription
This object contains some text which may be useful to render a betting history view. It offers no long-term
warranty as to the correctness of the text.
Field name Type Required Description
eventTypeDesc String The event type name,
translated into the
requested locale.
Available at
EVENT_TYPE groupBy
or lower.
eventDesc String The eventName, or
openDate + venue,
translated into the
requested locale.
Available at EVENT
groupBy or lower.
marketDesc String The market name or
racing market type
("Win", "To Be Placed
(2 places)", "To Be
Placed (5 places)" etc)
translated into the
requested locale.
Available at MARKET
groupBy or lower.
marketStartTime Date The start time of the
market (in ISO-8601
format, not translated).
Available at MARKET
groupBy or lower.
runnerDesc String The runner name,
maybe including the
handicap, translated
into the requested
locale. Available at
BET groupBy.
numberOfWinners int The numberOfWinners
on a market. Available
at BET groupBy.
RunnerId
This object contains the unique identifier for a runner
Field name Type Required Description
marketId MarketId The id of the market
bet on
selectionId SelectionId The id of the selection
bet on
handicap Handicap The handicap
associated with the
runner in case of asian
handicap markets, null
otherwise.
CurrentOrderSummaryReport
A container representing search results.
Field name Type Required Description
currentOrders List< CurrentOrderSum
> mary
The list of current
orders returned by your
query. This will be a
valid list (i.e. empty or
non-empty but never
'null').
moreAvailable boolean Indicates whether there
are further result items
beyond this page. Note
that underlying data is
highly time-dependent
and the subsequent
search orders query
might return an empty
result.
CurrentOrderSummary
Summary of a current order.
Field name Type Required Description
betId String The bet ID of the
original place order.
marketId String The market id the order
is for.
selectionId long The selection id the
order is for.
handicap double The handicap of the
bet.
priceSize PriceSize The price and size of
the bet.
bspLiability double Not to be confused with
size. This is the liability
of a given BSP bet.
side Side BACK/LAY
status OrderStatus Either EXECUTABLE
(an unmatched amount
remains) or
EXECUTION_COMPL
ETE (no unmatched
amount remains).
persistenceType PersistenceType What to do with the
order at turn-in-play.
orderType OrderType BSP Order type.
placedDate Date The date, to the
second, the bet was
placed.
matchedDate Date The date, to the
second, of the last
matched bet fragment
(where applicable)
averagePriceMatched double The average price
matched at. Voided
match fragments are
removed from this
average calculation.
sizeMatched double The current amount of
this bet that was
matched.
sizeRemaining double The current amount of
this bet that is
unmatched.
sizeLapsed double The current amount of
this bet that was
lapsed.
sizeCancelled double The current amount of
this bet that was
cancelled.
sizeVoided double The current amount of
this bet that was
voided.
regulatorAuthCode String The regulator
authorisation code.
regulatorCode String The regulator Code.
PlaceInstruction
Instruction to place a new order
Field name Type Required Description
orderType OrderType
selectionId long The selection_id.
handicap double The handicap applied
to the selection, if on
an asian-style market.
side Side Back or Lay
limitOrder LimitOrder A simple exchange bet
for immediate
execution
limitOnCloseOrder LimitOnCloseOrder Bets are matched if,
and only if, the returned
starting price is better
than a specified price.
In the case of back
bets, LOC bets are
matched if the
calculated starting price
is greater than the
specified price. In the
case of lay bets, LOC
bets are matched if the
starting price is less
than the specified
price. If the specified
limit is equal to the
starting price, then it
may be matched,
partially matched, or
may not be matched at
all, depending on how
much is needed to
balance all bets against
each other (MOC, LOC
and normal exchange
bets)
marketOnCloseOrder MarketOnCloseOrder Bets remain
unmatched until the
market is reconciled.
They are matched and
settled at a price that is
representative of the
market at the point the
market is turned
in-play. The market is
reconciled to find a
starting price and MOC
bets are settled at
whatever starting price
is returned. MOC bets
are always matched
and settled, unless a
starting price is not
available for the
selection. Market on
Close bets can only be
placed before the
starting price is
determined
PlaceExecutionReport
Field name Type Required Description
customerRef String Echo of the
customerRef if passed.
status ExecutionReportStatus
errorCode ExecutionReportErrorC
ode

marketId String Echo of marketId
passed
instructionReports List< PlaceInstructionR
> eport

LimitOrder
Place a new LIMIT order (simple exchange bet for immediate execution)
Field name Type Required Description
size double The size of the bet.
price double The limit price
persistenceType PersistenceType What to do with the
order at turn-in-play
LimitOnCloseOrder
Place a new LIMIT_ON_CLOSE bet
Field name Type Required Description
liability double The size of the bet.
price double The limit price of the
bet if LOC
MarketOnCloseOrder
Place a new MARKET_ON_CLOSE bet
Field name Type Required Description
liability double The size of the bet.
PlaceInstructionReport
Response to a PlaceInstruction
Field name Type Required Description
status InstructionReportStatus whether the command
succeeded or failed
errorCode InstructionReportError
Code
cause of failure, or null
if command succeeds
instruction PlaceInstruction The instruction that
was requested
betId String The bet ID of the new
bet. May be null on
failure.
placedDate Date The date on which the
bet was placed
averagePriceMatched double The average price
matched
sizeMatched double The size matched.
CancelInstruction
Instruction to fully or partially cancel an order (only applies to LIMIT orders)
Field name Type Required Description
betId String The betId
sizeReduction double If supplied then this is a
partial cancel. Should
be set to 'null' if no size
reduction is required.
CancelExecutionReport
Field name Type Required Description
customerRef String Echo of the
customerRef if passed.
status ExecutionReportStatus
errorCode ExecutionReportErrorC
ode

marketId String Echo of marketId
passed
instructionReports List< CancelInstruction
> Report

ReplaceInstruction
Instruction to replace a LIMIT or LIMIT_ON_CLOSE order at a new price. Original order will be cancelled
and a new order placed at the new price for the remaining stake.
Field name Type Required Description
betId String Unique identifier for the
bet
newPrice double The price to replace the
bet at
ReplaceExecutionReport
Field name Type Required Description
customerRef String Echo of the
customerRef if passed.
status ExecutionReportStatus
errorCode ExecutionReportErrorC
ode

marketId String Echo of marketId
passed
instructionReports List< ReplaceInstructio
> nReport

ReplaceInstructionReport
Field name Type Required Description
status InstructionReportStatus whether the command
succeeded or failed
errorCode InstructionReportError
Code
cause of failure, or null
if command succeeds
cancelInstructionReport CancelInstructionRepor
t
Cancelation report for
the original order
placeInstructionReport PlaceInstructionReport Placement report for
the new order
CancelInstructionReport
Field name Type Required Description
status InstructionReportStatus whether the command
succeeded or failed
errorCode InstructionReportError
Code
cause of failure, or null
if command succeeds
instruction CancelInstruction The instruction that
was requested
sizeCancelled double
cancelledDate Date
UpdateInstruction
Instruction to update LIMIT bet's persistence of an order that do not affect exposure
Field name Type Required Description
betId String Unique identifier for the
bet
newPersistenceType PersistenceType The new persistence
type to update this bet
to
UpdateExecutionReport
Field name Type Required Description
customerRef String Echo of the
customerRef if passed.
status ExecutionReportStatus
errorCode ExecutionReportErrorC
ode

marketId String Echo of marketId
passed
instructionReports List< UpdateInstruction
> Report

UpdateInstructionReport
Field name Type Required Description
status InstructionReportStatus whether the command
succeeded or failed
errorCode InstructionReportError
Code
cause of failure, or null
if command succeeds
instruction UpdateInstruction The instruction that
was requested

PriceProjection
Selection criteria of the returning price data
Field name Type Required Description
priceData Set< > PriceData The basic price data
you want to receive in
the response.
exBestOffersOverrides ExBestOffersOverrides Options to alter the
default representation
of best offer prices
Applicable to
EX_BEST_OFFERS
priceData selection
virtualise boolean Indicates if the returned
prices should include vi
. Applicable rtual prices
to EX_BEST_OFFERS
and EX_ALL_OFFERS
priceData selections,
default value is false.
rolloverStakes boolean Indicates if the volume
returned at each price
point should be the
absolute value or a
cumulative sum of
volumes available at
the price and all better
prices. If unspecified
defaults to false.
Applicable to
EX_BEST_OFFERS
and EX_ALL_OFFERS
price projections. Not
supported as yet.
ExBestOffersOverrides
Options to alter the default representation of best offer prices
Field name Type Required Description
bestPricesDepth int The maximum number
of prices to return on
each side for each
runner. If unspecified
defaults to 3.
rollupModel RollupModel The model to use when
rolling up available
sizes. If unspecified
defaults to STAKE
rollup model with
rollupLimit of minimum
stake in the specified
currency.
rollupLimit int The volume limit to use
when rolling up
returned sizes. The
exact definition of the
limit depends on the
rollupModel. If no limit
is provided it will use
minimum stake as
default the value.
Ignored if no rollup
model is specified.
rollupLiabilityThreshold double Only applicable when
rollupModel is
MANAGED_LIABILITY.
The rollup model
switches from being
stake based to liability
based at the smallest
lay price which is >=
rollupLiabilityThreshold
.service level default
(TBD). Not supported
as yet.
rollupLiabilityFactor int Only applicable when
rollupModel is
MANAGED_LIABILITY.
(rollupLiabilityFactor *
rollupLimit) is the
minimum liabilty the
user is deemed to be
comfortable with. After
the
rollupLiabilityThreshold
price subsequent
volumes will be rolled
up to minimum value
such that the liability >=
the minimum
liability.service level
default (5). Not
supported as yet.

MarketProfitAndLoss
Profit and loss in a market
Field name Type Required Description
marketId String The unique identifier for
the market
commissionApplied double The commission rate
applied to P&L values.
Only returned if
netOfCommision option
is requested
profitAndLosses List<RunnerProfitAndL
> oss
Calculated profit and
loss data.
RunnerProfitAndLoss
Profit and loss if selection is wins or loses

Field name Type Required Description

selectionId SelectionId The unique identifier for
the selection
ifWin double Profit and loss for the
market if this selection
is the winner
ifLose double Profit and loss for the
market if this selection
is the loser. Only
returned for
multi-winner odds
markets.
Type Aliases
Alias Type
MarketType
String
Venue
String
MarketId
String
SelectionId
long
Handicap
double
EventId
String
EventTypeId
String
CountryCode
String
ExchangeId
String
CompetitionId
String
Price
double
Size
double
BetId
String
MatchId
String
Accounts API
Please find below the details for the current Accounts API endpoints for the UK & Australian Exchange:
You can make requests for your UK Exchange wallet information by accessing the UK Exchange via the following
endpoints.
UK Exchange
Interface Endpoint JSON-RPC Prefix <methodname>
Example
JSON-RPC https://api.betfair.com/exc
hange/account/json-rpc/v1
<methodname> AccountAPING/v1.0/ge
tAccountFunds
JSON REST https://api.betfair.com/exc
hange/account/rest/v1.0

You can make requests for your Aus Exchange wallet information by accessing the Aus Exchange via the following
endpoints.
Australian Exchange
Interface Endpoint JSON-RPC Prefix <methodname>
Example
JSON-RPC https://api-au.betfair.com/
exchange/account/json-rp
c/v1
<methodname> AccountAPING/v1.0/getA
ccountFunds
JSON REST https://api-au.betfair.com/
exchange/account/rest/v1.
0

*Please note the getAccountFunds operations for the Australian Exchange doesnt currently return details
from the Australian wallet. This is due to be rectified in a future release.
Accounts Operations
Operation summary
DeveloperApp createDeveloperAppKeys (String
appName )

List< > DeveloperApp getDeveloperAppKeys ( )

AccountFundsResponse getAccountFunds ( )
AccountDetailsResponse getAccountDetails ( )
String getVendorClientId ( )
String getApplicationSubscriptionToken (
intsubscriptionLength )
Available to owner managed
(Vendor) App Keys Only
Status activateApplicationSubscription (
StringsubscriptionToken )

Status cancelApplicationSubscription (
StringsubscriptionToken )
Available to owner managed
(Vendor) App Keys Only
List< > ApplicationSubscription listApplicationSubscriptionTokens (
subscriptionStat SubscriptionStatus
us )

List< > AccountSubscription listAccountSubscriptionTokens ( ) Available to owner managed

(Vendor) App Keys Only
List< > SubscriptionHistory getApplicationSubscriptionHistory (
String vendorClientId )
Available to owner managed
(Vendor) App Keys Only
AccountStatementReport getAccountStatement(String
locale, int fromRecord, int
recordCount, itemDate TimeRange
Range, includeItem, IncludeItem Wa
lletwallet )

List< > CurrencyRate listCurrencyRates String (

fromCurrency)

createDeveloperAppKeys
Operation
createDeveloperAppKeys
DeveloperApp createDeveloperAppKeys ( String appName ) throws AccountAPINGException
Create 2 application keys for given user; one active and the other delayed
Parameter name Type Required Description
appName String A Display name for the
application.
Return type Description
DeveloperApp A map of application keys, one marked ACTIVE,
and the other DELAYED
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
getAccountDetails
Operation

getAccountDetails
AccountDetailsResponse getAccountDetails () throws AccountAPINGException
Returns the details relating your account, including your discount rate and Betfair point balance.
Return type Description
AccountDetailsResponse Response for retrieving account details.
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
Please note: The data returned by relies on two underlying services. The getAccountDetails p
is returned by a separate service from the other data. ointsBalance
As a consequence of this, in the event of a failure to a single underlying service, either the point
sBalance or the remaining data may not be included in the getAccountDetails response. If both
services fail, the error UNEXPECTED_ERROR will be returned.

getAccountFunds
Operation
getAccountFunds
AccountFundsResponse getAccountFunds ( ) throws AccountAPINGException
Get available to bet amount.
Return type Description
AccountFundsResponse Response for retrieving available to bet.
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
getDeveloperAppKeys
Operation
getDeveloperAppKeys
List< > DeveloperApp getDeveloperAppKeys ( ) throws AccountAPINGException
Get all application keys owned by the given developer/vendor
Return type Description
List< > DeveloperApp A list of application keys owned by the given
developer/vendor
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
getAccountStatement
getAccountStatement
AccountStatementReport String locale, int fromRecord, int recordCount, getAccountStatement ( Time
itemDateRange, includeItem, wallet Range IncludeItem Wallet ) throwsAccountAPINGException
Get account statement
Parameter name Type Required Description
locale String The language to be
used where applicable.
If not specified, the
customer account
default is returned.
fromRecord int Specifies the first
record that will be
returned. Records start
at index zero. If not
specified then it will
default to 0.
recordCount int Specifies the maximum
number of records to
be returned. Note that
there is a page size
limit of 100.
itemDateRange TimeRange Return items with an
itemDate within this
date range. Both from
and to date times are
inclusive. If from is not
specified then the
oldest available items
will be in range. If to is
not specified then the
latest items will be in
range. nb. This
itemDataRange is
currently only applied
when includeItem is set
to ALL or not specified,
else items are NOT
bound by itemDate.
includeItem IncludeItem Which items to include,
if not specified then
defaults to ALL.
wallet Wallet Which wallet to return
statementItems for. If
unspecified then the
UK wallet will be
selected
Return type Description
AccountStatementReport List of statement items chronologically ordered
plus moreAvailable boolean to facilitate paging
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
listCurrencyRates
listCurrencyRates
List< > CurrencyRate listCurrencyRates(String fromCurrency)throwsAccountAPINGException
Returns a list of currency rates based on given currency
Parameter name Type Required Description
fromCurrency String The currency from
which the rates are
computed. Please
GBP is currently note:
the only based
currency support
Return type Description
List< > CurrencyRate List of currency rates
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Account Operations (Vendor API)
Details of Account Operations that are applicable to licensed API software vendors only.
Required Headers
Please note - although the majority of API-NG calls require both the (sessionT X-Authentication
oken) and (Application Key) in the request header, this isn't applicable for some X-Application
Vendor API Account Operations. The applicable headers for each Vendor API operation are
included in the below table
X-Authentication X-Application
String getVendorClientId (
)

String getApplicationSubsc
riptionToken (
intsubscriptionLengt
h )
Available to owner
managed (Vendor)
App Keys Only
Status activateApplicationS
ubscription (
StringsubscriptionTo
ken )

Status cancelApplicationSu
bscription (
StringsubscriptionTo
ken )
Available to owner
managed (Vendor)
App Keys Only
List< ApplicationSub
> scription
listApplicationSubsc
riptionTokens ( Sub
subs scriptionStatus
criptionStatus )
Available to owner
managed (Vendor)
App Keys Only
List<AccountSubscr
> iption
listAccountSubscript
ionTokens( )

List<SubscriptionHis
> tory
getApplicationSubsc
riptionHistory (
String
vendorClientId )
Available to owner
managed (Vendor)
App Keys Only

activateApplicationSubscription
Operation
activateApplicationSubscription
Status activateApplicationSubscription ( String subscriptionToken ) throws AccountAPINGExcept
ion
Activates the customers subscription token for an application. The request is made by the customers
account using their session token (X-Authentication header) only.
Parameter name Type Required Description
subscriptionToken String Subscription token for
activation
Return type Description
Status
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
cancelApplicationSubscription
Operation
cancelApplicationSubscription
Status cancelApplicationSubscription ( String subscriptionToken ) throws AccountAPINGExcepti
on
Cancel the subscription token. The customers subscription will no longer be active once cancelled.
Parameter name Type Required Description
subscriptionToken String Subscription token to
cancel
Return type Description
Status
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
getApplicationSubscriptionHistory
getApplicationSubscriptionHistory
List< > SubscriptionHistory getApplicationSubscriptionHistory ( String vendorClientId ) throws Ac
countAPINGException
Returns a list of subscriptions tokens that have been associated with the customers account. This allows
a vendor to identify if a customer has a previous subscription to their application and the status of each
subscription.
Parameter name Type Required Description
vendorClientId
applicationKey

String
String
The unique customer
identifier
i The unique application
dentifier
Return type Description
List< > SubscriptionHistory List of subscription tokens associated with the
account

Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.

*Since *
getApplicationSubscriptionToken
Operation
getApplicationSubscriptionToken
int subscriptionLength String getApplicationSubscriptionToken ( ) throws AccountAPINGExcepti
on
Used to create new subscription tokens for an application. Returns the newly generated subscription
token which can be provided to the end user.
Parameter name Type Required Description
subscriptionLength int How many days the
subscription should
last. Open ended if
value not supplied.
Expiry time will be
rounded up to midnight
on the date of expiry.
clientReference String Any client reference for
this subscription token
request.
Return type Description
String Subscription token
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
getVendorClientId
getVendorClientId
String getVendorClientId ( ) throws AccountAPINGException
Returns the vendor client id for customer account which is a unique identifier for that customer. The
vendor client Id can be used to obtain the customers application subscription history via getApplicationSu
The request requires the X-Authentication header only bscriptionHistory.
Return type Description
String Vendor client id.

Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listAccountSubscriptionTokens
Operation
listAccountSubscriptionTokens
List< > AccountSubscription listAccountSubscriptionTokens ( ) throws AccountAPINGException
List of subscription tokens associated with the account
Return type Description
List< > AccountSubscription List of subscription tokens associated with the
account
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
listApplicationSubscriptionTokens
Operation
listApplicationSubscriptionTokens
subscrip List< > ApplicationSubscription listApplicationSubscriptionTokens ( SubscriptionStatus
tionStatus ) throws AccountAPINGException
Returns a list of subscription tokens for an application based on the subscription status passed in the
request. Returns all subscription token details, including the client reference and vendor client Id
associated with the subscription token.
Parameter name Type Required Description
subscriptionStatus SubscriptionStatus Optionally filter
response by
Subscription status of
the token
Return type Description
List< > ApplicationSubscription List of subscription tokens for an application
Throws Description
AccountAPINGException Generic exception that is thrown if this operation
fails for any reason.
Since 1.0.0
Accounts Exceptions
Exceptions
AccountAPINGException
This exception is thrown when an operation fails
Error code Description
INVALID_INPUT_DATA Invalid input data
INVALID_SESSION_INFORMATION The session token hasn't been provided, is invalid
or has expired.
UNEXPECTED_ERROR An unexpected internal error occurred that
prevented successful request processing.
INVALID_APP_KEY The application key passed is invalid or is not
present
SERVICE_BUSY The service is currently too busy to service this
request
TIMEOUT_ERROR Internal call to downstream service timed out
DUPLICATE_APP_NAME Duplicate application name
APP_KEY_CREATION_FAILED Creating application key version has failed
APP_CREATION_FAILED Application creation has been failed
NO_SESSION A session token header ('X-Authentication') has
not been provided in the request
NO_APP_KEY An application key header ('X-Application') has
not been provided in the request
SUBSCRIPTION_EXPIRED An application key is required for this operation
INVALID_SUBSCRIPTION_TOKEN The subscription token provided doesn't exist
TOO_MANY_REQUESTS Too many requests
Other parameters Type Required Description
errorDetails String the stack trace of the
error
requestUUID String
Accounts Enums
Enums
SubscriptionStatus
Value Description
ALL Any subscription status
ACTIVATED Only activated subscriptions
UNACTIVATED Only unactivated subscriptions
CANCELLED Only cancelled subscriptions
EXPIRED Only expired subscriptions
Status
Value Description
SUCCESS Sucess status
ItemClass
Value Description
UNKNOWN Statement item not mapped to a specific class. All
values will be concatenated into a single
key/value pair. The key will be
'unknownStatementItem' and the value will be a
comma separated string.

Wallet
Value Description
UK The UK Exchange wallet
AUSTRALIAN The Australian Exchange wallet
IncludeItem
Value Description
ALL Include all items
DEPOSITS_WITHDRAWALS Include payments only
EXCHANGE Include exchange bets only
POKER_ROOM Include poker transactions only
Accounts TypeDefinitions
Type definitions
ApplicationSubscription
Application subscription details
Field name Type Required Description
subscriptionToken String Application key
identifier
expiryDateTime Date Subscription Expiry
date
expiredDateTime Date Subscription Expired
date
createdDateTime Date Subscription Create
date
activationDateTime Date Subscription Activation
date
cancellationDateTime Date Subscription Cancelled
date
subscriptionStatus SubscriptionStatus Subscription status
clientReference String Client reference
vendorClientId String Vendor client Id
Subscription History
Application subscription history details
Field name Type Required Description
subscriptionToken String Application key
identifier
expiryDateTime Date Subscription Expiry
date
expiredDateTime Date Subscription Expired
date
createdDateTime Date Subscription Create
date
activationDateTime Date Subscription Activation
date
cancellationDateTime Date Subscription Cancelled
date
subscriptionStatus SubscriptionStatus Subscription status
clientReference String Client reference

AccountSubscription
Application subscription details
Field name Type Required Description
subscriptionTokens List< SubscriptionToke
> nInfo
Lis t of subscription
token details
applicationName String Application name
applicationVersionId String Application version Id
SubscriptionTokenInfo
Subscription token information
Field name Type Required Description
subscriptionToken String Subscription token
activatedDateTime Date Subscription Activated
date
expiryDateTime Date Subscription Expiry
date
expiredDateTime Date Subscription Expired
date
cancellationDateTime Date Subscription Cancelled
date
subscriptionStatus SubscriptionStatus Subscription status
DeveloperApp
Describes developer/vendor specific application
Field name Type Required Description
appName String The unique name of
the application
appId long A unique id of this
application
appVersions List< DeveloperAppVer
> sion
The application
versions (including
application keys)
DeveloperAppVersion
Describes a version of an external application
Field name Type Required Description
owner String The sportex user who
owns the specific
version of the
application
versionId long The unique Id of the
application version
version String The version identifier
string such as 1.0, 2.0.
Unique for a given
application.
applicationKey String The unqiue application
key associated with this
application version
delayData boolean Indicates whether the
data exposed by
platform services as
seen by this application
key is delayed or
realtime.
subscriptionRequired boolean Indicates whether the
application version
needs explicit
subscription
ownerManaged boolean Indicates whether the
application version
needs explicit
management by
producers. A value of
false indicates, this is a
version meant for
developer use.
active boolean Indicates whether the
application version is
currently active
AccountFundsResponse
Response for retrieving available to bet.
Field name Type Required Description
availableToBetBalance double Amount available to
bet.
exposure double Current exposure.
retainedCommission double Sum of retained
commission.
exposureLimit double Exposure limit.
discountRate double User Discount Rate.
pointsBalance int The Betfair points
balance
AccountDetailsResponse
Response for Account details.
Field name Type Required Description
currencyCode String Default user currency
Code.
firstName String First Name.
lastName String Last Name.
localeCode String Locale Code.
region String Region.
timezone String User Time Zone.
discountRate double User Discount Rate.
pointsBalance int The Betfair points
balance.
AccountStatementReport
A container representing search results.
Field name Type Required Description
accountStatement List< > StatementItem The list of statement
items returned by your
request.
moreAvailable boolean Indicates whether there
are further result items
beyond this page.
StatementItem
Summary of a cleared order.
Field name Type Required Description
refId String An external reference,
eg. equivalent to betId
in the case of an
exchange bet
statement item.
itemDate Date The date and time of
the statement item, eg.
equivalent to
settledData for an
exchange bet
statement item. (in
ISO-8601 format, not
translated)
amount double The amount of money
the balance is adjusted
by
balance double Account balance.
itemClass ItemClass Class of statement
item. This value will
determine which set of
keys will be included in
itemClassData
itemClassData Map<String,String> Key value pairs
describing the current
statement item. The set
of keys will be
determined by the
itemClass
legacyData StatementLegacyData Set of fields originally
returned from APIv6.
Provided to facilitate
migration from APIv6 to
API-NG, and ultimately
onto itemClass and
itemClassData

StatementLegacyData
Summary of a cleared order.
Field name Type Required Description
avgPrice double
betSize double
betType String
betCategoryType String
commissionRate String
eventId long
eventTypeId long
fullMarketName String
grossBetAmount double
marketName String
marketType String
placedDate Date
selectionId long
selectionName String
startDate Date
transactionType String
transactionId long
winLose String

TimeRange
TimeRange
Field name Type Required Description
from Date from, format: ISO 8601)
to Date to, format: ISO 8601
CurrencyRate
Currency rate
Field name Type Required Description
currencyCode String Three letter ISO 4217
code
rate double Exchange rate for the
currency specified in
the request

Vendor Services in API-NG

The introduction of Subscription Tokens, to provide a single identifier for a customer's
subscription to an application.
The use of Application Keys, which replace product and vendor software IDs to control
API access.
For details of the operations to manage subscriptions, please see the section of Accounts
the API-NG Reference Guide.
There are two key processes that Vendor will need to following when using the Vendor Services in API-NG:
Subscribing a Customer.
Checking a Customers Subscription History.
Each of these processes are detailed below.
Subscribing a Customer

1.
2.
3.
4.
5.
6.
7.
8.
1.
2.
3.
4.
Preconditions: Customer has a Betfair account. Vendor has a Betfair vendor account, the app key for their app,
and their (Vendor) session token.
Customer visits Vendors web site and decides to sign up for the Vendors app.
The Customer purchases a 12 month subscription to the application from the Vendors web site.
The Vendors web site server then calls the Account API-NG operation , getApplicationSubscriptionToken
passing in the Vendors app key, a valid session token for the Vendors Betfair account (to prove that they
own that App Key) and the length of the subscription required ( ). 365 days in this scenario
Betfair returns to the vendor a Subscription Token of the form ABCD-EFGH-IJKL.
The Subscription Token is then provided to the instance of the Vendors app used by the Customer.
This may happen in a number of ways, including:
i) Emailed from Vendor to Customer, who then types the subscription token into the app.
ii) Associated with the Customers app instance by the Vendor, so that the token can be cited by the app
based on Customer login to the app.
The Vendors App requires Customer to login to Betfair using interactive login method. See sample code
interactive login sample codehere
Betfair returns Customers session token to the app.
The subscription is then activated by the app calling passing in the activateApplicationSubscription
subscription token and a valid session token for the Customer

Checking a Customers Subscription History

In this scenario the Vendor wishes to check the customers subscription status to establish if the customer has:
An existing active subscription.
An expired subscription.
A cancelled subscription.
4.
1.
2.
3.
4.
1.
2.
3.
4.
5.
6.
7.
No current or previous subscription history (i.e. Customer is entirely new).
This can be done within the application itself (client side) or by Vendor on their app server (server side). Each
process is explained in more detail below:
Client side process:
Vendors app client requires Customer to login to Betfair using interactive login method.
Betfair returns Customers session token to the Vendors app client.
Vendors app client calls citing Vendors App Key in the request body getApplicationSubscriptionHistory
and the customer's session token in the X-Authentication header.
Betfair returns Customers subscription history. If an empty list is returned then the customer has no current
or previous subscription history (i.e. Customer is entirely new)
Server side process:
Vendors app client requires Customer to login to Betfair using interactive login method.
Betfair returns Customers session token to the Vendors app client.
Vendors app client calls citing Customers session token from step 1. getVendorClientId
Betfair returns Customers vendorClientId.
Vendors App client sends Customers vendorClientId to Vendors app server.
Vendors app server calls citing Vendors session token, Vendors app getApplicationSubscriptionHistory
key, and the vendorClientID from step 4.
Betfair returns Customers complete history for the Vendors app (as identified by the app key cited in step
5). If an empty list is returned then the customer has no current or previous subscription history (i.e.
Customer is entirely new).

Interface Definition Documents

The attached documents provide a machine readable description for the interfaces available via API-NG.
AccountAPING.xml
BettingAPING.xml
HeartbeatAPING.xml

Heartbeat API
This Heartbeat operation is provided to allow customers to automatically cancel their unmatched bets in the event of
their API client/s losing connectivity with the Betfair API.
There are two separate endpoints available for the UK and AUS Exchange:
UK Exchange
Interface Endpoint
JSON-RPC https://api.betfair.com/exchange/heartbeat/json-rpc/v1
Please note, the Australian Heartbeat service isn't currently available
You can make requests and place bets on Australian markets by accessing the Australian exchange server via the
following endpoints.
Australian Exchange
Interface Endpoint
JSON-RPC https://api-au.betfair.com/exchange/heartbeat/json-rpc/
v1

Operation summary
HeartbeatReport heartbeat ( int preferredTimeoutSeconds )
Detailed documentation
Heartbeat
Operations
heartbeat
Events
Type definitions
HeartbeatReport
Enums
ActionPerformed
Exceptions
APINGException
Operations
heartbeat
HeartbeatReportheartbeat(int preferredTimeoutSeconds)throwsAPINGException
This heartbeat operation is provided to help customers have their positions managed automatically in the
event of their API clients losing connectivity with the Betfair API. If a heartbeat request is not received
within a prescribed time period, then Betfair will attempt to cancel all 'LIMIT' type bets for the given
customer on the given exchange. There is no guarantee that this service will result in all bets being
cancelled as there are a number of circumstances where bets are unable to be cancelled. Manual
intervention is strongly advised in the event of a loss of connectivity to ensure that positions are correctly
managed. If this service becomes unavailable for any reason, then your heartbeat will be unregistered
automatically to avoid bets being inadvertently cancelled upon resumption of service. you should manage
your position manually until the service is resumed. Heartbeat data may also be lost in the unlikely event
of nodes failing within the cluster, which may result in your position not being managed until a
subsequent heartbeat request is received.
Parameter name Type Required Description
preferredTimeoutSeco
nds
int Maximum period in
seconds that may
elapse (without a
subsequent heartbeat
request), before a
cancellation request is
automatically submitted
on your behalf. The
minimum value is 10,
the maximum value
. permitted is 300
Passing 0 will result in
your heartbeat being
unregistered (or
ignored if you have no
current heartbeat
registered). You will still
get an actionPerformed
value returned when
passing 0, so this may
be used to determine if
any action was
performed since your
last heartbeat, without
actually registering a
new heartbeat. Passing
a negative value will
result in an error being
returned,
INVALID_INPUT_DAT
A. Any errors while
registering your
heartbeat will result in a
error being returned,
UNEXPECTED_ERRO
R. Passing a value that
is less than the
minimum timeout will
result in your heartbeat
adopting the minimum
timeout. Passing a
value that is greater
than the maximum
timeout will result in
your heartbeat
adopting the maximum
timeout. The minimum
and maximum timeouts
are subject to change,
so your client should
utilise the returned
actualTimeoutSeconds
to set an appropriate
frequency for your
subsequent heartbeat
requests.
Return type Description
HeartbeatReport Response from heartbeat operation
Throws Description
APINGException Thrown if the operation fails
Events
This interface does not define any events.
Type definitions
HeartbeatReport
Response from heartbeat operation
Field name Type Required Description
actionPerformed ActionPerformed The action performed
since your last
heartbeat request.
actualTimeoutSeconds int The actual timeout
applied to your
heartbeat request, see
timeout request
parameter description
for details.
Enums
ActionPerformed
Value Description
NONE No action was performed since last heartbeat, or
this is the first heartbeat
CANCELLATION_REQUEST_SUBMITTED A request to cancel all unmatched bets was
submitted since last heartbeat
ALL_BETS_CANCELLED All unmatched bets were cancelled since last
heartbeat
SOME_BETS_NOT_CANCELLED Not all unmatched bets were cancelled since last
heartbeat
CANCELLATION_REQUEST_ERROR There was an error requesting cancellation, no
bets have been cancelled
CANCELLATION_STATUS_UNKNOWN There was no response from requesting
cancellation, cancellation status unknown
Exceptions
APINGException
This exception is thrown when an operation fails

Error code Description

INVALID_INPUT_DATA Invalid input data
INVALID_SESSION_INFORMATION The session token passed is invalid
NO_APP_KEY An application key is required for this operation
NO_SESSION A session token is required for this operation
INVALID_APP_KEY The application key passed is invalid
UNEXPECTED_ERROR An unexpected internal error occurred that
prevented successful request processing.
Other parameters Type Required Description
errorDetails String Specific error details
requestUUID String

Navigation Data For Applications (beta)

This allows the retrieval of the full Betfair market navigation menu from a compressed file. This is a release, beta
the production version will be available from the . 28 July
th
The file can be accessed via and https://beta-api.betfair.com/exchange/betting/rest/v1/en/navigation/lhm.json
is updated every 5 minutes.

Additional Information
Betfair Price Increments
Below is a list of price increments per price 'group'. Placing a bet outside of these increments will result in an INVAL
error ID_ODDS
Odds Markets
Price Increment
1.01 2 0.01
2 3 0.02
3 4 0.05
4 6 0.1
6 10 0.2
10 20 0.5
20 30 1
30 50 2
50 100 5
100 1000 10
Asian Handicap & Total Goal Markets
Price Increment
1.01 1000 0.01
Currency Parameters
Guide to available currencies and minimum bet sizes.

Currency name Symbol Min Bet Size Min Deposit Size Minimum BSP
Liability

UK Sterling 2 10 10
Euro 2 15 20
US Dollar US$ 4 15 20
Hong Kong Dollars HK$ 25 150 125
Australian Dollar AUD 5 30 30
Canadian Dollar CAD 6 25 30
Danish Kroner DKK 30 150 150
Norwegian Kronor NOK 30 150 150
Swedish Krona SEK 30 150 150
Singapore Dollar SGD 6 30 30
Racecourse Abbreviations
The race course abbreviations files for Horse Racing and Gryhounds previously provided for API 6.0 is available via.
horsegreyhoundcourseabbreviations.xls
Runner Metadata Description
The RUNNER_METADATA returned by listMarketCatalogue for (when available) is described in the Horse Racing
table below.

Parameter Description Example

WEIGHT_UNITS The unit of weight used pounds
ADJUSTED_RATING Adjusted ratings are race-specific
ratings which reflect weights
allocated in the race and, in some
circumstances, the ages of the
horse. Collectively they represent
the chance each runner has on
form. https://www.timeform.com/Ra
cing/Articles/How_the_ratings_for_
a_race_are_calculated
79
DAM_YEAR_BORN The year the horses mother birth 1997
DAYS_SINCE_LAST_RUN The number of days since the horse
last ran
66
WEARING Any extra equipment the horse is
wearing
tongue strap
DAMSIRE_YEAR_BORN The year in which the horses
granfather was born on its mothers
die
1988
SIRE_BRED The country were the horses father
was bred
IRE
TRAINER_NAME The name of the horses trainer Fergal O'Brien
STALL_DRAW The stall number the horse is
starting from
10
SEX_TYPE The sex of the horse f
OWNER_NAME The owner of the horse Mr M. C. Fahy
SIRE_NAME The name of the horses father Revoque
FORECASTPRICE_NUMERATOR The forcast price numerator 1
JOCKEY_CLAIM The reduction in the weight that the
horse carries for a particular jockey
5
WEIGHT_VALUE The weight of the horse 163
DAM_NAME The name of the horses mother Rare Gesture
AGE The age of the horse 7
COLOUR_TYPE The colour of the horse b
DAMSIRE_BRED The country were the horse
grandfather was born
IRE
DAMSIRE_NAME The name of the horse grandfather Shalford
SIRE_YEAR_BORN The year the horses father was
born
1994
OFFICIAL_RATING The horses official rating 97
FORM The horses recent form 212246
BRED The country in which the horse was
born
IRE
runnerId

The runnerId for the horse

62434983
JOCKEY_NAME The name of the jockey Paddy Brennan
DAM_BRED The country where the horses
mother was born
IRE
COLOURS_DESCRIPTION The textual description of the jokey
silk
Royal blue and black check, white
sleeves and cap
COLOURS_FILENAME A relative URL to an image file
corresponding to the jockey silk.
You must add the value of this field
to the base URL: http://content-cac
he.betfair.com/feeds_images/Horse
s/SilkColours/
c20140225lei/00058836.jpg
CLOTH_NUMBER The number on the saddle 5

Time Zones
All times are returned in GMT. They can be converted to your local timezone using the timezone field returned by
the operation or into the local market timezone using the timezone returned for the event by getAccountDetails listM
arketCatalogue
The following table lists the time zones returned be the API along with their meaning.
Location Abbreviation Notes
Africa/Johannesburg RSA
America/Costa_Rica SJMT
America/Indiana/Indianapolis IEST North America Indiana East
America/Santiago SMT
Asia/Bangkok THAI
Asia/Calcutta INT
Asia/Dubai UAE
Australia/Adelaide ACST
Australia/Darwin ANST
Australia/Perth AWST
Australia/Queensland AQST
Australia/Sydney AEST
Brazil/East BRT
Brazil/West AMT
CET CET Central European Time
EET EET Eastern European Time
Etc/GMT-5 PKT
Europe/London UKT
Europe/Moscow MSK
GMT GMT Greenwich Mean Time
Hongkong HK
Jamaica KMT
Japan JPT
NZ NZT New Zealand
US/Alaska AKST
US/Arizona AST
US/Central CST
US/Eastern EST
US/Hawaii HST
US/Mountain MST
US/Pacific PST
Common Error Codes
Meaning FaultCode Client/Server Associated HTTP
Transport
Response Code
Comments
DSC-0009 ClassConversionFai
lure
Client 400 Invalid format for
parameter, for
example passing a
string where a
number was
expected. Can also
happen when a
value is passed that
does not match any
valid enum.
DSC-0018 MandatoryNotDefin
ed
Client 400 A parameter marked
as mandatory was
not provided
DSC-0019 Timeout Server 504 The request has
timed out
DSC-0021 NoSuchOperation Client 404 The operation
specified does not
exist
DSC-0023 NoSuchService Client 404
DSC-0034 UnknownCaller Client 400 An App Key hasn't
been provided in the
request
DSC-0035 UnrecognisedCrede
ntials
Client 400
DSC-0036 InvalidCredentials Client 400
DSC-0037 SubscriptionRequire
d
Client 403 The user is not
subscribed to the
App Key provided
DSC-0038 OperationForbidden Client 403 The App Key sent
with the request is
not permitted to
access the
operation
Virtual Bets
The Betfair Exchange uses a 'cross matching' algorithm to display the best possible prices (bets) available by taking
into account the back and lay offers (unmatched bets) across all selections.
You can return virtual bets in the response when using API-NG by including the virtualise":"true"
in the request e.g. listMarketBook [{"jsonrpc": "2.0", "method":
"SportsAPING/v1.0/listMarketBook", "params":
{"marketIds":["1.114101556"],"priceProjection":{"priceData":["EX_BEST_OFFERS"],"virtualise":"tr
}}, "id": 1}] ue"

One of the easiest ways to understand how we generate virtual bets for cross matching is to work through a couple
of examples.
Consider the following market and what would happen if we placed a very large back bet at 1.01 on The
Draw:
Without cross matching, this bet would be matched in three portions;
1) 150 at 5.0,
2) 250 at 3.0,
and 999 at 1.01 with anything remaining being left unmatched.
With cross matching we can do better.
We have a back bet on Newcastle for 120 at 2.0 and a back bet on Chelsea for 150 at 3.0 (shown in pink on
the available to lay side of the market).

These two bets can be matched against a back bet on The Draw at a price of 6.0, since 2.0, 3.0, and 6.0 form a
100% book. To ensure that the book is balanced, we choose the stakes to be inversely proportional to the prices.
This means that we take the full 120 at 2.0 on Newcastle, only 80 at 3.0 on Chelsea, and 40 at 6.0 on The Draw,
which is the first virtual bet
We now have a back bet on Newcastle for 75 at 2.5 and a back bet on Chelsea for 70 at 3.0 (again shown in pink
on the available to lay side of the market).
These two bets can be matched against a back bet on The Draw at a price of 3.75, since 2.5, 3.0, and 3.75 also
form a 100% book.
Balancing the stakes means that we need to take the full 75 at 2.5 on Newcastle, only 62.50 at 3.0 on Chelsea,
and 50 at 3.75 on The Draw, which is the second virtual bet. Since 3.75 is less than 5.0, the 150 at 5.0 would be
matched first followed by 50 at 3.75. If we continued this process we would get further matching at 1.50 and 1.05,
but for the purposes of displaying the market view we have the best 3 prices for the available to back bets on The
Draw, and so we can stop calculating the virtual bets. The virtual bets are just the bets that would have been
matched had we received a sufficiently large back bet at 1.01; in this example, 40 at 6.0 and 50 at 3.75. We take
these virtual bets and merge them with the existing bets on the market to generate the following market
view (with the virtual bets shown in green)
The process is repeated to obtain the virtual lay bets (available to back bets) for Newcastle and Chelsea.
Here we have a slightly different market (as before, chosen to make the numbers nice) and consider what
would happen if we placed a very large lay bet at 1000 on The Draw.

Without cross matching, this bet would be matched in three portions; 1) 100 at 10.0, 2) 50 at 50.0, and 2 at 1000
with anything remaining being left unmatched. With cross matching we can do better. We have a lay bet on
Newcastle for 300 at 2.0 and a lay bet on Chelsea for 150 at 3.0 (shown in blue on the available to back side of
the market). These two bets can be matched against a lay bet on The Draw at a price of 6.0, since 2.0, 3.0, and 6.0
form a 100% book. To ensure that the book is balanced, we choose the stakes to be inversely proportional to the
prices. This means that we take only 225 at 2.0 on Newcastle, the full 150 at 3.0 on Chelsea, and 75 at 6.0 on
The Draw, which is the first virtual bet.
Assuming these bets got matched, the market would look like this:

We now have a lay bet on Newcastle for 75 at 2.0 and a lay bet on Chelsea for 250 at 2.4 (again shown in blue
on the available to back side of the market). These two bets can be matched against a lay bet on The Draw at a
price of 12.0, since 2.0, 2.4, and 12.0 also form a 100% book. Balancing the stakes means that we need to take the
full 75 at 2.0 on Newcastle, only 62.50 at 2.4 on Chelsea, and 12.50 at 12.0 on The Draw, which is the second
virtual bet.
This leaves the following market:

This time we can't continue the process since there is no valid price for a virtual bet on The Draw that would result in
a 100% book, and so we can stop calculating the virtual bets. Again, the virtual bets are just the bets that would
have been matched had we received a sufficiently large lay bet at 1000; in this example, 75 at 6.0 and 12.50 at
12.0. We take these virtual bets and merge them with the existing bets on the market to generate the
following market view (with the virtual bets shown in orange):
Known Issues
This page contains a list of current known issues/defects on API-NG . We expect to fix these issues in a future
release.
listMarketBook - orderProjection does not include betPersistenceType for EXECUTABLE bets.
listMarketBook - when requesting multiple markets in a request, submitting a request for 'CLOSED' market/s
will cause the results for 'ACTIVE' markets not be returned in the response.
getAccountFunds - operations for the Australian Exchange doesnt currently return details from the
Australian wallet. This is due to be rectified in a future release.
listCurrentOrders - (AUS Exchange) - the dateRange parameter isn't currently available as part of the
request. This is due to be rectified in a future release.
listMarketCatalogue - (AUS Exchange) - doesn't current return totalMatched in the listMarketCatalogue
response. This is due to be rectified in a future release.
listMarketCatalogue - for ASIAN_HANDICAP markets persistenceEnabled = true for in-play markets.
However,ASIAN_HANDICAP markets are not offered in-play so KEEP bets cannot be placed.
listMarketCatalogue -non-runners are occasionally duplicated when returned via listMarketCatalogue.
(AUS Endpoint) - this service is currentlyunavailableuntil further notice Heartbeat