openapi: 3.2.0
info:
  title: Gemini Prediction Markets API
  description: 'API for trading prediction market contracts on Gemini.


    **Note:** Only fields documented in this specification are considered stable. Undocumented fields in API responses may change or be removed without notice.'
  version: 1.0.0
  contact:
    name: Gemini API Support
servers:
- url: https://api.gemini.com
  description: Production
- url: https://api.sandbox.gemini.com
  description: Sandbox
tags:
- name: Markets
  description: 'Public endpoints for browsing prediction markets.


    **Market Data:** Use these REST endpoints to discover active events and each contract''s `instrumentSymbol` (e.g., `GEMI-FEDJAN26-DN25`). For active trading and market making, prefer Prediction Markets WebSocket streams with that `instrumentSymbol`.

    - List Events - Discover active events and instrument symbols

    - Prediction Markets WebSocket Streams - Stream prices, depth, order events, and positions'
paths:
  /v1/prediction-markets/events:
    get:
      tags:
      - Markets
      summary: List prediction market events
      description: Returns a paginated list of prediction market events with optional filtering by status, category, sports-market classification, and search text. Repeated values for the same filter use OR semantics; different filters combine with AND semantics. Game events may include an `events` array containing full child event objects, each with its own contracts; child market types are open-ended and may include spreads, totals, player props, or future types.
      operationId: listEvents
      parameters:
      - name: status
        in: query
        description: Filter by event status (can specify multiple)
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MarketStatus'
        style: form
        explode: true
      - name: category
        in: query
        description: Filter by category (can specify multiple). If omitted, returns events from all categories.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - $ref: '#/components/parameters/SportFilter'
      - $ref: '#/components/parameters/SportsMarketTypeFilter'
      - $ref: '#/components/parameters/SportsMarketSubjectFilter'
      - $ref: '#/components/parameters/SportsMarketScopeFilter'
      - $ref: '#/components/parameters/SportsMarketMetricFilter'
      - name: search
        in: query
        description: Search text to filter events by title
        schema:
          type: string
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                activeEvents:
                  summary: List of active events
                  value:
                    data:
                    - id: evt_123
                      title: Will Bitcoin reach $100k by end of 2028?
                      slug: bitcoin-100k-2028
                      description: Bitcoin must reach $100,000 USD on any major exchange by December 31, 2028
                      imageUrl: https://example.com/btc.png
                      type: binary
                      category: crypto
                      series: null
                      ticker: BTC100K2028
                      status: active
                      resolvedAt: null
                      createdAt: '2026-01-01T00:00:00.000Z'
                      effectiveDate: '2026-01-01T00:00:00.000Z'
                      expiryDate: '2028-12-31T23:59:59.000Z'
                      liquidity: '500000.00'
                      tags:
                      - bitcoin
                      - cryptocurrency
                      - price-prediction
                      contracts:
                      - id: contract_123
                        label: BTC reaches $100,000 by end of 2028
                        description: null
                        prices:
                          buy:
                            'yes': '0.65'
                            'no': '0.35'
                          sell:
                            'yes': '0.65'
                            'no': '0.35'
                          bestBid: '0.64'
                          bestAsk: '0.66'
                          lastTradePrice: '0.65'
                        color: '#00ff00'
                        status: active
                        imageUrl: null
                        priceHistory: null
                        createdAt: '2026-01-01T00:00:00.000Z'
                        expiryDate: '2028-12-31T23:59:59.000Z'
                        resolutionSide: null
                        resolvedAt: null
                        termsAndConditionsUrl: https://example.com/terms
                        ticker: BTC100K2028
                        instrumentSymbol: GEMI-BTC100K2028
                        effectiveDate: '2026-01-01T00:00:00.000Z'
                    - id: evt_124
                      title: Will ETH reach $5k by end of 2028?
                      slug: ethereum-5k-2028
                      description: Ethereum must reach $5,000 USD on any major exchange by December 31, 2028
                      imageUrl: https://example.com/eth.png
                      type: binary
                      category: crypto
                      series: null
                      ticker: ETH5K2028
                      status: active
                      resolvedAt: null
                      createdAt: '2026-01-01T00:00:00.000Z'
                      effectiveDate: '2026-01-01T00:00:00.000Z'
                      expiryDate: '2028-12-31T23:59:59.000Z'
                      liquidity: '300000.00'
                      tags:
                      - ethereum
                      - cryptocurrency
                      - price-prediction
                      contracts:
                      - id: contract_125
                        label: ETH reaches $5,000 by end of 2028
                        description: null
                        prices:
                          buy:
                            'yes': '0.48'
                            'no': '0.52'
                          sell:
                            'yes': '0.48'
                            'no': '0.52'
                          bestBid: '0.47'
                          bestAsk: '0.49'
                          lastTradePrice: '0.48'
                        color: '#00ff00'
                        status: active
                        imageUrl: null
                        priceHistory: null
                        createdAt: '2026-01-01T00:00:00.000Z'
                        expiryDate: '2028-12-31T23:59:59.000Z'
                        resolutionSide: null
                        resolvedAt: null
                        termsAndConditionsUrl: https://example.com/terms
                        ticker: ETH5K2028
                        instrumentSymbol: GEMI-ETH5K2028
                        effectiveDate: '2026-01-01T00:00:00.000Z'
                    pagination:
                      limit: 50
                      offset: 0
                      total: 2
                sportsMarkets:
                  summary: Sports markets across leagues and periods
                  value:
                    data:
                    - id: evt_mlb_first_five_spread
                      title: Yankees at Red Sox - First 5 Innings Spread
                      type: binary
                      category: Sports
                      sportsMarket:
                        sport: baseball
                        type: spread
                        subject: team
                        scope:
                          type: inning
                          start: 1
                          end: 5
                        metric: runs
                      contracts: []
                    - id: evt_nfl_first_half_spread
                      title: Bills at Chiefs - First Half Spread
                      type: binary
                      category: Sports
                      sportsMarket:
                        sport: american_football
                        type: spread
                        subject: team
                        scope:
                          type: half
                          ordinal: 1
                        metric: points
                      contracts: []
                    - id: evt_ncaaf_team_total
                      title: Michigan Team Total vs Ohio State
                      type: binary
                      category: Sports
                      sportsMarket:
                        sport: american_football
                        type: total
                        subject: team
                        scope:
                          type: full_contest
                        metric: points
                      contracts: []
                    pagination:
                      limit: 50
                      offset: 0
                      total: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/prediction-markets/events/{eventTicker}:
    get:
      tags:
      - Markets
      summary: Get event by ticker
      description: Returns detailed information about a specific prediction market event. Game events may include an `events` array containing full child event objects, each with its own contracts; child market types are open-ended and may include spreads, totals, player props, or future types.
      operationId: getEvent
      parameters:
      - name: eventTicker
        in: path
        required: true
        description: The event ticker symbol (e.g., "BTC100K")
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/prediction-markets/events/{eventTicker}/strike:
    get:
      tags:
      - Markets
      summary: Get strike price for event
      description: 'Returns strike price information for a specific prediction market event.


        Useful for crypto Up/Down contracts where the strike price becomes available at the start of the observation window (typically ~5 minutes before expiry for 5M contracts).


        For Up/Down contracts, the `value` field will be `null` until the strike is captured at `availableAt` time.'
      operationId: getEventStrike
      parameters:
      - name: eventTicker
        in: path
        required: true
        description: The event ticker symbol (e.g., "BTC05M2603271950")
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Strike'
              examples:
                strikeAvailable:
                  summary: Strike price captured
                  value:
                    value: '98000.50'
                    type: reference
                    availableAt: '2026-03-27T19:45:00.000Z'
                strikePending:
                  summary: Strike pending (pre-T-0)
                  value:
                    value: null
                    type: reference
                    availableAt: '2026-03-27T19:45:00.000Z'
        '404':
          description: Strike not found (event doesn't exist or doesn't have strike data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Strike not found
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/prediction-markets/events/newly-listed:
    get:
      tags:
      - Markets
      summary: List newly listed events
      description: Returns a list of prediction market events created in the last 24 hours, sorted by creation date (newest first). Repeated values for the same sports-market filter use OR semantics; different filters combine with AND semantics.
      operationId: listNewlyListedEvents
      parameters:
      - name: category
        in: query
        description: Filter by category (can specify multiple). If omitted, returns events from all categories.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - $ref: '#/components/parameters/SportFilter'
      - $ref: '#/components/parameters/SportsMarketTypeFilter'
      - $ref: '#/components/parameters/SportsMarketSubjectFilter'
      - $ref: '#/components/parameters/SportsMarketScopeFilter'
      - $ref: '#/components/parameters/SportsMarketMetricFilter'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                newlyListedEvents:
                  summary: Newly listed events
                  value:
                    data:
                    - id: '4126'
                      title: SOL price today at 12am EST
                      slug: sol-price-today-at-12am-est
                      description: Interval SOL price prediction event
                      imageUrl: https://images.ctfassets.net/example.png
                      type: categorical
                      category: Crypto
                      series: SOL1H
                      ticker: SOL2603050500
                      status: active
                      resolvedAt: null
                      createdAt: '2026-03-05T02:57:31.548Z'
                      effectiveDate: null
                      expiryDate: '2026-03-05T05:00:00.000Z'
                      liquidity: null
                      tags:
                      - Solana
                      contracts:
                      - id: 4126-33859
                        label: SOL > $90
                        abbreviatedName: '>$90'
                        description: null
                        prices:
                          buy:
                            'yes': '0.42'
                            'no': '0.58'
                          sell:
                            'yes': '0.42'
                            'no': '0.58'
                          bestBid: '0.49'
                          bestAsk: '0.54'
                          lastTradePrice: '0.75'
                        color: '#4CAF50'
                        status: active
                        imageUrl: null
                        priceHistory: null
                        createdAt: '2026-03-05T02:57:31.548Z'
                        expiryDate: '2026-03-05T05:00:00.000Z'
                        resolutionSide: null
                        resolvedAt: null
                        termsAndConditionsUrl: https://example.com/terms
                        ticker: HI90
                        instrumentSymbol: GEMI-SOL2603050500-HI90
                        effectiveDate: null
                        marketState: open
                        sortOrder: 1
                    pagination:
                      limit: 50
                      offset: 0
                      total: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/prediction-markets/events/recently-settled:
    get:
      tags:
      - Markets
      summary: List recently settled events
      description: Returns a list of prediction market events settled in the last 24 hours, sorted by resolution date (most recently settled first). Repeated values for the same sports-market filter use OR semantics; different filters combine with AND semantics.
      operationId: listRecentlySettledEvents
      parameters:
      - name: category
        in: query
        description: Filter by category (can specify multiple). If omitted, returns events from all categories.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - $ref: '#/components/parameters/SportFilter'
      - $ref: '#/components/parameters/SportsMarketTypeFilter'
      - $ref: '#/components/parameters/SportsMarketSubjectFilter'
      - $ref: '#/components/parameters/SportsMarketScopeFilter'
      - $ref: '#/components/parameters/SportsMarketMetricFilter'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                recentlySettledEvents:
                  summary: Recently settled events
                  value:
                    data:
                    - id: '4100'
                      title: SOL price today at 4am EST
                      slug: sol-price-today-at-4am-est
                      description: Interval SOL price prediction event
                      imageUrl: https://images.ctfassets.net/example.png
                      type: categorical
                      category: Crypto
                      series: SOL1H
                      ticker: SOL2603050400
                      status: settled
                      resolvedAt: '2026-03-05T04:00:21.400Z'
                      createdAt: '2026-03-05T01:57:31.548Z'
                      effectiveDate: null
                      expiryDate: '2026-03-05T04:00:00.000Z'
                      liquidity: null
                      tags:
                      - Solana
                      contracts:
                      - id: 4100-33800
                        label: SOL > $90
                        abbreviatedName: '>$90'
                        description: null
                        prices:
                          buy: {}
                          sell: {}
                          bestBid: null
                          bestAsk: null
                          lastTradePrice: '0.80'
                        color: '#4CAF50'
                        status: settled
                        imageUrl: null
                        priceHistory: null
                        createdAt: '2026-03-05T01:57:31.548Z'
                        expiryDate: '2026-03-05T04:00:00.000Z'
                        resolutionSide: 'yes'
                        resolvedAt: '2026-03-05T04:00:21.400Z'
                        termsAndConditionsUrl: https://example.com/terms
                        ticker: HI90
                        instrumentSymbol: GEMI-SOL2603050400-HI90
                        effectiveDate: null
                        marketState: closed
                        sortOrder: 1
                    pagination:
                      limit: 50
                      offset: 0
                      total: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/prediction-markets/events/upcoming:
    get:
      tags:
      - Markets
      summary: List upcoming events
      description: Returns a list of approved prediction market events that are not yet active (pre-launch), sorted by start time (soonest first). Repeated values for the same sports-market filter use OR semantics; different filters combine with AND semantics.
      operationId: listUpcomingEvents
      parameters:
      - name: category
        in: query
        description: Filter by category (can specify multiple). If omitted, returns events from all categories.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - $ref: '#/components/parameters/SportFilter'
      - $ref: '#/components/parameters/SportsMarketTypeFilter'
      - $ref: '#/components/parameters/SportsMarketSubjectFilter'
      - $ref: '#/components/parameters/SportsMarketScopeFilter'
      - $ref: '#/components/parameters/SportsMarketMetricFilter'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                upcomingEvents:
                  summary: Upcoming events
                  value:
                    data:
                    - id: '4200'
                      title: Lakers vs Celtics
                      slug: lakers-vs-celtics-march-10
                      description: NBA game prediction market
                      imageUrl: https://images.ctfassets.net/example.png
                      type: binary
                      category: Sports
                      series: null
                      sportsMarket:
                        sport: basketball
                        type: moneyline
                        subject: contest
                        scope:
                          type: full_contest
                      ticker: NBA260310LAL-BOS
                      status: approved
                      resolvedAt: null
                      createdAt: '2026-03-04T12:00:00.000Z'
                      effectiveDate: '2026-03-10T19:30:00.000Z'
                      expiryDate: '2026-03-11T02:00:00.000Z'
                      liquidity: null
                      tags:
                      - NBA
                      - Basketball
                      subcategory:
                        id: 10
                        slug: sports_nba
                        name: NBA
                        path:
                        - Sports
                        - NBA
                      contracts:
                      - id: 4200-1
                        label: Lakers Win
                        abbreviatedName: LAL
                        description: null
                        prices:
                          buy: {}
                          sell: {}
                          bestBid: null
                          bestAsk: null
                          lastTradePrice: null
                        color: '#552583'
                        status: approved
                        imageUrl: null
                        priceHistory: null
                        createdAt: '2026-03-04T12:00:00.000Z'
                        expiryDate: '2026-03-11T02:00:00.000Z'
                        resolutionSide: null
                        resolvedAt: null
                        termsAndConditionsUrl: https://example.com/terms
                        ticker: LAL
                        instrumentSymbol: GEMI-NBA260310LAL-BOS-LAL
                        effectiveDate: '2026-03-10T19:30:00.000Z'
                        marketState: closed
                        sortOrder: 1
                    pagination:
                      limit: 50
                      offset: 0
                      total: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/prediction-markets/categories:
    get:
      tags:
      - Markets
      summary: List event categories
      description: Returns available prediction market event categories, optionally filtered by event status.
      operationId: getCategories
      parameters:
      - name: status
        in: query
        description: Filter categories by event status
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MarketStatus'
        style: form
        explode: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    items:
                      type: string
                    example:
                    - sports
                    - politics
                    - crypto
                    - entertainment
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    OrderSide:
      type: string
      enum:
      - buy
      - sell
    Outcome:
      type: string
      enum:
      - 'yes'
      - 'no'
      description: The outcome being traded (Yes or No)
    SportsMarketSubject:
      type: string
      enum:
      - contest
      - team
      - player
      - participant
      - other
      description: What the market is about. `participant` covers non-player entrants such as drivers and horses.
    MarketType:
      type: string
      enum:
      - binary
      - categorical
      description: Type of prediction market
    OrderBookEntry:
      type: object
      properties:
        side:
          $ref: '#/components/schemas/OrderSide'
        price:
          type: string
          example: '0.65'
        quantity:
          type: string
          example: '1000'
    SportsMarket:
      type: object
      additionalProperties: false
      description: Atomic sports-market classification shared by every contract grouped under the event. Present only for sports events. All fields except `metric` are required together.
      required:
      - sport
      - type
      - subject
      - scope
      properties:
        sport:
          $ref: '#/components/schemas/SportsMarketSport'
        type:
          $ref: '#/components/schemas/SportsMarketType'
        subject:
          $ref: '#/components/schemas/SportsMarketSubject'
        scope:
          $ref: '#/components/schemas/SportsMarketScope'
        metric:
          $ref: '#/components/schemas/SportsMarketMetric'
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
          example: InvalidInput
        message:
          type: string
          description: Human-readable error message
          example: orderId is required
    Contract:
      type: object
      description: 'Contract quantity and price validation is instrument-specific. Clients must validate order quantities and prices against the returned increment and minimum fields rather than assuming a fixed grid.

        '
      properties:
        id:
          type: string
        label:
          type: string
          description: Human-readable label for the contract's YES-space proposition (e.g., "SOL > $90")
        abbreviatedName:
          type:
          - string
          - 'null'
          description: Short form label (e.g., ">$90")
        description:
          type: object
          description: Rich text description
        prices:
          $ref: '#/components/schemas/ContractPrices'
        color:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/MarketStatus'
        imageUrl:
          type:
          - string
          - 'null'
        priceHistory:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PricePoint'
        createdAt:
          type: string
          format: date-time
        expiryDate:
          type:
          - string
          - 'null'
          format: date-time
        resolutionSide:
          $ref: '#/components/schemas/Outcome'
        resolvedAt:
          type:
          - string
          - 'null'
          format: date-time
        termsAndConditionsUrl:
          type: string
        ticker:
          type: string
        instrumentSymbol:
          type: string
        quantityIncrement:
          type:
          - string
          - 'null'
          description: Contract quantity grid from instrument refdata (for example, "0.01").
        quantityMinimum:
          type:
          - string
          - 'null'
          description: Minimum contract quantity from instrument refdata (for example, "1.00").
        priceIncrement:
          type:
          - string
          - 'null'
          description: Contract price grid from instrument refdata (for example, "0.0001").
        quoteAssetPrecision:
          type:
          - integer
          - 'null'
          description: Decimal places supported by the instrument's quote asset.
        priceMinimum:
          type:
          - string
          - 'null'
          description: Minimum contract price and anchor for the instrument price grid (for example, "0.0001").
        effectiveDate:
          type:
          - string
          - 'null'
          format: date-time
        marketState:
          type:
          - string
          - 'null'
          description: Trading state of the contract
          enum:
          - open
          - closed
        sortOrder:
          type:
          - integer
          - 'null'
          description: Display order within the event
        strike:
          $ref: '#/components/schemas/Strike'
        source:
          type:
          - string
          - 'null'
          deprecated: true
          description: 'Deprecated: use the event-level `sourceDetails` (`agency` + `index`) instead. Data source identifier for price observation (e.g., "GRR-KAIKO_BTCUSD_60S"). Present for crypto Up/Down contracts.'
          example: GRR-KAIKO_BTCUSD_60S
        settlementValue:
          type:
          - string
          - 'null'
          description: The observed settlement price. Only present after the contract is settled.
          example: '87654.32'
    PricePoint:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        price:
          type: string
    MarketStatus:
      type: string
      enum:
      - approved
      - active
      - closed
      - under_review
      - settled
      - invalid
      description: Status of a prediction market
    SportsMarketScopeType:
      type: string
      enum:
      - full_contest
      - regulation
      - half
      - quarter
      - period
      - inning
      - team_innings
      - over
      - powerplay
      - set
      - game
      - round
      - hole
      - match_day
      - session
      - super_over
      - race
      - sprint
      - qualifying
      - practice
      - stage
      - lap
      - series
      - season
      - tournament
      - competition
      - other
      description: Unit covered by the market. `full_contest` follows the market's official final-result rules; `regulation` covers scheduled regulation play only. Ordinal and range qualifiers are represented separately on `SportsMarketScope`.
    SourceDetails:
      type:
      - object
      - 'null'
      description: Structured data source information for price observation. Replaces the deprecated flat `source` string on the event and contract. Present for crypto Up/Down events. Both fields are omitted when not available.
      properties:
        agency:
          type:
          - string
          - 'null'
          description: The data provider / vendor name.
          example: Kaiko
        index:
          type:
          - string
          - 'null'
          description: The specific data feed identifier (the value previously carried by the flat `source` field).
          example: GRR-KAIKO_BTCUSD_60S
    Event:
      type: object
      description: A prediction market event containing one or more tradeable contracts
      properties:
        id:
          type: string
        title:
          type: string
          example: Will Bitcoin reach $100k by end of 2028?
        slug:
          type: string
          example: bitcoin-100k-2028
        description:
          type:
          - string
          - 'null'
        imageUrl:
          type:
          - string
          - 'null'
        type:
          $ref: '#/components/schemas/MarketType'
        category:
          type: string
          example: crypto
        series:
          type:
          - string
          - 'null'
        sportsMarket:
          $ref: '#/components/schemas/SportsMarket'
        ticker:
          type: string
          description: The event ticker (e.g., "BTC100K2028")
          example: BTC100K2028
        status:
          $ref: '#/components/schemas/MarketStatus'
        resolvedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        contracts:
          type: array
          description: Tradeable contracts within this event
          items:
            $ref: '#/components/schemas/Contract'
        events:
          type: array
          description: Full child or sibling event objects for the same game or underlying market. The available child market types are open-ended and may include spreads, totals, player props, or future types. Each child event includes its own contracts array.
          items:
            $ref: '#/components/schemas/NestedEvent'
        contractOrderbooks:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OrderBook'
        volume:
          type: string
          description: Total trading volume in USD
          example: '125000.00'
        liquidity:
          type: string
          description: Total liquidity in USD
          example: '50000.00'
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
        effectiveDate:
          type: string
          format: date-time
        expiryDate:
          type:
          - string
          - 'null'
          format: date-time
        subcategory:
          $ref: '#/components/schemas/Subcategory'
        source:
          type:
          - string
          - 'null'
          deprecated: true
          description: 'Deprecated: use `sourceDetails` (`agency` + `index`) instead. Data source identifier for price observation. Aggregated from contracts for crypto Up/Down events.'
          example: GRR-KAIKO_BTCUSD_60S
        sourceDetails:
          $ref: '#/components/schemas/SourceDetails'
        settlement:
          $ref: '#/components/schemas/Settlement'
    StrikeType:
      type: string
      description: 'Strike or condition inequality type for contract threshold evaluation. - `reference`: Crypto Up/Down reference strike price captured at `availableAt` time. - `above`: Higher/Lower contract threshold. - `spread`: Point, run, or goal handicap spread line. - `over`: Total or prop threshold evaluated as strict greater than (`>`). - `over_or_equal`: Total or prop threshold evaluated as greater than or equal to (`>=`). - `under`: Total or prop threshold evaluated as strict less than (`<`). - `under_or_equal`: Position, rank, or total threshold evaluated as less than or equal to (`<=`).'
      enum:
      - reference
      - above
      - spread
      - over
      - over_or_equal
      - under
      - under_or_equal
      example: spread
    OrderBook:
      type: object
      properties:
        bids:
          type: array
          items:
            $ref: '#/components/schemas/OrderBookEntry'
        asks:
          type: array
          items:
            $ref: '#/components/schemas/OrderBookEntry'
    EventsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Settlement:
      type: object
      description: Settlement information for resolved events
      properties:
        value:
          type:
          - string
          - 'null'
          description: The observed settlement value (e.g., the price at expiry for crypto contracts)
          example: '87654.32'
    NestedEvent:
      type: object
      description: A child or sibling prediction market event nested within a parent event
      properties:
        id:
          type: string
        title:
          type: string
        slug:
          type: string
        description:
          type:
          - string
          - 'null'
        imageUrl:
          type:
          - string
          - 'null'
        type:
          $ref: '#/components/schemas/MarketType'
        category:
          type: string
        series:
          type:
          - string
          - 'null'
        sportsMarket:
          $ref: '#/components/schemas/SportsMarket'
        ticker:
          type: string
        status:
          $ref: '#/components/schemas/MarketStatus'
        resolvedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        contracts:
          type: array
          description: Tradeable contracts within this nested event
          items:
            $ref: '#/components/schemas/Contract'
        contractOrderbooks:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OrderBook'
        volume:
          type: string
        liquidity:
          type: string
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
        effectiveDate:
          type: string
          format: date-time
        expiryDate:
          type:
          - string
          - 'null'
          format: date-time
        subcategory:
          $ref: '#/components/schemas/Subcategory'
        source:
          type:
          - string
          - 'null'
          deprecated: true
        sourceDetails:
          $ref: '#/components/schemas/SourceDetails'
        settlement:
          $ref: '#/components/schemas/Settlement'
    ContractPrices:
      type:
      - object
      - 'null'
      description: Current bid/ask pricing for the contract
      properties:
        buy:
          type: object
          description: Buy prices for each outcome
          properties:
            'yes':
              type: string
              description: Price to buy YES outcome
              example: '0.42'
            'no':
              type: string
              description: Price to buy NO outcome
              example: '0.58'
        sell:
          type: object
          description: Sell prices for each outcome
          properties:
            'yes':
              type: string
              description: Price to sell YES outcome
              example: '0.42'
            'no':
              type: string
              description: Price to sell NO outcome
              example: '0.58'
        bestBid:
          type:
          - string
          - 'null'
          description: Highest buy offer
          example: '0.49'
        bestAsk:
          type:
          - string
          - 'null'
          description: Lowest sell offer
          example: '0.54'
        lastTradePrice:
          type:
          - string
          - 'null'
          description: Most recent transaction price
          example: '0.75'
    SportsMarketMetric:
      type: string
      description: Statistic measured by the market. Interpret shared metric names using `sportsMarket.sport`.
      enum:
      - aces
      - assists
      - balls_faced
      - birdies
      - blocked_shots
      - blocks
      - bogeys
      - boundaries
      - break_points_won
      - cards
      - catches
      - clean_sheets
      - completed_passes
      - control_time
      - corners
      - defensive_rebounds
      - double_double
      - double_faults
      - doubles
      - eagles
      - earned_runs
      - errors
      - faceoff_wins
      - fairways_hit
      - fantasy_points
      - fastest_lap
      - field_goals_made
      - finishing_position
      - fouls
      - fours
      - free_throws_made
      - fumbles
      - games
      - goals
      - goals_allowed
      - greens_in_regulation
      - grid_position
      - hits
      - hits_allowed
      - hits_runs_rbis
      - holes_in_one
      - home_runs
      - innings_pitched
      - interceptions_thrown
      - kicking_points
      - knockdowns
      - laps_completed
      - laps_led
      - lap_time
      - longest_pass_completion
      - longest_reception
      - longest_rush
      - maiden_overs
      - offensive_rebounds
      - offsides
      - pars
      - passes
      - pass_attempts
      - pass_completions
      - passing_touchdowns
      - passing_yards
      - penalty_minutes
      - pitching_outs_recorded
      - pit_stops
      - points
      - points_assists
      - points_rebounds
      - points_rebounds_assists
      - positions_gained
      - power_play_points
      - putts
      - qualifying_position
      - rebounds
      - rebounds_assists
      - receiving_touchdowns
      - receiving_yards
      - receptions
      - red_cards
      - retirements
      - rounds
      - runs
      - runs_batted_in
      - runs_conceded
      - rush_attempts
      - rushing_touchdowns
      - rushing_yards
      - sacks
      - safety_cars
      - saves
      - sets
      - shots
      - shots_on_goal
      - shots_on_target
      - shutouts
      - significant_strikes
      - singles
      - sixes
      - steals
      - stolen_bases
      - strokes
      - strikeouts
      - submission_attempts
      - tackles
      - takedowns
      - three_pointers_made
      - tiebreaks_won
      - total_bases
      - total_points_won
      - total_strikes
      - touchdowns
      - triples
      - triple_double
      - turnovers
      - walks
      - wickets
      - wins
      - yellow_cards
      - other
    SportsMarketSport:
      type: string
      enum:
      - american_football
      - athletics
      - australian_rules_football
      - baseball
      - basketball
      - boxing
      - chess
      - cricket
      - cycling
      - darts
      - esports
      - golf
      - hockey
      - lacrosse
      - mixed_martial_arts
      - motorsports
      - rugby
      - sailing
      - soccer
      - tennis
      description: Sport whose rules give the market's scope and metric their sport-specific meaning.
    Strike:
      type: object
      description: Strike price or contract threshold information for Up/Down crypto contracts and sports prediction market contracts.
      properties:
        value:
          type:
          - string
          - 'null'
          description: The strike price value. Null for "reference" type strikes where the value is determined at availableAt time. For sports contracts, this represents the derived numeric strike value (e.g. spread margin, total line, or position/rank threshold).
          example: '87500.00'
        type:
          $ref: '#/components/schemas/StrikeType'
        availableAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the strike price becomes available
          example: '2026-03-27T19:45:00.000Z'
    SportsMarketScope:
      type: object
      additionalProperties: false
      description: Settlement scope. `ordinal` identifies one unit; `start` and `end` identify an inclusive range of units.
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/SportsMarketScopeType'
        ordinal:
          type: integer
          format: int32
          minimum: 0
          description: Optional ordinal within the scope type, such as half `1` or quarter `4`.
        start:
          type: integer
          format: int32
          minimum: 0
          description: Optional inclusive start of a scope range, such as inning `1`.
        end:
          type: integer
          format: int32
          minimum: 0
          description: Optional inclusive end of a scope range, such as inning `5`.
    SportsMarketType:
      type: string
      enum:
      - moneyline
      - spread
      - total
      - prop
      - correct_score
      - to_advance
      - futures
      - other
      description: Conventional sports-market family. `subject`, `scope`, and `metric` provide detail within the family. This classification is independent of the event's structural `type` (`binary` or `categorical`).
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          example: 50
        offset:
          type: integer
          example: 0
        total:
          type: integer
          example: 100
    Subcategory:
      type:
      - object
      - 'null'
      description: Nested category information for the event
      properties:
        id:
          type: integer
          description: Category identifier
          example: 35
        slug:
          type: string
          description: URL-friendly category identifier
          example: crypto_solana
        name:
          type: string
          description: Display name
          example: Solana
        path:
          type: array
          description: Category hierarchy path
          items:
            type: string
          example:
          - Crypto
          - Solana
  parameters:
    SportsMarketMetricFilter:
      name: sports_market_metric
      in: query
      description: Filter by `sportsMarket.metric`. Repeat the parameter to match any supplied value (OR). A metric can be queried without `sport`; use `sport` when its sport-specific meaning matters. Sports-market filters compose independently using AND. Unsupported enum values return `400 Bad Request`.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/SportsMarketMetric'
      style: form
      explode: true
    Offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
        minimum: 0
    Limit:
      name: limit
      in: query
      description: Maximum number of results to return (max 500)
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 500
    SportsMarketScopeFilter:
      name: sports_market_scope
      in: query
      description: Filter by `sportsMarket.scope.type`. Repeat the parameter to match any supplied value (OR). Ordinal and range qualifiers are not inferred by this filter. Sports-market filters compose independently using AND. Unsupported enum values return `400 Bad Request`.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/SportsMarketScopeType'
      style: form
      explode: true
    SportsMarketSubjectFilter:
      name: sports_market_subject
      in: query
      description: Filter by `sportsMarket.subject`. Repeat the parameter to match any supplied value (OR). Sports-market filters compose independently using AND. Unsupported enum values return `400 Bad Request`.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/SportsMarketSubject'
      style: form
      explode: true
    SportsMarketTypeFilter:
      name: sports_market_type
      in: query
      description: Filter by `sportsMarket.type`. Repeat the parameter to match any supplied value (OR). Sports-market filters compose independently using AND. Unsupported enum values return `400 Bad Request`.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/SportsMarketType'
      style: form
      explode: true
    SportFilter:
      name: sport
      in: query
      description: Filter by `sportsMarket.sport`. Repeat the parameter to match any supplied value (OR). Sports-market filters compose independently using AND. Unsupported enum values return `400 Bad Request`; valid combinations with no matching events return an empty result.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/SportsMarketSport'
      style: form
      explode: true
  responses:
    ServiceUnavailable:
      description: Prediction markets feature is temporarily unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-GEMINI-APIKEY
      description: Gemini API key with appropriate permissions
    payloadAuth:
      type: apiKey
      in: header
      name: X-GEMINI-PAYLOAD
      description: Base64-encoded private REST payload. See Gemini private REST authentication.
    signatureAuth:
      type: apiKey
      in: header
      name: X-GEMINI-SIGNATURE
      description: Hex HMAC-SHA384 signature of the payload using the API secret.