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

# Calculate payouts

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

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

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

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


## OpenAPI

````yaml POST /payouts:calculate
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:
  /payouts:calculate:
    post:
      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.


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


        Use 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.
      operationId: calculatePayouts
      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/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'
      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
components:
  schemas:
    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
    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
    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
    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
    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.
    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
    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.
    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
    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
    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.