Schemas

Error

error

string

Error code

Example: InvalidInput

message

string

Human-readable error message

Example: orderId is required

PredictionMarketsError

error

string · required

Prediction Markets error class

Example: InvalidInput

field

string

Request field associated with the error, when available

Example: orders

message

string

Human-readable error detail, when available

Example: orders must contain between 1 and 20 entries

AuthErrorResponse

result

string · enum · required

Enum values:

error

reason

string · required

Authentication or authorization error class

Example: MissingNonce

message

string · required

Human-readable authentication or authorization detail

Example: Must provide unique monotonic increasing 'nonce' field in payload

AccountGroupBlockedError

error

string · enum · required

Enum values:

This account is not permitted to trade prediction markets

code

string · enum · required

Enum values:

ACCOUNT_GROUP_BLOCKED

TermsNotAcceptedError

error

string · enum · required

Enum values:

TERMS_NOT_ACCEPTED

message

string · enum · required

Enum values:

Prediction markets terms must be accepted before placing orders

RestrictedSellOnlyError

error

string · enum · required

Enum values:

ACCOUNT_RESTRICTED_SELL_ONLY

message

string · enum · required

Enum values:

Your account is restricted to selling existing positions; buying is not permitted.

PredictionMarketsTerms

termsType

string · required

Terms type identifier

Example: PredictionsMarket

version

integer · required

Latest terms version

Example: 3

content

string · required

Terms content to display before acceptance

Example: These are the prediction market terms.

updatedAt

string · date-time · required

UTC timestamp when the terms content was last updated

Example: 2026-05-18T17:00:00Z

PredictionMarketsTermsStatus

hasAcceptedLatest

boolean · required

Whether the account group has accepted the latest configured Prediction Markets terms

Example: false

acceptedVersion

integer | null

Latest terms version accepted by the account group, if any

Example: 2

latestVersion

integer | null

Latest configured Prediction Markets terms version, if available

Example: 3

AcceptPredictionMarketsTermsResponse

success

boolean · required

MarketStatus

string · enum

Enum values:

approved

active

closed

under_review

settled

invalid

Status of a prediction market

MarketType

string · enum

Enum values:

binary

categorical

Type of prediction market

SportsMarketSport

string · enum

Enum values:

american_football

athletics

australian_rules_football

baseball

basketball

boxing

chess

cricket

Sport whose rules give the market's scope and metric their sport-specific meaning.

SportsMarketType

string · enum

Enum values:

moneyline

spread

total

prop

correct_score

to_advance

futures

other

Conventional sports-market family. subject, scope, and metric provide detail within the family. This classification is independent of the event's structural type (binary or categorical).

SportsMarketSubject

string · enum

Enum values:

contest

team

player

participant

other

What the market is about. participant covers non-player entrants such as drivers and horses.

SportsMarketScopeType

string · enum

Enum values:

full_contest

regulation

half

quarter

period

inning

team_innings

over

Unit covered by the market. full_contest follows the market's official final-result rules; regulation covers scheduled regulation play only. Ordinal and range qualifiers are represented separately on SportsMarketScope.

SportsMarketMetric

string · enum

Enum values:

aces

assists

balls_faced

birdies

blocked_shots

blocks

bogeys

boundaries

Statistic measured by the market. Interpret shared metric names using sportsMarket.sport.

SportsMarketScope

Settlement scope. `ordinal` identifies one unit; `start` and `end` identify an inclusive range of units.

type

SportsMarketScopeType · enum · required

Enum values:

full_contest

regulation

half

quarter

period

inning

team_innings

over

ordinal

integer · int32 · min: 0

Optional ordinal within the scope type, such as half 1 or quarter 4.

start

integer · int32 · min: 0

Optional inclusive start of a scope range, such as inning 1.

end

integer · int32 · min: 0

Optional inclusive end of a scope range, such as inning 5.

SportsMarket

Atomic sports-market classification shared by every contract grouped under the event. Present only for sports events. All fields except `metric` are required together.

sport

SportsMarketSport · enum · required

Sport whose rules give the market's scope and metric their sport-specific meaning.

Enum values:

american_football

athletics

australian_rules_football

baseball

basketball

boxing

