Historical odds in Python: one event's moves

export ODDSRELAY_KEY="your API key"
python3 main.py or_evt_2d7dd94b072d --bookmaker bet365 --from 2026-10-24T11:00:00Z --to 2026-10-24T15:00:00Z
python3 main.py or_evt_2d7dd94b072d --bookmaker bet365 --from 2026-10-24T11:00:00Z --to 2026-10-24T15:00:00Z --outcome Arsenal

"""The small HTTP helper every example here shares. Each folder keeps an identical copy, so any
folder runs on its own with nothing but the Python standard library."""
from __future__ import annotations

import gzip
import json
import os
import sys
import time
from http.client import HTTPMessage
from typing import Any
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

API = "https://api.oddsrelay.io"


def get(path: str, params: dict, headers: dict | None = None) -> tuple[int, HTTPMessage, Any]:
    """GET one route with gzip: (status, headers, decoded JSON or None). Waits out 429s, exits on errors."""
    key = os.environ.get("ODDSRELAY_KEY", "").strip()  # a stray newline would put the key in a ValueError
    if not key:
        sys.exit("set ODDSRELAY_KEY to your API key")
    query = urlencode({k: v for k, v in params.items() if v is not None})
    for attempt in range(3):
        req = Request(f"{API}{path}" + (f"?{query}" if query else ""), headers={
            "Authorization": f"Bearer {key}", "Accept-Encoding": "gzip", **(headers or {})})
        try:
            with urlopen(req, timeout=30) as res:
                status, hdrs, body = res.status, res.headers, res.read()
        except HTTPError as err:  # urllib raises for 304 and for every 4xx and 5xx
            status, hdrs, body = err.code, err.headers, err.read()
        except URLError as err:
            sys.exit(f"could not reach {API}: {err.reason}")
        if body and hdrs.get("Content-Encoding") == "gzip":
            body = gzip.decompress(body)
        if status == 429:  # rate-limited: wait as long as the reply says, unless that was the last try
            if attempt < 2:
                time.sleep(int(hdrs.get("Retry-After", "1")))
            continue
        if status >= 400:
            error = json.loads(body).get("error", {}) if body[:1] == b"{" else {}
            sys.exit(f"HTTP {status} {error.get('code', '')}: {error.get('message', '')} "
                     f"(request id {error.get('request_id', '-')})")
        return status, hdrs, json.loads(body) if body else None
    sys.exit("still rate-limited after 3 tries")


def afford(quote: dict, max_tokens: int | None) -> bool:
    """True when a quoted price is fine: free, within --max-tokens, or confirmed at the prompt."""
    left = "unknown" if quote["remaining"] is None else quote["remaining"]
    print(f"quote: {quote['cost']} tokens ({left} left)", file=sys.stderr)
    if quote["cost"] == 0 or (max_tokens is not None and quote["cost"] <= max_tokens):
        return True
    if max_tokens is None and sys.stdin.isatty():
        print("fetch it? [y/N] ", end="", file=sys.stderr, flush=True)  # stderr: stdout may be redirected
        return input().strip().lower() == "y"
    return False

"""One bookmaker's price changes for one event over a window, with the recording gaps.

Run: ODDSRELAY_KEY=<your key> python3 main.py <event id> --bookmaker bet365 --from <time> --to <time>
"""
from __future__ import annotations

import argparse
import sys
from typing import Iterator

from api import afford, get


def pages(path: str, params: dict) -> Iterator[dict]:
    """Every page of the window, following next_cursor until it is null."""
    cursor = None
    while True:
        page = get(path, {**params, "cursor": cursor})[2]
        yield page
        cursor = page["meta"]["next_cursor"]
        if cursor is None:
            return


