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

# List markets

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

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

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

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

## Examples

<CodeGroup>
  ```http Browse markets theme={null}
  GET /v1/markets
  ```

  ```http Get one market theme={null}
  GET /v1/markets?market_id=mkt_fed_dec_2026_cut
  ```

  ```http Search by words theme={null}
  GET /v1/markets?q=Fed%20rate%20cut&page_size=5
  ```

  ```http Filter results theme={null}
  GET /v1/markets?category=rates&page_size=20
  ```
</CodeGroup>

The response always contains `items`, `next_page_token`, `snapshot_id` and `as_of`. An ID lookup returns zero or one item with its full details. No match returns an empty `items` array.

Use `q` to search titles, descriptions and tags by words. Results are ordered by relevance. `page_size` sets the maximum results per page; use `next_page_token` to continue. Other filters, such as `category` or `venue`, narrow the search.

```http Include settlement evidence theme={null}
GET /v1/markets?market_id=mkt_fed_dec_2026_cut&include=EVIDENCE
```

Use `market_ids` for a batch lookup. Do not combine it with `market_id`. A `version` filter requires `market_id`.

```http Look up a Polymarket market theme={null}
GET /v1/markets?venue=polymarket&venue_market_id=1000001
```

Supply the venue together with its original numeric ID. The result returns the Rook ID and `family_ids`. Native IDs use exact decimal text in JSON. Do not combine native and Rook ID selectors.


## OpenAPI

````yaml GET /markets
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:
    get:
      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.


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


        Filter 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.
      operationId: listMarkets
      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
components:
  schemas:
    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
    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
    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
    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
    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
    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.