chess

cricket

type

SportsMarketType · enum · required

Conventional sports-market family. subject, scope, and metric provide detail within the family. This classification is independent of the event's structural type (binary or categorical).

Enum values:

moneyline

spread

total

prop

correct_score

to_advance

futures

other

subject

SportsMarketSubject · enum · required

What the market is about. participant covers non-player entrants such as drivers and horses.

Enum values:

contest

team

player

participant

other

SportsMarketScope · required

Settlement scope. ordinal identifies one unit; start and end identify an inclusive range of units.

metric

SportsMarketMetric · enum

Statistic measured by the market. Interpret shared metric names using sportsMarket.sport.

Enum values:

aces

assists

balls_faced

birdies

blocked_shots

blocks

bogeys

boundaries

OrderType

string · enum

Enum values:

limit

stop-limit

Order type. stop-limit orders require a stopPrice that triggers a limit order at price when the market reaches the trigger.

OrderSide

string · enum

Enum values:

buy

sell

Outcome

string · enum

Enum values:

yes

The outcome being traded (Yes or No)

TimeInForce

string · enum

Enum values:

good-til-cancel

immediate-or-cancel

fill-or-kill

Order execution behavior:

good-til-cancel - Order remains active until filled or cancelled (default)
immediate-or-cancel - Fill immediately or cancel remaining
fill-or-kill - Fill entire order immediately or cancel

Default: good-til-cancel

OrderStatus

string · enum

Enum values:

open

filled

cancelled

PositionStatus

string · enum

Enum values:

active

resolved

cancelled

Pagination

limit

integer

offset

integer

total

integer

PaginationSimple

limit

integer

offset

integer

count

integer

Number of items in current response

OrderBook

OrderBookEntry[]

OrderBookEntry

side

OrderSide · enum

Enum values:

buy

sell

price

string

quantity

string

OrderBookDepth

OrderBookLevel[]

lastUpdateTime

string · date-time

OrderBookLevel

price

string

quantity

string

orderCount

integer

Contract

Contract quantity and price validation is instrument-specific. Clients must validate order quantities and prices against the returned increment and minimum fields rather than assuming a fixed grid.

id

string

label

string

Human-readable label for the contract's YES-space proposition (e.g., "SOL > $90")

abbreviatedName

string | null

Short form label (e.g., ">$90")

description

object

Rich text description

prices

ContractPrices

Current bid/ask pricing for the contract

totalShares

string | null

color

string | null

status

MarketStatus · enum

Status of a prediction market

Enum values:

approved

active

closed

under_review

settled

invalid

imageUrl

string | null

array | null

createdAt

string · date-time

expiryDate

string | null · date-time

resolutionSide

Outcome · enum

The outcome being traded (Yes or No)

Enum values:

yes

resolvedAt

string | null · date-time

termsAndConditionsUrl

string

ticker

string

instrumentSymbol

string

quantityIncrement

string | null

Contract quantity grid from instrument refdata (for example, "0.01").

quantityMinimum

string | null

Minimum contract quantity from instrument refdata (for example, "1.00").

priceIncrement

string | null

Contract price grid from instrument refdata (for example, "0.0001").

quoteAssetPrecision

integer | null

Decimal places supported by the instrument's quote asset.

priceMinimum

string | null

Minimum contract price and anchor for the instrument price grid (for example, "0.0001").

effectiveDate

string | null · date-time

marketState

string | null · enum

Trading state of the contract

Enum values:

open

closed

sortOrder

integer | null

Display order within the event

Strike

Strike price or contract threshold information for Up/Down crypto contracts and sports prediction market contracts.

settlementValue

string | null

The observed settlement price. Only present after the contract is settled.

Example: 87654.32

StrikeType

string · enum

Enum values:

reference

above

spread

over

over_or_equal

under

under_or_equal

Strike or condition inequality type for contract threshold evaluation. - reference: Crypto Up/Down reference strike price captured at availableAt time. - above: Higher/Lower contract threshold. - spread: Point, run, or goal handicap spread line. - over: Total or prop threshold evaluated as strict greater than (>). - over_or_equal: Total or prop threshold evaluated as greater than or equal to (>=). - under: Total or prop threshold evaluated as strict less than (<). - under_or_equal: Position, rank, or total threshold evaluated as less than or equal to (<=).

