placeOrders

Operation

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

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

placeOrders 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 - MARKET_ON_CLOSE

To 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

[
    {
        "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
    }
]

[
    {
        "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 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

[{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/placeOrders", "params": {"marketId":"1.185101721","instructions":[{"selectionId":"35701728","handicap":"0","side":"BACK","orderType":"LIMIT_ON_CLOSE","limitOnCloseOrder":{"price":"5.0","liability":"2"}}]}, "id": 1}]

placeOrders Response

[{"jsonrpc":"2.0","result":{"status":"SUCCESS","marketId":"1.185101721","instructionReports":[{"status":"SUCCESS","instruction":{"selectionId":35701728,"handicap":0.0,"limitOnCloseOrder":{"liability":2.0,"price":5.0},"orderType":"LIMIT_ON_CLOSE","side":"BACK"},"betId":"237695599651","placedDate":"2021-07-08T08:45:54.000Z"}]},"id":1}]

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

[
    {
        "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": "PERSIST"
                    }
                }
            ]
        },
        "id": 1
    }
]

placeOrders Response

[
    {
        "jsonrpc": "2.0",
        "result": {
            "marketId": "1.109850906",
            "instructionReports": [
                {
                    "instruction": {
                        "selectionId": 237486,
                        "handicap": 0,
                        "limitOrder": {
                            "size": 2,
                            "price": 3,
                            "persistenceType": "PERSIST"
                        },
                        "orderType": "LIMIT",
                        "side": "LAY"
                    },
                    "betId": "31242604945",
                    "placedDate": "2013-10-30T14:22:47.000Z",
                    "averagePriceMatched": 0,
                    "sizeMatched": 0,
                    "status": "SUCCESS"
                }
            ],
            "status": "SUCCESS"
        },
        "id": 1
    }
]

Betting Enhancements

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.

Examples

FILL_OR_KILL order which was lapsed:

FILL_OR KILL requesting a minimum fill size of 3.00:

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 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/Liability

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

Examples

Placing a back bet targeting a £2 profit

Placing a lay bet targeting a £10 Payout

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

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

Asian Handicap & Total Goal Markets

Currency Parameters 

Guide to available currencies and minimum bet sizes.