Skip to main content

3.5 Bets

Three operations share the bets resource: placing a bet, reading one back, and listing many.

Available calls:

3.5.1 Place a bet​

Method and URL:

POST /bets

Your response to this call decides whether the bet stands. This is the only endpoint where MollyBet depends on you making a decision in real time.

Request Parameters:

bet_id [ string ]:

Our own internal unique ID for this bet, which you must store and be able to look up later. It is not necessarily a UUID — treat it as an opaque string.

selection_id [ string ]:

The selection ID you published for this selection, echoed back to you verbatim.

price [ number ]:

The requested decimal price, to three places after the decimal point.

stake [ array ]:

The requested stake.

customer_id [ string ]:

The ID of the client placing the bet.

Example request body:

{
    "bet_id": "0xf47ac10b-58cc-4372-a567-0e02b2c3d479",
    "selection_id": "1009283|2098120|9182890|for",
    "price": 2.345,
    "stake": ["EUR", 10.50],
    "customer_id": "0x1892873"
}

Return Data: an object describing the outcome of your decision.

status [ string ]:

One of accepted, failed or danger. See the table below.

message [ string ]:

Any information you can provide about the decision. Free text; anything is welcome, particularly on a rejection.

price [ number ]:

The matched price if the bet was accepted, otherwise the requested price. An accepted price should never be lower than the one requested.

stake [ array ]:

The matched stake.

StatusMeaning
acceptedThe bet has been successfully placed.
failedThe bet failed to place.
dangerThe bet is in danger.

danger is provisional: MollyBet will poll the single-bet endpoint until the bet reaches a settled state.

Example output data:

{
    "status": "accepted",
    "price": 2.345,
    "stake": ["EUR", 10.50],
    "message": null
}

If this call fails at the network level, MollyBet cannot tell whether you received it. Recovery is done by listing bets over the relevant date range and reconciling on bet_id.

3.5.2 Get a single bet​

Method and URL:

GET /bets/{bet_id}

Request Parameters:

bet_id [ string ] (required, path):

The bet ID we supplied at placement, for example d290f1ee-6c54-4b01-90e6-d701748f0851.

Return Data: a single statement object.

This call is used mainly to follow bets you reported as danger, until they transition to a final state.

Example output data:

{
    "bet_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "status": "won",
    "reason": null,
    "creation_date_time": "2024-03-01T22:30:00Z",
    "settlement_date_time": "2024-03-03T10:15:00Z",
    "profit_loss": ["EUR", 5.775],
    "stake": ["EUR", 10.50],
    "price": 1.550,
    "sport": "fb",
    "event_info": {
        "league": {"name": "Spain | LaLiga", "id": 16},
        "start_time": "2024-04-13T16:30:00+00:00",
        "extra_info": {
            "home": {"name": "Real Mallorca", "id": 181},
            "away": {"name": "Real Madrid", "id": 178}
        }
    },
    "bet_type": "for,ml,h",
    "selection_id": "2024-04-13,181,178|90311133|181|for",
    "customer_id": "b1449c45ba0008a7aae5dd9c70f60fbd",
    "extra": null
}

3.5.3 List bets​

Method and URL:

GET /bets/?fetch_by=<fetch_by>&start_date=<start_date>&end_date=<end_date>

Request Parameters:

fetch_by [ string ] (required):

Either EVENT_DATE or BET_SETTLEMENT_DATE, selecting which date the range applies to. Searching by event date is strongly preferred.

start_date [ string ] (required):

Start of the date range, ISO 8601, for example 2024-06-04T22:30:00Z.

end_date [ string ] (required):

End of the date range, ISO 8601.

statuses [ array ] (optional):

Filter by one or more bet statuses. When omitted, return bets of any status.

limit [ integer ] (optional, default: 1000):

How many results to return per page.

Return Data: a paginated envelope whose results array contains statement objects.

This endpoint serves two purposes: recovering the list of recent placements after a network error, and letting MollyBet check how you have settled bets.

3.5.4 The statement object​

The same object is returned by both read endpoints.

bet_id [ string ]:

The bet ID we supplied at placement.

status [ string ]:

The current bet status.

reason [ string ]:

Why the bet failed, was rejected or was voided. Send null if you have no reason to give.

creation_date_time [ string ]:

When the bet was placed, ISO 8601, for example 2024-06-04T22:30:00Z

settlement_date_time [ string ]:

When the bet settled, ISO 8601, for example 2024-06-06T10:30:00Z.

profit_loss [ array ]:

How much was won (profit) or lost (loss), as a currency amount.

stake [ array ]:

The amount staked, as a currency amount.

price [ number ]:

The price at which the bet was placed, to three decimal places.

sport [ string ]:

One of the supported sports.

event_info [ object ]:

The league, start time and sides of the event. See Event info.

bet_type [ string ]:

The bet type, identical to the one published on the offer.

selection_id [ string ]:

The selection ID of the bet.

customer_id [ string ]:

The customer who placed the bet. This must be the internal MollyBet client ID we sent you at placement.

extra [ object ]:

Any additional information, as a key-value dictionary. For example, the originally requested odds can be reported as {"requested_price": 1.234}.

3.5.4.1 Event info​

event_info carries the league, the start time, and an extra_info object whose shape depends on the kind of event.

For a normal two-sided event, extra_info contains home and away:

"event_info": {
    "league": {"name": "Spain | LaLiga", "id": 16},
    "start_time": "2024-04-13T16:30:00+00:00",
    "extra_info": {
        "home": {"name": "Real Mallorca", "id": 181},
        "away": {"name": "Real Madrid", "id": 178}
    }
}

For a multirunner event, it contains the event name and the runner the bet was on:

"event_info": {
    "league": {"name": "USA | Keeneland", "id": null},
    "start_time": "2024-04-17T19:04:00+00:00",
    "extra_info": {
        "event": "19:04 Keeneland",
        "runner": {"name": "Neon Icon", "id": null}
    }
}