Example: spread

Strike

Strike price or contract threshold information for Up/Down crypto contracts and sports prediction market contracts.

value

string | null

The strike price value. Null for "reference" type strikes where the value is determined at availableAt time. For sports contracts, this represents the derived numeric strike value (e.g. spread margin, total line, or position/rank threshold).

Example: 87500.00

type

StrikeType · enum

Enum values:

reference

above

spread

over

over_or_equal

under

under_or_equal

Example: spread

availableAt

string | null · date-time

When the strike price becomes available

Example: 2026-03-27T19:45:00.000Z

SourceDetails

PricePoint

timestamp

string · date-time

price

string

ContractPrices

Event

A prediction market event containing one or more tradeable contracts

id

string

title

string

slug

string

description

string | null

imageUrl

string | null

type

MarketType · enum

Type of prediction market

Enum values:

binary

categorical

category

string

series

string | null

SportsMarket

Atomic sports-market classification shared by every contract grouped under the event. Present only for sports events. All fields except metric are required together.

ticker

string

The event ticker (e.g., "BTC100K2028")

Example: BTC100K2028

status

MarketStatus · enum

Status of a prediction market

Enum values:

approved

active

closed

under_review

settled

invalid

resolvedAt

string | null · date-time

createdAt

string · date-time

Contract[]

Tradeable contracts within this event

object

volume

string

Total trading volume in USD

Example: 125000.00

liquidity

string

Total liquidity in USD

Example: 50000.00

tags

array | null

effectiveDate

string · date-time

expiryDate

string | null · date-time

subcategory

Subcategory

Nested category information for the event

sourceDetails

SourceDetails

Structured data source information for price observation. Replaces the deprecated flat source string on the event and contract. Present for crypto Up/Down events. Both fields are omitted when not available.

Settlement

Settlement information for resolved events

Subcategory

Settlement

Settlement information for resolved events

value

string | null

The observed settlement value (e.g., the price at expiry for crypto contracts)

Example: 87654.32

EventsResponse

Event[]

Pagination

ContractMetadata

contractId

string

contractName

string

contractTicker

string

eventTicker

string

eventName

string

category

string

contractStatus

string

eventType

string

Event type ("binary" or "categorical")

expiryDate

string | null · date-time

resolvedAt

string | null · date-time

resolutionSide

string | null

Winning outcome if resolved ("yes" or "no")

parentEventTicker

string | null

Parent event ticker for sub-events

startTime

string | null · date-time

Start datetime (ISO 8601)

ComboLeg

comboId

integer · int64 · required

Internal ID of the parent combo contract

Example: 456

legIndex

integer · required

Zero-based position of this leg in the combo

Example: 0

contractId

string · required

Internal ID of the underlying single contract, represented as a decimal string

Example: 101

requiredOutcome

string · enum · required

The outcome this leg must settle for the combo to settle YES

Enum values:

Yes

Example: Yes

legOutcome

string | null

The outcome this leg has settled to, if resolved ("Yes" or "No"). Null while the leg is still active.

Example: null

resolvedAt

string | null · date-time

UTC timestamp when this leg resolved. Null while still active.

Example: null

object

Full metadata for the underlying single contract

ComboResponse

object · required

Metadata for the combo contract itself (ticker, status, expiry, etc.)

ComboLeg[] · required

Ordered list of legs that make up this combo

ListCombosResponse

ComboResponse[] · required

List of combo contracts matching the query

object · required

CreateComboRequest

A canonical combo definition. The authenticated account is derived from the signed request and is not a request field.

CreateComboLeg[] · minItems: 2 · maxItems: 6 · required

Two to six distinct underlying contract legs. The service canonicalizes their complete set, so leg order does not create a distinct combo.

CreateComboLeg

contractId

string · required

Underlying contract ID as a decimal string.

Example: 101

requiredOutcome

string · enum · required

Required settlement outcome for this leg.

Enum values:

Yes

Example: Yes

CreateComboResponse

ComboSummary · required

alreadyExisted

boolean · required

false when this request created the canonical combo; true when the canonical combo already existed.

