# MatchPrior SDKs

Tiny, **zero-dependency** clients for the MatchPrior sports-prediction API — one file each,
nothing to install beyond the standard library. Full reference: <https://matchprior.com/docs.html>
· OpenAPI 3.1: <https://matchprior.com/openapi.yaml>

Get a key at <https://matchprior.com/pricing.html>. Authenticate with the `X-API-Key` header
(both clients do this for you). Every response carries `X-RateLimit-*` headers; a `429` means
you are over your monthly quota (both clients surface `retry_after` / `retryAfter`).

## TypeScript / JavaScript — `matchprior.ts`

Works anywhere `fetch` exists (Node 18+, Deno, browsers, Cloudflare Workers). No build needed
for JS; for TS, drop it in your project.

```ts
import { MatchPrior, MatchPriorError } from './matchprior.js';

const mp = new MatchPrior({ apiKey: process.env.MP_KEY! });

const { data } = await mp.predictions({ sport: 'football', limit: 5 });
for (const p of data) console.log(p.fixture.home, 'vs', p.fixture.away, '→', p.pick, p.fairOdds);

// Auto-paginate every upcoming tennis fixture:
for await (const p of mp.iterate('/v1/predictions', { sport: 'tennis' })) console.log(p.pick);

try {
  await mp.backtest({ sport: 'football' }); // Pro tier
} catch (e) {
  if (e instanceof MatchPriorError && e.status === 403) console.log('upgrade needed:', e.body);
}
```

## Python — `matchprior.py`

Standard library only (Python 3.8+).

```python
from matchprior import MatchPrior, MatchPriorError

mp = MatchPrior(api_key="mp_live_…")

page = mp.predictions(sport="football", limit=5)
for p in page["data"]:
    print(p["fixture"]["home"], "vs", p["fixture"]["away"], "→", p["pick"], p["fairOdds"])

# Auto-paginate:
for p in mp.iterate("/v1/predictions", sport="tennis"):
    print(p["pick"])

try:
    mp.backtest(sport="football")   # Pro tier
except MatchPriorError as e:
    if e.status == 429:
        print("over quota, retry after", e.retry_after, "seconds")
```

## What you get by tier

| | Free | Dev | Pro | Business |
|---|---|---|---|---|
| Quota / month | 250 | ~20k | ~150k | ~1M |
| Sports | 1 (assigned) | all 11 | all 11 | all 11 |
| `predictions` (probs, `fairOdds`, pick) | ✓ | ✓ | ✓ | ✓ |
| `/v1/accuracy` (the track record) | ✓ | ✓ | ✓ | ✓ |
| `/v1/ratings` (Elo) | — | ✓ | ✓ | ✓ |
| `rationale` + projected scores | — | — | ✓ | ✓ |
| `/v1/backtest` | — | — | ✓ | ✓ |

`fairOdds` is MatchPrior's own model-derived line (`1 / probability`) — our IP, never a resold
bookmaker price. These are calibrated probabilities for information, **not** betting advice.