Initial commit: Arbitrage

2026-05-15 15:06:30 +02:00
commit c9406410ae
12 changed files with 51372 additions and 0 deletions
@@ -0,0 +1,102 @@
+# Odds data schema
+
+Sample file: `odds/data/samples/boxing_odds.json`
+
+Source: [The Odds API](https://the-odds-api.com/) v4 — `GET /sports/{sport}/odds`
+
+## Top level
+
+The response is a **JSON array** of event objects.
+
+```json
+[
+  {
+    "id": "7605c958b8ffbe29c0dcb81e4d2c8a10",
+    "sport_key": "boxing_boxing",
+    "sport_title": "Boxing",
+    "commence_time": "2025-05-10T16:00:00Z",
+    "home_team": "Charlie Senior",
+    "away_team": "Cesar Ignacio Paredes",
+    "bookmakers": [ ... ]
+  }
+]
+```
+
+## Event fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique event id |
+| `sport_key` | string | API sport identifier |
+| `sport_title` | string | Human-readable sport name |
+| `commence_time` | ISO 8601 UTC | Scheduled start |
+| `home_team` | string | Home / first fighter name |
+| `away_team` | string | Away / second fighter name |
+| `bookmakers` | array | List of books offering lines on this event |
+
+## Bookmaker object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | string | Bookmaker slug (e.g. `unibet_uk`) |
+| `title` | string | Display name |
+| `last_update` | ISO 8601 | When this book’s lines were updated |
+| `link` | string \| null | Deep link to event on book site |
+| `sid` | string \| null | Book-specific event id |
+| `markets` | array | Markets offered for this event |
+
+## Market object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | string | Market type: `h2h` (moneyline), `h2h_lay` (exchange lay), etc. |
+| `last_update` | ISO 8601 | Market update time |
+| `outcomes` | array | Selections and prices |
+
+## Outcome object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Fighter name or `Draw` |
+| `price` | number | **Decimal** odds (European format) |
+| `link` | string \| null | Selection deep link |
+| `sid` | string \| null | Selection id at book |
+| `bet_limit` | number \| null | Max stake if provided |
+
+## Implied probability (for arbitrage)
+
+For decimal odds `d`:
+
+```
+implied_probability = 1 / d
+```
+
+For a **single** book’s full market (all mutually exclusive outcomes), sum of implied probabilities &gt; 1 indicates book margin (overround).
+
+**Cross-book arbitrage** (simplified): for each outcome, take the **best** (highest) decimal odds across books, then:
+
+```
+arb_sum = sum(1 / best_odds_i for each outcome i)
+```
+
+If `arb_sum < 1`, a risk-free profit is theoretically possible before fees and limits.
+
+## Normalized row (recommended for future code)
+
+| Column | Example |
+|--------|---------|
+| `event_id` | `7605c958...` |
+| `commence_time` | `2025-05-10T16:00:00Z` |
+| `home_team` | `Charlie Senior` |
+| `away_team` | `Cesar Ignacio Paredes` |
+| `bookmaker_key` | `unibet_uk` |
+| `market_key` | `h2h` |
+| `outcome_name` | `Charlie Senior` |
+| `price` | `1.03` |
+| `implied_prob` | `0.9709` |
+
+## API usage notes
+
+- Responses count against your API quota; check response headers `x-requests-remaining`.
+- Region and market query params filter payload size; sample uses `uk,eu` and `h2h`.
+- Prices are decimal in this project (`oddsFormat=decimal` in fetch script).