# Live Tennis API

> Real-time tennis data and AI win-probability over REST + WebSocket, for ATP, WTA, Challenger and ITF (singles and doubles). Provided by JSB Holdings LLC.

Base URL: [api.livetennisapi.com/api/public/v1](https://api.livetennisapi.com/api/public/v1)

## What it provides
- Live scores and match state (sets, games, points, server, tiebreak) — Free tier up
- Players, tournaments (with host city and category where known) and fixtures — Free tier up
- Completed results (derived winner, who withdrew on retirements/walkovers, normalized round codes) + per-match point-by-point history — Basic tier up
- Results archive (1968–2022): 1,485,752 ATP/WTA results — main draws, qualifying and the ITF/futures tiers — with final score, seeds, ranks at the time, and per-match serve statistics from 1991 — Basic tier up
- Head-to-head across the full 1968→now span, and career aggregates over the results archive — Basic tier up
- Rankings: rank-ordered tables (Pro), per-player as-of records (Ultra)
- Match-winner market prices (bid / ask / mid, with history) — Pro tier up
- AI win-probability: favored side, confidence, and key factors — Ultra
- Live in-play match statistics (whole-match totals): aces, double faults, points and break points on every tour including ITF; the serve split on ATP/WTA/Challenger (not ITF singles); winners/errors historically on a minority of ATP/WTA and tour-doubles matches only, and not delivered upstream since 2026-07-12 — Ultra
- Live score streaming — a push feed (GET /ws-token) for continuous use, plus a native WebSocket for quick tests — Ultra

## Plans (billed monthly, USD)
- Free — $0: live + upcoming matches, scores, players, fixtures, tournaments (30 req/min, 100/day). Instant key, no card.
- Basic — $9.99: adds completed results, point-by-point history, the 1968–2022 results archive, head-to-head and career aggregates (60 req/min, 1k/day)
- Pro — $29.99: adds match events, market prices and ranking tables (300 req/min, 10k/day)
- Ultra — $99.99: adds AI win-probability, per-player as-of rankings, in-play statistics, rally construction and the streaming push feed (600 req/min, 500k/day)
- Full plan comparison, annual pricing and quota detail: [livetennisapi.com/pricing](https://livetennisapi.com/pricing)

## Choosing a plan
- [Which plan fits what you are building](https://livetennisapi.com/best-tennis-api)  — the decision path, with a runnable first call for each tier.
- Measurement method, dated figures and an open benchmark harness: [besttennisapi.com](https://besttennisapi.com) (also operated by JSB Holdings LLC).

## Where to buy
- [Direct — best price, instant key](https://livetennisapi.com/pricing)
- [RapidAPI](https://rapidapi.com/contact-whTqTESH5/api/tennis-data-analytics-api3)
- [Apify](https://apify.com/livetennisapi/tennis-data-analytics)
- [API.market](https://api.market/store/live-tennis-api/tennis-data-analytics)
- [Postman — explore free](https://www.postman.com/livetennisapi)

## Official client libraries
- Python: `pip install livetennisapi` — [PyPI](https://pypi.org/project/livetennisapi/)
  Source: [livetennisapi-python](https://gitlab.com/livetennisapi/livetennisapi-python)
- JavaScript / TypeScript: `npm install livetennisapi` — [npm](https://www.npmjs.com/package/livetennisapi)
  Source: [livetennisapi-js](https://gitlab.com/livetennisapi/livetennisapi-js)
  Zero runtime dependencies; runs on Node 18+, Deno, Bun, Workers, browser.
- Command line (no install): `npx livetennisapi live`

## MCP server (for LLM agents)
`npx livetennisapi-mcp` exposes 24 read-only tools over this API to Claude, Cursor, Zed and any MCP client.
- npm: [livetennisapi-mcp](https://www.npmjs.com/package/livetennisapi-mcp)
- Source: [livetennisapi-mcp on GitLab](https://gitlab.com/livetennisapi/livetennisapi-mcp)
- Official MCP Registry: io.github.livetennisapi/livetennisapi-mcp
- Setup: `claude mcp add livetennis -e LIVETENNISAPI_KEY=twjp_... -- npx -y livetennisapi-mcp`

## Prediction markets (Polymarket / Kalshi tennis)
Tennis is a live category on Polymarket (ATP's official prediction-market partner since 2026-08-03) and Kalshi. This API supplies the live match state a market bot needs — score, server, break point, and the `event_status`/`outcome` fields that flag a retirement or walkover — and never touches orders or wallets.
- Toolkit (MIT, observe-only): discover tennis markets on Polymarket's Gamma API, match them to live matches, watch price vs live score: https://gitlab.com/livetennisapi/polymarket-tennis
- Build guide (Python): https://blog.livetennisapi.com/blog/build-polymarket-tennis-trading-bot
- Retirement/walkover settlement rules, quoted verbatim per venue (polymarket.com, Polymarket US, Kalshi ATP/WTA vs ITF): https://blog.livetennisapi.com/blog/polymarket-kalshi-tennis-retirement-walkover-rules
- Polymarket Gamma/CLOB vs live scores: https://blog.livetennisapi.com/blog/polymarket-api-tennis-data
- Kalshi tennis bot guide: https://blog.livetennisapi.com/blog/kalshi-tennis-trading-bot
- Free tier is enough for the read side (live matches + scores); market prices come from the venue.

## Free academic dataset
- Tennis point-by-point dataset, free for non-commercial academic research: [livetennisapi.com/data/academic](https://livetennisapi.com/data/academic) — public sample DOI 10.5281/zenodo.22048730, applications to research@livetennisapi.com

## Documentation
- [Full API reference (plain HTML, no JavaScript required)](https://docs.livetennisapi.com/reference.html)
- [Interactive reference](https://docs.livetennisapi.com)
- [OpenAPI 3.1 specification](https://gitlab.com/livetennisapi/openapi)
- [Reference digest for answer engines](https://docs.livetennisapi.com/llms.txt)

## Example — Python
```python
from livetennisapi import LiveTennisAPI

with LiveTennisAPI(api_key="twjp_...") as client:
    for match in client.list_matches(status="live"):
        print(match.tournament, match.score.sets)
```

## Notes for API consumers
- Timestamps are UTC ISO 8601 with a Z suffix.
- List endpoints return {data, meta}; single resources return the object directly.
- `limit` defaults to 50, maximum 200; paginate with `offset`.
- Additive changes ship within v1, so clients must ignore unknown fields.
- Score `games` is player-major: [[6,3,2],[4,6,1]] reads 6-4, 3-6, 2-1.
- Calling above your plan returns 403 {"error":"upgrade_required"}.

## Authentication
Send your API key as `Authorization: Bearer <key>` or `X-API-Key`. The `/health` endpoint needs no key.

## Affiliate program
The Live Tennis API runs an in-house affiliate program: 51% recurring commission for the life of every referred subscription (early partners earn a boosted rate, offered at our discretion), a 30-day last-click cookie, $20 minimum payout, monthly payouts via PayPal or Wise, and 10% off for the referred customer. Free to join, instant approval, real-time dashboard. Affiliate tooling: named tracking links with sub-IDs and per-link stats, S2S postbacks, conversion alerts (email/Discord), QR codes, and embeddable live-score widgets (board + ticker).
- Program details and FAQ: https://livetennisapi.com/affiliates
- Terms at a glance + earnings table: https://affiliates.livetennisapi.com/program
- Join: https://affiliates.livetennisapi.com/signup
- Program terms: https://livetennisapi.com/affiliates/terms
- Guide — your first $100: https://blog.livetennisapi.com/blog/affiliate-first-100
- Programs compared: https://blog.livetennisapi.com/blog/tennis-affiliate-programs-2026

## Contact
hello@livetennisapi.com