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.
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
Field
Required
Notes
id
yes
Top of the browse hierarchy — e.g. NBA, NFL, MLB.
name
yes
updatedAt
yes
ISO datetime.
sport
no
{ id, name }. There's no dedicated GET /sports — dedupe this across the /tournaments response to build a sport picker.
Can legitimately be "" — string fields default to empty rather than being omitted.
scheduled
no
ISO datetime.
tournamentId / tournamentName
no
For 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.
competitors
no
Competitor[] — { 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).
Field
Required
Notes
id
yes
name
yes
Can be "" for some market families — fall back to describing it by type/subType.
type
yes
moneyline | spread | total — but heavily overloaded: player/team props also report as moneyline. Branch on subType, not type, for display logic.
subType
yes
The 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.
categoryName
yes
e.g. "Game Lines". Falls back to "Other" when the subType isn't mapped to a category for that tournament.
Nested strike-level sibling markets, same shape as parent.
playerId
no
0 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.
Field
Required
Notes
contractId
yes
Hash of (event, market, outcome, strike). This is what you pass to orders/parlays.
outcomeId
yes
name / displayName
yes
Competitor name, "YES"/"NO", or "over 9"/"under 9" depending on market shape.
price / adjustedPrice
no
American 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 / adjustedPriceFormats
no
price / 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 / displayStrike
no
Pre-formatted strings ("+120", "-1.5") — "" when unpriced. price/strike are the numeric twins.
quantity
no
The resting stake on the other side of this selection at this price level — not very useful on its own.
value
no
That 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.
strike
no
The handicap/total line.
competitorId
no
0 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
Field
Required
Notes
expectedAveragePrice
yes
Echo this back into the place-order call.
expectedAveragePriceFormats
no
expectedAveragePrice in all display formats — { american, decimal, cents, probability }.
expectedAveragePriceAdjustedFormats
no
expectedAveragePriceAdjusted in all display formats — { american, decimal, cents, probability }.
priceList
yes
Price levels this estimate spans — also echoed back. The backend rejects the submit if the live price has moved off these levels.
availableQuantity / maxQuantity
yes
expectedPayout / expectedFeeAmount
no
2.2 MarketOrderResponse — POST /market-orders · GET /market-orders/{refId}
Field
Required
Notes
refId
yes
The order handle — poll by this.
status
yes
pending | completed | canceled | failed.
quantity / filledQuantity / openQuantity
yes
matchingStatus
no
matched | unmatched | partial.
winningStatus
no
profit | loss | push | tbd — set once settled.
eventId / marketId / strike
no
Populated once the order begins filling. strike stays absent on moneyline.
currentAveragePriceFormats
no
currentAveragePrice in all display formats — { american, decimal, cents, probability }.
fills
no
MarketOrderFill[] — only when get() is called with fills=true; one entry per match against the book. Each fill also carries averagePriceFormats — { american, decimal, cents, probability }.
Cursor 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
Field
Required
Notes
contractId
yes
eventId / marketId / outcomeId
yes
All three, every time — a leg with only contractId is rejected.
strike
no
Required 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.
Field
Required
Notes
parlayId
yes
offer.price / offer.adjustedPrice
no
Combined American price; adjusted is post-fee — show that one.
offer.priceFormats / offer.adjustedPriceFormats
no
price / adjustedPrice in all display formats — { american, decimal, cents, probability }.
pending → filled | failed. Failed usually means "price moved" — re-quote with the same legs.
settlementStatus
yes
tbd → profit | loss | push | void.
quotedPrice / adjustedPrice
yes
quotedPriceFormats / adjustedPriceFormats
no
quotedPrice / adjustedPrice in all display formats — { american, decimal, cents, probability }.
filledQuantity / unfilledQuantity
yes
payout
no
Only set once settlementStatus = profit.
legs
yes
ParlayResponseLeg[] — 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
Field
Required
Notes
id
yes
UUID — use for every subsequent call.
kycStatus
yes
PENDING | PHOTO_VERIFICATION_PROCESSING | SUCCESS | FAILURE | MORTALITY | PEP | OFAC — always PENDING at creation.
sharedSecret
yes
Returned 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.
Field
Required
Notes
firstName / lastName / dateOfBirth
yes
Immutable after creation.
addressLine1 / city / state / zip / countryCode
yes
Mutable via PATCH.
kycAt
yes
When KYC passed.
email / phoneNumber
no
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.
true if the user is eligible to retry KYC with corrected information.
failReason / supportEmail
no
Set 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
Field
Required
Notes
userId
no
null for the ISV's own standing-fund row.
fundType
yes
STANDING | INDIVIDUAL.
balance
yes
Decimal string, always 2dp — "100.00", not a float.
Refers to the standing fund, not the per-user tally, on STANDING ISVs.
refId / contractId
no
Links 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
Field
Required
Notes
name / title
yes
name is the machine key ("Trustly"); title is user-facing ("Online Banking").
Only 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.
Field
Required
Notes
confirmed
yes
On the state-response shape (HTTP 200).
mfaType
yes
Presence of this field is the discriminator — means HTTP 202, MFA challenge.
6.5 PNMOrderResponse — POST /payment/pnm/deposit · /withdraw
Always PENDING here — the real outcome arrives later via webhook.
pnmOrderIdentifier
yes
For 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
Field
Required
Notes
id
yes
Monotonic — dedupe/order by this, not timestamp.
op
yes
created | updated | deleted | test. MarketSelection/MatchedOrder only fire a subset of these.