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, and POST /private/v1/parlays/{parlayId}/confirm are gated server-side on the parlay user permission (via the x-required-permission annotation on the spec). A user without it gets 403 permission_denied on 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 a sub. Call GET /private/v1/users/USERID/permissions first 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

FieldValues
fillStatuspending (submitted to SPs) → filled | failed
failReasonA string explanation when fillStatus = failed — often "price moved", meaning you'll need to re-quote.
settlementStatustbd → profit | loss | push | void
per-leg settlementStatusprofit | 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 straight loss, 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

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

QueryDefaultEffect
limit150Maximum 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

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

QueryRequiredNotes
eventIdsyesComma-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

Same 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)

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:

NameRequiredNotes
eventIdsyesComma-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 /parlays is the source of truth. Use supported-contracts to keep the UX clean, but expect POST /parlays to sometimes come back with 400 no_offers_available even 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)

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" }
  ]
}
  • offers is sorted best-payout-first, and is empty when no liquidity provider priced the slip in time — not an error, just retry shortly.
  • price is the liquidity provider's own price with no ISV fee applied, so it can look better than the adjustedPrice you'll get back once you actually quote via POST /parlays. Don't show price to the user as the final number.
  • Quotes for the same set of contracts are cached regardless of quantity — compare maxQuantity against your intended quantity, and treat a recent updatedAt as 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

Body (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.length between 2 and 12 inclusive.
  • Each leg requires eventId, marketId, outcomeId, and contractId. strike is only needed for markets that have one (spreads, totals, etc.).
  • quantity > 0 in 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 }
    ]
  }
}
  • price is the combined American price; adjustedPrice is after the ISV fee. Show the adjusted one to your user.
  • maxQuantity caps how much you can confirm at this price.
  • offer.legs can legitimately come back empty ([]). Not every quoting SP is required to send per-leg prices along with its combined quote — a successful 200 with an empty legs array is expected behavior, not a sign of a broken response. Don't build logic that assumes legs is always populated.

Failure modes:

  • 422 — out-of-range leg count, malformed body, or leg validation (bad contractId, missing required field, etc.).
  • 400 no_offers_available — no SP could price the combo. There's no partial/absent-offer success 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

Body (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's maxQuantity.
  • 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

Not 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 score is { 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

Returns 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

NameTypeDefaultNotes
userIdUUIDunsetOnly honored on an ISV-only JWT (no sub) — required in that case. Ignored when the JWT carries a sub.
limitinteger251 ≤ limit ≤ 100.
tokenstringunsetOpaque cursor — pass the paging.token from the previous response.
orderBystringuuidField to order by.
orderDirenumdescasc | desc.
typeenumallconfirmed | canceled | all.
settlementTypeenumallpending | settled | all.
dateRangeFilterenumalltoday | this_week | this_month | all. Filters by createdAt.
parlayIDsstringunsetComma-separated list of parlay IDs to filter to.

Response (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. payout is 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 — requestedQuantity is deducted, fee is taken (fee on the response, ORDER_FEE transaction), and the remaining quantity is what actually goes on the parlay.
  • Settlement — when every leg has resolved, ProphetX credits the payout on a win (PAY transaction, payout set, settlementStatus = profit) or settles to loss / push / void with the corresponding ledger entry. The ParlayEvent webhook 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:

  1. Pop the user back to the quote screen.
  2. Call POST /parlays again with the same legs (or let the user edit them).
  3. Show the new offer.adjustedPrice and offer.maxQuantity.
  4. 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"

Did this page help you?