Data structures reference

Data structures reference

Every object the private API returns or accepts, in one place, organized by the six things you'll actually build against: fixtures, market orders, parlays, users, wallets, and payments. Field names, types, and requiredness come directly from the response/request models — when this page and the OpenAPI spec disagree, the spec wins.

This is a companion to the topic docs, not a replacement — go there for endpoint-by-endpoint flow, auth, and failure modes: Fixtures (browsing markets), Market Orders (single-contract trades), Parlays (2–12 leg trades), User Onboarding (users, KYC, terms), Wallets, Embedded UI (tokens + /embed/v1), Webhooks (push events).

Everything below is server-to-server (/private/v1/*) unless a section says otherwise. Payments live on /embed/v1/* and /embed/v2/* — see §6.

Reading the tables. "Required" means always present on a well-formed request/response. "no" means it can be null or absent — treat both the same. Where a field has a fixed set of values, they're spelled out in Notes rather than typed as an enum, since the API itself sends them as plain strings.


1. Fixtures

The browse hierarchy: a Tournament holds SportEvents, each of which holds Markets, each of which holds Selections — the thing you actually trade. Every selection carries its own contractId: the unique hash of (event, market, outcome, strike).

1.1 Tournament — GET /tournaments

FieldRequiredNotes
idyesTop of the browse hierarchy — e.g. NBA, NFL, MLB.
nameyes
updatedAtyesISO datetime.
sportno{ id, name }. There's no dedicated GET /sports — dedupe this across the /tournaments response to build a sport picker.
categoryno{ id, name, countryCode }.
{
  "id": 31,
  "name": "NFL",
  "sport": { "id": 16, "name": "American Football" },
  "category": { "id": 43, "name": "USA", "countryCode": "USA" },
  "updatedAt": "2026-07-12T02:00:27.859Z"
}

1.2 SportEvent — GET /sport-events

FieldRequiredNotes
eventIdyes
name / displayNameyes
statusyesnot_started | live | suspended | ended | closed | cancelled | interrupted | postponed | abandoned | delayed.
liveDisabledyes
type / subTypeyesCan legitimately be "" — string fields default to empty rather than being omitted.
schedulednoISO datetime.
tournamentId / tournamentNamenoFor an outright/futures event (e.g. a "2026 Travelers Championship — Tournament Winner" market), don't expect this to be the specific real-world tournament. Some sports (confirmed for golf) nest every outright event under one shared, generic tournament bucket — the real tournament name only appears in the event's own name/displayName, never as the parent tournament.
competitorsnoCompetitor[] — { id, name, displayName, abbreviation, side, country }. Coverage improves closer to start time.

Competitor.id is not stable across environments, even for the same real-world team. Sandbox and production mint their own internal IDs independently, so the same team can carry a different id in each — don't hardcode or cache an id-to-team mapping across environments; re-derive it per environment from name/abbreviation instead. This is separate from, and will outlast, the ongoing SDIO→OpticOdds data-provider migration: a handful of sports (MLB, soccer, UFC, golf, as of this writing) still source from SDIO and will get a second set of IDs until that migration completes, but the sandbox-vs-production mismatch is a permanent property of the ID scheme itself, confirmed on both sides of that migration.

1.3 Market — GET /markets

Nests two ways: a flat selections list-of-lists (one outer entry per outcome side) for simple markets like moneyline, or a marketContracts array of nested Market objects for markets built from stacked strike levels (spreads, totals).

FieldRequiredNotes
idyes
nameyesCan be "" for some market families — fall back to describing it by type/subType.
typeyesmoneyline | spread | total — but heavily overloaded: player/team props also report as moneyline. Branch on subType, not type, for display logic.
subTypeyesThe real discriminator — moneyline, moneyline_3_way (soccer 3-way, split into 3 binary Yes/No markets), both_teams_to_score, player_to_score_at_least_2_goals, etc.
categoryNameyese.g. "Game Lines". Falls back to "Other" when the subType isn't mapped to a category for that tournament.
statusyesactive | suspended | settled (and a few more).
strikeno0 on moneyline is a real value, not "unset."
totalQuantity / totalFillednoAggregate liquidity across all selections.
selectionsnoSelection[][] — iterate outer (per outcome) then inner (per price level).
marketContractsnoNested strike-level sibling markets, same shape as parent.
playerIdno0 except on player-prop markets, where it identifies the player the market is about. There's no lookup endpoint to resolve it to a name — read the player's name off the market/selection name instead.

SDK codegen note: marketContracts is a self-referencing schema (Market nests Market). Some third-party OpenAPI-to-SDK generators — including ReadMe's own api CLI (npx api install) — don't support circular $ref chains and will fail to generate a client from the published spec. If you hit this, either hand-write the client for GET /markets, or generate against a locally-flattened copy of the schema with marketContracts capped to a fixed depth.

1.4 Selection — nested in Market

The tradeable unit. For a true per-competitor market, name/competitorId identify the team directly. For single-question markets (moneyline_3_way, both_teams_to_score, player props), selections are just "YES"/"NO" with competitorId: 0 — the subject is named on the market, not the selection.

FieldRequiredNotes
contractIdyesHash of (event, market, outcome, strike). This is what you pass to orders/parlays.
outcomeIdyes
name / displayNameyesCompetitor name, "YES"/"NO", or "over 9"/"under 9" depending on market shape.
price / adjustedPricenoAmerican odds. null price means no resting liquidity at any level, not zero. adjustedPrice is currently always null on GET /markets; take fee-adjusted prices from /market-orders/estimate or the contract / market-selection webhooks.
priceFormats / adjustedPriceFormatsnoprice / adjustedPrice in all display formats — { american, decimal, cents, probability }. american is the canonical integer; decimal is total return per $1 stake (4dp); cents and probability are always equal (implied probability as a percentage, 2dp). Derived formats are rounded — do not use them as order guardrails.
displayPrice / displayStrikenoPre-formatted strings ("+120", "-1.5") — "" when unpriced. price/strike are the numeric twins.
quantitynoThe resting stake on the other side of this selection at this price level — not very useful on its own.
valuenoThat same resting liquidity, scaled by odds — the amount actually available for you to take at this price. Prefer value over quantity when sizing against available liquidity.
strikenoThe handicap/total line.
competitorIdno0 for single-question markets with no single competitor to attach to.

2. Market orders

Single-contract orders. Always estimate → place — the backend requires the estimate's expectedAveragePrice and priceList echoed back on submit as a price guardrail. Fills happen asynchronously; poll GET /market-orders/{refId} or subscribe to MarketOrderEvent.

2.1 EstimateResponse — POST /market-orders/estimate

FieldRequiredNotes
expectedAveragePriceyesEcho this back into the place-order call.
expectedAveragePriceFormatsnoexpectedAveragePrice in all display formats — { american, decimal, cents, probability }.
expectedAveragePriceAdjustedFormatsnoexpectedAveragePriceAdjusted in all display formats — { american, decimal, cents, probability }.
priceListyesPrice levels this estimate spans — also echoed back. The backend rejects the submit if the live price has moved off these levels.
availableQuantity / maxQuantityyes
expectedPayout / expectedFeeAmountno

2.2 MarketOrderResponse — POST /market-orders · GET /market-orders/{refId}

FieldRequiredNotes
refIdyesThe order handle — poll by this.
statusyespending | completed | canceled | failed.
quantity / filledQuantity / openQuantityyes
matchingStatusnomatched | unmatched | partial.
winningStatusnoprofit | loss | push | tbd — set once settled.
eventId / marketId / strikenoPopulated once the order begins filling. strike stays absent on moneyline.
currentAveragePriceFormatsnocurrentAveragePrice in all display formats — { american, decimal, cents, probability }.
fillsnoMarketOrderFill[] — only when get() is called with fills=true; one entry per match against the book. Each fill also carries averagePriceFormats — { american, decimal, cents, probability }.
{
  "refId": "a1b2c3d4-...", "contractId": "323ea256...",
  "quantity": 50.0, "filledQuantity": 32.5, "openQuantity": 17.5,
  "status": "pending", "matchingStatus": "partial",
  "currentAveragePrice": -152.0, "createdAt": "2026-07-28T15:53:02.19Z"
}

2.3 ListMarketOrdersResponse — GET /market-orders

FieldRequiredNotes
marketOrdersyesMarketOrderResponse[].
paging.tokennoCursor for the next page — absent when there isn't one.

3. Parlays

2–12 legs, every one of which must settle as profit for the parlay to win. Three-step flow: quote → confirm → poll, because the combined price can move while the user decides.

3.1 ParlayLeg — request, POST /parlays

FieldRequiredNotes
contractIdyes
eventId / marketId / outcomeIdyesAll three, every time — a leg with only contractId is rejected.
strikenoRequired in practice for spread/total legs — omitting it on those returns invalid_params.

3.2 CreateParlayResponse — POST /parlays

offer is a single object, not a list — and it can be null ("no sportsbook could price this combination"), which is a valid response, not an error.

FieldRequiredNotes
parlayIdyes
offer.price / offer.adjustedPricenoCombined American price; adjusted is post-fee — show that one.
offer.priceFormats / offer.adjustedPriceFormatsnoprice / adjustedPrice in all display formats — { american, decimal, cents, probability }.
offer.maxQuantitynoCap for the following confirm call.
offer.legsno{ contractId, price, priceFormats }[] — per-leg estimated price.
{
  "parlayId": "019f61d9-...",
  "offer": { "price": 405.0, "adjustedPrice": 376.0, "maxQuantity": 50.0, "legs": [] }
}

3.3 Parlay — GET /parlays/{parlayId}

FieldRequiredNotes
fillStatusyespending → filled | failed. Failed usually means "price moved" — re-quote with the same legs.
settlementStatusyestbd → profit | loss | push | void.
quotedPrice / adjustedPriceyes
quotedPriceFormats / adjustedPriceFormatsnoquotedPrice / adjustedPrice in all display formats — { american, decimal, cents, probability }.
filledQuantity / unfilledQuantityyes
payoutnoOnly set once settlementStatus = profit.
legsyesParlayResponseLeg[] — each carries its own event/market/selection/score/settlementStatus.

4. Users & onboarding

Three gates stand between a created user and their first trade: KYC, terms acceptance, and per-action permissions. POST /users is ISV-scoped; everything else needs the user's own JWT (sub + subsig).

4.1 CreateUserResponse — POST /users

FieldRequiredNotes
idyesUUID — use for every subsequent call.
kycStatusyesPENDING | PHOTO_VERIFICATION_PROCESSING | SUCCESS | FAILURE | MORTALITY | PEP | OFAC — always PENDING at creation.
sharedSecretyesReturned exactly once. Base64url, 32 bytes. Store it — it's the HMAC key for every future subsig.

4.2 UserResponse — GET /users/USERID

409-conflicts (user_pending_kyc) until KYC succeeds — check kyc-status instead in that case.

FieldRequiredNotes
firstName / lastName / dateOfBirthyesImmutable after creation.
addressLine1 / city / state / zip / countryCodeyesMutable via PATCH.
kycAtyesWhen KYC passed.
email / phoneNumberno

4.3 UserPermissionsResponse — GET /users/USERID/permissions

Both fields are open maps — iterate the keys you get, don't hard-code an exhaustive switch. If gates["not-suspended"].completed is false, every permission below comes back denied — that's an account-level block, not a per-action error.

FieldRequiredNotes
permissions[key]yes{ granted, description, denyReason? }. Known keys: market-order, parlay, deposit-*, withdraw-*.
gates[key]yes{ completed, description }. Known keys: kyc, terms, email-verify, phone-verify, not-suspended.

4.4 KycStatusResponse — GET /users/USERID/kyc-status

FieldRequiredNotes
kycStatusyesPENDING | PHOTO_VERIFICATION_PROCESSING | SUCCESS | FAILURE | MORTALITY | PEP | OFAC.
canRetryyestrue if the user is eligible to retry KYC with corrected information.
failReason / supportEmailnoSet on a terminal non-success status.

5. Wallet

Every ISV is provisioned as STANDING or INDIVIDUAL — that single setting decides what GET /wallets returns. Confirm which you are before designing around this. See Wallets for the full model.

5.1 Wallet — GET /wallets

FieldRequiredNotes
userIdnonull for the ISV's own standing-fund row.
fundTypeyesSTANDING | INDIVIDUAL.
balanceyesDecimal string, always 2dp — "100.00", not a float.
versionyesOptimistic-concurrency counter.

5.2 Transaction — GET /transactions

FieldRequiredNotes
idyesAlso the pagination cursor.
txTypeyesORDER | CANCEL | PAY | DEPOSIT | WITHDRAW | ORDER_FEE | COMMISSION | REFUND | ADJUSTMENT_INCREASE | ADJUSTMENT_REDUCE | APPROVE_WITHDRAW | REJECT_WITHDRAW.
amountyesSigned decimal — debits negative.
balanceBefore / balanceAfteryesRefers to the standing fund, not the per-user tally, on STANDING ISVs.
refId / contractIdnoLinks back to the order/parlay that caused this row.

6. Payments

The only path money moves in or out for INDIVIDUAL ISVs — there's no POST /deposit on the private API. Four providers, four shapes, one shared response envelope for the v2 ones. Lives on /embed/v1/* and /embed/v2/* — see Embedded UI (tokens + /embed/v1).

6.1 PaymentMethod — GET /payment/methods

FieldRequiredNotes
name / titleyesname is the machine key ("Trustly"); title is user-facing ("Online Banking").
integrationTypeyesBACKEND_SIGNED | WALLET_TOKEN.
supportedDirectionsyesDEPOSIT and/or WITHDRAW.

6.2 PaymentV2Response — shared: AeroPay deposit/withdraw, ZeroHash deposit

FieldRequiredNotes
transactionIdyes
statusyesPENDING | AUTHORIZED | COMPLETED | FAILED | CANCELED | WALLET_WRITE_FAILED.

6.3 ZeroHashUserStateResponse — GET /payment/zerohash

FieldRequiredNotes
statusyesneeds_onboarding | kyc_pending | approved | denied | restricted.
onboardingTokennoOnly when needs_onboarding — feed to the ZeroHash SDK.

6.4 AeroPayUserStateResponse / AeroPayMFAChallenge — GET /payment/aeropay

A union — this endpoint re-probes AeroPay on every call, so branch on the response shape, never on cached confirmed state. A previously-linked user can suddenly come back as a fresh MFA challenge.

FieldRequiredNotes
confirmedyesOn the state-response shape (HTTP 200).
mfaTypeyesPresence of this field is the discriminator — means HTTP 202, MFA challenge.

6.5 PNMOrderResponse — POST /payment/pnm/deposit · /withdraw

Card PII never reaches ISV servers — it's collected entirely inside PayNearMe's hosted widget.

FieldRequiredNotes
secureSmartTokenyesHand to PNM.init(token, { action }) client-side.
statusyesAlways PENDING here — the real outcome arrives later via webhook.
pnmOrderIdentifieryesFor support/debugging reference.

7. Webhooks

Every push event shares one envelope: { id, op, timestamp, data }. id is monotonically increasing per event type — use it for ordering and de-duplication. Signed EdDSA; verify with verify_webhook(). See Webhooks (push events).

7.1 Event envelope — common shape, all nine event types

FieldRequiredNotes
idyesMonotonic — dedupe/order by this, not timestamp.
opyescreated | updated | deleted | test. MarketSelection/MatchedOrder only fire a subset of these.
datayesShape depends on event type — see below.

7.2 data payload by event type

Eventdata shapeNotes
ContractEvent (/push/contracts){ contractId, price?, status, strike, ... }price: null means no liquidity.
ContractSettlementEvent (/push/contract-settlements){ contractId, result, ... }result: profit | loss | push | void. Written only for graded outcomes with matched orders, so untraded contracts never get one; see Webhooks 4.2.
MarketOrderEvent (/push/market-orders){ id, status?, fillStatus?, ... }Every field but id is optional.
MatchedOrderEvent (/push/matched-orders){ contractId, fillPrice, filledQuantity, sequenceNumber, ... }One event per fill, not per order.
ParlayEvent (/push/parlays){ id, userId, settlementStatus?, ... }
MarketSelectionEvent (/push/market-selections){ eventId, tournamentId, market: { selections[][] } }Full liquidity snapshot, up to 10 price levels per side. sequenceNumber — discard stale updates.

Field-accurate as of the current API models. If this page and the OpenAPI spec disagree, the spec wins.


Did this page help you?