Live Tennis API Markets API

openapi: 3.2.0
info:
  title: Live Tennis Markets API
  version: 1.13.76
  contact:
    name: Live Tennis API
    url: https://livetennisapi.com
  license:
    name: MIT
    identifier: MIT
  termsOfService: https://livetennisapi.com/terms
  description: 'Real-time tennis scores, player data, match-winner market prices, and

    model-driven match analysis. Read-only. Coverage spans ATP, WTA,

    Challenger, ITF and the junior Grand Slam draws — depth differs by tour

    and surface; `GET /history/coverage` states the measured numbers. Access is tiered (FREE / BASIC / PRO / ULTRA). Each tier includes

    everything in the tiers below it; the concrete deltas are:


    `FREE` — self-serve, no card (https://livetennisapi.com/subscribe/free). Live and upcoming matches, current scores, players, fixtures, the

    tournament catalogue (`/tournaments`), and your own usage stats. 30 requests/minute, 100/day. No market prices, no model fields, no

    WebSocket. Historical results are not part of the tier, but a FREE key

    may spend 20 calls per calendar month on the history endpoints as a

    taste of the product — served exactly like an entitled call. Past that

    they answer `403 upgrade_required` carrying

    `free_history_taste: "used"`. `BASIC` — adds historical data: the completed-match listing

    (`/history/matches`, and `status=completed` on `/matches`), the

    per-match point-by-point tape with the model win-probability on the

    rows where the model ran

    (`/history/matches/{matchId}`), the measured completeness rollup

    (`/history/coverage`), and the results archive (1968–2022) —

    deep results (`/history/archive/matches`), archive player bios

    (`/history/archive/players`), career aggregates

    (`/history/archive/career`) and head-to-head (`/h2h`). 60 requests/minute, 1,000/day. `PRO` — adds match events (`/matches/{matchId}/events`), market prices

    (`/markets`, `/markets/{matchId}/prices`, `/matches/{matchId}/prices`),

    the pre-built monthly bulk history packages (`/history/packages`), the

    rank-ordered rankings listing (`/rankings?system=`) and one player''s

    win/loss and set-based record (`/players/{playerId}/stats`). 300 requests/minute, 10,000/day. `ULTRA` — adds model analysis (`/matches/{matchId}/analysis`), the live

    model fields (`win_probability_p1`, `danger`) on every score object,

    in-play match statistics (`/matches/{matchId}/statistics`) and their

    per-player sums (`serve_return` on `/players/{playerId}/stats`), per-player

    as-of ranking records (`/rankings?player=`), the as-of Elo tape

    (`/rankings?system=elo` — both modes, plus `kind=elo` bulk packages),

    rally construction

    (`/rally/matches`, shot-by-shot charted data), career and per-match

    charting stats (`/charting/players`, `/charting/matches/{chartingMatchId}`),

    the reconstructed 2013–2022 archive tape

    (`/history/archive/matches/{archiveId}/tape` — also opened by ANY active

    History plan, Starter included), the WebSocket live feed at `/ws` and the

    high-fan-out push feed (`/ws-token`), and outbound webhooks (direct keys). 600 requests/minute, 500,000/day. History runs in two continuous halves, deliberately non-overlapping: the

    point-by-point tape (2023→now) covers January 2023 to now, match by

    match, point by point; the results archive (1968–2022) covers 1968

    through 2022 as winner/loser-shaped RESULTS (final score, seeds, ranks at

    the time — no point-by-point). The archive ends exactly where the tape

    begins, so no match is ever served from two datasets. Archive results played **2013–2022** additionally carry a RECONSTRUCTED

    point-by-point tape at `/history/archive/matches/{archiveId}/tape` — the

    score sequence behind the published result: reconstructed point sequences,

    no capture timestamps. 97,901 matches / 14,340,663 rows, seasons **2013–2022

    ONLY**: the archive holds a further 977,903 results from 1968–2012 and NOT

    ONE of them has a tape, because we hold no point sequence for those years and

    we do not manufacture one. Write the range as

    2013–2022, never as "pre-2023" — the second phrasing reads as 1968 onward

    and is wrong by 45 seasons.'
servers:
- url: https://api.livetennisapi.com/api/public/v1
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Markets
paths:
  /markets:
    get:
      summary: The match's match-winner market (PRO)
      description: 'The match-winner market mapped to this match — `data` holds at most one object, and `meta.count` is 0 when nothing is mapped.


        MATCH-WINNER ONLY. No handicaps or game spreads, no totals, no set-winner books, and no per-game or per-set derivative of any kind. A quote here is the probability that a player WINS THE MATCH. Venues do list tennis derivatives beside the match-winner book — game spreads such as "A (-3.5) vs B (+3.5)" among them — and this API deliberately publishes none of them: a derivative is refused at the mapping step so it can never be served as, or beside, a match-winner price (2026-09-22).'
      operationId: listMarkets
      parameters:
      - name: match_id
        in: query
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Markets
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Market'
                  meta:
                    type: object
                    properties:
                      match_id:
                        type: integer
                      count:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/UpgradeRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Markets
  /markets/{matchId}/prices:
    get:
      summary: Market + recent price ticks per side, newest first (PRO)
      description: 'The mapped match-winner market for one match, with its recent price ticks per side, newest first.


        404 with `error: no_market` (since 2026-09-02; `match_id` and `coverage: "none"` alongside) when no match-winner market is mapped to the match — a market is mapped only where one is published for that fixture, so a client walking every live match will meet this. A bare `not_found` means the match id itself does not exist. Every row of `GET /matches` carries `has_market`, so a slate can be filtered before any call here. `GET /matches/{matchId}` answers `200` for the same match with `market` and `market_price` set to `null` instead, and carries the live score in the same response, so a per-match poll built on the detail route never spends a call on a 404.


        Ticks are kept for 30 days and then deleted: a market older than that answers with an empty `prices` array while staying mapped — retention, not a fault. For paging past 500 ticks use `/matches/{matchId}/prices` with its cursor.'
      operationId: getMarketPrices
      parameters:
      - $ref: '#/components/parameters/matchId'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Market with `prices`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Market'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/UpgradeRequired'
        '404':
          description: '`error: not_found` — no such match id. `error: no_market` (with `match_id`, `coverage: "none"`, `detail`) — the match exists and no match-winner market is mapped to it; `has_market` on the match list says so without a probe.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          $ref: '#/components/responses/MatchGone'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Markets
components:
  parameters:
    matchId:
      name: matchId
      description: 'The match id. Every match route shares ONE id space, so the same value works everywhere `matchId` appears.


        Get it from any match list, where it is the `id` field of each match object:

        `GET /matches?status=live` (in progress), `GET /matches?status=upcoming` or `GET /fixtures` (scheduled), `GET /matches?status=completed` or `GET /history/matches` (finished).


        Ids are stable for the life of a match, so one captured before it starts still resolves after it finishes.

        '
      in: path
      required: true
      schema:
        type: integer
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 200
  responses:
    RateLimited:
      description: 'Rate limit exceeded (Retry-After header present). Three body shapes, told apart by `error` and `scope`: the per-MINUTE limit (`rate_limited`, with `upgrade_url`, `tier` and `price` naming the next tier up); the per-DAY quota (`rate_limited` with `scope: "day"`, `limit_per_day`, and `resets_at` — the absolute ISO instant the daily window resets); and `abuse_throttled` with `retry_at_epoch` — a 24-hour block applied to clients that keep hammering far past their cap, which a well-behaved retry loop never sees. Fix the loop rather than retrying through it.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad query parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UpgradeRequired:
      description: Your tier doesn't unlock this endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, unknown, or disabled credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MatchGone:
      description: 'The match id existed and was merged into another match record (since 2026-09-05). The body is `MatchMerged`, not `Error`: it carries a forwarding address, which is the whole point of answering 410 rather than 404.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MatchMerged'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Stable machine-readable code, e.g. bad_date, bad_coverage, bad_sequence, bad_points, bad_points_complete, bad_combination, points_read_disabled, bad_after_seq, bad_changed_since, bad_restated_since, points_disabled, bad_period, bad_year, bad_format, bad_tour, bad_tier, bad_country, ambiguous_name, not_charted, not_found, no_analysis, no_market, upgrade_required, rate_limited, abuse_throttled.
        detail:
          type: string
          description: Human-readable explanation, when one adds anything.
        allowed:
          type: array
          items:
            type: string
          description: On a rejected enumerated parameter, the values that would have been accepted (e.g. the coverage vocabulary for bad_coverage).
    Market:
      type: object
      properties:
        id:
          type: integer
        question:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
          enum:
          - active
          - resolved
          - closed
          - null
        volume:
          type:
          - number
          - 'null'
        liquidity:
          type:
          - number
          - 'null'
        end_date:
          type:
          - string
          - 'null'
          format: date-time
        prices:
          type: array
          description: Prices endpoint / match detail only; newest first
          items:
            $ref: '#/components/schemas/Price'
    MatchMerged:
      type: object
      description: The 410 GONE body for a match id that was merged into another match record. Distinct from `Error` because it carries a forwarding address.
      properties:
        error:
          type: string
          description: Always `merged`.
        merged_into:
          type:
          - integer
          - 'null'
          description: 'The id that absorbed this one — re-point your records at it. Null means the forwarding target is unknown: nothing to forward you to, drop the id. On a merge chain this is the END of the chain, never an intermediate id that would 410 in turn.'
        merged_at:
          type: string
          format: date-time
          description: When THIS id stopped existing (UTC). On a chain it is the FIRST hop — the moment your copy of this id went stale.
        detail:
          type: string
          description: Human-readable explanation; differs for a merge and for a retirement so the two are distinguishable without parsing prose.
    Price:
      type: object
      description: Prediction-market top-of-book quote (probability-like, [0,1]); reflects market trading, not an official line, and can lag live scores. Tagged so a synthesised quote is never mistaken for a live book.
      properties:
        side:
          type:
          - integer
          - 'null'
          description: '1 = players.p1''s outcome, 2 = players.p2''s - decided by our name-verified match-market mapping, never by the venue''s own display order (the venue lists roughly half of all pairings the other way round). Fixed 2026-09-09: ticks served before that date followed the venue''s display order, so on those markets side was reversed; the mapping is stored, so re-reading any tick now returns the correct side.'
        bid:
          type:
          - number
          - 'null'
        ask:
          type:
          - number
          - 'null'
        mid:
          type:
          - number
          - 'null'
          description: The venue's observed midpoint at the instant we polled or streamed it - never a model estimate. Only mid is always real; see synthetic.
        spread:
          type:
          - number
          - 'null'
        price_source:
          type:
          - string
          - 'null'
          description: Feed category, e.g. prediction_market
        synthetic:
          type:
          - boolean
          - 'null'
          description: 'true = bid/ask are estimated from mid (mid +/- 0.005, not a live order book) - mid itself is the venue''s observed midpoint, never a model estimate; false = real top-of-book from the live order-book stream; null = unknown (older ticks). The live stream attaches when a match goes live, so pre-match ticks are synthetic: true by design.'
        timestamp:
          type:
          - string
          - 'null'
          format: date-time
          description: When we observed this quote (UTC) - our observation clock, not a venue publication time.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Direct API key: Authorization: Bearer <key>'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key