Parlays (2–12 leg trades)
A parlay combines 2–12 individual selections into one order: every leg must settle as profit for the parlay to settle as profit. The workflow is quote → confirm → poll, not a single-shot submit, because the price is stitched together from the constituent legs and can move while your user is deciding.
Same-game parlays (SGP) are supported. There's nothing special to do on your end — a parlay is automatically treated as an SGP when 2+ of its legs share the same eventId, including combinations of player props on the same event. It changes settlement behavior (see the push/void note in §2) but not the request shape.
Auth varies by endpoint. POST /parlays (create) and POST /parlays/{parlayId}/confirm are user-scoped (sub == acting user's UUID + subsig). GET /parlays and GET /parlays/{parlayId} accept either a user-scoped JWT or an ISV-only JWT with ?userId= (see sections 8–9). The browsing endpoints in section 3 and the indicative-pricing endpoint in section 5 are ISV-only — no sub at all. See Authentication.
Required permission:
parlay.GET /private/v1/parlays/supported-contracts,POST /private/v1/parlays, andPOST /private/v1/parlays/{parlayId}/confirmare gated server-side on theparlayuser permission (via thex-required-permissionannotation on the spec). A user without it gets403 permission_deniedon those calls.GET /parlays,GET /parlays/{parlayId}, the browsing endpoints, and the quotes endpoint are not permission-gated — a user can read their own parlay history regardless of KYC or suspension status, and an ISV-scoped read isn't rejected for lacking asub. CallGET /private/v1/users/USERID/permissionsfirst to see whether a user is cleared to confirm — see User Onboarding.
For single-contract orders, see Market Orders (single-contract trades).
1. The flow
GET /private/v1/parlays/tournaments ─► (optional) browse parlay-mode
GET /private/v1/parlays/markets tournaments/events/markets to
GET /private/v1/parlays/events/{eventId}/markets build a bet-slip UI
POST /private/v1/parlays/quotes ─► (optional) indicative price for
a candidate slip, before quoting
GET /private/v1/parlays/supported-contracts ─► pre-filter a bet slip to
parlay-eligible contracts
POST /private/v1/parlays ─► 201 with parlayId + offer
POST /private/v1/parlays/{parlayId}/confirm ─► commit at the quoted price
GET /private/v1/parlays/{parlayId} ─► poll fillStatus + settlementStatus
GET /private/v1/parlays ─► user's parlay history (token-paginated)
Polling is the simplest option. If you'd rather not poll, subscribe to ParlayEvent webhooks — see Webhooks (push events).
2. The state model
| Field | Values |
|---|---|
fillStatus | pending (submitted to SPs) → filled | failed |
failReason | A string explanation when fillStatus = failed — often "price moved", meaning you'll need to re-quote. |
settlementStatus | tbd → profit | loss | push | void |
per-leg settlementStatus | profit | loss | tbd | push | void |
The most common failure path is: you got a quote, the user took a moment, the SP price moved, and confirm now fails. The recovery is to re-quote with the same legs and try again.
What happens to the parlay when a leg pushes or voids depends on the other legs — it's not a single rule. A pushed/voided leg is excluded and the parlay's odds are recomputed on the remaining legs only when every other leg is still winning and the parlay is not a same-game parlay (SGP — 2+ legs sharing the same event). If it's an SGP, any leg pushing or voiding settles the entire parlay as a full-refund
push, with no recompute. If a non-SGP parlay has a losing leg alongside the pushed/voided one, the whole parlay settles as a straightloss, also with no recompute.
3. Browsing parlay-eligible markets (optional)
Three ISV-only endpoints (no sub, not permission-gated) for building a parlay bet-slip UI — browsing which tournaments, events, and markets are currently set up for parlay mode. None of these create or price anything; they're read-only catalog data, a parlay-mode parallel to the main Fixtures endpoints.
Only markets in categories set up for parlay mode appear here at all — a tournament with none, or an event with none of its markets in a parlay category, is simply left out of the response. Markets not allowed in-play are removed once an event goes live. Some categories only show one side of a market (the Over, the Yes, the home team); the other side is dropped. marketContracts on a market lists its other strikes (e.g. each handicap on a spread), with favorite marking the main one.
GET /private/v1/parlays/tournaments — tournaments available in parlay mode
GET /private/v1/parlays/tournaments — tournaments available in parlay modeReturns the tournaments you can build parlays from, each with its upcoming events and the tabs (grouped categories, e.g. "Popular" or "Player Props") that apply to that tournament — the top level of the parlay market layout.
| Query | Default | Effect |
|---|---|---|
limit | 150 | Maximum tournaments to return. Missing, non-numeric, or ≤ 0 falls back to the default. |
{
"tournaments": [
{
"id": 648,
"name": "NBA",
"events": [
{
"id": 20023797,
"name": "Lakers vs Celtics",
"displayName": "Lakers vs Celtics",
"scheduled": "2026-04-01T12:00:00Z",
"status": "not_started",
"quantity": 0
}
],
"groupCategories": [ { "id": 10, "name": "Popular" } ]
}
]
}events[].quantity is total open exchange quantity on the event (not parlay volume) — it falls as quantity fills or is canceled.
GET /private/v1/parlays/markets — parlay markets for several events
GET /private/v1/parlays/markets — parlay markets for several eventsReturns parlay markets for a batch of events in one call, so you're not making a request per event. Markets come back as a flat list per event, each carrying the tab it belongs to in groupedCategoryID/groupedCategoryName — this endpoint does not return a tab list; use the per-event endpoint below for that. An event with zero parlay markets is left out, so you may get back fewer events than you asked for.
| Query | Required | Notes |
|---|---|---|
eventIds | yes | Comma-separated event IDs. |
[
{
"eventId": 20023797,
"markets": [
{
"id": 219,
"name": "Moneyline",
"type": "regular",
"status": "open",
"categoryID": 5,
"categoryName": "Game Lines",
"groupedCategoryID": 10,
"groupedCategoryName": "Popular",
"outcomes": [
{ "id": 1, "name": "Lakers", "isParlaySupported": true, "contractId": "abc..." },
{ "id": 2, "name": "Celtics", "isParlaySupported": true, "contractId": "def..." }
]
}
]
}
]GET /private/v1/parlays/events/{eventId}/markets — parlay markets for one event
GET /private/v1/parlays/events/{eventId}/markets — parlay markets for one eventSame market data as above, but for a single event, plus groupedCategories — the ordered list of tabs so you know which ones exist and what order to show them in. Markets within a tab already come back in display order. isParlaySupported on each outcome tells you whether that specific strike can be added to a parlay right now.
{
"markets": [ { "...": "same ParlayModeMarket shape as above" } ],
"groupedCategories": [
{ "id": 10, "name": "Popular" },
{ "id": 11, "name": "Player Props" }
]
}Failure modes for all three: 400 (bad eventIds), 401, 403, 500, and 502 (upstream markets service unavailable) on the two market-listing endpoints.
4. GET /private/v1/parlays/supported-contracts — pre-filter a bet slip (optional)
GET /private/v1/parlays/supported-contracts — pre-filter a bet slip (optional)Not every contract can be priced as a parlay leg. Sports pricing engines (SPs) selectively opt contracts in and out, so if you send POST /parlays with a leg that's currently unsupported, the request will validate but fail to quote (400 no_offers_available) once no SP can price the combo. This endpoint gives you the eligibility list up front so you can grey out unsupportable legs before the user builds a slip that can't be priced.
Auth: user-scoped (sub + subsig). Requires the parlay permission — same gate as the other parlay endpoints.
Query:
| Name | Required | Notes |
|---|---|---|
eventIds | yes | Comma-separated sport event IDs. |
Response (ParlaySupportedContractsResponse):
{
"supportedContracts": [
{
"eventId": 20023797,
"contractIds": [
"8315d4bc44d06eef736959e0b214c170",
"2d179d1578e669e97a2e57735f0cbef8"
]
}
]
}Notes:
- Events with zero supported contracts are omitted from the response entirely — don't rely on every event you asked about appearing in
supportedContracts. If an event isn't in the array, none of its contracts are parlay-eligible right now. - Support can change over time — treat this as a live snapshot, not a static configuration. Re-check before quoting when a lot of time has passed between slip build and confirm.
- This is advisory only: the actual parlay quote via
POST /parlaysis the source of truth. Usesupported-contractsto keep the UX clean, but expectPOST /parlaysto sometimes come back with400 no_offers_availableeven for a contract you last saw as supported.
3.1 Structural eligibility rules
supported-contracts only reflects per-contract SP availability (§3 above). Separately, a slip can be rejected because of how its legs combine with each other, regardless of individual contract support:
- No duplicate legs. The same contract can't appear twice in one slip.
- Can't play both sides of the same market. Two legs on the same moneyline, the same spread, or the same total (e.g. both the over and the under) are rejected.
- Moneyline vs. opposite-side spread within 0.5 points. A moneyline leg combined with a spread leg on the opposite side, within 0.5 points of a pick'em line, is rejected as effectively betting both sides of the same outcome.
- Two or more moneylines on the same event plus any spread leg is rejected outright — but a single moneyline paired with a spread is fine as long as it doesn't trip the rule above.
None of this is pre-checked by supported-contracts — a slip that violates one of these rules will fail at POST /parlays with 400 no_offers_available, the same generic error as a plain SP-unavailability case. Validate these combinations client-side if you want to catch them before the user submits.
5. POST /private/v1/parlays/quotes — indicative price (optional)
POST /private/v1/parlays/quotes — indicative price (optional)Prices a candidate parlay slip without creating a parlay — useful for showing a live price next to single-contract prices while a bet slip is still being built. This is an ISV-level call: it isn't tied to a user, isn't permission-gated, and doesn't return a parlayId — a quote from here can't be confirmed. To actually trade, call POST /parlays (section 6) and confirm the resulting parlay.
Body (CreateParlayQuoteRequest):
{
"contractIds": ["abc...", "def..."],
"quantity": 25.00
}contractIds: 2–12 unique contract IDs. quantity in USD, > 0.
Response (CreateParlayQuoteResponse):
{
"offers": [
{ "price": 220, "maxQuantity": 50.00, "updatedAt": "2026-04-01T12:00:00Z" }
]
}offersis sorted best-payout-first, and is empty when no liquidity provider priced the slip in time — not an error, just retry shortly.priceis the liquidity provider's own price with no ISV fee applied, so it can look better than theadjustedPriceyou'll get back once you actually quote viaPOST /parlays. Don't showpriceto the user as the final number.- Quotes for the same set of contracts are cached regardless of
quantity— comparemaxQuantityagainst your intended quantity, and treat a recentupdatedAtas a sign the quote is still fresh. - The call can take up to a few seconds — this is a live multi-provider pricing round-trip, not a cache lookup.
Failure modes: 400, 401, 403, 422 (validation), 500, 503 (no provider available to price right now).
6. POST /private/v1/parlays — create a quote
POST /private/v1/parlays — create a quoteBody (CreateParlayRequest):
{
"quantity": 10.00,
"legs": [
{ "eventId": 1, "marketId": 7, "outcomeId": 2, "contractId": "abc..." },
{ "eventId": 2, "marketId": 9, "outcomeId": 1, "contractId": "def...", "strike": 220.5 }
]
}Rules:
legs.lengthbetween 2 and 12 inclusive.- Each leg requires
eventId,marketId,outcomeId, andcontractId.strikeis only needed for markets that have one (spreads, totals, etc.). quantity > 0in USD.
Response (201, CreateParlayResponse):
{
"parlayId": "00000000-0000-0000-0000-000000000000",
"offer": {
"price": 615,
"adjustedPrice": 590,
"maxQuantity": 50.00,
"legs": [
{ "contractId": "abc...", "price": -120 },
{ "contractId": "def...", "price": +150 }
]
}
}priceis the combined American price;adjustedPriceis after the ISV fee. Show the adjusted one to your user.maxQuantitycaps how much you can confirm at this price.offer.legscan legitimately come back empty ([]). Not every quoting SP is required to send per-leg prices along with its combined quote — a successful200with an emptylegsarray is expected behavior, not a sign of a broken response. Don't build logic that assumeslegsis always populated.
Failure modes:
422— out-of-range leg count, malformed body, or leg validation (badcontractId, missing required field, etc.).400 no_offers_available— no SP could price the combo. There's no partial/absent-offersuccess response for this case — the request fails outright. Your options are to retry, drop legs, or reduce quantity.
7. POST /private/v1/parlays/{parlayId}/confirm — commit
POST /private/v1/parlays/{parlayId}/confirm — commitBody (ConfirmParlayRequest):
{ "quantity": 10.00 }quantity > 0, and must be ≤ the offer.maxQuantity returned by the quote.
Response (200, ConfirmParlayResponse):
{
"parlayId": "...",
"confirmedAt": "...",
"requestedQuantity": 10.00,
"fee": 0.50,
"quantity": 9.50
}Failure modes:
402— insufficient balance.422— malformed body.400 quantity_exceeds_offer— requested quantity is above the offer'smaxQuantity.400 parlay_not_valid— the parlay wasn't found or has expired.
After confirm, the parlay is submitted to SPs for filling. Move on to polling — or subscribe to the parlay webhook and let updates push to you.
8. GET /private/v1/parlays/{parlayId} — the full state
GET /private/v1/parlays/{parlayId} — the full stateNot permission-gated (see the callout in the intro). With a sub claim in the JWT, the parlay must belong to that user. With an ISV-only JWT (no sub), the parlay may belong to any user of your ISV — but only a confirmed parlay resolves this way; an unconfirmed quote is a 404 for an ISV-only token (there's no user yet to resolve ownership through).
Response (Parlay):
{
"parlayId": "...",
"fillStatus": "filled",
"failReason": null,
"settlementStatus": "tbd",
"quotedPrice": -115.0,
"adjustedPrice": -120.0,
"requestedQuantity": 50.00,
"fee": 2.00,
"quantity": 48.00,
"filledQuantity": 48.00,
"unfilledQuantity": 0.00,
"payout": null,
"confirmedAt": "...",
"legs": [
{
"contractId": "abc...",
"event": { "...": "..." },
"market": { "...": "..." },
"selection": { "...": "..." },
"score": { "...": "..." },
"settlementStatus": "tbd"
}
]
}payout is populated only when settlementStatus = profit.
- Per-leg
scoreis{ home, away, isFinal }— a settlement-tracking convenience scoped to the legs of parlays you've actually placed, not a general live-score feed. There's no way to look up a score for an event you haven't placed a parlay on, and no clock/period/time-remaining data anywhere in the API — integrate your own sports-data provider if you need general in-play game-state.
9. GET /private/v1/parlays — list a user's parlay history
GET /private/v1/parlays — list a user's parlay historyReturns a user's parlays, most-recent first, token-paginated. The response shape is different from the GET-by-ID above — this endpoint returns ParlayHistoryItem (a lighter-weight history record), not the full Parlay. Not permission-gated (see the callout in the intro).
With a sub claim in the JWT, returns that user's parlays. With an ISV-only JWT (no sub), returns the parlays of the user named by ?userId= (required in that case) — that user must belong to your ISV, or you get a 404.
Query parameters
| Name | Type | Default | Notes |
|---|---|---|---|
userId | UUID | unset | Only honored on an ISV-only JWT (no sub) — required in that case. Ignored when the JWT carries a sub. |
limit | integer | 25 | 1 ≤ limit ≤ 100. |
token | string | unset | Opaque cursor — pass the paging.token from the previous response. |
orderBy | string | uuid | Field to order by. |
orderDir | enum | desc | asc | desc. |
type | enum | all | confirmed | canceled | all. |
settlementType | enum | all | pending | settled | all. |
dateRangeFilter | enum | all | today | this_week | this_month | all. Filters by createdAt. |
parlayIDs | string | unset | Comma-separated list of parlay IDs to filter to. |
Response (ListParlaysResponse)
ListParlaysResponse){
"parlays": [
{
"parlayId": "00000000-0000-0000-0000-000000000000",
"status": "filled",
"settlementStatus": "tbd",
"requestedPrice": -115.0,
"requestedQuantity": 50.00,
"confirmedPrice": -118.0,
"quantity": 48.00,
"settledPrice": null,
"maxProfit": 41.60,
"payout": null,
"createdAt": "...",
"updatedAt": "...",
"legs": [
{ "contractId": "abc...", "eventId": 1, "marketId": 7, "outcomeId": 2 }
]
}
],
"paging": { "limit": 25, "token": "eyJpZCI6MTAwfQ==" }
}paging.token is absent when there are no more pages — that's how you know to stop.
Field meanings
status— lifecycle status as a free-form string for forward compatibility. Known values:open,filled,finalized,pending_payout,payout_submitted,settled,rejected,void,failed. Don't switch exhaustively on this; treat unknowns as "no further state changes expected on our side".settlementStatus— same enum as the GET-by-ID:profit|loss|tbd|push|void.requestedPrice/requestedQuantity— the quote you confirmed against.confirmedPrice/quantity— the price actually filled and the quantity after fee, populated once filled (absent before).settledPrice/payout— populated once settled.payoutis realized profit.maxProfit— projected profit if the parlay wins fully.
The list endpoint is a thin summary view — there's intentionally less information here than in
GET /parlays/{parlayId}. Use the list to populate a history UI, and the GET-by-ID when the user clicks into one row.
10. Money movement is automatic
Just like single-contract orders, you don't move money for parlay flow. ProphetX handles it on its side:
- Quantity debit at confirm —
requestedQuantityis deducted, fee is taken (feeon the response,ORDER_FEEtransaction), and the remainingquantityis what actually goes on the parlay. - Settlement — when every leg has resolved, ProphetX credits the payout on a win (
PAYtransaction,payoutset,settlementStatus = profit) or settles toloss/push/voidwith the corresponding ledger entry. TheParlayEventwebhook fires on every state change.
No manual posting from your side. See Wallets for the resulting TransactionType rows.
11. Handling failed fills
If fillStatus = failed after confirm, failReason will usually read "price moved" — meaning the SP pulled or revised their price between your quote and your confirm. Standard handling:
- Pop the user back to the quote screen.
- Call
POST /parlaysagain with the same legs (or let the user edit them). - Show the new
offer.adjustedPriceandoffer.maxQuantity. - Confirm again if the user accepts.
Don't try to retry-confirm the same parlayId — it's a terminal state.
12. Curl
BASE="https://isv-api.sandbox.prophetx.dev/private/v1"
# -1. (Optional) Browse parlay-mode tournaments/events, then markets for one event
curl "$BASE/parlays/tournaments?limit=50" -H "Authorization: Bearer $JWT_ISV"
curl "$BASE/parlays/events/20023797/markets" -H "Authorization: Bearer $JWT_ISV"
# 0. (Optional) Pre-filter: which contracts on these events can be parlayed?
curl "$BASE/parlays/supported-contracts?eventIds=1,2" \
-H "Authorization: Bearer $JWT_USER"
# 0.5 (Optional) Indicative price for a candidate slip, before quoting for real
curl -X POST "$BASE/parlays/quotes" \
-H "Authorization: Bearer $JWT_ISV" \
-H "Content-Type: application/json" \
-d '{ "contractIds": ["abc...", "def..."], "quantity": 25.00 }'
# 1. Quote
curl -X POST "$BASE/parlays" \
-H "Authorization: Bearer $JWT_USER" \
-H "Content-Type: application/json" \
-d '{
"quantity": 10.00,
"legs": [
{ "eventId":1, "marketId":7, "outcomeId":2, "contractId":"abc..." },
{ "eventId":2, "marketId":9, "outcomeId":1, "contractId":"def...", "strike":220.5 }
]
}'
# → 201 { "parlayId":"<id>", "offer": { ... } }
# 2. Confirm
curl -X POST "$BASE/parlays/<id>/confirm" \
-H "Authorization: Bearer $JWT_USER" \
-H "Content-Type: application/json" \
-d '{ "quantity": 10.00 }'
# 3. Poll
curl "$BASE/parlays/<id>" -H "Authorization: Bearer $JWT_USER"
# 4. History (most recent first; paginate via `paging.token`)
curl "$BASE/parlays?limit=25&type=confirmed&dateRangeFilter=this_week" \
-H "Authorization: Bearer $JWT_USER"
# 5. (Optional) Same two reads, from an ISV-only token for one named user
curl "$BASE/parlays?userId=<userId>&limit=25" -H "Authorization: Bearer $JWT_ISV"
curl "$BASE/parlays/<id>" -H "Authorization: Bearer $JWT_ISV"Updated 5 days ago
