# SportMkt API Documentation

> Real-time sports prediction market data. No signup required — every visitor gets an API key automatically.

**Base URL:** `https://sportmkt.live/api/v1`

---

## Authentication

Every request returns your API key in the `X-Api-Key` response header. For persistent identity, send it back on subsequent requests:

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

Browsers receive a cookie automatically. Bots and AI agents should store and reuse the `X-Api-Key` header value from the first response.

---

## Token System

Every API call costs **1 token**. Your tier determines how many tokens you get:

| 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 |

Check your current usage and limits: `GET /api/v1/me`

---

## Endpoints

### GET /api/v1/me

Your API key, tier, token usage, and rate limits.

**Response:**

```json
{
  "api_key": "sd_abc123...",
  "visitor_type": "bot",
  "tier": "free",
  "tokens_today": 42,
  "tokens_total": 1337,
  "limits": {
    "tokens_per_minute": 30,
    "tokens_per_day": 2000
  },
  "member_since": "2026-03-12T00:00:00Z"
}
```

---

### GET /api/v1/events

List active events sorted by 24h volume.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sport` | string | Filter by sport slug (e.g. `tennis`, `basketball`, `esports`) |
| `league` | string | Filter by league name |
| `live` | boolean | Set to `true` for live events only |
| `limit` | integer | Max results (default `50`, max `200`) |
| `offset` | integer | Pagination offset |

**Example:**

```http
GET /api/v1/events?sport=tennis&live=true&limit=10
```

**Response fields per event:** `title`, `slug`, `sport`, `league`, `teams`, `score`, `period`, `live`, `volume_24h`, `liquidity`, `market_count`, `odds`, `tags`

---

### GET /api/v1/events/:slug

Full event detail with all markets and outcomes.

**Example:**

```http
GET /api/v1/events/atp-napolit-neuchri-2026-03-11
```

**Response includes:**

- Event metadata: title, sport, league, teams, score, status
- All markets: moneyline, set winner, over/under, totals
- Per market: outcomes, prices (probabilities), decimal odds, CLOB token IDs, best bid/ask, spread, 24h volume

---

### GET /api/v1/events/:slug/markets

Markets only for a given event — lighter payload than the full event endpoint.

**Example:**

```http
GET /api/v1/events/atp-napolit-neuchri-2026-03-11/markets
```

---

### GET /api/v1/live

All currently live events with real-time scores and moneyline odds. Optimized for dashboards and tickers.

**Response:**

```json
{
  "live_events": [
    {
      "title": "Player A vs Player B",
      "slug": "atp-playera-playerb-2026-03-19",
      "sport": "tennis",
      "score": "6-4, 3-2",
      "period": "Set 2",
      "odds": { "home": 0.62, "away": 0.38 }
    }
  ]
}
```

---

### GET /api/v1/sports

List of available sports with event counts and total 24h volume.

**Response:**

```json
{
  "sports": [
    {
      "sport": "tennis",
      "event_count": 45,
      "live_count": 12,
      "total_volume_24h": 125000
    }
  ]
}
```

---

### GET /api/v1/leagues

List leagues, optionally filtered by sport.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sport` | string | Filter by sport slug |

---

### GET /api/v1/tags

All Polymarket category tags with event counts.

---

### GET /api/v1/usage

Your hourly token usage — useful for building consumption dashboards.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `hours` | integer | Lookback window (default `24`, max `168`) |

---

### GET /api/v1/pricing

All tiers with pricing, token limits, and feature details.

---

### GET /api/v1/token-costs

Token cost per endpoint.

---

### GET /api/v1/health

System status check. **Costs 0 tokens.**

**Response:**

```json
{
  "status": "ok",
  "timestamp": "2026-03-19T12:00:00Z"
}
```

---

## Rate Limiting

When you exceed your token limit the API returns **HTTP 429**:

```json
{
  "error": "Rate limit exceeded",
  "message": "You've used all 30 tokens/minute on the free tier. Upgrade for more.",
  "tier": "free",
  "tokens_per_minute": 30,
  "upgrade": { "url": "/pricing" },
  "your_api_key": "sd_..."
}
```

**Rate limit headers on every response:**

| Header | Description |
|--------|-------------|
| `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 |

---

## Market Types

| Type | Description |
|------|-------------|
| `moneyline` | Match winner |
| `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** in the range `0.00`–`1.00`. Markets are binary (Yes/No) or multiple-choice.

---

## Data Source

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

---

## Quick Start (Python)

```python
import requests

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

# Step 1: get your API key (auto-assigned on first request)
me = requests.get(f"{BASE}/me").json()
key = me["api_key"]
print(f"Key: {key}  Tier: {me['tier']}  Tokens today: {me['tokens_today']}")

# Step 2: 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']}")

# Step 3: fetch all tennis events
events = requests.get(
    f"{BASE}/events",
    params={"sport": "tennis", "limit": 20},
    headers={"X-Api-Key": key}
).json()
for ev in events["events"]:
    print(f"{ev['title']}  vol={ev['volume_24h']}")
```

---

## Quick Start (curl)

```bash
# Your key is in the X-Api-Key response header
curl -s https://sportmkt.live/api/v1/me | python3 -m json.tool

# Save your key
KEY=$(curl -sI https://sportmkt.live/api/v1/health | grep -i x-api-key | awk '{print $2}' | tr -d '\r')

# Live events
curl -s https://sportmkt.live/api/v1/live -H "X-Api-Key: $KEY" | python3 -m json.tool

# Tennis events
curl -s "https://sportmkt.live/api/v1/events?sport=tennis" -H "X-Api-Key: $KEY" | python3 -m json.tool
```

---

## Content Negotiation

This API is agent-friendly. Omit `text/html` from your `Accept` header (or send `Accept: application/json`) and the server returns machine-readable formats:

- `GET /` → JSON API index with your key and all endpoint paths
- `GET /docs` → raw Markdown (this document)
- All `/api/v1/*` routes → JSON always

Bots and AI agents are automatically detected by `User-Agent` and served the appropriate format without needing special headers.