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/get-started/  This will guide you to the correct licence for your intended usage.

  • • 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/account/registration 

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

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

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

  • • How do I place bets below minimum £2 stake?
  • It is possible to place bets of less than £2.  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.

    If you have a 'Unmatched' bet of at least £2.00 on a specific selectionId in a market, you can submit further placeOrder requests for a stake of less than £2.00 on the same selectionId, cancel the original unmatched bet and the adjust the price of the new bet below £2 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 £2).  Using the cancelOrders service.

    For example, reducing a £3 stake bet by £2 would leave you with an unmatched bet of £1 which you can then place at the desired odds using the replacOrders instruction:

    canceOrders

    [{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/cancelOrders", "params": {"marketId":"1.119532513","instructions":[{"betId":"52882616087","sizeReduction":"2"}]}, "id": 1}]

    replaceOrders request

    [{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/replaceOrders", "params": {"marketId":"1.119532513","instructions":[{"betId":"52882640505","newPrice":"4.5"}]}, "id": 1}]

    replaceOrder response

    [{"jsonrpc":"2.0","result":{"status":"SUCCESS","marketId":"1.119532513","instructionReports":[{"status":"SUCCESS","cancelInstructionReport":{"status":"SUCCESS","instruction":{"betId":"52882640505"},"sizeCancelled":1.0},"placeInstructionReport":{"status":"SUCCESS","instruction":{"selectionId":9618613,"limitOrder":{"size":1.0,"price":4.5,"persistenceType":"LAPSE"},"orderType":"LIMIT","side":"BACK"},"betId":"52882717122","placedDate":"2015-07-17T10:32:43.000Z","averagePriceMatched":0.0,"sizeMatched":0.0}}]},"id":1}]

     

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

  • • Why do I receive APP_KEY_CREATION_FAILED when making a createDeveloperAppKeys request?
  • You are attempting to create an Application Key for an account which has already had them assigned. 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.

    Simply use “getDeveloperAppKeys” to retrieve the App Keys you created previously.

  • • Why am I receiving delayed data when using a 'live' Application Key?
  • You will received delayed data when using 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'.

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

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

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

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

  • • How do I get a sessionToken?
  • A sessionToken can be obtained by using either of the API-NG 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.

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

  • • Is 'Cashout' available via the Betfair API?
  • • 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.

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

  • • Why does the API prefix the market id with "1." or "2."?
  • The prefix is to identify the specific Exchange the market belongs to.

    1 = UK Exchange

    2 = AUS Exchange.

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

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

  • • Which NTP servers do Betfair use?
  • • 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.

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

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

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

  • • 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 retrieve horseracing silks and other horse related meta data?
  • • 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
     

  • • 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 via http://docs.developer.betfair.com/docs/display/1smk3cen4v3lu3yomq5qye0ni/Interactive+Login+-+API+Endpoint 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

  • • 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 via http://docs.developer.betfair.com/docs/display/1smk3cen4v3lu3yomq5qye0ni/Interactive+Login+-+API+Endpoint 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

  • • 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}]

  • • 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 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.it
    3. Copy the value for the cookie with name ssoid and paste this into the Demo Tool

  • • How can I receive notifications of API releases?
  • • 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.

  • • 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/)

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

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

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

  • • Exchange Stream API -- How do I get access?
  • • 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.

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

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

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

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

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

  • • Exchange Stream API -- How do I managed re-connections?
  • With respect to managing re-connections, here are the key points:

    1)      Store your subscription message (with all filters exactly as you sent – this is key)
    2)      Update initialClk + clk whenever we send it to you
    3)      On re-connection send the subscription message as above

    What then happens is:

    1)      You will receive one message with ct=RESUB_DELTA – this will patch you to the latest version
    2)      Some markets could come with img=true – in which case you must replace price points.
    3)      Most will have con=true – i.e. we’ve conflated price points

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