Odds-API.io Settlement API

openapi: 3.2.0
info:
  description: 'Odds-API.io is a powerful sports betting odds comparison API, providing real-time data from 450+ bookmakers across 34 sports with near zero latency.


    - 450+ bookmakers supported

    - 34 sports including Football, Basketball, Tennis, Esports and more

    - Real-time odds with close to zero latency

    - Pre-match & In-play odds coverage

    - 99.9% uptime for reliability'
  title: Odds-API.io - Real-Time Sports Betting Odds API (v3)…
  contact: {}
  version: 3.0.0
servers:
- url: https://api.odds-api.io/v3
tags:
- name: Settlement
paths:
  /settlements:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Returns the settlement record for up to 50 events: status, whether the result is final, and the final scores. Every id gets an answer, including cancelled and not yet resulted events. Paid plans only.'
      tags:
      - Settlement
      summary: Get Settlements
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: 74919888,73722728
        description: Comma-separated event ids (1 to 50)
        name: eventIds
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.SettlementsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Paid plans only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '503':
          description: Storage unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: 'Get the settlement record for up to 50 events: status, whether the result is final and the final scores, including cancelled events. Paid plans only.'
      operationId: getSettlements
      x-operation-id-source: derived
  /settlements/grade:
    post:
      security:
      - ApiKeyAuth: []
      description: Grades up to 50 bet selections against final results. Each selection is the event id, market name, side and, where the market has one, the line (hdp) and label exactly as served on /odds. Returns won, lost, void, half_won, half_lost, pending or ungradeable per selection, with a reason for void, pending and ungradeable answers (reason is null for won, lost, half_won and half_lost). Paid plans only.
      tags:
      - Settlement
      summary: Grade Selections
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Selections to grade. At most 64 KB.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.GradeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.GradesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Paid plans only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '503':
          description: Storage unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Grade up to 50 bet selections against final results and get won, lost, void, half won, half lost, pending or ungradeable for each one. Paid plans only.
      operationId: postSettlementsGrade
      x-operation-id-source: derived
