# SportStatsAPI

> Sports data API: fixtures, live scores, results, match events, lineups, box scores, play-by-play, standings, teams and players for soccer, basketball, baseball, hockey, tennis, handball, volleyball, American football and horse racing. Strong on lower leagues (for example the German Regionalliga with official DFB data). Names in English, German, Spanish, Italian and French.

Base URL: https://api.sportstatsapi.com/api/v1
Docs (OpenAPI): https://api.sportstatsapi.com/swagger/index.html

## Access

- API key in the header `Authorization: Bearer <key>` (or `X-API-Key: <key>`). Keys can be limited to sports or to single leagues.
- Rate limit per key per minute; every answer carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`; 429 with `Retry-After` when exceeded.
- Answers: `{"success": true, "data": ..., "meta": {"total", "limit", "offset"}}`; errors: `{"success": false, "error": {"code", "message"}}`.
- `?lang=de|es|it|fr` translates team, league and country names.
- Times are UTC. Dates are `YYYY-MM-DD`.

## Pay per call (AI agents, no signup)

Without an API key, paid endpoints answer `402 Payment Required` with x402 payment offers (USDC on Base, settled by P2Flux). Pay with any x402 client (for example the P2Flux MCP, https://agent.p2flux.com/mcp) and repeat the request with the `PAYMENT-SIGNATURE` header. One payment, one answer; errors (404, 400) are never charged.

- Free: /sports, /{sport}/leagues
- $0.002: lists (matches, live matches, standings, team search, injuries, horse racing lists)
- $0.005: one item (a match and its stats, lineups, injuries, play-by-play; a team or squad; a player; a race)
- $0.02: a match or team briefing (/{sport}/matches/{id}/briefing, /{sport}/teams/{id}/briefing, /tennis/players/{id}/briefing)
- These prices apply from a prepaid balance (deposit once, at least 1 USDC; calls are taken from it; the unused rest can be withdrawn). A single payment per call settles on chain and costs at least $0.01.
- Offers and samples: https://api.sportstatsapi.com/.well-known/x402

## MCP (for AI assistants)

Endpoint: https://mcp.sportstatsapi.com/mcp (streamable HTTP; also https://api.sportstatsapi.com/api/mcp)
Header: `Authorization: Bearer <key>`
Tools: list_sports, find_leagues, find_teams, get_matches, get_live_matches, get_match, get_match_briefing, get_team_briefing, get_match_details, get_standings, get_team, get_player.

Claude Code: `claude mcp add --transport http sportstats https://mcp.sportstatsapi.com/mcp --header "Authorization: Bearer <key>"`

## Main endpoints ({sport} = soccer, basketball, baseball, hockey, tennis, handball, volleyball, american-football)

- GET /sports: sports available to the key
- GET /{sport}/leagues: leagues and ids (`?future=true`: only with upcoming matches)
- GET /{sport}/matches: matches by `date`, `date_from`/`date_to`, `league_id`, `league_name`, `status`; paging `limit`, `offset`
- GET /{sport}/matches/live: matches in play
- GET /{sport}/matches/{id}: one match with events
- GET /{sport}/matches/{id}/briefing (every sport): ready context for one match (form, streaks, home and away records, head-to-head, table and gaps, stakes, schedule, injuries, lineups), each statement also as a sentence; `?lang=`, `?format=md`. Facts only, no predictions.
- GET /{sport}/facts?league_id=&since=: what finished matches changed (story, runs, table), newest first, as facts and sentences
- GET /{sport}/teams/{id}/briefing (tennis: /tennis/players/{id}/briefing): a team's form, streaks, records, table place, last and next match, injuries; same options. After a match, the match briefing adds the story (comeback, late winner, red cards).
- GET /soccer/matches/{id}/stats, /lineups, /injuries
- GET /{sport}/matches/{id}/stats (box score), /play-by-play (basketball, baseball, hockey, tennis, american-football)
- GET /{sport}/leagues/{id}/standings
- GET /{sport}/teams?q=name, /teams/{id}, /teams/{id}/squad
- GET /{sport}/players/{id}
- GET /horse-racing/races, /races/{id}, /races/{id}/runners, /races/{id}/results, /meetings

## Notes

- Lower-league soccer: results and official details (lineups, goal and card minutes) appear about 30 minutes after the final whistle where an official source exists.
- Team logos and player photos are linked (`logo_url`, `photo_url`); image rights are not included in the licence.
- Data older than the current and the last season is served from the archive (header `X-Data-Tier: archive`, slower).