4.3 Orders Requests
These functions are used to place new orders on MollyBet and to retrieve and manipulate the state of placed orders.
Available calls:
- 4.3.1 Create a new bet placement order
- 4.3.2 Create multiple bet placement orders on the MollyBet exchange
- 4.3.3 Return up-to-date information about an order
- 4.3.4 Close immediately an order
- 4.3.5 Close multiple orders
- 4.3.6 Request to close all open orders
- 4.3.7 Return information about placed orders matching certain requisites
- 4.3.8 Return the list of filter options for placers
- 4.3.9 Return the list of filter options for countries
- 4.3.10 Return the list of filter options for competitions
- 4.3.11 Return the list of filter options for events
- 4.3.12 Calculate a position for placed orders
4.3.1 Create a new bet placement order
Method and URL:
POST /v1/orders/
When placing through a normal betslip, MollyBet API will attempt to place the stake requested, at a price equal or better than the requested price. MollyBet will select the optimal account, placing as much stake as possible on the bookies offering the best price, automatically performing conversion in different currencies if needed.
If placement happens through a lay betslip, the stake field represents the potential return, while the price is the price you are willing to offer. MollyBet API will fill your order by placing enough bets until it meets your specified return with odds worse than the requested price.
All the accounts available will be considered, unless limited by the accounts parameter.
Placement will happen immediately provided that the price and stake requested are available on the market. If not, the order will remain in open state until new suitable offers appear, or the timeout specified in duration expires.
Note: MollyBet API will often not place full stake due to rounding. Typically, bookie accounts have constraints on the stake amount that they accept. In some cases, the stake amount must be a multiple of a certain value (stake increment), and have a minimum value, and possibly a maximum value. If, after conversion of the stake from the requested order currency into the bookie account currency, followed by rounding down to the nearest multiple of the stake increment, we find that the stake is below the minimum stake for that bookie account, then MollyBet API will not attempt to place in that account.
Request Parameters:
betslip_id [ string ]:
The ID of an open betslip, from which the sport, event_id, and bet_type will be taken.
price [ float ] (minimum: 1.0, maximum: 1000):
For a normal betlsip: the minimum price at which you're happy to bet. For a lay betslip: the maximum price you're happy to offer.
stake [ list[string, float] ]:
The amount you wish to stake on this bet (a [ccy_code, amount] list). Note that this is expressed in lay terms (the backer's stake) if you are placing through a lay betslip.
duration [ float ] (optional, default: 15, minimum: 1, maximum: 259200):
The length of time, in seconds, for which you want MollyBet to try and place the order.
keep_open_ir [ bool ] (optional, default: false):
If possible, keep the order open until the first goal or red card (rather than closing it as soon as the event goes in-running). The order will still be closed if it is filled or expires beforehand.
accounts [ list[list[string, string], ...] ] (optional, default: []):
Restrict placement to the specified list of bookie accounts. If this parameter is omitted or an empty list (the default), placement is allowed to use all accounts selected on the betslip.
Accounts are specified as a list of 2-item lists [bookie, username], e.g.:
[["bdaq", "_a6649ca0_"], ["sbo", "_056aa2f7_"]]
Any accounts supplied here that are not already on the betslip will be ignored. If account re-selection is enabled via
adaptive_bookies, this parameter will be honoured only until re-selection occurs.
adaptive_bookies [ list[string, ...] ] (optional):
The set of bookies from which MollyBet is allowed to re-select accounts in case of bookie errors during placement. If this parameter is omitted or null (the default), account re-selection is disabled; if the value is an empty list, re-selection is enabled for all bookies.
When re-selection occurs, any accounts inherited from the betslip that are not eligible for re-selection will be discarded.
bookie_min_stakes [ object{string -> list[string, float]} ] (optional, default: {}):
Only place a bet with certain bookies if intending to request at least a certain stake. Format is an object with bookie codes as keys and 2-items lists [currency code, amount] as value, e.g.:
{
"bf": ["GBP", 50.00],
"sbo": ["HKD", 1000.00]
}
Note that these are expressed in lay terms if you are placing through a lay betslip.
exchange_mode [ string ] (optional, default: "make_and_take"):
How this order should interact with the MollyBet exchange:
"make_and_take": Initially attempt to fill the order by consuming the best-priced available stake across the MollyBet exchange, as well as across other bookies and exchanges. If the order still has unfilled stake after this, advertise that stake on the MollyBet exchange for other customers to take at the price you specified; your order will continue to try to take the best available stake from other bookies and exchanges even while its remaining stake is advertised on the MollyBet exchange. This is the default behaviour.
"take_only": Only allow the order to be filled by consuming the best-available stake across the MollyBet exchange and other bookies and exchanges. Your order's remaining stake cannot be consumed by other orders (at your price point), and will not be made visible to anyone else. Your order can consume available stake from orders already posted to the MollyBet exchange (at their price point), but only if those orders have failed to match with anything else.
"dark": Like "make_and_take", except that the liquidity generated from your order's remaining stake is not visible to other customers. They can still match with your order if your price satisfies their requirements, but until that happens they don't know what your price is.
Note that this parameter is only meaningful when the "molly" bookie is available for the order to use.
min_taker_want_stake [ list[string, float] ] (optional):
For orders using the "dark" exchange mode: the minimum total amount that another order must have requested in order to be allowed to match with your order at your price point. The value you specify here (a [ccy_code, amount] list) cannot exceed your order want stake.
Set this to a non-zero value to prevent other customers from discovering your price point when placing small orders.
user_data [ string ] (optional):
Extra user data to attach to the order. It will be reported back as the user_data field in orders json. Max length: 256 unicode characters.
request_uuid [ UUID string ] (optional):
A UUID that uniquely identifies this request.
This is used to prevent duplicate orders from being placed in the event that your request is repeated. If you try to create multiple orders using the same UUID within a 24-hour period, only the first request will be acted upon.
Return Data: A structure containing details of the order placed.
Output Format:
order_id [ int ]:
The unique ID of the order.
bet_type [ string ]:
The bet type of the order.
bet_type_description [ string ]:
An human-readable explanation of the bet type.
order_type [ string ]:
Whether this is a "normal" or "lay" order.
sport [ string ]:
The sport of the order.
placer [ string ]:
MollyBet account username that placed the order.
want_price [ float ]:
The price requested for the order.
want_stake [ list[string, float] ]:
The total stake requested to place, in [currency code, amount] format.
ccy_rate [ float ]:
The exchange rate from Pounds Sterling to the want currency at the time of placement, i.e.
amount in want currency = amount in GBP × ccy_rate.
placement_time [ ISO 8601 datetime string ]:
The date and time at which the order was placed.
expiry_time [ ISO 8601 datetime string ]:
The date and time at which the order expires.
exchange_mode [ string ]:
The MollyBet exchange interaction mode as passed in the create order request; null for older orders.
closed [ bool ]:
true if the order is closed.
close_reason [ string ]:
If the order is closed, a code reporting why the error was closed (e.g. order_filled, timed_out, cancelled, etc.)
event_info [ object ]:
A structure reporting known information about the sport event the order was placed on.
bets [ list[object, ...] ] (optional):
The list of bets placed to fill this order.
This field is missing at placement time because placement happens asynchronously; further calls to query the order state (e.g. Order Info, Orders List...) will contain a list of bets. The description for this structure is in the Order Info format documentation.
user_data [ string ]:
Whatever value was provided as the user_data field in the POST /v1/orders request, if any.
status [ string ]:
The current status of the order. See list of order statuses.
The event_info structure contains the following attributes:
event_id [ string ]:
An opaque identifier for the event.
home_id [ int ]:
The unique ID of the home team.
home_team [ string ]:
The name of the home team.
away_id [ int ]:
The unique ID of the away team.
away_team [ string ]:
The name of the away team.
competition_id [ int ]:
The unique ID of the event competition.
competition_name [ string ]:
The name of the event competition.
start_time [ ISO 8601 datetime string ]:
The start time of the event, if known.
date [ ISO 8601 date string ]:
The date of the event.
Note that this date usually refers to European time: different bookmakers in different time zones may report an event under different dates.
Example:
An example result for a order placement response could be:
{
"order_id": 19581948,
"bet_type": "for,ahunder,40",
"bet_type_description": "Corners: Under 10.0 corners (Asian)",
"order_type": "normal",
"sport": "fb_corn",
"placer": "johndoe",
"want_price": 2.0,
"want_stake": ["EUR", 60.0],
"ccy_rate": 1.160200,
"placement_time": "2016-09-27T14:16:11.719478+00:00",
"expiry_time": "2016-09-27T14:17:11.718960+00:00",
"exchange_mode": "make_and_take",
"closed": false,
"close_reason": null,
"event_info": {
"event_id": "2016-09-27,194,178",
"home_id": 194,
"home_team": "BV Borussia 09 Dortmund",
"away_id": 178,
"away_team": "Real Madrid CF",
"competition_id": 28,
"competition_name": "UEFA Champions League",
"competition_country": "EU",
"start_time": "2016-09-27T18:45:00+00:00",
"date": "2016-09-27",
}
}
4.3.2 Create multiple bet placement orders on the MollyBet exchange
Method and URL:
POST /v1/orders/batch/
Create multiple orders, analogously to Open Order. This method of placing orders does not require first creating a betslip. All requested orders will first be validated, and then either all placed, or all rejected. It is not possible for some orders to be placed while others are rejected due to validation errors. Orders made in this way will only be eligible for the MollyBet exchange.
The request is an array orders, containing requests in a very similar format to a regular Open Order.
The maximum number of orders in the array is 200.
Parameters handled analogously to Open Order:
price:
stake:
duration (optional):
exchange_mode (optional):
min_taker_want_stake (optional):
user_data (optional):
request_uuid (optional):
Additional parameters, that otherwise would have been drawn from the betslip
order_type:
Supports the same options as betslip_type that would otherwise have been specified when opening the betslip.
sport:
event_id:
bet_type:
Example Request:
{
"orders": [
{
"sport": "fb",
"event_id": "2016-10-17,49,53",
"bet_type": "for,h",
"duration": 300,
"price": 2.5,
"stake": ["EUR", 100]
},
{
"sport": "fb",
"event_id": "2016-10-17,43,57",
"bet_type": "for,a",
"duration": 60,
"price": 1.8,
"stake": ["GBP", 20]
}
]
}
Return Data: An array of orders placed, with the same number of elements, and the same order, as the request.
Example of response structure:
{
"orders": [
{
"bet_type": "for,h",
...
"event_info": {
...
},
...
"want_price": 2.5,
"want_stake": ["EUR", 100.0]
},
{
"bet_type": "for,a",
...
}
]
}
4.3.3 Return up-to-date information about an order
Method and URL:
GET /v1/orders/<order_id>/
URL Parameters:
order_id:
The unique ID of the order as returned by Open Order.
Return Data: A structure containing info about the requested order.
Output Format:
The structure returned by the call is the same of the one returned by Open Order, but it will contain the list of placed bets too.
The format of the bet structure is the following:
bet_id [ int ]:
The unique ID of the bet.
order_id [ int ]:
The unique ID of the order the bet was placed for.
bookie_bet_id [ string ] (optional):
The bet ID returned by the bookmaker.
status [ object ]:
The current state of the bet. A JSON structure containing the attributes:
code [ string ]:
The code of the status, see list of bet statuses.
reason [ string ] (optional):
The reason for the bet state, usually available only for failed bets.
sport [ string ]:
The sport of the order.
event_id [ string ]:
An opaque identifier for the event.
bookie [ string ]:
The code of the bookmaker the bet was placed on.
username [ string ]:
The bookmaker account username the bet was placed on.
bet_type [ string ]:
The bet type of the order.
ccy_rate [ float ]:
The exchange rate from Pounds Sterling to the bet currency at the time of placement, i.e.
amount in bet currency = amount in GBP × ccy_rate.
order_ccy_rate [ float ]:
The exchange rate from Pounds Sterling to the order want currency at the time of bet placement, i.e.
amount in want currency = (amount in bet currency ÷ ccy_rate) × order_ccy_rate.
order_ccy_ratemay be different from the order's ownccy_rateif the bet was placed a long time after the order (e.g. in a future fulfilment order).
want_price [ float ]:
The price requested for this bet.
got_price [ float ]:
The price obtained by this bet.
want_stake [ list[string, float] ]:
The stake requested to place for this bet, in [currency code, amount] format.
got_stake [ list[string, float] ]:
The stake placed in this bet, in [currency code, amount] format.
profit_loss [ list[string, float] ] (optional):
The profit or loss of this bet, if settled, in [currency code, amount] format.
reconciled [ bool ]:
true if MollyBet and the bookmaker agree on the bet profit loss, false if there is a disagreement (while it is investigated). null if the bet is still unsettled.
exchange_role [ string ]:
"maker" or "taker" for bets on the MollyBet exchange. null for non-exchange bets.
Example:
The same order in the Open Order example may be returned as the following structure after one bet is placed and settled:
{
"order_id": 19581948,
"bet_type": "for,ahunder,40",
"bet_type_description": "Corners: Under 10.0 corners (Asian)",
"order_type": "normal",
"sport": "fb_corn",
"placer": "johndoe",
"want_price": 2.0,
"want_stake": ["EUR", 60.0],
"ccy_rate": 1.160200,
"placement_time": "2016-09-27T14:16:11.719478+00:00",
"expiry_time": "2016-09-27T14:17:11.718960+00:00",
"exchange_mode": "make_and_take",
"closed": true,
"close_reason": "order_filled",
"event_info": {
"event_id": "2016-09-27,194,178",
"home_id": 194,
"home_team": "BV Borussia 09 Dortmund",
"away_id": 178,
"away_team": "Real Madrid CF",
"competition_id": 28,
"competition_name": "UEFA Champions League",
"competition_country": "EU",
"start_time": "2016-09-27T18:45:00+00:00",
"date": "2016-09-27",
},
"bets": [
{
"bet_id": 3324372947,
"order_id": 19581948,
"bookie_bet_id": "5575992964",
"status": {
"code": "settled"
},
"sport": "fb_corn",
"event_id": "2016-09-27,194,178",
"bookie": "sbo",
"username": "_ae3d7f51_",
"bet_type": "for,ahunder,40",
"ccy_rate": 10.068,
"order_ccy_rate": 1.168902,
"want_price": 2.01,
"got_price": 2.010101,
"want_stake": ["HKD", 502.52],
"got_stake": ["HKD", 502.52],
"profit_loss": ["HKD", -502.52],
"reconciled": true,
"exchange_role": null
}
],
"user_data": null,
"status": "reconciled"
}
4.3.4 Close immediately an order
Method and URL:
POST /v1/orders/<order_id>/close/
URL Parameters:
order_id:
The ID of the order to cancel.
4.3.5 Close multiple orders
Method and URL:
POST /v1/orders/close_many/
Close multiple orders synchronously.
Request Parameters:
order_ids [ list[int, ...] ]:
The set of orders to cancel, identified by order ID. Maximum 500
Return Data: A list "closed" of the IDs of all orders succesfully closed (or that had previously been closed) and a list "not_found" of any order IDs that were requested to be closed that have not been. The request will be considered succesful no matter how many orders are closed vs not_found.
Example:
"data": {
"closed": [23, 45, 46],
"not_found": [39]
}
4.3.6 Request to close all open orders
Method and URL:
POST /v1/orders/close_all/
Request immediate cancellation of all your open orders.
An order message will be sent for each closed order indicating its new status.
Request Parameters:
sport [ string ] (optional):
Only close orders on this exact sport.
event_id [ string ] (optional):
Only close orders on this event. sport must also have been specified.
Return Data: A list of IDs of the orders being closed.
4.3.7 Return information about placed orders matching certain requisites
Method and URL:
GET /v1/orders/
Request Parameters:
page [ int ] (optional, default: 1, minimum: 1):
Number of the page to retrieve.
page_size [ int ] (optional, default: 25, minimum: 1, maximum: 1000):
Maximum number of items per page.
order_by [ list[string, ...] ] (optional, default: ["placement_time desc"]):
How to order the results, as a list of "attribute asc|desc" strings.
placer [ string ] (optional):
Show only orders placed by this MollyBet account (username).
group_id [ int ] (optional):
Show only orders placed by accounts in the given group.
date_from [ ISO 8601 datetime string ] (optional):
Show only orders placed from this date/time on.
date_to [ ISO 8601 datetime string ] (optional):
Show only orders placed before this date/time.
event_start_from [ ISO 8601 datetime string ] (optional):
Show only orders on events that start after this date/time. Note: in some rare cases only the date of the event is known, not the start time. In such cases, the start time is assumed to be 12:00 UTC for the purpose of this filter.
event_start_to [ ISO 8601 datetime string ] (optional):
Show only orders on events that start before this date/time. Note: same note from event_start_from applies here.
sport [ string ] (optional):
Show only orders placed on this sport (sport code).
event_id [ list[string, ...] ] (optional, default: []):
Show only orders placed on this event.
competition_id [ int ] (optional):
Show only orders placed on this competition (specified by competition id).
competition_country [ string ] (optional):
Show only orders placed on this country (a two-letters country code).
search [ string ] (optional):
Show only orders with a certain substring in the players/teams names.
placed_inrunning [ bool ] (optional):
If value is 'true', include only orders placed after the event has started. If value is 'false', only orders placed before the event started are included. If ommitted or null, both inrunning and deadball orders are included.
status [ list[string, ...] ] (optional):
Show only orders with selected statuses.
order_type [ string ] (optional):
Show only orders of a certain type.
exchange_mode [ string ] (optional):
Show only placed using a certain exchange mode.
wanted_ids [ list[string, ...] ] (optional):
Filter orders that contain these IDs. These might be present as order IDs, bet IDs or bookie bet IDs.
Return Data: A list of order structures matching the filters provided in the request.
4.3.8 Return the list of filter options for placers
Method and URL:
GET /v1/orders/filters/placers/
Output Format:
A list of objects of the form:
username [ string ]:
The unique username of the placer, to be used for filtering.
name [ string ]:
The display name for the placer option.
4.3.9 Return the list of filter options for countries
Method and URL:
GET /v1/orders/filters/countries/
Output Format:
A list of objects of the form:
competition_country [ string ]:
The unique ID of the country, to be used for filtering.
name [ string ]:
The display name for the country option.
4.3.10 Return the list of filter options for competitions
Method and URL:
GET /v1/orders/filters/competitions/
Request Parameters:
competition_country [ string ] (optional):
The unique ID of the event country.
Output Format:
A list of objects of the form:
competition_id [ integer ]:
The unique ID of the competition, to be used for filtering.
competition_country [ string ]:
The unique ID of the competition country.
name [ string ]:
The display name for the competition option.
4.3.11 Return the list of filter options for events
Method and URL:
GET /v1/orders/filters/events/
Request Parameters:
competition_country [ string ] (optional):
The unique ID of the event country.
competition_id [ int ] (optional):
The unique ID of the event competition.
event_date_from [ ISO 8601 date string ] (optional):
Only return events on or after this date.
event_date_to [ ISO 8601 date string ] (optional):
Only return events before or on this date.
Output Format:
A list of objects of the form:
event_id [ string ]:
The unique ID of the event, to be used for filtering.
name [ string ]:
The display name for the event option.
4.3.12 Calculate a position for placed orders
Method and URL:
GET /v1/orders/position/
Request Parameters:
The method accepts the same parameters of the Orders List call.
Output Format:
payoff_grid [ object{ccy_code -> string, values -> list[list[float, ...], ...]} ] (optional):
An object reporting what would be the Profit/Loss according to each possible outcome of the sport event. It contains a currency code and a grid of numbers, usually a 10 × 10, reporting, in the position values[M][N], the profit or loss of this position if the event result was home: M, away: N.
totals [ object{string -> object} ]:
Information about the matched price and stake for each bet type.
placers [ list[string, ...] ]:
List of usernames of the MollyBet accounts that placed bets making this position.
unknown_bets_num [ int ]:
The number of bets on this position whose state is currently unknown.
unknown_grid [ object{ccy_code -> string, values -> list[list[float, ...], ...]} ] (optional):
An object with the same meaning of the payoff_grid reporting the possible profit/loss for bets which are in an unknown state, if any.
The objects returned in the totals object have the following attribute:
bet_type_description [ string ]:
An human-readable explanation of the bet type.
got_price [ float ] (optional):
The weighted-average price obtained on this bet type.
got_stake [ list[string, float] ]:
The total stake placed on this bet type, as a [currency code, amount] 2-elements list.
unknown_price [ float ] (optional):
The weighted-average price for bets whose state is currently unknown.
unknown_stake [ list[string, float] ]:
The total stake for bets whose state is currently unknown, as a [currency code, amount] 2-elements list.
Example:
After some bets have placed for Borussia Dortmund as home team winning, for a combined stake of 100 EUR at an average decimal price of 2.88, the following position grid could be returned:
{
"payoff_grid": {
"ccy_code": "EUR",
"values": [
[-100.00, -100.00, -100.00, /* ... other 7 values */ ],
[188.00, -100.00, -100.00, /* ... other 7 values */ ],
[188.00, 188.00, -100.00, /* ... other 7 values */ ],
/* ... other 7 rows */
]
},
"totals": {
"for,h": {
"bet_type_description": "BV Borussia 09 Dortmund",
"got_price": 2.88,
"got_stake": ["EUR", 100.00],
"unknown_price": null,
"unknown_stake": ["EUR", 0.0],
}
},
"placers": ["john", "jack"],
"unknown_bets_num": 0,
"unknown_grid": null
}