...
Table of Contents-zone | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operation
|
|
|
|
|
|
Description
Throws | Description |
---|---|
Generic exception that is thrown if this operation fails for any reason. |
Since 1.0.0
Fill or Kill bets
By setting the optional parameter ‘TimeInForce’ on a limitOrder submission to the value ‘FILL_OR_KILL’ and optionally passing a minFillSize value, the Exchange will only match the order if at least the specified minFillSize can be matched (if passed) or the whole order matched (if not). Any order which cannot be so matched, and any remaining unmatched part of the order (if minFillSize is specified) will be immediately cancelled.
Please note: the matching algorithm for Fill or Kill orders behaves slightly differently to that for standard limit orders. Whereas the price on a limit order represents the lowest price at which any fragment should be matched, the price on a Fill or Kill order represents the lower limit of the Volume Weighted Average Price (“VWAP”) for the entire volume matched. So, for instance, a Fill or Kill order with price = 5.4 and size = 10 might be matched as £2 @ 5.5, £6 @ 5.4 and £2 @ 5.3.
Market version parameter
We have added an additional optional parameter ‘marketVersion’ to the ‘placeOrders’ and ‘replaceOrders’ operations. The MarketBook data item, which contains the dynamic data on a market, including its prices, has always returned an integer market ‘version’. This ‘version’ is incremented when significant events – runner removal, turn in-play etc. – occur. Now, by passing that version as ‘marketVersion’ with your orders, you can specify that if the market version has been incremented beyond that value, your orders should lapse and not be submitted for matching.
This functionality should be of use to those who want to bet right up to the actual ‘off’ of a horserace or sporting event but be confident that you’re not inadvertently bet into the first seconds of in-play after the off. Similarly, in managed football markets, you can avoid your bets reaching the Exchange after the market has reformed following a goal being scored etc.
Bet to Payout or Profit/Liability
Currently, best execution, which guarantees that you’ll receive the best possible price, means that you receive a greater potential payout to the same stakes (or risk a smaller potential payout to the same backer’s stakes, for layers).
If alternatively you should wish to benefit by receiving the same potential payout as you originally requested, but to smaller stakes, you can now specify on a LimitOrder (placeOrders) an optional ‘betTargetType’ of ‘PAYOUT’ or ‘BACKERS_PROFIT’ (the latter being identical to layers’ liability) and a ‘betTargetSize’ representing the value of that payout or profit, together with the usual ‘price’ parameter to represent their limit price. Your bet will then be matched to achieve that payout or profit at the specified price or better.
Should all or any of the order be unmatched after first reaching the Exchange, the unmatched portion will be expressed in standard price and backers’ stake terms (by dividing the remaining unmatched payout by the price, or unmatched profit by the price – 1, and placed on the unmatched queue), after this point the bet behaves like any other.
Ability to place lower minimum stakes at larger prices
In order to allow customers to bet to smaller stakes on longer-priced selections, an extra property has been added to our Currency Parameters – “Min Bet Payout”.
As currently bets where the backer’s stake is at and above the ‘Min Bet Size’ for the currency concerned (£2 for GBP) are valid. In addition, bets below this value are valid if the payout of the bet would be equal to or greater than the value of ‘Min Bet Payout’ - £10 for GBP. For example, a bet of £1 @ 10, or 10p @ 100 or 1p @ 1000 are all valid as they all target a payout of £10 or more.
Please note: This function is only enabled for UK & International customers and not .it, .es, .dk jurisdictions.
Each Way Betting
Each Way betting is available via the API. Each Way markets can be identified as marketType EACH_WAY using listMarketCatalogue. The divisor that applies to the EACH_WAY market is returned by listMarketCatalogue via the MARKET_DESCRIPTION MarketProjection.
Please see table a table that indicates how the “Each-Way divisor" is determined for specific race types:
Race Type | Number of Runners(1) | Number of Places | Fraction of Win Odds “Each-Way divisor" |
Handicap | 16 or more | 4 | 1/4 |
Handicap | 12 to 15 | 3 | 1/4 |
Handicap | 8 to 11 | 3 | 1/5 |
Handicap | 5 to 7 | 2 | 1/4 |
Non-Handicap | 8 or more | 3 | 1/5 |
Non-Handicap | 5 to 7 | 2 | 1/4 |
(1) Number of Runners at Market creation time; place terms are fixed for the life of the market (like Betfair Place market) not dependent on number of runners at the off (like Fixed Odds EW markets)
We will not offer EW markets if the number of runners at market creation time is 4 or fewer
Betfair Price Increments
Below is a list of price increments per price 'group'. Placing a bet outside of these increments will result in an INVALID_ODDS error
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 |
Placing a BetTo 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 placeOrders Request
placeOrders Response
Placing a Betfair SP Bet - MARKET_ON_CLOSETo place a bet on a selection at Betfair SP (MARKET_ON_CLOSE) 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. placeOrders Request
placeOrders Response
Placing a Betfair SP Bet - LIMIT_ON_CLOSEBelow is an example of a Betfair SP Bet - using the orderType LIMIT_ON_CLOSE. Please refer to Additional Information#CurrencyParameters for Min BSP liability for LAY bets. The below example show a LIMIT_ON_CLOSE BACK order for a minimum price of 5.0 and a stake of £2. placeOrders Request
placeOrders Response
Placing a 'Keep' Bet To place a bet that will be kept once a market turns in-play (if unmatched), you must include the below parameters i.e. "persistenceType": "PERSIST" The bet will then be placed automatically into the in-play market at the start of the event. placeOrders Request
placeOrders Response
Betting EnhancementsFill or Kill betsBy setting the optional parameter ‘TimeInForce’ on a limitOrder submission to the value ‘FILL_OR_KILL’ and optionally passing a minFillSize value, the Exchange will only match the order if at least the specified minFillSize can be matched (if passed) or the whole order matched (if not). Any order which cannot be so matched, and any remaining unmatched part of the order (if minFillSize is specified) will be immediately cancelled. Please note: the matching algorithm for Fill or Kill orders behaves slightly differently to that for standard limit orders. Whereas the price on a limit order represents the lowest price at which any fragment should be matched, the price on a Fill or Kill order represents the lower limit of the Volume Weighted Average Price (“VWAP”) for the entire volume matched. So, for instance, a Fill or Kill order with price = 5.4 and size = 10 might be matched as £2 @ 5.5, £6 @ 5.4 and £2 @ 5.3. ExamplesFILL_OR_KILL order which was lapsed:
FILL_OR KILL requesting a minimum fill size of 3.00:
Market version parameterWe have added an additional optional parameter ‘marketVersion’ to the ‘placeOrders’ and ‘replaceOrders’ operations. The MarketBook data item, which contains the dynamic data on a market, including its prices, has always returned an integer market ‘version’. This ‘version’ is incremented when significant events – runner removal, turn in-play etc. – occur. Now, by passing that version as ‘marketVersion’ with your orders, you can specify that if the market version has been incremented beyond that value, your orders should lapse and not be submitted for matching. This functionality should be of use to those who want to bet right up to the actual ‘off’ of a horse race or sporting event but be confident that you’re not inadvertently bet into the first seconds of in-play after the off. Similarly, in managed football markets, you can avoid your bets reaching the Exchange after the market has reformed following a goal being scored etc. Notes on 'version' behavior The ‘market version’ value (on listMarketBook and on ESA) is incremented for any and all changes to the market. However, to prevent falsely blocking bets we keep track of the last material change (which we define as one performed under suspension**) and will only accept bets placed with that version or later.
** this includes: - Runner removal and addition - Turn in-play - Lapsing or voiding bets (eg on goals being scored in managed Football market) But not (e.g.) updating Tennis court times or Golf tee times as they become more accurately known on the day.
Bet to Payout or Profit/LiabilityPlace a bet specifying your target payout, profit or liability, instead of the backers stake ('size'). Currently, best execution, which guarantees that you’ll receive the best possible price, means that you receive a greater potential payout to the same stakes (or risk a smaller potential payout to the same backer’s stakes, for layers). If you wish to benefit by receiving the same potential payout as you originally requested, but to smaller stakes, you can now specify on a LimitOrder (placeOrders) an optional ‘betTargetType’ of ‘PAYOUT’ or ‘BACKERS_PROFIT’ (the latter being identical to layers’ liability) and a ‘betTargetSize’ representing the value of that payout or profit, together with the usual ‘price’ parameter to represent their limit price. Your bet will then be matched to achieve that payout or profit at the specified price or better. Should all or any of the order be unmatched after first reaching the Exchange, the unmatched portion will be expressed in standard price and backers’ stake terms (by dividing the remaining unmatched payout by the price, or unmatched profit by the price – 1, and placed on the unmatched queue), after this point the bet behaves like any other. Please note: This function is only enabled for UK & International customers and not .it, .es, .dk and .se jurisdictions. ExamplesPlacing a back bet targeting a £2 profit
Placing a lay bet targeting a £10 Payout
Ability to place lower minimum stakes at larger pricesIn order to allow customers to bet to smaller stakes on longer-priced selections, an extra property has been added to our Currency Parameters – “Min Bet Payout”. As currently LIMIT bets where the backer’s stake is at and above the ‘Min Bet Size’ for the currency concerned (£1 for GBP) are valid. In addition, bets below this value are valid if the payout of the bet would be equal to or greater than the value of ‘Min Bet Payout’ - £10 for GBP. For example, a bet of £1 @ 10, or 10p @ 100 or 1p @ 1000 are all valid as they all target a payout of £10 or more. This functionality is available to "orderType: LIMIT" bets only. Please note: This function is only enabled for UK & International customers and not .it, .es, .dk and .se jurisdictions. Each Way BettingEach Way betting is available via the API. Each Way markets can be identified as marketType EACH_WAY using listMarketCatalogue. Please note: your potential liability for an each way bet is 'size' x 2, so for a 10 size bet your available to bet balance will be reduced by 20, for example. The divisor that applies to the EACH_WAY market is returned by listMarketCatalogue via the MARKET_DESCRIPTION MarketProjection. Please see table a table that indicates how the “Each-Way divisor" is determined for specific race types:
(1) Number of Runners at Market creation time; place terms are fixed for the life of the market (like Betfair Place market) not dependent on number of runners at the off (like Fixed Odds EW markets) We will not offer EW markets if the number of runners at market creation time is 4 or fewer Betfair Price IncrementsBelow is a list of price increments per price 'group'. Placing a bet outside of these increments will result in an INVALID_ODDS error Odds Markets
Asian Handicap & Total Goal Markets
Currency Parameters
Guide to available currencies and minimum bet sizes. |