> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rook.pm/llms.txt
> Use this file to discover all available pages before exploring further.

# Compose a Combo

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

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

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

See the [integration guide](/guides/combos) for the workflow and interpretation of this response.


## OpenAPI

````yaml POST /markets:compose
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.
security:
  - ApiKeyBearer: []
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.
paths:
  /markets:compose:
    post:
      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.


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


        Use 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.
      operationId: composeMarket
      parameters:
        - name: X-Client-Request-Id
          in: header
          required: false
          schema:
            type: string
          description: Caller correlation reference; not an idempotency guarantee.
      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'
      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’s 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
components:
  schemas:
    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
    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
    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
    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
    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
    ScenarioColumn:
      oneOf:
        - $ref: '#/components/schemas/ScenarioRef'
        - $ref: '#/components/schemas/JointScenarioRef'
    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
    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
    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
    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.
    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’s 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]+$
    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
    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.
    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]+)?$
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: >-
        Proposed server-to-server API key. No client request HMAC signing scheme
        is specified.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.