Frequently Asked Questions

  • • Are there any costs associated with API access?
  • API access is free for development purposes (using the delayed App Key) for private betting customers and licensed software vendors. To obtain a real-time / live App Key, apply for access by following the 'get started' process. A one-off activation fee of £299 applies. Activation fees are non-refundable.

    Commercial access is subject to our normal licensing requirements which are detailed here.

    If you are unsure which licence type applies to you please follow the get started guide via https://developer.betfair.com/en/get-started/.  This will guide you to the correct licence for your intended usage.

  • • What data/request limits exist on the Exchange API?
  • Although you can request multiple markets from listMarketBook, listMarketCatalogue and listMarketProfitandLoss, there are limits on the amount of data requested in one request.

    Please see the Market Data Limits for further information.

     

  • • What do I need to get started?
  • To get started with the API you require a Betfair account, an Application Key and a valid session token.

    You can open a Betfair account via https://register.betfair.com

    To obtain a session token and Application Key please follow the instructions here

  • • How do I place bets below minimum £1 stake?
  • It is possible to place bets of less than £1.  However, we'd recommend that you only do this for 'greening-up' or short-term testing.  Placing bets consistently below the minimum stake level may result in your account being suspended as this is in breach of our terms and conditions.

    Please Note - some stake and price combinations aren't permitted - any attempt to place, cancel or update a bet at these stake and price combinations will result in the error INVALID_PROFIT_RATIO

    If you have an 'Unmatched' bet of at least £1.00 on a specific selectionId in a market, you can submit further placeOrder requests for a stake of less than £1.00 on the same selectionId, cancel the original unmatched bet, and adjust the price of the new bet below £1 accordingly.

    Alternatively, you can place an unmatched bet and then reduce the bet size to give you the new required stake amount (of less than £1) using the cancelOrders service.

  • • Why are the prices displayed on the website different from what I see in my API application?
  • The Betfair Sports Exchange tries to match bets against the bets placed by other users as well as equivalent bets where possible. These "virtual" bets follow the rules for cross-matching as outlined in the API documentation.

     

    For example, if a customer backs Player A in a tennis match at odds of 2.0, the exchange matches any lay bet at odds of 2.0 or better on Player A. In addition, the Exchange also calculates all possible matches that are equivalent to a lay bet on Player A. So, if a customer backs Player B at odds of 2.0 or better, the Exchange matches it with the back bet on Player A. The Betfair website calculates the possible virtual bets that the Betfair Sports Exchange creates and displays those bets as if they were placed by other customers normally.

     

    In other words, bets displayed on the Betfair website may be actual bets placed by customers, or virtual bets that the website knows the Betfair Sports Exchange will match due to the cross-matching rules. By default, virtual bets are not returned via API-NG when making a request to listMarketBook. However, you can return virtual bets in the response when using API-NG by including the virtualise":"true" in the listMarketBook request e.g. [{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listMarketBook", "params": {"marketIds":["1.114101556"],"priceProjection":{"priceData":["EX_BEST_OFFERS"],"virtualise":"true"}}, "id": 1}]

    NOTE: It is important to understand that bets placed through the API are matched in the exact same way as bets placed on the website. In other words, a bet placed through the API is matched with either direct opposite bets or with the virtual bet, if available.

  • • What is an Application Key?
  • Betfair use the Application Key to identify all requests that are made to the Exchange API. An Application Key is required to make requests to the Exchange API and must be included in a 'X-Application' HTTP header for all API requests.  Please see our article regarding Application Keys for further information.

  • • Why am I receiving delayed data when using a 'live' Application Key?
  • You will receive delayed data when using a Live Application Key if your Betfair account isn't funded or if an override has been applied to your account. To deposit funds please login to your account via the Betfair website and click on 'Deposit'.

  • • Is there an API testbed available?
  • There isn't an API test bed available. Customers wishing to perform functional API testing should use the assigned delayed App Key when making requests.

    Delayed Application Keys are explained in more detail here.

  • • Can I place Sportsbook bets via the API?
  • The Exchange API doesn't include Betfair Sportsbook odds nor does it allow bets to be placed via the Betfair Sportsbook.

  • • How do I login to the API?
  • The Exchange API offers two 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 login flow makes use of Betfair's login pages.

    Further information is available via the API documentation.

  • • Is 'Cashout' available via the Betfair API?
  • • Why am I receiving the error BETTING_RESTRICTED_LOCATION?
  • This error indicates that you are accessing Betfair from a location that is restricted for legal or regulatory reasons.  You will need to access Betfair from a different location.   You can use https://www.maxmind.com/en/geoip_demo to identify the location specific location to which your IP address has been assigned by your server provider.

    If the your IP is identified as being based in the US (or any other restricted location) you will need to submit a correction request to Maxmind via https://www.maxmind.com/en/correction

    One confirmed by Maxmind, any corrections will be applied when we upload the latest GeoIP files to our servers on a Thursday evening, as part of a weekly process.

  • • How do I get a sessionToken?
  • A sessionToken can be obtained by using either of the Betfair Exchange API login methods - non-interactive and interactive login.


    For testing purposes you can also retrieve the sessionToken from your web browser (while logged into the Betfair website). Please see instructions here 

  • • Why am I receiving TEMPORARY_BAN_TOO_MANY_REQUESTS when attempting to Login?
  • You have made more than 100 successful login requests in a minute.  In the event of a breach of the login limit the account will be prevented from creating new login session for a 20 minute period. The error TEMPORARY_BAN_TOO_MANY_REQUESTS will be returned in these circumstances. All existing sessions will continue to be valid.

  • • How do I retrieve a list of markets?
  • You can retrieve a list of available markets using the listMarketCatalogue operation. The results returned will be subject to the filters you apply in your request.

    Please see further details & examples via our Getting Started guide.

     

     

  • • Can I retrieve details of football scores and incidents via the Exchange API?
  • No, unfortunately, football (soccer) scores and incident data isn't available via the Exchange API.  You would need to retrieve this data from other third party sources.

  • • How do I optimise the performance of my API application?
  • To optimise performance and ensure that your application is interacting with the Betfair API as efficiently as possible, we strongly recommend the following as best practice.

    Enabling HTTP compression

    HTTP compression is a capability built into both web servers and web clients to reduce the number of bytes transmitted in an HTTP response. This makes better use of available bandwidth and increases performance while reducing download time. When enabled, HTTP protocol data is compressed before it is sent from the server. Clients capable of receiving compressed HTTP data announce that they support compression in the HTTP header. Almost all modern web browsers support HTTP Compression by default.

    The Betfair API uses HTTP to handle communication between API clients and servers. Therefore, the JSON messages can be compressed using the same HTTP compression used by web browsers. Custom API applications may need some modification before they can take advantage of this feature. Specifically, they need to send an additional HTTP header to indicate they support receipt of compressed responses from the API. In addition, some environments require you to explicitly decompress the response.

    We would therefore recommend that all Betfair API requests are sent with the ‘Accept-Encoding: gzip, deflate’ request header.

    HTTP persistent connection

    We recommend that Connection: keep-alive header is set for all requests to guarantee a persistent connection and therefore reducing latency.

    Other performance tips

    Additional advice regarding optimizing HTTPClient performance can be found via http://hc.apache.org/httpclient-3.x/performance.html

  • • Why do I receive APP_KEY_CREATION_FAILED when making a createDeveloperAppKeys request?
  • This error can occur for two specific reasons:

    You are attempting to create an Application Key for an account which has already had them assigned

    OR

    You are providing an Application Name that already exists. All Application Names

    Each account is assigned with a unique set of Application Keys; once you have successfully created your set of Application Keys you cannot create additional keys. 

    You can use the “getDeveloperAppKeys” operation to retrieve the Application Keys you created previously.

  • • How many Application Keys can I assign to my Betfair account?
  • You are permitted to have one set of Application Keys for your Betfair account. If you have multiple Betfair accounts you will need to create a separate App Key for each of them.

  • • How can I display results after the event?
  • Runner status (WINNER, LOSER) is available via the ‘status’ field returned by listMarketBook after a market has been settled.

    For example please see here

  • • Why do you have a delay on placing bets on a market that is ‘in-play’
  • In-play markets usually carry a time delay varying from 1-12 seconds. This delay is in place to allow customers to cancel unmatched orders on the system when there is a change in market conditions. This delay protects both backers and layers and leads to greater liquidity.  

    The amount of delay your placeOrders/replaceOrders  requests are subject to can be determined from using the betDelay field in the listMarketBook response.

  • • How do I create an Application Key?
  • You can create a set of Application Keys (one 'delayed' for development and testing and one 'live' for betting) by using the createDeveloperAppKeys service via the Accounts API Demo Tool.

  • • How do I identify markets that will be turned ‘in-play’?
  • Using listMarketCatalogue set the MarketFilter 'turnInPlayEnabled' parameter in request to ‘true’. This will return all markets that are due to be turned in-play

  • • Which NTP servers do Betfair use?
  • • How do I identify markets that are in-play right now?
  • Using listMarketCatalogue set the MarketFilter ‘inPlayOnly’ parameter in the request to ‘true’. This will return all markets that are in-play at the time the request is made.

  • • Is there a reason why horse racing (eventTypeId 7) doesn't appear in the API response?
  • Horse racing markets will not be returned via the API if you are attempting to access the service from a location/IP address which is restricted for legal reasons.

    For example, horse racing markets are not returned when requested from Germany or a German based IP address.

  • • 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.

    Third party interfaces to Betfair, used by multiple users, and which act as a direct proxy of a user request should use the interactive login instead.

  • • How do I retrieve my assigned Application Keys?
  • You can retrieve your App Keys using the getDeveloperAppKeys service within the Accounts API Demo Tool. This operation will provide details of your delayed and live Application Key and requires your Betfair session Token to be included in the request. You can retrieve a session token from an API login request or by logging into the Betfair website via www.betfair.com and then accessing the Accounts API Demo Tool using a new browser tab.  Once you have input the session token press the Execute button at the bottom of the Demo tool to send the request.

  • • Why am I receiving delayed Exchange market data?
  • You’ll receive delayed Exchange market data if you are logged out, logged in but have never funded your account or if your account has been restricted by Betfair to received delayed data only.

    Website and mobile

    Please log in to your Betfair account to receive the latest Exchange odds for betting.

    If you're accessing the Exchange via www.betfair.com/exchange/plus/ or one of our mobile apps, you'll receive delayed market data (odds) and limited traded volumes whilst you're logged out of your account. The delay applied to this data is variable, up to 3 minutes. You'll need to be logged in and have funded your account at least once previously to receive the latest Exchange odds. To deposit funds please login to your account via the Betfair website and click on 'Deposit'.

    Additionally, you will receive delayed data if an override has been applied by Betfair to your account.

    API

    Vendor App customers - apps require you to login by default to access live Betfair Exchange prices. You will only receive delayed data if your account has never been funded or it your account has been restricted by Betfair to receive delayed data.

    API Direct Access Developers - you'll receive delayed data when using a delayed App Key or when using a live App Key if your Betfair account has never been funded or if an override has been applied to your account, or App Key. 

     

    If you've further questions on this, please raise a support ticket here.

    To return to the Betfair Exchange website, click here.

  • • How do I retrieve the returned Betfair SP via the API?
  • You need to request SP_AVAILABLE in the listMarketBook request when the market is first turned in-play as shown in the example request below:

     

    "jsonrpc": "2.0", "method": "SportsAPING/v1.0/listMarketBook", "params": {"marketIds":["1.115539145"],"priceProjection":{"priceData":["EX_BEST_OFFERS","SP_AVAILABLE"]}}, "id": 1}]

  • • How can I use the Italian Exchange with the API?
  • To use the Italian Exchange with the API you need to create an Application Key for your Italian Exchange account by following the process outlined here.

    Once you have done this, you will need to login to the API using the Italian Exchange endpoint which is as follows:

    Non-interactive Login https://identitysso.betfair.it/api/certlogin

    Interactive Login https://identitysso.betfair.it/view/login?product=&url=https://www.betfair.it


    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.

  • • How do I cancel all existing ‘executable’ bets?
  • Make a request to cancel orders without specifying a marketId or instruction.

  • • How can I track my bet matches using listCurrentOrders?
  • To efficiently track new bet matches from a specific time, customers should use a combination of the dateRange, orderBy "BY_MATCH_TIME" and orderProjection “ALL” to filter fully/partially matched orders from the list of returned bets. The response will then filter out any bet records that have no matched date and provide a list of betIds in the order which they are fully/partially matched from the date and time specified in the dateRange field.

  • • How do I retrieve horseracing silks and other horse related meta data?
  • • Can I enable 2-Step Authentication and still use the API non-interactive login method?
  • Yes, enabling 2-Step Authentication for login to the Betfair website will not affect your ability to login to API using the non-interactive login method. 2-Step Authentication and the non-interactive login are handled independently of each other.

  • • Australian jurisdiction - How do I retrieve a session token for use with the Demo Tool?
  • Unfortunately, the API Demo tool doesn't currently support session retrieval for the .au Exchange.

    Please try making a  POST request to the Login method by following the instructions via http://docs.developer.betfair.com/docs/display/1smk3cen4v3lu3yomq5qye0ni/Interactive+Login+-+API+Endpoint using the Italian endpoint.

    Alternatively, using Google Chrome you can inspect and copy the session directly from the browser by doing the following:

    1,  Press Ctrl+Shif+J 
    2.  Selection Resource > Cookies >  www.betfair.au
    3. Copy the value for the cookie with name ssoid and paste this into the Demo Tool
     

  • • How do I identify/display the key handicap line for handicap markets?
  • Use the KeyLineDescription from the listMarketBook response to identify and display the handicap that's currently being displayed via the Betfair website.

    For example, you'd receive the following from the listMarketBook response, indicating that the currency key line is selectionId is 19484 and handicap :5.5 for this market:

    Request 

    [{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listMarketBook", "params": {"marketIds":["1.139230347"]}, "id": 1}]

    Response (showing key fields only)
    ..................
       "keyLineDescription": {
                        "keyLine": [
                            {
                                "selectionId": 19484,
                                "handicap": 5.5
                            },
                            {
                                "selectionId": 19484,
                                "handicap": 5.5
                            }
                        ]

    Once you've identified the KeyLine you can make a request for that single selection using the listRunnerBook operation.  This will restrict the response to return the prices available at the key line only, significantly reducing the size of the response.

    Request (for single runner only)

    [{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listRunnerBook", "params": {"marketId":"1.139230347","selectionId":"19484","handicap":"5.5","priceProjection":{"priceData":["EX_BEST_OFFERS"],"virtualise":"true"}}, "id": 1}]

    Response (for single runner only)

    [{"jsonrpc":"2.0","result":[{"marketId":"1.139230347","isMarketDataDelayed":false,"status":"OPEN","betDelay":0,"bspReconciled":false,"complete":true,"inplay":false,"numberOfWinners":0,"numberOfRunners":402,"numberOfActiveRunners":402,"lastMatchTime":"2018-01-24T12:52:56.942Z","totalMatched":12267.62,"totalAvailable":26527.81,"crossMatching":true,"runnersVoidable":false,"version":2022983656,"runners":[{"selectionId":19484,"handicap":5.5,"status":"ACTIVE","lastPriceTraded":1.96,"totalMatched":8780.24,"ex":{"availableToBack":[{"price":1.94,"size":146.21},{"price":1.92,"size":1330.56},{"price":1.88,"size":1201.74}],"availableToLay":[{"price":1.98,"size":2976.8},{"price":1.99,"size":129.43},{"price":2.0,"size":20.0}],"tradedVolume":[]}}],"keyLineDescription":{"keyLine":[{"selectionId":19484,"handicap":5.5},{"selectionId":56294,"handicap":-5.5}]}}],"id":1}]

  • • How do I track players to my Affiliate account?
  • To track activity and players to your Affiliate and partnerships account, please contact your Account Manager or partners@betfair.com who will supply you with the necessary links and formats. Please note if you do not apply the correct links or parameters you will not receive affiliate commission or earnings from the players you have referred.

  • • Why am I receiving INVALID_SESSION_INFORMATION?
  • The session token hasn't been provided, is invalid or has expired.  Please login to the API again to create a new session token.

  • • How do I place Betfair SP limit on close bet via the API?
  • You can do this by specifying the LIMIT_ON_CLOSE orderType in the placeOrders request.

    Please see an example below of a back bet specifying a minimum price of 3.8 with a liability of £2

     

    [{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/placeOrders", "params": {"marketId":"1.115196564","instructions":[{"selectionId":"7695602","handicap":"0","side":"BACK","orderType":"LIMIT_ON_CLOSE","limitOnCloseOrder":{"price":"3.8","liability":"2"}}]}, "id": 1}] Please see an example below of a lay bet specifying a minimum price of 5.0 with a liability of £10.0 [{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/placeOrders", "params": {"marketId":"1.115196564","instructions":[{"selectionId":"7695602","handicap":"0","side":"LAY","orderType":"LIMIT_ON_CLOSE","limitOnCloseOrder":{"price":"5.0","liability":"10"}}]}, "id": 1}]

  • • Exchange Stream API - How do the heartbeat requests work?
  • We have two types of heartbeat:

    1. Client initiated: op=heartbeat – this is purely for a client to test a connection – you can send this whenever you choose
    2. Server initiated: this has a rate on the Subscribe / ChangeMessage
      1. We send one of these in the absence of market activity

    See below for an example of a server heartbeat below using a frequency of 1000 ms:

    S: {"op":"marketSubscription","id":8,"heartbeatMs":1000,"marketFilter":{"marketIds":["1.324"]},"marketDataFilter":{}}
    R: {"op":"status","id":8,"statusCode":"SUCCESS","error":false}
    R{"op":"mcm","id":8,"initialClk":"xAeGqeqzBsQHkdq8uQbEB9jygrkG","clk":"AAAAAAAA","conflateMs":0,"heartbeatMs":1000,"pt":1449855400048,"ct":"SUB_IMAGE"}
    R: {"op":"mcm","id":8,"clk":"AEYAVAA7","pt":1449855401068,"ct":"HEARTBEAT"}
    R: {"op":"mcm","id":8,"clk":"AIEBAJ4BAIEB","pt":1449855402068,"ct":"HEARTBEAT"}
    R: {"op":"mcm","id":8,"clk":"AMoBAOMBANMB","pt":1449855403068,"ct":"HEARTBEAT"}
    R: {"op":"mcm","id":8,"clk":"AIQCAK4CAJ4C","pt":1449855404068,"ct":"HEARTBEAT"}

    The heartbeat itself:

    • Always has a clk – which should be stored
    • Never contains data.
    • Is sent only if no other traffic has been sent to the client in the interval and is set at 5000 millisecond by default.
  • • Why am I receiving the error PERMISSION_DENIED?
  • The error indicates that your Application Key doesn't have the necessary permissions to request the service or that you are attempting to place a bet from a restricted location.

  • • I have an API problem, what details do I need to provide to support?
  • When raising API issues via https://developer.betfair.com/support/ please provide the following details:

     

    Your details:

    • Your App Key
    • Username/ AccountId
    • ErrorCode/UUID (if exception) e.g. “errorCode :  UNEXPECTED_ERROR requestUUID : prdang007-11130238-0005ef4437”

    API Request details:

    • Date/Time of the issue with timezone
    • Operation/Endpoint URL
    • JSON request
    • JSON response
    • Expected behavior
    • Actual behavior
    • Your Application logs (if available)

    This will help us to fully investigate any issues in a timely manner.

  • • How can I receive notifications of API releases?
  • • Romanian jurisdiction - How do I retrieve a session token for use with the Demo Tool?
  • Unfortunately, the API Demo tool doesn't currently support session retrieval for the Romanian (.ro) juristiction.

    Please try making a  POST request to the Login method by following the instructions using the .ro endpoint.

    Alternatively, using Google Chrome you can inspect and copy the session directly from the browser by doing the following:

    1,  Press Ctrl+Shif+J 
    2.  Selection Resource > Cookies >  www.betfair.ro
    3. Copy the value for the cookied with name ssoid and paste this into the Demo Tool

  • • Exchange Stream API - How do you unsubscribe from a market?
  • Changing your MarketSubscriptionMessage to request a different marketFilter (marketId etc) will automatically unsubscribe you from the current market that your subscribed to.

  • • Italian Exchange - How do I retrieve a session token for use with the Demo Tool?
  • Unfortunately, the API Demo tool doesn't currently support session retrieval for the .it Exchange.

    Please try making a  POST request to the Login method by following the instructions using the Italian endpoint.

    Alternatively, using Google Chrome you can inspect and copy the session directly from the browser by doing the following:

    1,  Press Ctrl+Shif+J 
    2.  Selection Resource > Cookies >  www.betfair.it
    3. Copy the value for the cookie with name ssoid and paste this into the Demo Tool

  • • What is the definition of RANK and what is the default sort criteria for listMarketCatalogue?
  • RANK is an assigned priority that is determined by our Market Operations team in our back-end system. A result's overall rank is derived from the ranking given to the flowing attributes for the result:

    EventType
    Competition
    Competitor
    StartTime
    MarketType
    MarketId

    For example, EventType is ranked by the most popular sports types and marketTypes are ranked in the following order:

    ODDS
    ASIAN
    LINE
    RANGE

    If all other dimensions of the result are equal, then the results are ranked in MarketId order.

  • • Can I bet on the .com Exchange with an Italian Exchange account?
  • No, to bet on the .com Exchange you would have to register a .com Exchange account from outside of Italy and using a non Italian based address.  This would need to be verifiable by Betfair using the documents outlined via http://kyc.betfair.com/ 

  • • Why am I received the error REJECTED_BY_REGULATOR when using the Italian Exchange?
  • The REJECTED_BY_REGULATOR errors from the Italian Exchange API are thrown if the request to the Italian regulator times out.
     
    Therefore, providing that all of the other betting rules (posted here) this would be the only reason for an occurrence of this error.

    This may happen when there is a problem with the network link between Betfair and the Italian regulator.

  • • Exchange Stream API - How can I match OCM and MCM messages from the Stream API?
  • The Order Changes and Market Changes are being produced by 2 independent systems (albeit being triggered by the same underlying event) so we can give no guarantee as to the order in which they will be sent, nor do we provide a parameter to match the OCM to the MCM.

  • • How to I retrieve LAPSED or CANCELLED bets for an ACTIVE market?
  • LAPSED or CANCELLED bet are available via the listClearedOrders service once a market has been settled, but not for ACTIVE markets. LAPSED or CANCELLED aren't returned via listCurrentOrders

  • • Why am I receiving the DUPLICATE_TRANSACTION error?
  • A duplicate CustomerRef has been submitted in the placeOrders request. - Please note: There is a time window associated with the de-duplication of duplicate submissions which is 60 seconds.

  • • Spanish Exchange - How do I retrieve a session token for use with the Demo Tool?
  • Unfortunately, the API Demo tool doesn't currently support session retrieval for the .es Exchange.

    Please try making a  POST request to the Login method by following the instructions using the Spanish endpoint.

    Alternatively, using Google Chrome you can inspect and copy the session directly from the browser by doing the following:

    1,  Press Ctrl+Shif+J 
    2.  Selection Resource > Cookies >  www.betfair.es
    3. Copy the value for the cookie with name ssoid and paste this into the Demo Tool

  • • How can I access the Vendor Services API operations?
  • The Vendor Services API operations are only available to licensed Software Vendors who've had their applications security certified by Betfair.

    If you're interested in providing your application to other Betfair customers under the terms of the Software Vendor Licence, please complete the Software Vendor sign up form here.

  • • How do I resolve the 'failedhostname 'http://identitysso.betfair.com' doesn't match' error when using non-interactive login with Python?
  • Please take a look at the article via the Python support pages which I believe explains why you are experiencing this issue (http://docs.python-requests.org/en/latest/community/faq/)