ComboSummary

id

integer · int64 · required

Internal combo ID.

Example: 456

canonicalLegKey

string · required

Canonical identity of the complete combo leg set.

Example: 101:Yes|202:No

legCount

integer · int32 · required

Number of legs in the combo.

Example: 2

instrumentRegistered

boolean · required

Whether the combo has been registered with an instrument symbol.

ComboSummaryLeg[] · required

Canonically ordered combo legs.

displayName

string

Human-readable combo name, when available.

status

string

Current combo status, when available.

instrumentId

integer · int64

Associated instrument ID, when available.

instrumentSymbol

string

Associated instrument symbol, when available.

Example: GEMI-CMB-0526-A7F3B2C1D4E5

latestExpiryDate

string · date-time

Latest expiry among the underlying legs, when available.

createdAt

string · date-time

Creation time, when available.

updatedAt

string · date-time

Most recent update time, when available.

ComboSummaryLeg

comboId

integer · int64 · required

Parent combo ID.

legIndex

integer · int32 · required

Zero-based leg position in canonical order.

contractId

string · required

Underlying contract ID as a decimal string.

requiredOutcome

string · enum · required

Required settlement outcome for the leg.

Enum values:

Yes

legOutcome

string | null · enum

Settled outcome for the leg, when resolved.

Enum values:

Yes

resolvedAt

string | null · date-time

Resolution time for the leg, when resolved.

object

Underlying contract metadata, when available.

ComboWriteError

error

string · required

Error class.

Example: InvalidInput

message

string · required

Human-readable error detail.

Example: a combo needs 2-6 legs

code

string

Machine-readable code for validation or missing-leg errors, when available.

Example: COMBO_VALIDATION_ERROR

OrderRequest

symbol

string · required

Contract instrument symbol

Example: GEMI-FEDJAN26-DN25

orderType

OrderType · enum · required

Order type. stop-limit orders require a stopPrice that triggers a limit order at price when the market reaches the trigger.

Enum values:

limit

stop-limit

side

OrderSide · enum · required

Enum values:

buy

sell

quantity

string · decimal · required

Number of contracts

Example: 100

price

string · decimal · required

Limit price (0-1 range)

Example: 0.65

outcome

Outcome · enum · required

The outcome being traded (Yes or No)

Enum values:

yes

stopPrice

string · decimal

The price to trigger a stop-limit order (0-1 range). Only available for stop-limit orders. See Stop-Limit Orders above for stopPrice/price constraints.

Example: 0.60

timeInForce

TimeInForce · enum

Order execution behavior:

good-til-cancel - Order remains active until filled or cancelled (default)
immediate-or-cancel - Fill immediately or cancel remaining
fill-or-kill - Fill entire order immediately or cancel

Enum values:

good-til-cancel

immediate-or-cancel

fill-or-kill

Default: good-til-cancel

makerOrCancel

boolean

Set to true to require maker-only behavior. If the order would immediately take liquidity, the order is cancelled instead of filling.

Default: false

PlaceOrderBatchRequest

OrderRequest[] · minItems: 1 · maxItems: 20 · required

Orders to submit. Every entry is validated before any order is submitted. All orders use the account associated with the authenticated request.

BatchOrderResponse

An accepted order returned for one batch entry.

orderId

integer · int64 · required

status

string · enum · required

Enum values:

open

filled

cancelled

closed

symbol

string · required

side

OrderSide · enum · required

Enum values:

buy

sell

outcome

Outcome · enum · required

The outcome being traded (Yes or No)

Enum values:

yes

orderType

OrderType · enum · required

Order type. stop-limit orders require a stopPrice that triggers a limit order at price when the market reaches the trigger.

Enum values:

limit

stop-limit

timeInForce

string · enum · required

Enum values:

good-til-cancel

immediate-or-cancel

fill-or-kill

maker-or-cancel

quantity

string · required

Original order quantity

filledQuantity

string · required

Amount filled so far

remainingQuantity

string · required

Amount remaining to fill

price

string · required

Limit price

createdAt

string · date-time · required

updatedAt

string · date-time · required

hashOrderId

string

Hashed order ID; omitted when unavailable

clientOrderId

