4.2 Betslips Requests
A betslip must be open when an API client wants to place bets on a certain event.
The betslip will select the best available accounts to use for placing bets on the selected bet type, and will commence a PMM cycle on each of those accounts. A PMM (Price, Min and Max) is the process of repeatedly opening up a betslip on the bookie website to ensure we have the latest price for that bet type, and also the minimum and maximum stakes available for that bet.
The state of the betslips is sent to the client via the asynchronous stream, using async betslips messages.
Available calls:
4.2.1 Open a new betslip for a given event and bet type
Method and URL:
POST /v1/betslips/
When a betslip is opened the system will fetch the available prices and stake ranges on the supplied event (as determined by event_id). The betslip is identified by a betslip_id attribute which should be used to manipulate its state in further MollyBet API calls.
Request Parameters:
sport [ string ]:
The sport for the event in which you're interested
event_id [ string ]:
The event ID for the event in which you're interested
bet_type [ string ]:
The bet type in which you're interested
equivalent_bets [ bool ] (optional, default: true):
Use bets that are equivalent to the bet type you've requested in addition to the bet type you've actually asked for.
For example, a bet on under 0.5 goals is equivalent to a bet on correct score 0-0. With this option set, we'll try and bet on both (assuming there are sufficient bookie accounts available).
multiple_accounts [ bool ] (optional, default: false):
If you have multiple accounts with a given bookie, add all of them to the betslip.
This means that if this betslip is used for placing an order then we may potentially place multiple bets on the same bookie simultaneously. Note, however, that with this option set equivalent bets will only be used if the requested bet type is not available.
If this option is not given, then a single account per bookie will be selected and used.
want_bookies [ list[string, ...] ] (optional):
The set of bookies from which to select accounts to display on the betslip. If this option is omitted, then accounts from all available bookies will be used.
equivalent_bets_bookies [ list[string, ...] ] (optional):
List of bookies for which equivalent bet types should be enabled.
If omitted or empty, equivalent bet types will apply to all bookies.
betslip_type [ string ] (optional, default: "normal"):
What mode to open the betslip in.
Possible options are "normal" and "lay". Normal betslips always display price to back the outcome and your potential loss. Lay betslips always display lay odds and your potential profit (i.e. backer's odds and risk).
That is, in a lay betslip all price and stake fields will be populated with lay values. That is the case for exchanges, but also external bookmakers where equivalent bets were found; those will be converted to lay odds by MollyBet API.
A normal betslip can be opened with any bet type, while a lay betslip may only be opened with an against, bet type.
Placement through a lay betslip creates a lay order, and must be provided with lay inputs for the price and stake fields.
Return Data: An object with the new betslip attributes.
Output Format:
betslip_id [ string ]:
The unique identifier for the betslip.
sport [ string ]:
The sport for the event.
event_id [ string ]:
The event ID for the event.
bet_type [ string ]:
The bet type of the betslip.
betslip_type [ string ]:
The type of the betslip, as passed in from the request.
equivalent_bets [ bool ]:
Whether equivalent bets are enabled for this betslip.
multiple_accounts [ bool ]:
Whether multiple accounts are enabled for this betslip.
want_bookies [ list[string, ...] ]:
The set of bookies enabled for this betslip.
is_open [ bool ]:
If true this betslip is still open.
expiry_ts [ float ]:
Unix timestamp for the time when the betslip will expire.
bookies_with_offers [ list[string, ...] ]:
List of bookies which have offers for this selection.
equivalent_bets_bookies [ list[string, ...] ]:
The equivalent_bets_bookies as provided by the user.
close_reason [ string ]:
The reason, if any, why the betslip was closed.
customer_username [ string ]:
The username for the account that opened the betslip.
customer_ccy [ string ]:
The currency code for the account that opened the betslip.
invalid_accounts [ object{string -> object{string -> string}} ]:
Any invalid accounts that were found, with the reason.
accounts [ list[object, ...] ]:
list of accounts currently selected for this betslip.
The accounts attribute is a list of objects with format:
bookie [ string ]:
The bookmaker code of this account.
username [ string ]:
The username of this account.
bet_type [ string ]:
A string representing the bet type.
See List of Bet Types for explanations.
status [ string ] (optional):
Status of the last pmm on this account, if any.
price_list [ list[object, ...] ] (optional):
Price list of the last PMM on this account, if any.
Every object of the list has two attribute:
bookie [ list[object, ...] ] (optional):
The original price and min/max entries as received by the bookie.
effective [ list[object, ...] ]:
The net price and min/max after taking commission, referral fees, etc. into account.
Both lists contain PMM objects with attributes:
price [ float ]:
The decimal or lay price of the offer, depending on betslip type.
min [ list[string, float] ]
The minimum stake that can be placed as a 2-items list: [currency code, amount], expressed as a lay stake if the betslip is of type lay.
max [ list[string, float] ]
The maximum stake that can be placed as a 2-items list: [currency code, amount], expressed as a lay stake if the betslip is of type lay.
Normal bookies only offer one PMM for their selections, so their price list will contain a single item. Exchanges may have different prices for each selection and the list will report all of them.
See the Get Betslip output for an example of these objects.
Example:
Example request:
{
"sport": "fb",
"event_id": "2016-10-17,49,53",
"bet_type": "for,h"
}
Example return data:
This is a sample of a betslip returned by the Open Betslip call, so it is returned before the bookie can report the current price and available stake: these details can be returned later (see the Get Betslip output for example) or via asynchronous messages.
{
"betslip_id": "cd75b859154f44b28e7dbd637c5b92fb",
"sport": "fb",
"event_id": "2016-10-17,49,53",
"bet_type": "for,h",
"betslip_type": "normal",
"equivalent_bets": true,
"multiple_accounts": false,
"is_open": true,
"expiry_ts": 1476197232.96185,
"bookies_with_offers": ["bdaq", "bf", "sing2", "pin", "ibc", "mbook", "sbo"],
"equivalent_bets_bookies": [],
"want_bookies": [],
"close_reason": null,
"customer_username": "johndoe",
"customer_ccy": "EUR",
"invalid_accounts": {},
"accounts": [
{"bookie": "bdaq", "username": "_a6649ca0_", "bet_type": "against,ah,a,-2"},
{"bookie": "bdaq", "username": "_a6649ca0_", "bet_type": "for,ah,h,-2"},
{"bookie": "bdaq", "username": "_a6649ca0_", "bet_type": "for,h"},
{"bookie": "ibc", "username": "_de96a92f_", "bet_type": "for,ah,h,-2"},
{"bookie": "ibc", "username": "_62ce0e10_", "bet_type": "for,h"},
{"bookie": "sbo", "username": "_fd3fed83_", "bet_type": "for,ah,h,-2"},
{"bookie": "sbo", "username": "_056aa2f7_", "bet_type": "for,h"}
]
}
4.2.2 List the currently open betslips
Method and URL:
GET /v1/betslips/
Return Data: A list containing the betslip_id of each currently open betslip.
4.2.3 Get the current state of an open betslip
Method and URL:
GET /v1/betslips/<betslip_id>/
The betslip state includes the same attributes returned by Open Betslip and the state that has been accumulated asynchronously with the PMM responses. Note that the most efficient way to react to PMMs is not to use this call but to listen for PMMs on the async channel.
URL Parameters:
betslip_id:
The identifier of the betslip as returned by Open Betslip.
Return Data: An object with the same format of the Open Betslip output, possibly with more information.
Example:
Example output:
{
"betslip_id": "923264e50fe34ab49053d2a369a3a7be",
"sport": "fb",
"event_id": "2016-10-17,49,53",
"bet_type": "for,h",
"betslip_type": "normal",
"bet_type_description": "HOME",
"equivalent_bets": true,
"multiple_accounts": false,
"is_open": true,
"expiry_ts": 1476199028.620634,
"bookies_with_offers": ["bdaq", "bf", "sing2", "pin", "ibc", "mbook", "sbo"],
"equivalent_bets_bookies": [],
"want_bookies": [],
"close_reason": null,
"customer_username": "johndoe",
"customer_ccy": "EUR",
"invalid_accounts": {},
"accounts": [
{
"bookie": "bdaq", "username": "_a6649ca0_", "bet_type": "against,ah,a,-2",
"status": "success", "price_list": [
{
"bookie": {
"price": 2.075, "min": ["GBP", 0.46], "max": ["GBP", 999.75]
},
"effective": {
"price": 2.064, "min": ["GBP", 0.46], "max": ["GBP", 999.75]
}
},
{
"bookie": {
"price": 2.0, "min": ["GBP", 0.5], "max": ["GBP", 1000.0]
},
"effective": {
"price": 1.99, "min": ["GBP", 0.5], "max": ["GBP", 1000.0]
}
}
]
},
{
"bookie": "sbo", "username": "_056aa2f7_", "bet_type": "for,h",
"status": "success", "price_list": [
{
"bookie": {
"price": 2.12, "min": ["MYR", 4.5], "max": ["MYR", 6923.7]
},
"effective": {
"price": 2.12, "min": ["GBP", 0.81], "max": ["GBP", 1356.01]
}
}
]
}
]
}
4.2.4 Extend the betslip expiration timeout
Method and URL:
POST /v1/betslips/<betslip_id>/refresh/
Betslips have an expiration timeout (see the expiry_ts attribute in Get Betslip). If you want to keep the betslip open for longer you can use this method.
URL Parameters:
betslip_id:
The identifier of the betslip as returned by Open Betslip.
4.2.5 Close a betslip
Method and URL:
DELETE /v1/betslips/<betslip_id>/
Closing the betslip releases the resources associated to it, in particular it stops the PMM cycle.
URL Parameters:
betslip_id:
The identifier of the betslip as returned by Open Betslip.