def report(rows: list[dict], outcome: str | None) -> int:
    """Print a line per row, in order, and return how many rows moved a price the code already held."""
    held: dict[tuple, float | None] = {}
    moves = 0
    for row in rows:
        if outcome and row["outcome"] != outcome:
            continue
        key = (row["outcome"], row.get("index", 0))
        name = f"{row['outcome']} ({key[1] + 1})" if key[1] else str(row["outcome"])
        if row.get("removed"):
            print(f"{row['timestamp']}  {name}  left the board")
            held[key] = None
            continue
        if held.get(key) is not None and row["price"] != held[key]:
            moves += 1
        print(f"{row['timestamp']}  {name}  {row['price']}")
        held[key] = row["price"]
    return moves


def main() -> None:
    ap = argparse.ArgumentParser(description="Print one bookmaker's price changes for one event.")
    ap.add_argument("event_id")
    ap.add_argument("--bookmaker", required=True, help="one bookmaker key, such as bet365")
    ap.add_argument("--from", dest="start", required=True, help="the window's start, ISO 8601")
    ap.add_argument("--to", dest="end", required=True, help="the window's end, at most 24 hours later")
    ap.add_argument("--market", default="h2h", help="one market key")
    ap.add_argument("--outcome", help="one outcome's name; every outcome when left out")
    ap.add_argument("--max-tokens", type=int, help="spend up to this many tokens a page without asking")
    args = ap.parse_args()
    path = f"/v2/historical/events/{args.event_id}/odds"
    params = {"from": args.start, "to": args.end, "bookmakers": args.bookmaker, "markets": args.market}
    if not afford(get(path, {**params, "quote": "true"})[2], args.max_tokens):
        sys.exit("not fetched: pass --max-tokens, or say yes at the prompt")
    rows, gaps = [], []
    for page in pages(path, params):
        rows += page["data"]
        gaps += page["meta"]["gaps"]
    print(f"{report(rows, args.outcome)} moves")
    for gap in gaps:
        print(f"recording gap at {gap['timestamp']}: {gap.get('why') or 'no reason given'}")


if __name__ == "__main__":
    main()

2026-10-24T10:59:59.543Z  Arsenal  1.42
2026-10-24T10:59:59.543Z  Draw  4.5
2026-10-24T10:59:59.543Z  Everton  8.0
2026-10-24T13:05:29.852Z  Draw  4.75
2026-10-24T13:05:29.852Z  Everton  7.0
2026-10-24T13:25:39.499Z  Arsenal  1.4
2026-10-24T13:25:39.499Z  Draw  5.0
2026-10-24T13:32:26.339Z  Arsenal  1.38
2026-10-24T13:32:26.339Z  Everton  7.5
2026-10-24T13:33:56.907Z  Arsenal  1.364
2026-10-24T13:33:56.907Z  Everton  8.0
2026-10-24T14:00:04.326Z  Arsenal  left the board
2026-10-24T14:00:04.326Z  Draw  left the board
2026-10-24T14:00:04.326Z  Everton  left the board
8 moves

{
  "meta": {
    "feed_type": "historical_event",
    "event_id": "or_evt_da71d5873e85",
    "ids": ["or_evt_da71d5873e85"],
    "from": "2026-10-16T19:00:00.000Z",
    "to": "2026-10-16T19:45:00.000Z",
    "count": 2,
    "next_cursor": null,
    "historical": true,
    "gaps": []
  },
  "data": [
    {
      "timestamp": "2026-10-16T18:59:58.120Z",
      "event_id": "or_evt_da71d5873e85",
      "bookmaker": "bet365",
      "market": "h2h",
      "outcome": "Arsenal",
      "price": 2.2,
      "last_update": "2026-10-16T18:59:51Z"
    },
    {
      "timestamp": "2026-10-16T19:12:03.441Z",
      "event_id": "or_evt_da71d5873e85",
      "bookmaker": "bet365",
      "market": "h2h",
      "outcome": "Arsenal",
      "price": 2.1,
      "last_update": "2026-10-16T19:12:01Z"
    }
  ]
}