string

Client-provided order ID; omitted when unavailable

globalOrderId

string

Global order ID; omitted when unavailable

stopPrice

string

Stop trigger price; omitted unless populated for a stop-limit order

avgExecutionPrice

string

Average price of fills; omitted when unavailable

cancelledAt

string · date-time

Cancellation time; omitted unless the order was cancelled

ContractMetadata

promoCashApplied

string

Promotional cash reserved or applied to the order; omitted when unavailable

fundsOnHold

string

Cash reserved for the unfilled portion of a resting buy order; omitted when unavailable

PlaceOrderBatchSuccessResult

BatchOrderResponse · required

An accepted order returned for one batch entry.

PlaceOrderBatchErrorResult

error

string · required

Error class for a rejected entry

Example: InsufficientFunds

message

string · required

Human-readable detail for a rejected entry

Example: Insufficient funds

PlaceOrderBatchResult

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: order
	type = object · requires: error, message

Properties for Variant 1:

PlaceOrderBatchSuccessResult

BatchOrderResponse · required

An accepted order returned for one batch entry.

PlaceOrderBatchResponse

PlaceOrderBatchResult[] · minItems: 1 · maxItems: 20 · required

One result for each submitted order, in request order.

CancelOrderBatchRequest

array · minItems: 1 · maxItems: 20 · required

Order IDs to cancel. Each ID may be an integer or a quoted numeric string. All IDs are validated before any cancellation is attempted.

CancelOrderBatchSuccessResult

orderId

integer · int64 · required

Order ID from the corresponding request entry.

Example: 12345678

result

string · enum · required

Enum values:

CancelOrderBatchErrorResult

orderId

integer · int64 · required

Order ID from the corresponding request entry.

Example: 12345678

error

string · required

Error class for a rejected cancellation

Example: OrderNotFound

message

string · required

Human-readable detail for a rejected cancellation

Example: Order 12345678 not found

CancelOrderBatchResult

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: orderId, result
	type = object · requires: orderId, error, message

Properties for Variant 1:

CancelOrderBatchSuccessResult

orderId

integer · int64 · required

Order ID from the corresponding request entry.

Example: 12345678

result

string · enum · required

Enum values:

CancelOrderBatchResponse

CancelOrderBatchResult[] · minItems: 1 · maxItems: 20 · required

One result for each requested cancellation, in request order.

OrderResponse

orderId

integer · int64

hashOrderId

string | null

clientOrderId

string | null

globalOrderId

string | null

status

OrderStatus · enum

Enum values:

open

filled

cancelled

symbol

string

side

OrderSide · enum

Enum values:

buy

sell

outcome

Outcome · enum

The outcome being traded (Yes or No)

Enum values:

yes

orderType

OrderType · enum

Order type. stop-limit orders require a stopPrice that triggers a limit order at price when the market reaches the trigger.

Enum values:

limit

stop-limit

quantity

string

Original order quantity

filledQuantity

string

Amount filled so far

remainingQuantity

string

Amount remaining to fill

price

string

Limit price

stopPrice

string | null

Stop trigger price (populated for stop-limit orders)

avgExecutionPrice

string | null

Average price of fills

createdAt

string · date-time

updatedAt

string · date-time

cancelledAt

string | null · date-time

ContractMetadata

OrdersResponse

OrderResponse[]

PaginationSimple

Position

symbol

string

instrumentId

integer · int64

totalQuantity

string

Total position size

quantityOnHold

string

Quantity currently on hold from open orders

avgPrice

string

Average entry price

outcome

Outcome · enum

The outcome being traded (Yes or No)

Enum values:

yes

ContractMetadata

prices

PositionPrices

Current bid/ask/last-trade prices for the contract

resolutionSide

string | null

Winning outcome ("yes" or "no") if the contract has resolved

isAboveAutoStartThreshold

boolean

Whether the position is above the auto-start threshold

isLive

boolean

Whether the market is currently live/active

realizedPl

string | null

Realized profit/loss from sells

marketValue

string

Mark-to-market value of the position in USD at the current sell price (bestBid for YES, bestAsk for NO). Absent from the response when the held outcome has no live sell quote (no liquidity to sell into) — surface a no-liquidity state rather than a price the user cannot transact at. lastTradePrice is still returned for display. Treat as Optional<T>.

