{ "openapi": "3.1.0", "info": { "title": "Rook API", "version": "0.1.0-design", "description": "Markets, settlement relationships, scenarios, payouts and market data." }, "servers": [ { "url": "https://api.rook.pm/v1", "description": "Proposed API origin; not an assertion these operations are callable." } ], "tags": [ { "name": "Reference data", "description": "Events, unified markets and native-ID resolution." }, { "name": "Families and scenarios", "description": "Family scope and versioned scenario columns." }, { "name": "Relationships and Combos", "description": "Related-market discovery, selected-set inference and Combo interpretation." }, { "name": "Payouts and exposure", "description": "Scoped per-unit payouts and stateless portfolio/candidate calculations." }, { "name": "Market data", "description": "Current prices, history, L2 books, prints, statistics and published fees." }, { "name": "Fair values", "description": "Future private customer estimates; not Rook forecasts." }, { "name": "Coverage and updates", "description": "Supported capabilities and incremental semantic changes." } ], "security": [ { "ApiKeyBearer": [] } ], "paths": { "/events": { "get": { "operationId": "listEvents", "tags": [ "Reference data" ], "summary": "List events", "description": "Find the venue events that contain markets you want to inspect. Browse by keyword, venue, category or family; for an exact native lookup, supply venue and venue_event_id. For example, venue=polymarket&venue_event_id=900001 looks up a numeric Polymarket event ID. Use event_id instead when you already have its Rook ID.\n\nEach item returns the Rook event_id, venue, original venue_event_id, source title, market_ids and family_ids. Events preserve the venue's grouping: Rook never merges related venue events or creates an event from analytically related markets. A family can connect several events without changing them.\n\nThe response always uses items; an exact lookup returns zero or one event. Follow market_ids to /markets, or family_ids to /families to discover the broader group across events. Other filters narrow results, and pagination preserves the search snapshot.", "parameters": [ { "name": "event_id", "in": "query", "required": false, "description": "Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate. Omit to browse. Exact lookup retains the items envelope.", "schema": { "type": "string", "minLength": 1 }, "example": "evt_pm_900001" }, { "name": "venue_event_id", "in": "query", "required": false, "description": "Original venue event ID. For Polymarket this is its numeric Gamma event ID, encoded as decimal text. It is not a market ID.", "schema": { "type": "string", "minLength": 1 }, "example": "900001" }, { "name": "family_id", "in": "query", "required": false, "description": "Rook family ID connecting related markets across original venue events. Omit to browse. Exact lookup retains the items envelope.", "schema": { "type": "string", "minLength": 1 }, "example": "fam_fed_dec_2026" }, { "name": "q", "in": "query", "required": false, "description": "Search titles, descriptions and tags by words, ignoring letter case. Results are ordered by relevance with stable ID tie-breaking. Other filters narrow the matches.", "schema": { "type": "string", "minLength": 1 }, "example": "Fed rate cut" }, { "name": "category", "in": "query", "required": false, "description": "Exact category label used by the catalog, for example rates. Narrows search results.", "schema": { "type": "string" } }, { "name": "venue", "in": "query", "required": false, "description": "Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID.", "schema": { "type": "string" }, "example": "polymarket" }, { "name": "status", "in": "query", "required": false, "description": "Filter by the resource lifecycle status. This does not indicate analytical coverage or feed freshness.", "schema": { "type": "string", "enum": [ "OPEN", "CLOSED", "RESOLVED", "UNKNOWN" ] } }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" }, "example": { "items": [ { "event_id": "evt_pm_900001", "title": "Fed rate cut \u2014 December 2026", "description": "Illustrative source event containing the cut market. The related hold market belongs to another original venue event.", "category": "rates", "status": "OPEN", "market_ids": [ "mkt_fed_dec_2026_cut" ], "family_ids": [ "fam_fed_dec_2026" ], "observed_at": "2026-10-19T12:00:00Z", "venue": "polymarket", "venue_event_id": "900001" } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/markets": { "get": { "operationId": "listMarkets", "tags": [ "Reference data" ], "summary": "List markets", "description": "Find markets and inspect their settlement rules, outcome sides and venue listings. Supply venue plus venue_market_id to translate a native market ID into a Rook market_id, or use market_id when you already have the Rook ID. For example, venue=polymarket&venue_market_id=1000001 uses the numeric Polymarket market ID, not its slug, condition ID or outcome token ID.\n\nEach market returns its Rook market_id, original event references, family_ids, settlement summary, payout conditions and outcomes. Outcome listings retain venue_market_id, venue_event_ids and venue outcome identifiers. Rook can map settlement-equivalent listings to one market, while each listing keeps its original venue event membership. Related markets remain separate markets.\n\nFilter by event_id to stay inside an original venue event, or family_id to find related markets across events. Add include=EVIDENCE for settlement sources or include=LEGS for a Combo. Use market_ids for a batch Rook-ID lookup. Single, batch and native market selectors are mutually exclusive; version requires market_id. Exact lookups keep the items envelope and return an empty array when no mapping is known.", "parameters": [ { "name": "market_id", "in": "query", "required": false, "description": "Rook canonical market ID. Resolve a venue_market_id first; related markets do not share an ID merely because they share a family. Omit to browse. Exact lookup retains the items envelope.", "schema": { "type": "string", "minLength": 1 }, "example": "mkt_fed_dec_2026_cut" }, { "name": "venue_market_id", "in": "query", "required": false, "description": "Original venue market ID. For Polymarket this is its numeric Gamma market ID, encoded as decimal text. It is not an event, condition or CLOB token ID.", "schema": { "type": "string", "minLength": 1 }, "example": "1000001" }, { "name": "version", "in": "query", "required": false, "description": "Market version to retrieve. Requires market_id. Omit for the current version.", "schema": { "type": "string", "minLength": 1 } }, { "name": "include", "in": "query", "required": false, "description": "Add settlement evidence or Combo leg details to each returned market.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "EVIDENCE", "LEGS" ] } }, "style": "form", "explode": true }, { "name": "market_ids", "in": "query", "required": false, "description": "Rook market IDs in this resource. On an event these reflect its source venue membership; on a family they identify the related market members.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true }, { "name": "q", "in": "query", "required": false, "description": "Search titles, descriptions and tags by words, ignoring letter case. Results are ordered by relevance with stable ID tie-breaking. Other filters narrow the matches.", "schema": { "type": "string", "minLength": 1 }, "example": "Fed rate cut" }, { "name": "event_id", "in": "query", "required": false, "description": "Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate. Omit to browse. Exact lookup retains the items envelope.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, { "name": "family_id", "in": "query", "required": false, "description": "Rook family ID connecting related markets across original venue events. Omit to browse. Exact lookup retains the items envelope.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, { "name": "venue", "in": "query", "required": false, "description": "Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID.", "schema": { "type": "string" }, "example": "polymarket" }, { "name": "category", "in": "query", "required": false, "description": "Exact category label used by the catalog, for example rates. Narrows search results.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by the resource lifecycle status. This does not indicate analytical coverage or feed freshness.", "schema": { "type": "string", "enum": [ "OPEN", "CLOSED", "RESOLVED", "UNKNOWN" ] } }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMarketsResponse" }, "example": { "items": [ { "market_id": "mkt_fed_dec_2026_cut", "version": "1", "title": "Will the Fed cut rates at its December 2026 decision?", "description": "Illustrative rates-market market for the documentation walkthrough.", "event_ids": [ "evt_pm_900001" ], "family_ids": [ "fam_fed_dec_2026" ], "category": "rates", "settlement_summary": "YES pays 1 USDC per share if the policy-rate target is lower after the decision than immediately before it.", "payout_conditions": [ "A cut pays YES 1 USDC and NO 0 USDC.", "An unchanged rate or a hike pays YES 0 USDC and NO 1 USDC." ], "outcomes": [ { "outcome_id": "out_fed_dec_2026_cut_yes", "label": "YES", "listings": [ { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "venue": "polymarket", "venue_market_id": "1000001", "venue_outcome_id": "YES", "outcome_id": "out_fed_dec_2026_cut_yes", "mapping_version": "1", "status": "OPEN", "trading_rules": { "quantity_unit": "shares", "quote_currency": "USDC", "payout_currency": "USDC", "payout_unit": "1", "quantity_increment": "1", "tick_bands": [ { "lower_price": "0", "upper_price": "1", "tick_size": "0.01" } ] }, "observed_at": "2026-10-19T12:00:00Z", "venue_event_ids": [ "900001" ] } ] }, { "outcome_id": "out_fed_dec_2026_cut_no", "label": "NO", "listings": [] } ], "is_combo": false, "analytical_only": false, "observed_at": "2026-10-19T12:00:00Z" } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/markets:resolve": { "post": { "operationId": "resolveMarkets", "tags": [ "Reference data" ], "summary": "Resolve markets", "description": "Translate a batch of native venue market identifiers into Rook IDs before requesting analytics. Each input requires venue and a unique client_reference. A venue_market_id alone resolves a market and returns its outcomes and listings; add venue_outcome_id to resolve one outcome side. Token IDs, or supported ticker/slug plus outcome forms, can resolve an individual listing.\n\nFor Polymarket, venue_market_id is the numeric market ID, encoded as decimal text. It is distinct from a numeric venue_event_id, a condition ID and a CLOB token ID. To look up an event, use /events with venue and venue_event_id. A market selector must never be populated with an event ID.\n\nEach result echoes the native input and returns RESOLVED, UNRESOLVED or AMBIGUOUS. A resolved market includes market_id, market_version, event_ids, family_ids and outcomes; a resolved outcome also includes outcome_id, listing_id and mapping_version. Unknown or ambiguous inputs carry a reason and are never guessed. One failed item does not hide the results for other inputs. Use returned outcome/listing IDs in payouts, relationships and evaluations.", "parameters": [ { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveMarketsResponse" }, "example": { "items": [ { "client_reference": "rfq_leg_1", "status": "RESOLVED", "market_id": "mkt_fed_dec_2026_cut", "market_version": "1", "input": { "client_reference": "rfq_leg_1", "venue": "polymarket", "venue_market_id": "1000001" }, "event_ids": [ "evt_pm_900001" ], "family_ids": [ "fam_fed_dec_2026" ], "outcomes": [ { "outcome_id": "out_fed_dec_2026_cut_yes", "label": "YES", "listings": [ { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "venue": "polymarket", "venue_market_id": "1000001", "venue_outcome_id": "YES", "outcome_id": "out_fed_dec_2026_cut_yes", "mapping_version": "1", "status": "OPEN", "trading_rules": { "quantity_unit": "shares", "quote_currency": "USDC", "payout_currency": "USDC", "payout_unit": "1", "quantity_increment": "1", "tick_bands": [ { "lower_price": "0", "upper_price": "1", "tick_size": "0.01" } ] }, "observed_at": "2026-10-19T12:00:00Z", "venue_event_ids": [ "900001" ] } ] }, { "outcome_id": "out_fed_dec_2026_cut_no", "label": "NO", "listings": [] } ] }, { "client_reference": "rfq_leg_2", "status": "RESOLVED", "market_id": "mkt_fed_dec_2026_hold", "market_version": "1", "input": { "client_reference": "rfq_leg_2", "venue": "polymarket", "venue_market_id": "1000002" }, "event_ids": [ "evt_pm_900002" ], "family_ids": [ "fam_fed_dec_2026" ], "outcomes": [ { "outcome_id": "out_fed_dec_2026_hold_yes", "label": "YES", "listings": [] }, { "outcome_id": "out_fed_dec_2026_hold_no", "label": "NO", "listings": [] } ] } ], "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveMarketsRequest" }, "example": { "inputs": [ { "client_reference": "rfq_leg_1", "venue": "polymarket", "venue_market_id": "1000001" }, { "client_reference": "rfq_leg_2", "venue": "polymarket", "venue_market_id": "1000002" } ] } } } } } }, "/families": { "get": { "operationId": "listFamilies", "tags": [ "Families and scenarios" ], "summary": "List families", "description": "Discover Rook's grouping of related markets across the events maintained by venues. A family sits above venue events and their markets; it does not replace the events or rewrite their source membership. Use family_id for one family, market_ids to find families containing supplied markets, or q to search by topic.\n\nEach item returns family_id, event_ids, market_ids, a readable description, analytical_coverage and available scenario versions. Event and market responses include family_ids so you can reach the same family from either starting point. Several memberships remain explicit rather than forcing an arbitrary exclusive tree.\n\nUse /events?family_id=... to browse its original venue events, /markets?family_id=... for member markets and /scenarios for a published scenario catalog. Membership describes the grouping; analytical_coverage states whether settlement analysis is available. Listing an event in a family does not claim that every market in that event has supported payout analysis.", "parameters": [ { "name": "family_id", "in": "query", "required": false, "description": "Rook family ID connecting related markets across original venue events. Omit to browse. Exact lookup retains the items envelope.", "schema": { "type": "string", "minLength": 1 }, "example": "fam_fed_dec_2026" }, { "name": "q", "in": "query", "required": false, "description": "Search titles, descriptions and tags by words, ignoring letter case. Results are ordered by relevance with stable ID tie-breaking. Other filters narrow the matches.", "schema": { "type": "string", "minLength": 1 }, "example": "Fed rate cut" }, { "name": "market_ids", "in": "query", "required": false, "description": "Rook market IDs in this resource. On an event these reflect its source venue membership; on a family they identify the related market members.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true }, { "name": "category", "in": "query", "required": false, "description": "Exact category label used by the catalog, for example rates. Narrows search results.", "schema": { "type": "string" } }, { "name": "venue", "in": "query", "required": false, "description": "Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFamiliesResponse" }, "example": { "items": [ { "family_id": "fam_fed_dec_2026", "title": "December 2026 Fed rate decision", "description": "Related markets across two distinct illustrative Polymarket events. Original event membership is preserved; the family connects the cut and hold markets.", "market_ids": [ "mkt_fed_dec_2026_cut", "mkt_fed_dec_2026_hold" ], "current_scenario_version": "1", "scenario_versions": [ "1" ], "supported_convention_ids": [ "demo_all_legs_win_v1" ], "analytical_coverage": "COMPLETE", "observed_at": "2026-10-19T12:00:00Z", "event_ids": [ "evt_pm_900001", "evt_pm_900002" ] } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/scenarios": { "get": { "operationId": "listScenarios", "tags": [ "Families and scenarios" ], "summary": "List scenarios", "description": "Retrieve the possible settlement cases published for a Rook family. Supply family_id and scenario_version from /families; optionally select specific scenario_ids. Each item provides a scenario reference, readable label and description, plus how many underlying states it represents.\n\nPass the returned references unchanged to /payouts:calculate or use the family/version pin in /relationships:analyze and /evaluations:run. Scenario IDs only have meaning within their family and version. A wrong-family or stale reference fails explicitly. Pagination returns more columns from the same published catalog; it does not alter the scenario scope.", "parameters": [ { "name": "family_id", "in": "query", "required": true, "description": "Rook family ID connecting related markets across original venue events. Narrows the selection to this resource.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "example": "fam_fed_dec_2026" }, { "name": "scenario_version", "in": "query", "required": true, "description": "Published family scenario-catalog version. Use together with family_id to pin scenario meaning.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "example": "1" }, { "name": "scenario_ids", "in": "query", "required": false, "description": "Return only these scenario IDs within the required family and scenario_version. Repeat the parameter for multiple IDs.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScenariosResponse" }, "example": { "items": [ { "reference": { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" }, "label": "Rate cut", "description": "The announced policy-rate target is lower than before the decision.", "representation": "CUT_HOLD_HIKE", "represented_state_count": 1 }, { "reference": { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hold" }, "label": "Rate unchanged", "description": "The announced policy-rate target is unchanged.", "representation": "CUT_HOLD_HIKE", "represented_state_count": 1 }, { "reference": { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" }, "label": "Rate hike", "description": "The announced policy-rate target is higher than before the decision.", "representation": "CUT_HOLD_HIKE", "represented_state_count": 1 } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/relationships": { "get": { "operationId": "listRelationships", "tags": [ "Relationships and Combos" ], "summary": "Discover relationships", "description": "Discover markets connected by settlement logic to a known market, outcome or original venue event. Supply exactly one Rook selector: market_id, outcome_id or event_id. For a native ID, first obtain the Rook ID from /events, /markets or /markets:resolve.\n\nResults explain relationships such as implication or exclusivity and identify the related market and original event IDs. Related markets may belong to different venue events. Discovery preserves both events and exposes their connection through families and relationships. Optional type and related_venue filters narrow results; family_id and scenario_version must be supplied together.\n\nUse this endpoint to discover neighbors. To analyze a specific basket, explicitly select its outcomes and call /relationships:analyze; discovered neighbors are not automatically included in calculations.", "parameters": [ { "name": "market_id", "in": "query", "required": false, "description": "Rook canonical market ID. Resolve a venue_market_id first; related markets do not share an ID merely because they share a family. Narrows the selection to this resource.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "example": "mkt_fed_dec_2026_cut" }, { "name": "outcome_id", "in": "query", "required": false, "description": "Rook outcome ID identifying one payout side, such as YES or NO.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, { "name": "event_id", "in": "query", "required": false, "description": "Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate. Narrows the selection to this resource.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, { "name": "family_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Rook family ID connecting related markets across original venue events. Narrows the selection to this resource." }, { "name": "type", "in": "query", "required": false, "description": "Filter by a supported settlement relationship type, such as implication or exclusivity.", "schema": { "$ref": "#/components/schemas/RelationType" } }, { "name": "related_venue", "in": "query", "required": false, "description": "Only return discovered neighbors with listings on this venue; does not change the starting selection.", "schema": { "type": "string" } }, { "name": "scenario_version", "in": "query", "required": false, "description": "Published family scenario-catalog version. Use together with family_id to pin scenario meaning.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRelationshipsResponse" }, "example": { "items": [ { "relationship_id": "rel_fed_cut_hold_exclusive", "type": "EXCLUSIVITY", "from_outcome_id": "out_fed_dec_2026_cut_yes", "to_outcome_id": "out_fed_dec_2026_hold_yes", "related_market_ids": [ "mkt_fed_dec_2026_cut", "mkt_fed_dec_2026_hold" ], "related_event_ids": [ "evt_pm_900001", "evt_pm_900002" ], "explanation": "The same Fed decision cannot both lower the policy rate and leave it unchanged. The two YES outcomes never pay together in these scenarios.", "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "witnesses": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hold" } ] } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/markets:compose": { "post": { "operationId": "composeMarket", "tags": [ "Relationships and Combos" ], "summary": "Compose a Combo", "description": "Interpret an explicitly supplied set of outcome legs as one Combo payout under a supported venue/product settlement convention. Supply at least two legs, venue and settlement_convention_id; optional scenario_pins make interpretation reproducible.\n\nThe response returns an analytical market with its outcomes, interpreted settlement conditions, coverage and versions. Findings explain impossible or redundant legs and include supporting scenarios. The combined payout follows the stated product convention, including supported exceptional settlements; it is not the sum of individual positions.\n\nUse the returned outcome IDs for payout or exposure calculations. Composition does not create a venue event, attach the Combo to a fabricated event, create a tradable venue listing or submit an order. Unsupported conventions or joint scenario scope fail explicitly.", "parameters": [ { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComposeMarketResponse" }, "example": { "market": { "market_id": "mkt_combo_cut_and_no_hold", "version": "1", "title": "Fed cuts rates AND does not hold rates", "description": "Illustrative two-leg ticket. The second leg adds no condition when a cut already requires a change.", "event_ids": [], "family_ids": [ "fam_fed_dec_2026" ], "category": "rates", "settlement_summary": "Pays 1 USDC if the policy rate is cut; the no-hold leg is automatically satisfied by a cut.", "payout_conditions": [ "A cut pays YES 1 USDC.", "A hold or hike pays YES 0 USDC." ], "outcomes": [ { "outcome_id": "out_combo_cut_and_no_hold_yes", "label": "YES", "listings": [] }, { "outcome_id": "out_combo_cut_and_no_hold_no", "label": "NO", "listings": [] } ], "is_combo": true, "analytical_only": true, "observed_at": "2026-10-19T12:00:00Z", "legs": [ { "outcome_id": "out_fed_dec_2026_cut_yes" }, { "outcome_id": "out_fed_dec_2026_hold_no" } ], "settlement_convention_id": "demo_all_legs_win_v1" }, "coverage": { "complete": true, "submitted_count": 2, "supported_count": 2, "items": [ { "input_reference": "out_fed_dec_2026_cut_yes", "outcome_id": "out_fed_dec_2026_cut_yes", "status": "SUPPORTED", "family_ids": [ "fam_fed_dec_2026" ] }, { "input_reference": "out_fed_dec_2026_hold_no", "outcome_id": "out_fed_dec_2026_hold_no", "status": "SUPPORTED", "family_ids": [ "fam_fed_dec_2026" ] } ] }, "versions": { "market_versions": [ { "market_id": "mkt_fed_dec_2026_cut", "version": "1" }, { "market_id": "mkt_fed_dec_2026_hold", "version": "1" }, { "market_id": "mkt_combo_cut_and_no_hold", "version": "1" } ], "mapping_version": "1", "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "as_of": "2026-10-19T12:00:00Z" }, "findings": [ { "code": "REDUNDANT_LEG", "explanation": "If the Fed cuts rates, it cannot hold rates unchanged. The second leg does not change this ticket\u2019s payout.", "leg_indices": [ 1 ], "witnesses": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" } ] } ] } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComposeMarketRequest" }, "example": { "client_reference": "rfq_cut_no_hold", "venue": "polymarket", "settlement_convention_id": "demo_all_legs_win_v1", "legs": [ { "outcome_id": "out_fed_dec_2026_cut_yes" }, { "outcome_id": "out_fed_dec_2026_hold_no" } ], "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ] } } } } } }, "/relationships:analyze": { "post": { "operationId": "analyzeRelationships", "tags": [ "Relationships and Combos" ], "summary": "Analyze relationships", "description": "Explain how an explicitly selected set of outcomes can pay together. Supply outcome_id or listing_id references in selection; resolve native market IDs first. The response can include pair relationships, basket overlap/gap counts and example settlement witnesses.\n\nFor example, two outcomes can be mutually exclusive even when their markets appear in different original venue events. The analysis uses published family scenarios rather than titles or price correlation. Returned scenario pins and the paying_definition state the scope of the finding; FULL_PAYOUT distinguishes full wins from fractional payouts.\n\nOnly supplied outcomes participate, and duplicate references to the same canonical outcome are deduplicated for set counts. Witness limits bound returned examples, not the scenario domain used to prove a finding. Complete-coverage requests reject missing interpretations; partial requests identify the supported subset explicitly.", "parameters": [ { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeRelationshipsResponse" }, "example": { "relationships": [ { "relationship_id": "rel_fed_cut_hold_exclusive", "type": "EXCLUSIVITY", "from_outcome_id": "out_fed_dec_2026_cut_yes", "to_outcome_id": "out_fed_dec_2026_hold_yes", "related_market_ids": [ "mkt_fed_dec_2026_cut", "mkt_fed_dec_2026_hold" ], "related_event_ids": [ "evt_pm_900001", "evt_pm_900002" ], "explanation": "The same Fed decision cannot both lower the policy rate and leave it unchanged. The two YES outcomes never pay together in these scenarios.", "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "witnesses": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hold" } ] } ], "baskets": [ { "classification": "EXCLUSIVE", "outcome_ids": [ "out_fed_dec_2026_cut_yes", "out_fed_dec_2026_hold_yes" ], "selected_outcome_count": 2, "scenario_count": 3, "representation": "CUT_HOLD_HIKE", "paying_definition": "POSITIVE_PAYOUT", "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "paying_counts": { "none": 1, "exactly_one": 2, "two_or_more": 0 }, "gap_witnesses": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" } ], "overlap_witnesses": [] } ], "coverage": { "complete": true, "submitted_count": 2, "supported_count": 2, "items": [ { "input_reference": "out_fed_dec_2026_cut_yes", "outcome_id": "out_fed_dec_2026_cut_yes", "status": "SUPPORTED", "family_ids": [ "fam_fed_dec_2026" ] }, { "input_reference": "out_fed_dec_2026_hold_yes", "outcome_id": "out_fed_dec_2026_hold_yes", "status": "SUPPORTED", "family_ids": [ "fam_fed_dec_2026" ] } ] }, "versions": { "market_versions": [ { "market_id": "mkt_fed_dec_2026_cut", "version": "1" }, { "market_id": "mkt_fed_dec_2026_hold", "version": "1" } ], "mapping_version": "1", "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "as_of": "2026-10-19T12:00:00Z" } } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeRelationshipsRequest" }, "example": { "selection": [ { "outcome_id": "out_fed_dec_2026_cut_yes" }, { "outcome_id": "out_fed_dec_2026_hold_yes" } ], "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "include": [ "PAIRS", "BASKET", "WITNESSES" ] } } } } } }, "/payouts:calculate": { "post": { "operationId": "calculatePayouts", "tags": [ "Payouts and exposure" ], "summary": "Calculate payouts", "description": "Return the exact per-unit terminal payout of each selected outcome across settlement scenarios. Supply selection using Rook outcome or listing IDs. Optionally provide scenario references from /scenarios; omit them to retrieve all applicable columns under returned family/version pins.\n\nEach matrix contains ordered scenario_columns and payout rows for only the requested outcomes. Read values[i] against scenario_columns[i], with the row's currency and payout unit. Cross-family Combo cases use compatible joint scenario references rather than unrelated row indices.\n\nUse this endpoint to answer when a market pays or to apply your own exact quantity arithmetic. For portfolio totals and candidate comparisons, use /evaluations:run. Values preserve exact decimals or rational fractions. Pagination continues columns with unchanged selection and pins; unsupported coverage is rejected or labeled according to require_complete_coverage.", "parameters": [ { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculatePayoutsResponse" }, "example": { "matrices": [ { "scenario_columns": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hold" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" } ], "rows": [ { "outcome_id": "out_fed_dec_2026_cut_yes", "listing_id": "lst_pm_fed_dec_2026_cut_yes", "payout_currency": "USDC", "payout_unit": "1", "values": [ "1", "0", "0" ] }, { "outcome_id": "out_fed_dec_2026_hold_yes", "payout_currency": "USDC", "payout_unit": "1", "values": [ "0", "1", "0" ] } ], "total_column_count": 3, "representation": "CUT_HOLD_HIKE" } ], "next_page_token": null, "coverage": { "complete": true, "submitted_count": 2, "supported_count": 2, "items": [ { "input_reference": "out_fed_dec_2026_cut_yes", "outcome_id": "out_fed_dec_2026_cut_yes", "status": "SUPPORTED", "family_ids": [ "fam_fed_dec_2026" ] }, { "input_reference": "out_fed_dec_2026_hold_yes", "outcome_id": "out_fed_dec_2026_hold_yes", "status": "SUPPORTED", "family_ids": [ "fam_fed_dec_2026" ] } ] }, "versions": { "market_versions": [ { "market_id": "mkt_fed_dec_2026_cut", "version": "1" }, { "market_id": "mkt_fed_dec_2026_hold", "version": "1" } ], "mapping_version": "1", "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "as_of": "2026-10-19T12:00:00Z" } } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculatePayoutsRequest" }, "example": { "selection": [ { "outcome_id": "out_fed_dec_2026_cut_yes" }, { "outcome_id": "out_fed_dec_2026_hold_yes" } ], "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ] } } } } } }, "/evaluations:run": { "post": { "operationId": "runEvaluation", "tags": [ "Payouts and exposure" ], "summary": "Evaluate exposure", "description": "Calculate what supplied positions pay at settlement, and compare the effect of explicitly supplied hypothetical trades. Positions identify a Rook outcome/listing, a positive exact quantity and HELD or OWED convention. Candidates supply signed quantity changes; each candidate is evaluated separately against the same baseline.\n\nResults include baseline and after-candidate payout groups, candidate deltas, best/worst cases with feasible witnesses, and requested contributions or rankings. Contributions reconcile to totals. Unrelated families or currencies remain separate; whole-book extrema are exact only when compatible joint witnesses exist.\n\nTerminal payout is the settlement cash flow, not a probability or historical-entry P&L. Optional MIDPOINT or LIQUIDATION pricing uses Rook observations and reports missing or stale valuation inputs. No candidate fills, inventory writes or hedge discovery occur. Pin scenario versions to reproduce a result.", "parameters": [ { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunEvaluationResponse" }, "example": { "evaluation_id": "eval_rates_sell_250_cut", "baseline": { "groups": [ { "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "scenario_columns": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hold" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" } ], "currency": "USDC", "total_scenario_count": 3, "terminal_payouts": [ "1000", "300", "0" ], "minimum_payout": "0", "maximum_payout": "1000", "minimum_witnesses": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" } ], "maximum_witnesses": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" } ], "minimum_tie_count": 1, "maximum_tie_count": 1, "contributions": [ { "position_id": "inventory_cut", "outcome_id": "out_fed_dec_2026_cut_yes", "values": [ "1000", "0", "0" ] }, { "position_id": "inventory_hold", "outcome_id": "out_fed_dec_2026_hold_yes", "values": [ "0", "300", "0" ] } ] } ], "whole_book": [ { "status": "EXACT", "currency": "USDC", "minimum": "0", "maximum": "1000", "minimum_witness": { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" }, "maximum_witness": { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" } } ] }, "candidates": [ { "candidate_id": "sell_250_cut", "after": { "groups": [ { "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "scenario_columns": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hold" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" } ], "currency": "USDC", "total_scenario_count": 3, "terminal_payouts": [ "750", "300", "0" ], "minimum_payout": "0", "maximum_payout": "750", "minimum_witnesses": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" } ], "maximum_witnesses": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" } ], "minimum_tie_count": 1, "maximum_tie_count": 1, "contributions": [ { "position_id": "inventory_cut", "outcome_id": "out_fed_dec_2026_cut_yes", "values": [ "750", "0", "0" ] }, { "position_id": "inventory_hold", "outcome_id": "out_fed_dec_2026_hold_yes", "values": [ "0", "300", "0" ] } ] } ], "whole_book": [ { "status": "EXACT", "currency": "USDC", "minimum": "0", "maximum": "750", "minimum_witness": { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" }, "maximum_witness": { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" } } ] }, "delta_groups": [ { "scenario_columns": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_cut" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hold" }, { "family_id": "fam_fed_dec_2026", "scenario_version": "1", "scenario_id": "scn_hike" } ], "currency": "USDC", "payout_deltas": [ "-250", "0", "0" ], "improved_count": 0, "worsened_count": 1 } ] } ], "coverage": { "complete": true, "submitted_count": 2, "supported_count": 2, "items": [ { "input_reference": "out_fed_dec_2026_cut_yes", "outcome_id": "out_fed_dec_2026_cut_yes", "status": "SUPPORTED", "family_ids": [ "fam_fed_dec_2026" ] }, { "input_reference": "out_fed_dec_2026_hold_yes", "outcome_id": "out_fed_dec_2026_hold_yes", "status": "SUPPORTED", "family_ids": [ "fam_fed_dec_2026" ] } ] }, "versions": { "market_versions": [ { "market_id": "mkt_fed_dec_2026_cut", "version": "1" }, { "market_id": "mkt_fed_dec_2026_hold", "version": "1" } ], "mapping_version": "1", "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "as_of": "2026-10-19T12:00:00Z" }, "pricing": [], "warnings": [] } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunEvaluationRequest" }, "example": { "positions": [ { "position_id": "inventory_cut", "instrument": { "outcome_id": "out_fed_dec_2026_cut_yes" }, "position_type": "HELD", "quantity": "1000" }, { "position_id": "inventory_hold", "instrument": { "outcome_id": "out_fed_dec_2026_hold_yes" }, "position_type": "HELD", "quantity": "300" } ], "candidates": [ { "candidate_id": "sell_250_cut", "trades": [ { "trade_id": "trade_cut_250", "instrument": { "outcome_id": "out_fed_dec_2026_cut_yes" }, "quantity_delta": "-250" } ] } ], "scenario_pins": [ { "family_id": "fam_fed_dec_2026", "scenario_version": "1" } ], "include": [ "SUMMARY", "PAYOUTS", "CONTRIBUTIONS", "SCENARIOS" ], "pricing": { "mode": "NONE" } } } } } } }, "/quotes": { "get": { "operationId": "getQuotes", "tags": [ "Market data" ], "summary": "Get quotes", "description": "Fetch the latest bid, ask and last-trade observations for explicitly selected Rook listing_ids. Listing IDs identify an outcome on a venue and come from /markets or /markets:resolve; a market ID alone does not select a side or venue.\n\nEvery requested listing receives a status-bearing result. Available values specify the selected outcome orientation, quote currency, payout unit, source timestamps and mapping/book revisions. A missing side, stale source or unavailable feed remains explicit rather than becoming zero. Use /orderbooks for executable depth and /price-history for recorded observations; a quote is an observation, not an execution guarantee.", "parameters": [ { "name": "listing_ids", "in": "query", "required": true, "description": "Rook listing IDs from /markets or /markets:resolve. Select the venue and outcome side explicitly; repeat the query parameter for multiple listings.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "lst_pm_fed_dec_2026_cut_yes" ] }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetQuotesResponse" }, "example": { "items": [ { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "market_id": "mkt_fed_dec_2026_cut", "outcome_id": "out_fed_dec_2026_cut_yes", "venue": "polymarket", "status": "LIVE", "quote_currency": "USDC", "payout_currency": "USDC", "payout_unit": "1", "quantity_unit": "shares", "mapping_version": "1", "quote_id": "quote_cut_120000", "book_revision": "book_1842", "best_bid": { "price": "0.40", "quantity": "1200" }, "best_ask": { "price": "0.42", "quantity": "900" }, "midpoint": "0.41", "spread": "0.02", "last_trade_price": "0.41", "last_trade_quantity": "250", "last_trade_at": "2026-10-19T11:59:52Z", "origin": "VENUE", "upstream_status": "CONNECTED", "times": { "source_timestamp": "2026-10-19T11:59:59.800Z", "received_at": "2026-10-19T11:59:59.910Z", "published_at": "2026-10-19T12:00:00Z" } } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/price-history": { "get": { "operationId": "listPriceHistory", "tags": [ "Market data" ], "summary": "Get price history", "description": "Retrieve recorded bid, ask, midpoint or last-trade prices for selected Rook listing_ids in a UTC time window. Supply start_time, end_time and field; sampling_interval optionally requests a supported sampling cadence.\n\nItems identify the listing, field, price, observation/source times, sampling method and whether a value was carried forward. Gaps remain explicit and missing observations do not become fabricated candles. Follow next_page_token with the same filters and time range to continue the snapshot. For transaction records rather than sampled prices, use /trades.", "parameters": [ { "name": "listing_ids", "in": "query", "required": true, "description": "Rook listing IDs from /markets or /markets:resolve. Select the venue and outcome side explicitly; repeat the query parameter for multiple listings.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "lst_pm_fed_dec_2026_cut_yes" ] }, { "name": "start_time", "in": "query", "required": true, "description": "UTC start of the requested observation/execution window. Must precede end_time when both are supplied.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-19T11:58:00Z" }, { "name": "end_time", "in": "query", "required": true, "description": "UTC end of the requested observation/execution window. Must follow start_time when both are supplied.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-19T12:00:00Z" }, { "name": "field", "in": "query", "required": true, "description": "Price observation to retrieve: BID, ASK, MIDPOINT or LAST_TRADE, oriented to the selected listing outcome.", "schema": { "type": "string", "enum": [ "BID", "ASK", "MIDPOINT", "LAST_TRADE" ] }, "example": "MIDPOINT" }, { "name": "sampling_interval", "in": "query", "required": false, "description": "Supported sampling cadence, such as 1m. The response reports its sampling and carry-forward method; consult coverage for available intervals.", "schema": { "type": "string" }, "example": "1m" }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPriceHistoryResponse" }, "example": { "items": [ { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "field": "MIDPOINT", "price": "0.40", "quote_currency": "USDC", "observed_at": "2026-10-19T11:58:00Z", "source_timestamp": "2026-10-19T11:58:00Z", "sampling_method": "LAST_OBSERVATION_PER_INTERVAL", "carried_forward": false, "status": "AVAILABLE" }, { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "field": "MIDPOINT", "price": "0.41", "quote_currency": "USDC", "observed_at": "2026-10-19T11:59:00Z", "source_timestamp": "2026-10-19T11:59:00Z", "sampling_method": "LAST_OBSERVATION_PER_INTERVAL", "carried_forward": false, "status": "AVAILABLE" } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/orderbooks": { "get": { "operationId": "getOrderBooks", "tags": [ "Market data" ], "summary": "Get order books", "description": "Get a level-2 bid/ask snapshot for selected Rook listing_ids. Set depth to request the maximum returned price levels per side; quantities are for the listing's selected outcome and stated quantity unit.\n\nEach result identifies its book revision, source/receipt times, returned depth and whether more depth exists. Cumulative size/notional and derived prices refer to that same revision and actual returned levels. Empty, one-sided, crossed, stale and unavailable books have distinct states. Use these snapshots to inspect liquidity; they do not reserve size or place orders.", "parameters": [ { "name": "listing_ids", "in": "query", "required": true, "description": "Rook listing IDs from /markets or /markets:resolve. Select the venue and outcome side explicitly; repeat the query parameter for multiple listings.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "lst_pm_fed_dec_2026_cut_yes" ] }, { "name": "depth", "in": "query", "required": false, "description": "Maximum price levels requested per book side. Results disclose actual returned depth and whether more levels exist.", "schema": { "type": "integer", "minimum": 1, "default": 10 }, "example": 2 }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderBooksResponse" }, "example": { "items": [ { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "venue": "polymarket", "status": "LIVE", "quote_currency": "USDC", "quantity_unit": "shares", "snapshot_id": "book_snapshot_1842", "book_revision": "book_1842", "bids": [ { "price": "0.40", "quantity": "1200", "cumulative_quantity": "1200", "cumulative_notional": "480" }, { "price": "0.39", "quantity": "800", "cumulative_quantity": "2000", "cumulative_notional": "792" } ], "asks": [ { "price": "0.42", "quantity": "900", "cumulative_quantity": "900", "cumulative_notional": "378" }, { "price": "0.43", "quantity": "600", "cumulative_quantity": "1500", "cumulative_notional": "636" } ], "returned_depth": 2, "has_more_depth": true, "depth_scope": "Top 2 levels per side; cumulative notional excludes fees.", "best_bid": { "price": "0.40", "quantity": "1200" }, "best_ask": { "price": "0.42", "quantity": "900" }, "times": { "source_timestamp": "2026-10-19T11:59:59.800Z", "received_at": "2026-10-19T11:59:59.910Z", "published_at": "2026-10-19T12:00:00Z" } } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/trades": { "get": { "operationId": "listTrades", "tags": [ "Market data" ], "summary": "List trades", "description": "Retrieve public executions for selected Rook listing_ids, optionally bounded by UTC start/end times. Choose ASC for replay or DESC for the latest records; cursor pagination preserves the filters and order.\n\nRecords contain execution price, quantity, notional, units, execution/receipt timestamps and trade identity/provenance. Correction records and source identity rules let clients reconcile repeats without inventing executions. These are venue market prints rather than authenticated private fills; use your venue or broker for account execution history.", "parameters": [ { "name": "listing_ids", "in": "query", "required": true, "description": "Rook listing IDs from /markets or /markets:resolve. Select the venue and outcome side explicitly; repeat the query parameter for multiple listings.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "lst_pm_fed_dec_2026_cut_yes" ] }, { "name": "start_time", "in": "query", "required": false, "description": "UTC start of the requested observation/execution window. Must precede end_time when both are supplied.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-19T11:59:00Z" }, { "name": "end_time", "in": "query", "required": false, "description": "UTC end of the requested observation/execution window. Must follow start_time when both are supplied.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-19T12:00:00Z" }, { "name": "order", "in": "query", "required": false, "description": "Execution-time ordering: ASC for chronological replay or DESC for most recent first. Keep unchanged during pagination.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "DESC" }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTradesResponse" }, "example": { "items": [ { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "trade_id": "trd_cut_10384", "source_trade_id": "demo-pm-trade-10384", "price": "0.41", "quantity": "250", "notional": "102.50", "quote_currency": "USDC", "aggressor": "BUY", "executed_at": "2026-10-19T11:59:52Z", "received_at": "2026-10-19T11:59:52.150Z", "record_type": "EXECUTION", "identity_method": "VENUE" } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/market-stats": { "get": { "operationId": "getMarketStats", "tags": [ "Market data" ], "summary": "Get market statistics", "description": "Measure trading activity for selected Rook listings over 1h, 24h, 7d or lifetime. The response identifies the actual window, units, currency, source and calculation method for each statistic.\n\nMarket-level values retain a scope_key so a client selecting YES and NO listings does not count the same underlying volume twice. Traded quantity, traded notional, open interest and liquidity are distinct measures; unavailable fields are explicit. Use /trades for the execution records behind activity measures and /orderbooks for current depth.", "parameters": [ { "name": "listing_ids", "in": "query", "required": true, "description": "Rook listing IDs from /markets or /markets:resolve. Select the venue and outcome side explicitly; repeat the query parameter for multiple listings.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "lst_pm_fed_dec_2026_cut_yes" ] }, { "name": "window", "in": "query", "required": true, "description": "Statistics window ending at the response observation time: 1h, 24h, 7d or lifetime.", "schema": { "type": "string", "enum": [ "1h", "24h", "7d", "lifetime" ] }, "example": "24h" }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMarketStatsResponse" }, "example": { "items": [ { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "window": "24h", "window_start": "2026-10-18T12:00:00Z", "window_end": "2026-10-19T12:00:00Z", "statistics": [ { "name": "traded_quantity", "value": "82000", "unit": "shares", "currency": null, "scope_key": "pm_demo_fed_dec_cut_market", "source": "polymarket", "method": "Sum of execution quantities in the window.", "as_of": "2026-10-19T12:00:00Z" }, { "name": "traded_notional", "value": "33620", "unit": "currency", "currency": "USDC", "scope_key": "pm_demo_fed_dec_cut_market", "source": "polymarket", "method": "Sum of price times quantity in the window.", "as_of": "2026-10-19T12:00:00Z" }, { "name": "trade_count", "value": "74", "unit": "executions", "currency": null, "scope_key": "pm_demo_fed_dec_cut_market", "source": "polymarket", "method": "Distinct execution records in the window.", "as_of": "2026-10-19T12:00:00Z" }, { "name": "vwap", "value": "0.41", "unit": "USDC per share", "currency": "USDC", "scope_key": "pm_demo_fed_dec_cut_market", "source": "polymarket", "method": "Traded notional divided by traded quantity.", "as_of": "2026-10-19T12:00:00Z" } ] } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/fee-schedules": { "get": { "operationId": "getFeeSchedules", "tags": [ "Market data" ], "summary": "Get fee schedules", "description": "Look up published venue fee rules applicable to selected Rook listings. Omit effective_at for current rules or provide a UTC timestamp for an available historical schedule.\n\nResults identify schedule/version, effective periods, currency, formula and required account inputs where known. Unsupported or unknown schedules are explicit; a missing fee is never assumed to be zero. Account tier, rebates or discounts may require information outside this API. A schedule provides evaluation context without promising a final account-specific execution cost.", "parameters": [ { "name": "listing_ids", "in": "query", "required": true, "description": "Rook listing IDs from /markets or /markets:resolve. Select the venue and outcome side explicitly; repeat the query parameter for multiple listings.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "lst_pm_fed_dec_2026_cut_yes" ] }, { "name": "effective_at", "in": "query", "required": false, "description": "UTC time at which a fee schedule must apply. Omit for the current applicable schedule; unavailable historical rules are explicit.", "schema": { "type": "string", "format": "date-time" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFeeSchedulesResponse" }, "example": { "items": [ { "listing_id": "lst_pm_fed_dec_2026_cut_yes", "status": "UNAVAILABLE", "schedule_id": null, "version": null, "currency": "USDC", "required_account_inputs": [], "reason": "No verified fee schedule is available for this illustrative listing. Fees must not be assumed to be zero." } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/fair-values:batchUpsert": { "post": { "operationId": "batchUpsertFairValues", "tags": [ "Fair values" ], "summary": "Save fair values", "description": "Future extension. Save your own outcome probabilities or expected per-unit payouts in an authorized private scope_id. Each estimate pins a Rook outcome and market version and records your source, observation time and optional expiry.\n\nThe batch is atomic: validation or revision conflicts reject the entire batch. PROBABILITY requires a value in [0,1] and an explicit FULL_PAYOUT event; EXPECTED_PAYOUT requires its payout currency. Saved records return private IDs, server revisions and timestamps. These are customer estimates, not venue prices or Rook forecasts, and marginal values do not define joint scenario probabilities.", "parameters": [ { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertFairValuesResponse" }, "example": { "items": [ { "fair_value_id": "fv_rates_cut_desk", "scope_id": "rates_desk", "outcome_id": "out_fed_dec_2026_cut_yes", "market_version": "1", "value_type": "PROBABILITY", "probability_event": "FULL_PAYOUT", "value": "0.46", "source": "rates-desk-model-v3", "observed_at": "2026-10-19T11:45:00Z", "valid_until": "2026-10-19T18:00:00Z", "updated_at": "2026-10-19T12:00:00Z", "revision": "1", "status": "CURRENT" } ], "updated_at": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed-future", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertFairValuesRequest" }, "example": { "scope_id": "rates_desk", "fair_values": [ { "outcome_id": "out_fed_dec_2026_cut_yes", "market_version": "1", "value_type": "PROBABILITY", "probability_event": "FULL_PAYOUT", "value": "0.46", "source": "rates-desk-model-v3", "observed_at": "2026-10-19T11:45:00Z", "valid_until": "2026-10-19T18:00:00Z" } ] } } } } } }, "/fair-values": { "get": { "operationId": "listFairValues", "tags": [ "Fair values" ], "summary": "List fair values", "description": "Future extension. Read your saved estimates in an authorized private scope_id. Optionally filter by outcome IDs, value type or update time; follow next_page_token with unchanged filters.\n\nEach record retains its outcome/market version, source, observation and expiry times, revision and stale/superseded status. A rule amendment does not silently transfer an estimate to new settlement terms. Estimates stay private to the authenticated customer and scope; explicitly select any values used by future analytics.", "parameters": [ { "name": "scope_id", "in": "query", "required": true, "description": "Your authorized private book or strategy namespace; access comes from the API key.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "example": "rates_desk" }, { "name": "outcome_ids", "in": "query", "required": false, "description": "Only return estimates for these Rook outcome IDs. Repeat the parameter for multiple outcomes.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "out_fed_dec_2026_cut_yes" ] }, { "name": "value_type", "in": "query", "required": false, "description": "Filter customer estimates to PROBABILITY or EXPECTED_PAYOUT; these values have different units and meanings.", "schema": { "type": "string", "enum": [ "PROBABILITY", "EXPECTED_PAYOUT" ] } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only saved estimates updated at or after this UTC timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFairValuesResponse" }, "example": { "items": [ { "fair_value_id": "fv_rates_cut_desk", "scope_id": "rates_desk", "outcome_id": "out_fed_dec_2026_cut_yes", "market_version": "1", "value_type": "PROBABILITY", "probability_event": "FULL_PAYOUT", "value": "0.46", "source": "rates-desk-model-v3", "observed_at": "2026-10-19T11:45:00Z", "valid_until": "2026-10-19T18:00:00Z", "updated_at": "2026-10-19T12:00:00Z", "revision": "1", "status": "CURRENT" } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed-future" } }, "/fair-values/{id}": { "delete": { "operationId": "deleteFairValue", "tags": [ "Fair values" ], "summary": "Delete a fair value", "description": "Future extension. Delete one private fair-value record by its Rook record ID. Authorization must grant access to its owner and scope. Supply if_revision to reject deletion if the record has changed since it was read.\n\nSuccess returns 204 with no response body. Deleting the estimate does not delete its market, modify settlement payouts or change positions.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "description": "Rook ID of the private fair-value record to delete, obtained from the save or list response.", "example": "fv_rates_cut_desk" }, { "name": "if_revision", "in": "query", "required": false, "description": "Only delete if the saved record still has this server revision; a mismatch returns a conflict.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "example": "1" }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "204": { "description": "Success.", "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed-future" } }, "/coverage": { "get": { "operationId": "getCoverage", "tags": [ "Coverage and updates" ], "summary": "Get coverage", "description": "Check whether selected Rook markets, listings or a family support the capabilities your workflow needs. Supply one selector scope, or omit selectors for the coverage overview; venue can narrow the results.\n\nResults distinguish catalog presence from analytical support and market-data availability. They disclose supported settlement conventions, history ranges, sampling intervals, freshness and service limits where applicable. A market may be known and have family membership while its payout analysis remains unsupported. Check coverage before selecting analysis inputs rather than treating missing support as a zero payout.", "parameters": [ { "name": "listing_ids", "in": "query", "required": false, "description": "Rook listing IDs from /markets or /markets:resolve. Select the venue and outcome side explicitly; repeat the query parameter for multiple listings.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true }, { "name": "market_ids", "in": "query", "required": false, "description": "Rook market IDs in this resource. On an event these reflect its source venue membership; on a family they identify the related market members.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "mkt_fed_dec_2026_cut" ] }, { "name": "family_id", "in": "query", "required": false, "description": "Rook family ID connecting related markets across original venue events. Narrows the selection to this resource.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, { "name": "venue", "in": "query", "required": false, "description": "Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": false, "description": "Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot.", "schema": { "type": "string" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCoverageResponse" }, "example": { "items": [ { "input_id": "mkt_fed_dec_2026_cut", "venue": "polymarket", "family_id": "fam_fed_dec_2026", "catalog_status": "KNOWN", "analytical_status": "SUPPORTED", "capabilities": [ "CONTRACT_DETAILS", "RELATIONSHIPS", "SCENARIOS", "PAYOUTS", "EXPOSURE", "QUOTES", "PRICE_HISTORY", "ORDERBOOKS", "TRADES" ], "supported_convention_ids": [ "demo_all_legs_win_v1" ], "history_start": "2026-10-01T00:00:00Z", "available_intervals": [ "1m", "1h" ], "observed_at": "2026-10-19T12:00:00Z" } ], "next_page_token": null, "snapshot_id": "snap_rates_20261019_120000", "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } }, "/changes": { "get": { "operationId": "listChanges", "tags": [ "Coverage and updates" ], "summary": "List changes", "description": "Follow incremental changes to markets, native mappings, families, scenario versions and coverage. Without cursor, start at the current point; persist next_cursor and pass it on the next poll. Optional family_ids and resource_types scope the feed.\n\nEach record identifies the changed resource, version, change type and occurrence time. Refresh affected reference data and explicitly revalidate cached results when settlement or mapping versions change. The feed is reference metadata rather than price ticks or account fills. Expired cursors fail explicitly and require a new snapshot; changing feed filters also requires a new cursor scope.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Continuation cursor from the previous change-feed response. Omit to start at the current point; keep filters unchanged on subsequent polls.", "schema": { "type": "string" } }, { "name": "resource_types", "in": "query", "required": false, "description": "Reference resource types to follow. These filter semantic/catalog changes, not prices or private fills.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "CONTRACT", "MAPPING", "FAMILY", "SCENARIO_VERSION", "COVERAGE" ] } }, "style": "form", "explode": true, "example": [ "SCENARIO_VERSION" ] }, { "name": "family_ids", "in": "query", "required": false, "description": "Rook family memberships for this resource, or family IDs to scope a change feed. Preserve all returned memberships.", "schema": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 1 }, "style": "form", "explode": true, "example": [ "fam_fed_dec_2026" ] }, { "name": "page_size", "in": "query", "required": false, "description": "Maximum change records per page; continue with next_cursor when has_more is true.", "schema": { "type": "integer", "minimum": 1, "default": 50 } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Caller correlation reference; not an idempotency guarantee." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChangesResponse" }, "example": { "items": [ { "change_id": "chg_rates_scenarios_v1", "resource_type": "SCENARIO_VERSION", "resource_id": "fam_fed_dec_2026", "change_type": "CREATED", "version": "1", "occurred_at": "2026-10-19T11:30:00Z", "description": "Published cut, hold and hike scenarios for the December 2026 Fed decision." } ], "next_cursor": "cursor_rates_20261019_120000", "has_more": false, "as_of": "2026-10-19T12:00:00Z" } } }, "headers": { "X-Request-Id": { "description": "Server request trace ID.", "schema": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } } } }, "x-availability": "proposed" } } }, "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "description": "Proposed server-to-server API key. No client request HMAC signing scheme is specified." } }, "schemas": { "Decimal": { "type": "string", "description": "Exact base-10 value encoded as a string; no exponent or non-finite values.", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "ExactValue": { "oneOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "object", "properties": { "numerator": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "denominator": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "required": [ "numerator", "denominator" ], "additionalProperties": false } ], "description": "Exact calculation value: finite decimal string, or reduced rational with positive denominator. Never round a repeating rational to pretend it is exact." }, "RelationType": { "type": "string", "enum": [ "EQUALITY", "COMPLEMENT", "IMPLICATION", "EXCLUSIVITY", "OVERLAP" ] }, "Evidence": { "type": "object", "properties": { "source_url": { "type": "string", "format": "uri" }, "passage": { "type": "string" }, "captured_at": { "type": "string", "format": "date-time" }, "rule_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "required": [ "source_url", "rule_version" ], "additionalProperties": true }, "ScenarioRef": { "type": "object", "properties": { "family_id": { "type": "string", "minLength": 1, "description": "Rook family ID connecting related markets across original venue events." }, "scenario_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1, "description": "Rook scenario ID within its family and published scenario version." } }, "required": [ "family_id", "scenario_version", "scenario_id" ], "additionalProperties": false }, "JointScenarioRef": { "type": "object", "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioRef" }, "minItems": 2 } }, "required": [ "components" ], "additionalProperties": false, "description": "Compatible tuple of Rook family scenario references; components have distinct family/version scopes." }, "ScenarioColumn": { "oneOf": [ { "$ref": "#/components/schemas/ScenarioRef" }, { "$ref": "#/components/schemas/JointScenarioRef" } ] }, "ScenarioPin": { "type": "object", "properties": { "family_id": { "type": "string", "minLength": 1, "description": "Rook family ID connecting related markets across original venue events." }, "scenario_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "required": [ "family_id", "scenario_version" ], "additionalProperties": false }, "InstrumentRef": { "type": "object", "properties": { "outcome_id": { "type": "string", "minLength": 1, "description": "Rook payout-side ID. YES and NO have separate IDs." }, "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." } }, "required": [], "additionalProperties": false, "description": "Supply exactly one outcome_id or listing_id; never both.", "oneOf": [ { "required": [ "outcome_id" ] }, { "required": [ "listing_id" ] } ] }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "invalid_inputs": { "type": "array", "items": { "type": "object", "properties": { "input_reference": { "type": "string" }, "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "code", "request_id" ], "additionalProperties": true }, "CoverageItem": { "type": "object", "properties": { "input_reference": { "type": "string" }, "outcome_id": { "type": "string", "minLength": 1, "description": "Rook payout-side ID. YES and NO have separate IDs." }, "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "status": { "type": "string", "enum": [ "SUPPORTED", "UNRESOLVED", "UNSUPPORTED", "STALE", "CONFLICTING" ] }, "reason_code": { "type": "string" }, "reason": { "type": "string" }, "family_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } } }, "required": [ "input_reference", "status" ], "additionalProperties": true }, "Coverage": { "type": "object", "properties": { "complete": { "type": "boolean" }, "submitted_count": { "type": "integer", "minimum": 0 }, "supported_count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageItem" } } }, "required": [ "complete", "submitted_count", "supported_count", "items" ], "additionalProperties": true }, "VersionContext": { "type": "object", "properties": { "market_versions": { "type": "array", "items": { "type": "object", "properties": { "market_id": { "type": "string", "minLength": 1, "description": "Rook canonical market ID; obtain it by resolving a venue and native market ID." }, "version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "required": [ "market_id", "version" ], "additionalProperties": false } }, "mapping_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "scenario_pins": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioPin" } }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "market_versions", "scenario_pins", "as_of" ], "additionalProperties": true }, "TradingRules": { "type": "object", "properties": { "quantity_unit": { "type": "string" }, "quote_currency": { "type": "string" }, "payout_currency": { "type": "string" }, "payout_unit": { "$ref": "#/components/schemas/ExactValue" }, "minimum_quantity": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "minimum_notional": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "quantity_increment": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "tick_bands": { "type": "array", "items": { "type": "object", "properties": { "lower_price": { "$ref": "#/components/schemas/Decimal" }, "upper_price": { "$ref": "#/components/schemas/Decimal" }, "tick_size": { "$ref": "#/components/schemas/Decimal" } }, "required": [ "lower_price", "upper_price", "tick_size" ], "additionalProperties": false } }, "fee_schedule_id": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "quantity_unit", "quote_currency", "payout_currency", "payout_unit" ], "additionalProperties": true }, "Listing": { "type": "object", "properties": { "listing_id": { "type": "string", "description": "Rook ID identifying one outcome listing on a particular venue.", "minLength": 1 }, "venue": { "type": "string", "description": "Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID." }, "venue_market_id": { "type": "string", "description": "Original venue market ID. For Polymarket this is its numeric Gamma market ID, encoded as decimal text. It is not an event, condition or CLOB token ID.", "minLength": 1 }, "venue_outcome_id": { "type": "string", "description": "Original outcome selector on the venue, such as YES or NO. Selects a side within the native market; distinct from a Rook outcome_id.", "minLength": 1 }, "token_id": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "outcome_id": { "type": "string", "description": "Rook outcome ID identifying one payout side, such as YES or NO.", "minLength": 1 }, "mapping_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "status": { "type": "string", "enum": [ "OPEN", "HALTED", "CLOSED", "DISPUTED", "RESOLVED", "UNKNOWN" ], "description": "Filter by the resource lifecycle status. This does not indicate analytical coverage or feed freshness." }, "ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "venue_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "trading_rules": { "$ref": "#/components/schemas/TradingRules" }, "listed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "opens_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closes_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "source_updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "observed_at": { "type": "string", "format": "date-time" }, "venue_event_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "description": "Original venue event ID. For Polymarket this is its numeric Gamma event ID, encoded as decimal text. It is not a market ID." }, "description": "Original event IDs reported by this listing\u2019s venue. Preserved per listing so canonicalization cannot erase source event membership." } }, "required": [ "listing_id", "venue", "venue_market_id", "venue_event_ids", "venue_outcome_id", "outcome_id", "mapping_version", "status", "trading_rules", "observed_at" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "venue": { "const": "polymarket" } }, "required": [ "venue" ] }, "then": { "properties": { "venue_market_id": { "pattern": "^[0-9]+$" }, "venue_event_ids": { "items": { "pattern": "^[0-9]+$" } } } } } ] }, "Outcome": { "type": "object", "properties": { "outcome_id": { "type": "string", "description": "Rook outcome ID identifying one payout side, such as YES or NO.", "minLength": 1 }, "label": { "type": "string" }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } } }, "required": [ "outcome_id", "label", "listings" ], "additionalProperties": true }, "Market": { "type": "object", "properties": { "market_id": { "type": "string", "description": "Rook canonical market ID. Resolve a venue_market_id first; related markets do not share an ID merely because they share a family.", "minLength": 1 }, "version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": "string" }, "event_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "description": "Rook IDs of the original venue events containing these markets or listings. Family membership never rewrites event membership." }, "family_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "description": "Rook family memberships for this resource, or family IDs to scope a change feed. Preserve all returned memberships." }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact category label used by the catalog, for example rates. Narrows search results." }, "tags": { "type": "array", "items": { "type": "string" } }, "image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "settlement_summary": { "type": "string" }, "payout_conditions": { "type": "array", "items": { "type": "string" } }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/Outcome" }, "minItems": 1 }, "is_combo": { "type": "boolean" }, "analytical_only": { "type": "boolean" }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentRef" } }, "settlement_convention_id": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ], "description": "Supported venue/product settlement convention for Combo interpretation." }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" } }, "observed_at": { "type": "string", "format": "date-time" } }, "required": [ "market_id", "version", "title", "event_ids", "family_ids", "settlement_summary", "payout_conditions", "outcomes", "is_combo", "analytical_only", "observed_at" ], "additionalProperties": true }, "Event": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate.", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact category label used by the catalog, for example rates. Narrows search results." }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "RESOLVED", "UNKNOWN" ], "description": "Filter by the resource lifecycle status. This does not indicate analytical coverage or feed freshness." }, "market_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "description": "Rook market IDs in this resource. On an event these reflect its source venue membership; on a family they identify the related market members." }, "family_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "description": "Rook family memberships for this resource, or family IDs to scope a change feed. Preserve all returned memberships." }, "starts_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expected_settlement_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "observed_at": { "type": "string", "format": "date-time" }, "venue": { "type": "string", "minLength": 1, "description": "Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID.", "example": "polymarket" }, "venue_event_id": { "type": "string", "minLength": 1, "description": "Original venue event ID. For Polymarket this is its numeric Gamma event ID, encoded as decimal text. It is not a market ID.", "example": "900001" } }, "required": [ "event_id", "title", "status", "market_ids", "family_ids", "observed_at", "venue", "venue_event_id" ], "additionalProperties": true, "description": "One original venue event, wrapped with a Rook ID and family references. The pair (venue, venue_event_id) defines source identity. Rook preserves the source title and market grouping; it never synthesizes or merges events to represent related markets.", "allOf": [ { "if": { "properties": { "venue": { "const": "polymarket" } }, "required": [ "venue" ] }, "then": { "properties": { "venue_event_id": { "pattern": "^[0-9]+$" } } } } ] }, "Family": { "type": "object", "properties": { "family_id": { "type": "string", "description": "Rook family ID connecting related markets across original venue events.", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": "string" }, "market_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "description": "Rook market IDs in this resource. On an event these reflect its source venue membership; on a family they identify the related market members." }, "current_scenario_version": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "scenario_versions": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "supported_convention_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "analytical_coverage": { "type": "string", "enum": [ "COMPLETE", "PARTIAL", "UNAVAILABLE" ] }, "observed_at": { "type": "string", "format": "date-time" }, "event_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "description": "Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate." }, "description": "Rook IDs of the original venue events containing these markets or listings. Family membership never rewrites event membership." } }, "required": [ "family_id", "title", "event_ids", "market_ids", "current_scenario_version", "scenario_versions", "analytical_coverage", "observed_at" ], "additionalProperties": true, "description": "Rook grouping above original venue events and their related markets. event_ids and market_ids expose membership; analytical_coverage separately reports support. Source events remain unchanged and resources may carry several family references." }, "Scenario": { "type": "object", "properties": { "reference": { "$ref": "#/components/schemas/ScenarioRef" }, "label": { "type": "string" }, "description": { "type": "string" }, "representation": { "type": "string" }, "represented_state_count": { "type": "integer", "minimum": 0 } }, "required": [ "reference", "label", "description", "representation", "represented_state_count" ], "additionalProperties": true, "description": "Human-readable settlement scenario; no internal variables, predicates or AST." }, "Relationship": { "type": "object", "properties": { "relationship_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "type": { "$ref": "#/components/schemas/RelationType" }, "from_outcome_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "to_outcome_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "related_market_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "related_event_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "explanation": { "type": "string" }, "scenario_pins": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioPin" } }, "witnesses": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" } } }, "required": [ "relationship_id", "type", "from_outcome_id", "to_outcome_id", "explanation", "scenario_pins", "witnesses" ], "additionalProperties": true }, "ResolveInput": { "type": "object", "properties": { "client_reference": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "venue": { "type": "string", "description": "Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID." }, "venue_market_id": { "type": "string", "description": "Original venue market ID. For Polymarket this is its numeric Gamma market ID, encoded as decimal text. It is not an event, condition or CLOB token ID.", "minLength": 1 }, "venue_outcome_id": { "type": "string", "description": "Original outcome selector on the venue, such as YES or NO. Selects a side within the native market; distinct from a Rook outcome_id.", "minLength": 1 }, "token_id": { "type": "string", "description": "Native outcome token ID. Polymarket CLOB token IDs are large decimal strings and must never pass through a floating-point number.", "minLength": 1 }, "ticker": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "client_reference", "venue" ], "additionalProperties": false, "description": "Supply venue and at least one exact native identity form. A venue_market_id alone resolves the whole market; add venue_outcome_id to select a side. Token, ticker+outcome and slug+outcome forms select an individual listing. If multiple forms are provided they must identify the same source record or fail validation. Unknown/ambiguous mappings are not guessed. Event IDs belong in /events?venue=...&venue_event_id=..., never venue_market_id.", "anyOf": [ { "required": [ "venue_market_id" ] }, { "required": [ "token_id" ] }, { "required": [ "ticker", "venue_outcome_id" ] }, { "required": [ "slug", "venue_outcome_id" ] } ], "allOf": [ { "if": { "properties": { "venue": { "const": "polymarket" } }, "required": [ "venue" ] }, "then": { "properties": { "venue_market_id": { "pattern": "^[0-9]+$" } } } } ] }, "ResolveMarketsRequest": { "type": "object", "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/ResolveInput" }, "minItems": 1, "description": "One or more native identifier tuples; unique client_reference per tuple. Each returns a status-bearing mapping result." } }, "required": [ "inputs" ], "additionalProperties": false }, "ResolvedInput": { "type": "object", "properties": { "client_reference": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "status": { "type": "string", "enum": [ "RESOLVED", "UNRESOLVED", "AMBIGUOUS" ], "description": "Filter by the resource lifecycle status. This does not indicate analytical coverage or feed freshness." }, "market_id": { "type": "string", "description": "Rook canonical market ID. Resolve a venue_market_id first; related markets do not share an ID merely because they share a family.", "minLength": 1 }, "market_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "outcome_id": { "type": "string", "description": "Rook outcome ID identifying one payout side, such as YES or NO.", "minLength": 1 }, "listing_id": { "type": "string", "description": "Rook ID identifying one outcome listing on a particular venue.", "minLength": 1 }, "mapping_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "reason_code": { "type": "string" }, "reason": { "type": "string" }, "input": { "$ref": "#/components/schemas/ResolveInput", "description": "Original native selector echoed unchanged." }, "event_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "description": "Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate." }, "description": "Rook IDs of the original venue events containing these markets or listings. Family membership never rewrites event membership." }, "family_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "description": "Rook family ID connecting related markets across original venue events." }, "description": "Rook family memberships for this resource, or family IDs to scope a change feed. Preserve all returned memberships." }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } } }, "required": [ "client_reference", "status", "input" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "status": { "const": "RESOLVED" } } }, "then": { "required": [ "market_id", "market_version", "event_ids", "family_ids", "outcomes" ] }, "else": { "required": [ "reason_code", "reason" ] } }, { "if": { "properties": { "status": { "const": "RESOLVED" }, "input": { "anyOf": [ { "required": [ "venue_outcome_id" ] }, { "required": [ "token_id" ] } ] } }, "required": [ "status", "input" ] }, "then": { "required": [ "outcome_id", "listing_id", "mapping_version" ] } } ] }, "ResolveMarketsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedInput" } }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "as_of" ], "additionalProperties": true }, "ComposeMarketRequest": { "type": "object", "properties": { "client_reference": { "type": "string", "description": "Caller correlation reference for this requested analytical Combo." }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentRef" }, "minItems": 2, "description": "At least two explicitly selected outcome/listing references; retained in the interpreted market." }, "venue": { "type": "string", "description": "Venue whose supported product settlement convention applies; not an order destination." }, "settlement_convention_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "scenario_pins": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioPin" }, "description": "Optional family/version pins for reproducible interpretation; otherwise current compatible versions are selected once." } }, "required": [ "legs", "venue", "settlement_convention_id" ], "additionalProperties": false }, "ComposeMarketResponse": { "type": "object", "properties": { "market": { "$ref": "#/components/schemas/Market" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "versions": { "$ref": "#/components/schemas/VersionContext" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "explanation": { "type": "string" }, "leg_indices": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "witnesses": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } } }, "required": [ "code", "explanation" ], "additionalProperties": false } } }, "required": [ "market", "coverage", "versions", "findings" ], "additionalProperties": true }, "AnalyzeRelationshipsRequest": { "type": "object", "properties": { "selection": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentRef" }, "minItems": 1, "description": "Explicit supplied outcome/listing references; resolved canonical outcomes are deduplicated for set statistics." }, "scenario_pins": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioPin" }, "description": "Optional explicit family/version pins; returned even when selected automatically." }, "paying_definition": { "type": "string", "enum": [ "POSITIVE_PAYOUT", "FULL_PAYOUT" ], "description": "POSITIVE_PAYOUT by default; FULL_PAYOUT distinguishes fractional settlements.", "default": "POSITIVE_PAYOUT" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "PAIRS", "BASKET", "WITNESSES", "EVIDENCE" ] }, "description": "Requested outputs; default PAIRS, BASKET and WITNESSES.", "default": [ "PAIRS", "BASKET", "WITNESSES" ] }, "witness_limit": { "type": "integer", "minimum": 0, "default": 5, "description": "Maximum example witnesses per finding; never limits the domain used to establish the finding." }, "require_complete_coverage": { "type": "boolean", "default": true, "description": "True rejects incomplete selected-set scope; false explicitly labels analysis of the supported subset." } }, "required": [ "selection" ], "additionalProperties": false }, "BasketSummary": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "PARTITION", "EXCLUSIVE", "EXHAUSTIVE", "OVERLAPPING", "UNCOMPUTED" ] }, "outcome_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "scenario_count": { "type": "integer", "minimum": 0 }, "representation": { "type": "string" }, "paying_definition": { "type": "string", "enum": [ "POSITIVE_PAYOUT", "FULL_PAYOUT" ] }, "gap_witnesses": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "overlap_witnesses": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "scenario_pins": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioPin" } }, "selected_outcome_count": { "type": "integer", "minimum": 0 }, "paying_counts": { "type": "object", "properties": { "none": { "type": "integer", "minimum": 0 }, "exactly_one": { "type": "integer", "minimum": 0 }, "two_or_more": { "type": "integer", "minimum": 0 }, "exact_k": { "type": "array", "items": { "type": "object", "properties": { "paying_count": { "type": "integer", "minimum": 0 }, "scenario_count": { "type": "integer", "minimum": 0 } }, "required": [ "paying_count", "scenario_count" ], "additionalProperties": false } } }, "required": [ "none", "exactly_one", "two_or_more" ], "additionalProperties": false } }, "required": [ "classification", "outcome_ids", "scenario_count", "representation", "paying_definition", "scenario_pins", "selected_outcome_count", "paying_counts" ], "additionalProperties": true }, "AnalyzeRelationshipsResponse": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/Relationship" } }, "baskets": { "type": "array", "items": { "$ref": "#/components/schemas/BasketSummary" } }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "versions": { "$ref": "#/components/schemas/VersionContext" } }, "required": [ "relationships", "baskets", "coverage", "versions" ], "additionalProperties": true }, "CalculatePayoutsRequest": { "type": "object", "properties": { "selection": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentRef" }, "minItems": 1, "description": "One or more explicitly selected outcome/listing references; no rows for unrequested instruments." }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" }, "minItems": 1, "description": "Optional single-family references or compatible cross-family tuples selecting columns; omit for all applicable columns." }, "scenario_pins": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioPin" }, "description": "Optional immutable family/version pins; must agree with explicit scenario references." }, "require_complete_coverage": { "type": "boolean", "default": true, "description": "True rejects missing selected payout interpretations; false returns scoped coverage and supported rows." }, "page_size": { "type": "integer", "minimum": 1, "default": 50, "description": "Requested maximum scenario columns per page; proposed default 50, subject to disclosed service bound." }, "page_token": { "type": "string", "description": "Continuation bound to the same selection, filters and pinned versions; no input changes between pages." } }, "required": [ "selection" ], "additionalProperties": false }, "PayoutRow": { "type": "object", "properties": { "outcome_id": { "type": "string", "minLength": 1, "description": "Rook payout-side ID. YES and NO have separate IDs." }, "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "payout_currency": { "type": "string" }, "payout_unit": { "$ref": "#/components/schemas/ExactValue" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/ExactValue" } } }, "required": [ "outcome_id", "payout_currency", "payout_unit", "values" ], "additionalProperties": true }, "PayoutMatrix": { "type": "object", "properties": { "scenario_columns": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutRow" } }, "total_column_count": { "type": "integer", "minimum": 0 }, "representation": { "type": "string" } }, "required": [ "scenario_columns", "rows", "total_column_count", "representation" ], "additionalProperties": true, "description": "Rows are supplied outcomes; values align to the ordered scenario_columns. Separate compatible currency/scenario groups; no global index across groups." }, "CalculatePayoutsResponse": { "type": "object", "properties": { "matrices": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutMatrix" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "versions": { "$ref": "#/components/schemas/VersionContext" } }, "required": [ "matrices", "next_page_token", "coverage", "versions" ], "additionalProperties": true }, "Position": { "type": "object", "properties": { "position_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "instrument": { "$ref": "#/components/schemas/InstrumentRef" }, "position_type": { "type": "string", "enum": [ "HELD", "OWED" ] }, "quantity": { "$ref": "#/components/schemas/Decimal" } }, "required": [ "position_id", "instrument", "position_type", "quantity" ], "additionalProperties": false, "description": "Quantity must be strictly positive; position_type determines receipt versus obligation. No entry-price or RFQ quote inputs in the initial service." }, "CandidateTrade": { "type": "object", "properties": { "trade_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "instrument": { "$ref": "#/components/schemas/InstrumentRef" }, "quantity_delta": { "$ref": "#/components/schemas/Decimal" } }, "required": [ "trade_id", "instrument", "quantity_delta" ], "additionalProperties": false, "description": "Nonzero signed delta in desk payout units: positive acquires/increases a claim; negative decreases/writes an obligation under the stated convention. Does not assert execution eligibility." }, "Candidate": { "type": "object", "properties": { "candidate_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "trades": { "type": "array", "items": { "$ref": "#/components/schemas/CandidateTrade" }, "minItems": 1 } }, "required": [ "candidate_id", "trades" ], "additionalProperties": false, "description": "A simultaneous trade package; distinct candidates are independent alternatives against the same baseline." }, "RankingRequest": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "TERMINAL_PAYOUT", "MARK_TO_SETTLEMENT" ] }, "direction": { "type": "string", "enum": [ "ASC", "DESC" ] }, "limit": { "type": "integer", "minimum": 1, "default": 10 } }, "required": [ "metric", "direction" ], "additionalProperties": false }, "PricingRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "NONE", "MIDPOINT", "LIQUIDATION" ], "default": "NONE" }, "max_quote_age_ms": { "type": "integer", "minimum": 0 } }, "required": [ "mode" ], "additionalProperties": false, "description": "Prices come from Rook. LIQUIDATION uses available bid/ask depth; incomplete execution-side coverage is disclosed, never assumed filled." }, "RunEvaluationRequest": { "type": "object", "properties": { "positions": { "type": "array", "items": { "$ref": "#/components/schemas/Position" }, "description": "Current client positions with HELD/OWED convention and positive exact quantities; may be empty for standalone candidates." }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" }, "description": "Optional independently evaluated alternatives; trades inside each candidate form one simultaneous package." }, "scenario_pins": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioPin" }, "description": "Optional family/version pins for the supplied book plus all candidates; current compatible versions chosen once otherwise." }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" }, "minItems": 1, "description": "Optional selected column references; conditions results on exactly that scenario domain." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "SUMMARY", "PAYOUTS", "CONTRIBUTIONS", "OFFSETS", "SCENARIOS" ] }, "description": "Requested result detail; default SUMMARY. Full vectors must fit declared scope or fail explicitly.", "default": [ "SUMMARY" ] }, "ranking": { "$ref": "#/components/schemas/RankingRequest", "description": "Metric, direction and positive result limit; ranks the whole stated domain before limiting returned results." }, "pricing": { "$ref": "#/components/schemas/PricingRequest", "description": "Rook price convention and optional maximum quote age; default mode NONE means payout-only." }, "require_complete_coverage": { "type": "boolean", "default": true, "description": "True rejects incomplete structural coverage; false preserves explicitly scoped partial results." } }, "required": [ "positions" ], "additionalProperties": false, "description": "At least one position or candidate is required. Empty positions is valid for standalone candidate analysis. All supplied holdings and candidates use a common comparison scope; selected scenarios condition the result.", "anyOf": [ { "properties": { "positions": { "minItems": 1 } } }, { "required": [ "candidates" ], "properties": { "candidates": { "minItems": 1 } } } ] }, "RankedOutcome": { "type": "object", "properties": { "scenario": { "$ref": "#/components/schemas/ScenarioColumn" }, "terminal_payout": { "$ref": "#/components/schemas/ExactValue" }, "mark_to_settlement": { "anyOf": [ { "$ref": "#/components/schemas/ExactValue" }, { "type": "null" } ] } }, "required": [ "scenario", "terminal_payout" ], "additionalProperties": true }, "Contribution": { "type": "object", "properties": { "position_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "outcome_id": { "type": "string", "minLength": 1, "description": "Rook payout-side ID. YES and NO have separate IDs." }, "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/ExactValue" } } }, "required": [ "position_id", "outcome_id", "values" ], "additionalProperties": true }, "OffsetFinding": { "type": "object", "properties": { "position_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "minItems": 2 }, "classification": { "type": "string", "enum": [ "EXACT", "PARTIAL", "CONDITIONAL", "NONE" ] }, "residual_range": { "$ref": "#/components/schemas/ExactValue" }, "explanation": { "type": "string" }, "failure_scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "heuristic_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "position_ids", "classification", "residual_range", "explanation", "failure_scenarios" ], "additionalProperties": true, "description": "Exact identities and heuristic rankings are labeled separately; no independent universe search." }, "ExposureGroup": { "type": "object", "properties": { "scenario_columns": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "scenario_pins": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioPin" } }, "currency": { "type": "string" }, "total_scenario_count": { "type": "integer", "minimum": 0 }, "terminal_payouts": { "type": "array", "items": { "$ref": "#/components/schemas/ExactValue" } }, "minimum_payout": { "$ref": "#/components/schemas/ExactValue" }, "maximum_payout": { "$ref": "#/components/schemas/ExactValue" }, "minimum_witnesses": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "maximum_witnesses": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "minimum_tie_count": { "type": "integer", "minimum": 0 }, "maximum_tie_count": { "type": "integer", "minimum": 0 }, "ranked_outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/RankedOutcome" } }, "contributions": { "type": "array", "items": { "$ref": "#/components/schemas/Contribution" } }, "offsets": { "type": "array", "items": { "$ref": "#/components/schemas/OffsetFinding" } } }, "required": [ "scenario_pins", "currency", "total_scenario_count", "minimum_payout", "maximum_payout", "minimum_witnesses", "maximum_witnesses", "minimum_tie_count", "maximum_tie_count" ], "additionalProperties": true }, "WholeBookExtreme": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "EXACT", "BOUND", "UNAVAILABLE" ] }, "currency": { "type": "string" }, "minimum": { "anyOf": [ { "$ref": "#/components/schemas/ExactValue" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "$ref": "#/components/schemas/ExactValue" }, { "type": "null" } ] }, "minimum_witness": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioColumn" }, { "type": "null" } ] }, "maximum_witness": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioColumn" }, { "type": "null" } ] }, "reason": { "type": "string" } }, "required": [ "status", "currency", "minimum", "maximum" ], "additionalProperties": true }, "BookResult": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/ExposureGroup" } }, "whole_book": { "type": "array", "items": { "$ref": "#/components/schemas/WholeBookExtreme" } } }, "required": [ "groups", "whole_book" ], "additionalProperties": true }, "CandidateResult": { "type": "object", "properties": { "candidate_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "after": { "$ref": "#/components/schemas/BookResult" }, "delta_groups": { "type": "array", "items": { "type": "object", "properties": { "scenario_columns": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioColumn" } }, "currency": { "type": "string" }, "payout_deltas": { "type": "array", "items": { "$ref": "#/components/schemas/ExactValue" } }, "improved_count": { "type": "integer", "minimum": 0 }, "worsened_count": { "type": "integer", "minimum": 0 } }, "required": [ "currency", "improved_count", "worsened_count" ], "additionalProperties": false } } }, "required": [ "candidate_id", "after", "delta_groups" ], "additionalProperties": true }, "PricingObservation": { "type": "object", "properties": { "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "quote_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "status": { "type": "string", "enum": [ "AVAILABLE", "STALE", "INCOMPLETE", "UNAVAILABLE" ] }, "price": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "currency": { "type": "string" }, "source_timestamp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "received_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "fee_status": { "type": "string", "enum": [ "KNOWN", "PARTIAL", "UNKNOWN" ] } }, "required": [ "listing_id", "status", "price", "currency", "source_timestamp", "received_at", "fee_status" ], "additionalProperties": true }, "RunEvaluationResponse": { "type": "object", "properties": { "evaluation_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "baseline": { "$ref": "#/components/schemas/BookResult" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/CandidateResult" } }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "versions": { "$ref": "#/components/schemas/VersionContext" }, "pricing": { "type": "array", "items": { "$ref": "#/components/schemas/PricingObservation" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "evaluation_id", "baseline", "candidates", "coverage", "versions", "pricing", "warnings" ], "additionalProperties": true, "description": "Trace ID does not imply a saved portfolio or GET-able evaluation. Full-scope extrema are not calculated from a truncated response page." }, "Level": { "type": "object", "properties": { "price": { "$ref": "#/components/schemas/Decimal" }, "quantity": { "$ref": "#/components/schemas/Decimal" }, "cumulative_quantity": { "$ref": "#/components/schemas/Decimal" }, "cumulative_notional": { "$ref": "#/components/schemas/Decimal" } }, "required": [ "price", "quantity" ], "additionalProperties": true }, "DataTimes": { "type": "object", "properties": { "source_timestamp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "received_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "source_timestamp", "received_at", "published_at" ], "additionalProperties": true }, "Quote": { "type": "object", "properties": { "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "market_id": { "type": "string", "minLength": 1, "description": "Rook canonical market ID; obtain it by resolving a venue and native market ID." }, "outcome_id": { "type": "string", "minLength": 1, "description": "Rook payout-side ID. YES and NO have separate IDs." }, "venue": { "type": "string" }, "status": { "type": "string", "enum": [ "LIVE", "STALE", "EMPTY", "ONE_SIDED", "CROSSED", "UNAVAILABLE" ] }, "quote_currency": { "type": "string" }, "quantity_unit": { "type": "string" }, "quote_id": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "book_revision": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "best_bid": { "anyOf": [ { "$ref": "#/components/schemas/Level" }, { "type": "null" } ] }, "best_ask": { "anyOf": [ { "$ref": "#/components/schemas/Level" }, { "type": "null" } ] }, "midpoint": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "spread": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "last_trade_price": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "last_trade_quantity": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "last_trade_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "origin": { "type": "string", "enum": [ "VENUE", "DERIVED" ] }, "derivation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "times": { "$ref": "#/components/schemas/DataTimes" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payout_currency": { "type": [ "string", "null" ] }, "payout_unit": { "anyOf": [ { "$ref": "#/components/schemas/ExactValue" }, { "type": "null" } ] }, "mapping_version": { "type": [ "string", "null" ] }, "spread_bps": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "upstream_status": { "type": "string", "enum": [ "CONNECTED", "DISCONNECTED", "UNKNOWN" ] } }, "required": [ "listing_id", "status", "best_bid", "best_ask", "midpoint", "spread", "times" ], "additionalProperties": true }, "OrderBook": { "type": "object", "properties": { "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "venue": { "type": "string" }, "status": { "type": "string", "enum": [ "LIVE", "STALE", "EMPTY", "UNAVAILABLE" ] }, "quote_currency": { "type": "string" }, "quantity_unit": { "type": "string" }, "snapshot_id": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "book_revision": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "bids": { "type": "array", "items": { "$ref": "#/components/schemas/Level" } }, "asks": { "type": "array", "items": { "$ref": "#/components/schemas/Level" } }, "returned_depth": { "type": "integer", "minimum": 0 }, "has_more_depth": { "type": "boolean" }, "depth_scope": { "type": "string" }, "times": { "$ref": "#/components/schemas/DataTimes" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "best_bid": { "anyOf": [ { "$ref": "#/components/schemas/Level" }, { "type": "null" } ] }, "best_ask": { "anyOf": [ { "$ref": "#/components/schemas/Level" }, { "type": "null" } ] } }, "required": [ "listing_id", "status", "bids", "asks", "returned_depth", "has_more_depth", "depth_scope", "times" ], "additionalProperties": true }, "PriceObservation": { "type": "object", "properties": { "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "field": { "type": "string", "enum": [ "BID", "ASK", "MIDPOINT", "LAST_TRADE" ] }, "price": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "quote_currency": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "source_timestamp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sampling_method": { "type": "string" }, "carried_forward": { "type": "boolean" }, "status": { "type": "string", "enum": [ "AVAILABLE", "MISSING", "STALE" ] } }, "required": [ "listing_id", "field", "price", "observed_at", "source_timestamp", "sampling_method", "carried_forward", "status" ], "additionalProperties": true }, "Trade": { "type": "object", "properties": { "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "trade_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "source_trade_id": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "price": { "$ref": "#/components/schemas/Decimal" }, "quantity": { "$ref": "#/components/schemas/Decimal" }, "notional": { "$ref": "#/components/schemas/Decimal" }, "quote_currency": { "type": "string" }, "aggressor": { "anyOf": [ { "type": "string", "enum": [ "BUY", "SELL" ] }, { "type": "null" } ] }, "executed_at": { "type": "string", "format": "date-time" }, "received_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "record_type": { "type": "string", "enum": [ "EXECUTION", "CORRECTION", "CANCELLATION" ] }, "corrects_trade_id": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "identity_method": { "type": "string", "enum": [ "VENUE", "DERIVED" ] } }, "required": [ "listing_id", "trade_id", "source_trade_id", "price", "quantity", "quote_currency", "executed_at", "record_type", "identity_method" ], "additionalProperties": true }, "Statistic": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "unit": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_key": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "source": { "type": "string" }, "method": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "value", "unit", "scope_key", "source", "method", "as_of" ], "additionalProperties": true }, "MarketStats": { "type": "object", "properties": { "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "window": { "type": "string" }, "window_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "window_end": { "type": "string", "format": "date-time" }, "statistics": { "type": "array", "items": { "$ref": "#/components/schemas/Statistic" } } }, "required": [ "listing_id", "window", "window_start", "window_end", "statistics" ], "additionalProperties": true }, "FeeSchedule": { "type": "object", "properties": { "listing_id": { "type": "string", "minLength": 1, "description": "Rook ID for one outcome listing on one venue; preserves venue provenance." }, "schedule_id": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "version": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "KNOWN", "ACCOUNT_DEPENDENT", "UNAVAILABLE" ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maker_formula": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taker_formula": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "$ref": "#/components/schemas/Decimal" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "rounding": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "cap": { "anyOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ] }, "effective_from": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "effective_until": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "required_account_inputs": { "type": "array", "items": { "type": "string" } }, "source_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "listing_id", "status", "schedule_id", "version", "required_account_inputs" ], "additionalProperties": true }, "FairValueInput": { "type": "object", "properties": { "outcome_id": { "type": "string", "minLength": 1, "description": "Rook payout-side ID. YES and NO have separate IDs." }, "market_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "value_type": { "type": "string", "enum": [ "PROBABILITY", "EXPECTED_PAYOUT" ] }, "probability_event": { "type": "string", "enum": [ "FULL_PAYOUT" ] }, "value": { "$ref": "#/components/schemas/Decimal" }, "currency": { "type": "string" }, "source": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "if_revision": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "required": [ "outcome_id", "market_version", "value_type", "value", "source", "observed_at" ], "additionalProperties": false, "description": "Probability: 0<=value<=1 and probability_event required. Expected payout: matching payout currency required. Conditional checks and numerical decimal comparison are server validation rules.", "allOf": [ { "if": { "properties": { "value_type": { "const": "PROBABILITY" } } }, "then": { "required": [ "probability_event" ] } }, { "if": { "properties": { "value_type": { "const": "EXPECTED_PAYOUT" } } }, "then": { "required": [ "currency" ] } } ] }, "BatchUpsertFairValuesRequest": { "type": "object", "properties": { "scope_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "fair_values": { "type": "array", "items": { "$ref": "#/components/schemas/FairValueInput" }, "minItems": 1, "description": "Nonempty batch of explicit outcome estimates; all validations and revision preconditions pass before any write." } }, "required": [ "scope_id", "fair_values" ], "additionalProperties": false }, "FairValue": { "type": "object", "properties": { "fair_value_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "scope_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "outcome_id": { "type": "string", "minLength": 1, "description": "Rook payout-side ID. YES and NO have separate IDs." }, "market_version": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "value_type": { "type": "string", "enum": [ "PROBABILITY", "EXPECTED_PAYOUT" ] }, "probability_event": { "anyOf": [ { "type": "string", "enum": [ "FULL_PAYOUT" ] }, { "type": "null" } ] }, "value": { "$ref": "#/components/schemas/Decimal" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "valid_until": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "type": "string", "format": "date-time" }, "revision": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "status": { "type": "string", "enum": [ "CURRENT", "EXPIRED", "SUPERSEDED" ] } }, "required": [ "fair_value_id", "scope_id", "outcome_id", "market_version", "value_type", "value", "source", "observed_at", "updated_at", "revision", "status" ], "additionalProperties": true }, "BatchUpsertFairValuesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FairValue" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "items", "updated_at" ], "additionalProperties": true }, "CoverageRecord": { "type": "object", "properties": { "input_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "venue": { "type": "string" }, "family_id": { "type": "string", "minLength": 1, "description": "Rook family ID connecting related markets across original venue events." }, "catalog_status": { "type": "string", "enum": [ "KNOWN", "UNKNOWN" ] }, "analytical_status": { "type": "string", "enum": [ "SUPPORTED", "PARTIAL", "UNSUPPORTED" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "supported_convention_ids": { "type": "array", "items": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 } }, "history_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "available_intervals": { "type": "array", "items": { "type": "string" } }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "observed_at": { "type": "string", "format": "date-time" } }, "required": [ "input_id", "catalog_status", "analytical_status", "capabilities", "observed_at" ], "additionalProperties": true }, "Change": { "type": "object", "properties": { "change_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "resource_type": { "type": "string", "enum": [ "CONTRACT", "MAPPING", "FAMILY", "SCENARIO_VERSION", "COVERAGE" ] }, "resource_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "change_type": { "type": "string", "enum": [ "CREATED", "UPDATED", "SUPERSEDED", "REVOKED" ] }, "version": { "anyOf": [ { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, { "type": "null" } ] }, "occurred_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" } }, "required": [ "change_id", "resource_type", "resource_id", "change_type", "occurred_at" ], "additionalProperties": true }, "ListEventsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "ListMarketsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Market" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "ListFamiliesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Family" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "ListScenariosResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Scenario" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "ListRelationshipsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Relationship" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "GetQuotesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "next_page_token": { "type": "null", "description": "All requested IDs are accounted for in one bounded batch; no silent truncation." }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "ListPriceHistoryResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PriceObservation" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "GetOrderBooksResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderBook" } }, "next_page_token": { "type": "null", "description": "All requested IDs are accounted for in one bounded batch; no silent truncation." }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "ListTradesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "GetMarketStatsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MarketStats" } }, "next_page_token": { "type": "null", "description": "All requested IDs are accounted for in one bounded batch; no silent truncation." }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "GetFeeSchedulesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FeeSchedule" } }, "next_page_token": { "type": "null", "description": "All requested IDs are accounted for in one bounded batch; no silent truncation." }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "ListFairValuesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FairValue" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "GetCoverageResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageRecord" } }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshot_id": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_page_token", "snapshot_id", "as_of" ], "additionalProperties": true }, "ListChangesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "next_cursor": { "type": "string", "description": "Opaque text identifier. Preserve its exact value.", "minLength": 1 }, "has_more": { "type": "boolean" }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_cursor", "has_more", "as_of" ], "additionalProperties": true } } } }