components:
  schemas:
    dto.SideFloats:
      type: object
      description: 'Home/away pair that can be fractional. Cricket overs use cricket notation: 19.3 means nineteen overs and three balls.'
      properties:
        away:
          type: number
          example: 20
        home:
          type: number
          example: 20
    controllers.GradeRequest:
      type: object
      required:
      - selections
      properties:
        selections:
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/controllers.GradeSelectionRequest'
    dto.PeriodScore:
      type: object
      properties:
        away:
          type: integer
        home:
          type: integer
        overs:
          allOf:
          - $ref: '#/components/schemas/dto.SideFloats'
          description: Cricket only. Overs bowled by each side in this innings.
        wickets:
          allOf:
          - $ref: '#/components/schemas/dto.SideInts'
          description: Cricket only. Wickets lost by each side in this innings.
    dto.Score:
      type: object
      properties:
        away:
          type: integer
        home:
          description: 'Headline result: includes overtime, never a penalty shootout.'
          type: integer
        periods:
          description: Keyed p1..pN (that period only), ft, ot and ap (running totals after regulation, overtime and a penalty shootout), currentgame, mapN, inningN. See https://docs.odds-api.io/guides/live-events#period-scores
          type: object
          additionalProperties:
            $ref: '#/components/schemas/dto.PeriodScore'
    controllers.GradesResponse:
      type: object
      properties:
        grades:
          type: array
          description: One grade per selection, in the order sent.
          items:
            $ref: '#/components/schemas/controllers.GradeResponse'
    controllers.ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Error message
    dto.SideInts:
      type: object
      description: Home/away pair of whole numbers (cricket wickets).
      properties:
        away:
          type: integer
          example: 9
        home:
          type: integer
          example: 6
    controllers.GradeSelectionRequest:
      type: object
      required:
      - eventId
      - market
      properties:
        ref:
          type: string
          description: Your own id for the bet, echoed back. At most 64 characters.
          example: bet-1
        eventId:
          description: Event id, as a number or a numeric string.
          oneOf:
          - type: integer
          - type: string
          example: 74919888
        market:
          type: string
          description: Market name as served on /odds, for example ML, Spread, Totals HT, Corners Totals, Player Props.
          example: Spread
        side:
          type: string
          description: 'home, away, draw, over, under, yes, no, odd, even, 1x, 12, x2, none, neither, or an HT/FT pair such as draw/home. Leave it out when the label carries the bet: correct scores, Winning Margin, goal counts, highest scoring half, Home/Away Team Exact Goals (or send that market''s own team), and First/Last Match Corner when the label is 1 or 2. Correct Score and Set Betting also take the score itself as side ("2-1") instead of a label.'
          example: home
        hdp:
          type: number
          description: The line as served on /odds. Handicaps are stated for the home side. Required on handicap, totals, corners, bookings and player prop markets.
          example: -0.25
        label:
          type: string
          description: 'Row label as served. Required for Player Props ("Arike Ogunbowale (Assists)") and labelled markets: Home/Away Team Exact Goals ("Arsenal - 2 Goals"), Correct Score ("2-1"), Winning Margin ("2 (1)"), goal counts ("3+ Goals") and Highest Scoring Half ("2nd Half"). First/Last Match Corner also take "1" or "2".'
          example: Arike Ogunbowale (Assists)
        tieRule:
          type: string
          enum:
          - lose
          - void
          description: What a level score does to a moneyline bet in sports where books differ. Ignored where a fixed rule applies.
    settlement.Basis:
      type: object
      description: The score the verdict was computed from. Only on graded score markets.
      properties:
        scope:
          type: string
          enum:
          - regulation
          - full_game
          - match_result
          - first_half
          - second_half
          - first_period
          - period_2
          - period_3
          - period_4
          - period_5
          - games
          - map_1
          - map_2
          - map_3
          - map_4
          - map_5
          example: regulation
        home:
          type: integer
          example: 3
        away:
          type: integer
          example: 2
    controllers.SettlementResponse:
      type: object
      properties:
        eventId:
          type: integer
          example: 74919888
        sport:
          type: string
          example: Football
        status:
          type: string
          enum:
          - pending
          - live
          - awaiting_result
          - settled
          - cancelled
          example: settled
        final:
          type: boolean
          description: True when you can stop polling this event.
          example: true
        settledAt:
          type: string
          format: date-time
          description: When we recorded the final state. Omitted when unknown.
          example: '2026-10-04T19:02:11Z'
        scores:
          allOf:
          - $ref: '#/components/schemas/dto.Score'
          description: Present only for settled events with a usable score.
    controllers.SettlementsResponse:
      type: object
      properties:
        settlements:
          type: array
          items:
            $ref: '#/components/schemas/controllers.SettlementResponse'
        notFound:
          type: array
          description: Event ids we have never seen.
          items:
            type: string
          example:
          - '999'
    controllers.GradeResponse:
      type: object
      properties:
        ref:
          type: string
          example: bet-1
        eventId:
          type: integer
          example: 74919888
        result:
          type: string
          enum:
          - won
          - lost
          - void
          - half_won
          - half_lost
          - pending
          - ungradeable
          example: won
        reason:
          type:
          - string
          - 'null'
          description: Null for won, lost, half_won and half_lost. Always set otherwise.
          enum:
          - push
          - event_cancelled
          - event_not_started
          - event_live
          - awaiting_result
          - awaiting_stats
          - event_not_found
          - unsupported_market
          - invalid_side
          - invalid_line
          - invalid_label
          - incomplete_score
          - ambiguous_tie
          - player_not_matched
          - stats_unavailable
          - result_unavailable
          - null
          example: null
        final:
          type: boolean
          description: True when you can stop polling this selection.
          example: true
        basis:
          $ref: '#/components/schemas/settlement.Basis'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey
      description: Your Odds-API.io API key, sent as the apiKey query parameter. Get one at https://odds-api.io/pricing.
x-origin:
- url: https://api.odds-api.io/v3/docs/doc.json
  format: swagger
  version: '2.0'
  converter:
    url: https://github.com/mermade/oas-kit
    version: 7.0.8