Example: 65.00

unrealizedPnl

string

Unrealized P&L in USD (marketValue - costBasis). Absent whenever marketValue is absent. Treat as Optional<T>.

Example: 12.50

unrealizedPct

number · double

Unrealized P&L as a percentage of cost basis. Expressed as a percent (e.g. 12.5 represents 12.5%, not 0.125); rounded to 4 decimal places. Absent when there is no live sell quote, or when cost basis is zero. Treat as Optional<T>.

Example: 23.81

PositionPrices

PositionsResponse

Position[]

total

integer | null

Total number of positions (for pagination)

SettledPosition

A historically settled position in a resolved prediction market contract.

accountId

integer · int64

Account that held the position

instrumentId

integer · int64

Unique instrument identifier for the contract

instrumentSymbol

string

Contract instrument symbol

Example: GEMI-FEDJAN26-DN25

position

string

Signed position held at settlement. Positive values represent a yes position; negative values represent a no position.

Example: 125

positionQuantity

string

Absolute quantity held at settlement (unsigned)

Example: 125

outcome

Outcome · enum

The outcome being traded (Yes or No)

Enum values:

yes

payout

string

Payout received from settlement. 0 when the position lost.

Example: 125.00

resolutionSide

string · enum

The winning outcome of the contract

Enum values:

yes

settledAt

string · date-time

Settlement timestamp (ISO 8601)

ContractMetadata

costBasis

string | null

Total amount spent to enter the position, net of any prior realized P&L from partial sells. Omitted when cost-basis data is not available.

Example: 78.75

realizedPnl

string | null

Realized profit or loss recorded from sells prior to settlement. Omitted when not available.

Example: 0

netProfit

string | null

Net profit for the position, computed as payout - costBasis + realizedPnl. Omitted when costBasis is not available.

Example: 46.25

SettledPositionsResponse

SettledPosition[]

total

integer | null

Total number of settled positions across all pages for the current filter set.

totalPayout

string

Sum of payout across all settled positions in the filter set. Retained for binary back-compat with the legacy response shape; field is absent (not null) on the unified backend because computing a roll-up over the full filtered set would require a separate aggregate query (deferred until a partner asks). Play's default OptionHandlers omits absent Option fields rather than emitting null.

totalCostBasis

string

Sum of costBasis across all settled positions in the filter set. Retained for binary back-compat; field is absent (not null) on the unified backend (see totalPayout).

totalNetProfit

string

Sum of netProfit across all settled positions in the filter set. Retained for binary back-compat; field is absent (not null) on the unified backend (see totalPayout).

CashedOutPosition[]

Cash-outs (early sells before contract resolution) in the same account-scoped time window as the returned page's settled positions. Field is absent (not null) when withCashOuts=true is not passed on the request. positions[] pagination is unaffected — limit/offset continue to scope positions[] only.

totalCashOutProceeds

string

Sum of cashOuts[].proceeds over the returned cash-outs. Field is absent (not null) when withCashOuts=true is not passed on the request.

Example: 120.00

totalCashOutCostBasis

string

Sum of cashOuts[].costBasis over the returned cash-outs. Field is absent (not null) when withCashOuts=true is not passed on the request.

Example: 100.00

totalCashOutNetProfit

string

Sum of cashOuts[].netProfit over the returned cash-outs. Field is absent (not null) when withCashOuts=true is not passed on the request.

Example: 20.00

CashedOutPosition

A qualifying cash-out (early sell before contract resolution) with cost-basis context. Exposed only via the `withCashOuts=true` sibling array on `POST /v1/prediction-markets/positions/settled`. Distinct from `SettledPosition` — cash-outs don't have a `payout` or `resolutionSide` since the contract hadn't resolved when the user sold.

accountId

integer · int64 · required

Account that held the position.

Example: 456

instrumentId

integer · int64 · required

Contract instrument ID.

Example: 16789219

instrumentSymbol

string · required

Contract instrument symbol.

Example: GEMI-FEDJAN26-DN25

timestamp

string · date-time · required

