# SportMkt

> Real-time sports prediction market data API — live scores, market odds, and probabilities from Polymarket

## What this site provides

SportMkt exposes Polymarket prediction market data for sports events as a clean REST JSON API. Every event has market-implied win probabilities (0.00–1.00), best bid/ask spreads, 24h volume, and live scores. Sports covered: tennis, basketball, baseball, hockey, soccer, MMA, esports (CS2, League of Legends, Dota 2), American football, cricket, golf.

## API Base URL

```
https://sportmkt.live/api/v1
```

## Authentication

No signup required. Your API key is **auto-assigned** on first request and returned in the `X-Api-Key` response header. Send it back on subsequent requests for persistent identity and usage tracking.

```
X-Api-Key: sd_your_key_here
```

Free tier: **30 tokens/min, 2,000 tokens/day** — no credit card needed.

## Key Endpoints

| Method | Path | Description | Token cost |
|--------|------|-------------|-----------|
| GET | /api/v1/me | Your API key, tier, and token usage | 1 |
| GET | /api/v1/events | All active events (filter by sport, league, live) | 1 |
| GET | /api/v1/events/{slug} | Full event detail with all markets | 1 |
| GET | /api/v1/events/{slug}/markets | Markets only (lighter payload) | 1 |
| GET | /api/v1/live | All currently live events with scores | 1 |
| GET | /api/v1/sports | Available sports with event counts | 1 |
| GET | /api/v1/leagues | Leagues, filterable by sport | 1 |
| GET | /api/v1/tags | All tags with event counts | 1 |
| GET | /api/v1/usage | Your hourly token usage | 1 |
| GET | /api/v1/pricing | Tier pricing and limits | 1 |
| GET | /api/v1/token-costs | Token cost per endpoint | 1 |
| GET | /api/v1/health | System status | **0** |

## Query Parameters

**GET /api/v1/events**
- `sport` — filter by sport slug (e.g. `tennis`, `basketball`, `esports`)
- `league` — filter by league name
- `live` — `true` for live events only
- `limit` — max results (default 50, max 200)
- `offset` — pagination offset

**GET /api/v1/usage**
- `hours` — lookback window (default 24, max 168)

**GET /api/v1/leagues**
- `sport` — filter by sport slug

## Response Headers (every response)

- `X-Api-Key` — your assigned API key
- `X-RateLimit-Limit` — tokens per minute for your tier
- `X-RateLimit-Remaining` — tokens remaining this minute
- `X-RateLimit-Daily-Limit` — tokens per day
- `X-RateLimit-Daily-Remaining` — tokens remaining today

## Rate Limit Response (HTTP 429)

```json
{
  "error": "Rate limit exceeded",
  "tier": "free",
  "tokens_per_minute": 30,
  "upgrade": { "url": "/pricing" },
  "your_api_key": "sd_..."
}
```

## Token Tiers

| Tier | Price | Tokens/min | Tokens/day |
|------|-------|-----------|-----------|
| Free | $0 | 30 | 2,000 |
| Basic | $19/mo | 60 | 10,000 |
| Pro | $79/mo | 300 | 100,000 |
| Enterprise | Custom | 1,000 | 1,000,000 |

## Market Types

- `moneyline` — match winner probability
- `tennis_first_set_winner` — first set winner
- `tennis_set_totals` — total sets over/under
- `tennis_match_totals` — total games over/under
- `tennis_first_set_totals` — first set games over/under

Prices are market-implied probabilities (0.00 = 0%, 1.00 = 100%). Outcomes are binary (Yes/No) or multiple-choice.

## Content Negotiation

This API supports agent-friendly content negotiation:
- `GET /` with `Accept: application/json` → returns JSON API index
- `GET /docs` with `Accept: application/json` → returns raw Markdown documentation
- Bots and AI agents are automatically detected and served the appropriate format

## Quick Start

```python
import requests

BASE = "https://sportmkt.live/api/v1"

# Get your API key (auto-assigned)
me = requests.get(f"{BASE}/me").json()
key = me["api_key"]

# Fetch live events
live = requests.get(f"{BASE}/live", headers={"X-Api-Key": key}).json()
for ev in live["live_events"]:
    print(f"{ev['title']} — {ev['score']} — {ev['odds']}")

# Fetch tennis events
events = requests.get(f"{BASE}/events?sport=tennis&limit=20", headers={"X-Api-Key": key}).json()
```

## Full Documentation

https://sportmkt.live/docs

## Data Source

All market data sourced from [Polymarket](https://polymarket.com) via their Gamma API and real-time sports WebSocket.