- How Do I Get Started?
- Login
- Request Headers
- API Endpoints
- JSON
- JSON-RPC
- API Demo Tools
- Example Requests
- Request A List Of Available Event Types
- Request a List of Events for an Event Type
- Request the Market Information for an Event
- Horse Racing - Today's Win & Place Markets
- Request a List of Football Competitions
- Request Market Prices
- Placing a Bet
- Placing a Betfair SP Bet - MARKET_ON_CLOSE
- Placing a Betfair SP Bet - LIMIT_ON_CLOSE
- Retrieving Details of Bet/s Placed on a Market/s
- Retrieving the Result of a Settled Market
- Retrieving Details of Bets on a Settled Market - including P&L & Commission paid.
How Do I Get Started?
To use the Exchange API you require the following:
- A Betfair account. you can open a Betfair account here
- An Application Key - you can create an Application Key by following the instructions here
- A sessionToken - you can create a session token by using either of the API login methods or by following the instructions here
Login
The Betfair API offers three login flows for developers, depending on the use case of your application:.
- Non-Interactive login - if you are building an application that 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 that will be used interactively, then this is the flow for you. This flow has two variants:
- Interactive login - API method - This flow makes use of a JSON API Endpoint and is the simplest way to get started if you are looking to create your own login form.
- Interactive login - Desktop Application- This login flow makes use of Betfair's login pages and allows your app to gracefully handle all errors and re-directions in the same way as the Betfair website
Request Headers
- All requests must include a HTTP header named "X-Application" containing the Application Key assigned to you.
- All requests must include a HTTP header "X-Authentication" containing your sessionToken.
- All requests must include a HTTP header "Accept" with the value application/json
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.
API Endpoints
You can make requests and place bets on UK & international markets by accessing the Global Exchange via the following endpoints.
Please find the details for the current Betting API endpoints:
Global Exchange
Interface | Endpoint | JSON-RPC Prefix | <method> Example |
|---|---|---|---|
| JSON-RPC | https://api.betfair.com/exchange/betting/json-rpc/v1 | <method> | SportsAPING/v1.0/listMarketBook |
| JSON REST | https://api.betfair.com/exchange/betting/rest/v1.0/ | listMarketBook/ |
You can make requests for your UK Exchange wallet information by accessing the Global Exchange via the following endpoints.
Please find the details for the current Accounts API endpoints:
Global Exchange
Interface | Endpoint | JSON-RPC Prefix | <method> Example |
|---|---|---|---|
| JSON-RPC | <method> | AccountAPING/v1.0/getAccountFunds | |
| JSON REST | https://api.betfair.com/exchange/account/rest/v1.0 | getAccountFunds/ |
Spanish & Italian Exchange
Please see separate documentation for the Spanish & Italian Exchange
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.
{
"filter" : { }
}
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 JSON-RPC at:
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 listCompetitions operation and passing in a filter to find all markets with a corresponding event type id of 1 (i.e., all Football markets), the POST data for the JSON-RPC endpoint would be:
{
"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:
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:
API Demo Tools
Our Demo Tools can be used by developers for quick experimentation and interaction with the production API system
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 in jsonrpc format:
- Request A List Of Available Event Types (listEventTypes)
- Request a List of Events for an Event Type (listEvents)
- Request the Market Information for an Event (listMarketCatalogue)
- Horse Racing - Today's Win & Place Markets
- Request a List of Football Competitions (listCompetitions)
- Request Market Prices (listMarketBook)
- Placing a Bet (placeOrders)
- Placing a Betfair SP Bet - MARKET_ON_CLOSE (placeOrders)
- Placing a Betfair SP Bet - LIMIT_ON_CLOSE (placeOrders)
- Retrieving Details of Bet/s Placed on a Market/s (listCurrentOrders)
- Retrieving the Result of a Settled (listMarketBook)
- Retrieving Details of Bets on a Settled Market - including P&L & Commission paid (listClearedOrders)
Request A List Of Available Event Types
You can make a request using the listEventTypes service which will return a response containing the eventTypes (e.g. Soccer, Horse Racing etc.) that are currently available on Betfair.
[
{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listEventTypes",
"params": {
"filter": {}
},
"id": 1
}
]
Request a List of Events for an Event Type
The below example demonstrates how to retrieve a list of events using listEvents (eventIds) for a specific event type. The request shows how to retrieve all Soccer events that are taking place in a single day.
[
{
"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
}
]
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) using listMarketCatalogue. You can include one or more eventId's in the requests provide that you stay within the Market Data Limits
[
{
"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
}
]
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 using listMarketCatalogue. The marketStartTime (from & to) should be updated accordingly.
[
{
"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
}
]
Request a List of Football Competitions
To retrieve all football competitions, you can make a request to the listCompetitions operation with the following market filter:
{
"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:
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)
Request Market Prices
Once you have identified the market (marketId) that your interested in using the listMarketCatalogue service, you can request prices for that market using the listMarketBook API call.
This is an example showing a request for the best prices (back and lay) and trading volume including virtual bets.
[{
"jsonrpc": "2.0",
"method": "SportsAPING/v1.0/listMarketBook",
"params": {
"marketIds": ["1.127771425"],
"priceProjection": {
"priceData": ["EX_BEST_OFFERS", "EX_TRADED"],
"virtualise": "true"
}
},
"id": 1
}]
Placing a Bet
To place a bet you require the marketId and selectionId parameters from the listMarketCatalogue API call. The 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 placeOrders response
[
{
"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
}
]
[
{
"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 - MARKET_ON_CLOSE
To place a bet on a selection at Betfair SP, you need to specify the parameters below in the placeOrders request. The below example would place a Betfair SP back bet on the required selection for a stake of £2.00.
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": "10"
}
}
]
},
"id": 1
}
]
[
{
"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
}
]
Placing a Betfair SP Bet - LIMIT_ON_CLOSE
Below is an example of a Betfair SP Bet - using the orderType LIMIT_ON_CLOSE . Please refer to Additional Information#CurrencyParameters for Min BSP liability.
[{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/placeOrders", "params": {"marketId":"1.148683414","instructions":[{"selectionId":"15319829","handicap":"0","side":"LAY","orderType":"LIMIT_ON_CLOSE","limitOnCloseOrder":{"price":"5","liability":"10"}}]}, "id": 1}
Retrieving Details of Bet/s Placed on a Market/s
You can use the listCurrentOrders request to retrieve a bet/s placed on a specific market/s.
[{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listCurrentOrders", "params": {"marketIds":["1.117020524"],"orderProjection":"ALL","dateRange":{}}, "id": 1}]
[{"jsonrpc":"2.0","result":{"currentOrders":[{"betId":"45496907354","marketId":"1.117020524","selectionId":9170340,"handicap":0.0,"priceSize":{"price":10.0,"size":5.0},"bspLiability":0.0,"side":"BACK","status":"EXECUTABLE","persistenceType":"LAPSE","orderType":"LIMIT","placedDate":"2015-01-22T13:01:53.000Z","averagePriceMatched":0.0,"sizeMatched":0.0,"sizeRemaining":5.0,"sizeLapsed":0.0,"sizeCancelled":0.0,"sizeVoided":0.0,"regulatorCode":"GIBRALTAR REGULATOR"}],"moreAvailable":false},"id":1}]
Retrieving the Result of a Settled Market
[{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listMarketBook", "params": {"marketIds":["1.114363660"],"priceProjection":{"priceData":["EX_BEST_OFFERS"]}}, "id": 1}]
Retrieving Details of Bets on a Settled Market - including P&L & Commission paid.
You can retrieve details of a settled bet/market using the listClearedOrders request. The below request uses a specific settledDatRange to limit the returned records and groupBy MARKET rollup to group results at markeId level.
[{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listClearedOrders", "params": {"betStatus":"SETTLED","settledDateRange":{"from":"2018-04-30T23:00:00Z","to":"2018-05-31T23:00:00Z"},"groupBy":"MARKET"}, "id": 1}]