Wall-clock timestamp when the cash-out order closed (ISO 8601).

Example: 2026-05-15T14:30:00.000Z

filledQuantity

string · required

Quantity sold (cumulative filled quantity on the cash-out order).

Example: 10

side

string · enum · required

Always sell for cash-outs.

Enum values:

sell

Example: sell

proceeds

string · required

Amount received from the sale in USD. For prediction sells, proceeds flow through cash_balance rather than closed_orders.total_spend, so the value is derived from position-balance snapshots before/after the fill.

Example: 10.50

costBasis

string · required

Cost basis allocated proportionally to the filled quantity ((costBasisSpend / costBasisPositionBalance) * filledQuantity).

Example: 10.00

netProfit

string · required

Realized P&L from this cash-out fill (proceeds - costBasis). Equals the ledger realized_pl delta on the position-balance row pair around the fill; falls back to 0 under transient market-data lag so a missing post-fill snapshot can't poison the page.

Example: 0.50

ContractMetadata

ContractShareVolume

symbol

string

Contract instrument symbol

Example: GEMI-FED260318-CUT25

totalQty

string

Total taker volume across all participants (in shares)

Example: 94625

userAggressorQty

string | null

The authenticated user's taker (aggressor) volume (in shares)

Example: 1

userRestingQty

string | null

The authenticated user's maker (resting) volume (in shares)

Example: 0

VolumeMetricsResponse

eventTicker

string

The event ticker

Example: FED260318

ContractShareVolume[]

PredictionMarketVolumeCategory

categoryPath

string[] · required

Display-name path from the top-level category to this category. It replaces recursive child nodes.

Example: ["Sports","Football","Pro Football"]

volume

string · pattern: ^(?:0|[1-9][0-9]*)(?… · required

Total volume for this category, including all descendant categories.

Example: 143567.25

PredictionMarketHourlyVolumeCategory

periodStart

string · date-time · required

Inclusive UTC start of this hourly period.

Example: 2026-07-20T00:00:00Z

categoryPath

string[] · required

Display-name path from the top-level category to this category. It replaces recursive child nodes.

Example: ["Sports","Football","Pro Football"]

volume

string · pattern: ^(?:0|[1-9][0-9]*)(?… · required

Total volume for this category in this hour, including all descendant categories.

Example: 143567.25

PredictionMarketVolumeDecimal

string · pattern: ^(?:0|[1-9][0-9]*)(?…

Non-negative decimal string. Preserve it as a string to avoid floating-point precision loss.

Example: 143567.25

MakerRebateRateRule

id

integer · int64 · required

Stable identifier for this rate rule.

Example: 12

rebate_multiplier_bps

integer · int32 · required

Portion of the maker fee that is rebated, in basis points (10000 bps = 100%).

Example: 5000

effective_from

string | null · date-time · required

ISO-8601 timestamp at which this rule becomes effective. Always present; in practice never null.

Example: 2026-03-19T00:00:00Z

category

string

Market category this rule applies to. When absent, the rule applies to all categories.

Example: Crypto

effective_to

string · date-time

ISO-8601 timestamp after which this rule is superseded. Omitted when the rule is still current.

Example: 2026-04-19T00:00:00Z

MakerRebateRatesResponse

MakerRebateRateRule[] · required

MakerRebatePayout

id

integer · int64 · required

Stable payout identifier.

Example: 9182

total_volume_usd

string · required

Total qualifying maker volume contributing to this payout, in USD.

Example: 12450.00

total_rebate_usd

string · required

Total rebate paid, in USD.

Example: 6.23

total_fill_count

integer · int32 · required

Number of qualifying maker fills that contributed to the payout.

Example: 187

status

string · required

Payout status (e.g. PENDING, PAID).

Example: PAID

paid_at

string | null · date-time · required

ISO-8601 timestamp at which the rebate was credited. Always present; null for payouts that have not yet been paid.

Example: 2026-05-20T21:00:00Z

created_at

string | null · date-time · required

ISO-8601 timestamp at which the payout row was created. Always present.

Example: 2026-05-20T20:55:12Z

MakerRebatePayoutsResponse

MakerRebatePayout[] · required

MakerRebateLifetimeSummary

total_earned_usd

string · required

Sum of total_rebate_usd across payouts in the window.

Example: 152.40

total_fill_count

integer · int64 · required

Sum of qualifying maker fills across payouts in the window.

Example: 4218

total_volume_usd

string · required

Sum of qualifying maker volume (USD) across payouts in the window.

Example: 304800.00

payout_count

integer · int32 · required

Number of payouts in the window. Always present; 0 when no payouts exist in the window.

Example: 27

first_payout_date

string | null · date · required

Date of the earliest payout in the window, or null if no payouts exist.

Example: 2026-03-19

last_payout_date

string | null · date · required

Date of the most recent payout in the window, or null if no payouts exist.

Example: 2026-05-20

LiquidityRewardsConfig

enabled

boolean · required

True when the program is fully configured upstream. When false, the response collapses to { "enabled": false } only.

Example: true

max_spread_cents

integer · int32

Quotes wider than this spread score zero in the scoring algorithm. Only present when enabled is true.

Example: 10

min_payout_threshold_usd

string

Daily reward amounts below this threshold are suppressed (sub-threshold accounts get no row at all). Only present when enabled is true.

Example: 1.00

LiquidityRewardEvent

event_ticker

string · required

Event ticker (e.g. BTC2605202100).

Example: BTC2605202100

title

string · required

Event title.

Example: BTC above $95,000?

category

string · required

Market category.

Example: Crypto

daily_pool_usd

string · required

Daily USD reward pool budgeted for this event.

Example: 500.00

pool_source

string · enum · required

Whether the pool came from a per-event override or the category default.

Enum values:

event_override

category_default

unspecified

Example: event_override

ends_at

string | null · date-time · required

ISO-8601 timestamp at which the event ends and stops scoring. null when the underlying event has no end timestamp set.

Example: 2026-05-20T21:00:00Z

qualifying_maker_count

integer · int32 · required

Number of accounts that met qualifying-maker criteria in the most recent snapshot window for this event.

Example: 14

icon_url

string

Optional URL for the event icon. Omitted when not configured.

Example: https://example.com/btc.png

LiquidityRewardsEventsResponse

LiquidityRewardEvent[] · required

Pagination · required

last_score_date

string | null · date · required

Most recent date for which scoring has been written. null when no scoring has run yet.

Example: 2026-05-19

LiquidityEventScore

event_id

integer · int64 · required

Stable event identifier.

Example: 1234567890

event_name

string · required

Event title.

Example: BTC above $95,000?

category_name

string · required

Market category.

Example: Crypto

normalized_score

string · required

This account's normalized score for the event on the scoring date (0-1 range as a decimal string).

Example: 0.4521

snapshot_count

integer · int32 · required

Number of snapshots in which this account had a qualifying quote.

Example: 1180

total_snapshots

integer · int32 · required

Total snapshots taken for the event on the scoring date.

Example: 1440

event_reward_usd

string · required

Portion of the day's total reward attributed to this event.

Example: 8.20

LiquidityDailySummary

payout_date

string · date · required

Date the payout applies to (Eastern Time).

Example: 2026-05-07

total_reward_usd

string · required

Total USD reward for the day across all events the account scored on.

Example: 12.45

payout_status

string · required

Status of the day's payout (e.g. PENDING, PAID, ZERO_AMOUNT).

Example: PAID

paid_at

string | null · date-time · required

ISO-8601 timestamp the day's payout was credited. Always present; null if not yet paid.

Example: 2026-05-08T21:00:00Z

LiquidityEventScore[] · required

Per-event score breakdown showing how the day's total was distributed.

LiquidityRewardsDailySummaryResponse

LiquidityDailySummary[] · required

LiquidityRewardsLifetimeSummary

total_earned_usd

string · required

Sum of total_reward_usd across daily payouts in the window.

Example: 84.20

payout_count

integer · int32 · required

Number of daily payouts in the window. Always present; 0 when no payouts exist in the window.

Example: 12

first_payout_date

string | null · date · required

Date of the earliest payout in the window, or null if no payouts exist.

Example: 2026-05-08

last_payout_date

string | null · date · required

Date of the most recent payout in the window, or null if no payouts exist.

Example: 2026-05-20