What it is

A sportsbook price is a probability wearing a costume, and every data source dresses it differently. This project is the unglamorous, exacting work of making five heterogeneous odds feeds — PropLine, MoneyLine, The Odds API, SportsGameOdds and Unabated — behave like one instrument, and of giving the agents who read that instrument a mathematical framework they cannot improvise around.

It runs as a twice-daily scan. Each feed is wrapped in its own connector (a small client plus a written contract of its quirks), pulled on a quota-aware schedule, normalised into a single merged board of events, and screened for the one quantity that matters: the overround of the best cross-book pair — take the shortest price on each side of an event, wherever it is offered, convert both to implied probabilities, and add them. If the sum is below 1, the pair locks a profit regardless of outcome; the distance below (or above) 1 is the market’s price for the hedge, and the scan ranks every event by it.

The mathematics

Three conversions do most of the work, and all of them live in one 501-line, standard-library-only Python module, hedge.py, with its own test suite:

  • Odds are probabilities. American odds are an encoding, not a number type: to_decimal parses +158 / −194 / 2.58 into decimal odds, and implied probability is simply 1/d. Most downstream confusion in this domain is a parsing bug wearing a suit.
  • Overround is the vig, made visible. overround(ds) = Σ 1/dᵢ − 1. A single book’s overround is its margin; the cross-book overround of the best pair is the screening statistic for the whole scan — observed tightest pairs run at 0.4–1.2%, i.e. two competing books jointly pricing an event to within a percent of fair.
  • De-vig before you judge. fair_prob normalises a side’s implied probability by the total implied probability of all outcomes — the standard way to recover an estimate of the market’s true belief from prices that sum to more than 1.
  • An offset is an equation, not a hunch. Take a position that pays B·(dp−1) if one outcome lands, and offset it with a cash stake H at decimal dh on the other. The lock condition is B·(dp−1) = H·dh, so H = B·(dp−1)/dh — floored to the cent, because rounding up an offsetting stake silently spends cash you may not have. Every offsetting shape the framework supports (multi-book splits, dutching, closing out an existing position) is the same move: write both outcomes explicitly, solve for the stake that equalises them, and show the caller both numbers rather than asking it to trust the lock.

Connecting five sources that disagree

The feeds disagree structurally, and each disagreement is a distinct engineering problem:

  • Identity is per-source. The same sportsbook appears under unrelated keys in different feeds — one major book is carried only under its corporate parent’s key (williamhill_us) and was “absent” from an early coverage audit purely because the audit searched for the literal name. Book identity is a mapping table, maintained and re-verified, not a string match.
  • Parameters fail silently. One feed’s league parameter accepts ncaa_basketball and ncaa_football — and returns an empty, successful response for ncaab, ncaaf, or any uppercase variant. Empty is a valid HTTP 200. The defence is a liveness discipline: a pull that returns zero rows for a league known to have games is treated as an error, never as a quiet day.
  • Events don’t match across feeds. Team naming and start-time conventions differ enough that an early merged board carried the same game twice under variant names. Canonicalisation (normalised team/event identity) took split games from 81 duplicate entries to zero on the 2026-11-11 board of 68 unique games.
  • Quotas are a budget, not a limit message. The feeds price attention differently: per-pull credits, per-day event caps, rate spacing. The scan schedule is built from those budgets — every feed in the morning pull; only the unmetered three in the afternoon — so the system never spends its last credit discovering it needed one.
  • Coverage is stated, not assumed. The merged board knows its own blind spots: which books no public feed carries, which source IDs were last re-verified when. A board that claims full coverage and has 60% is worse than a board that says 5 of 9.

The agent framework

The scan is run by AI agents, so the framework’s most important component is a rule, not a library: every number in an output comes from the calculator, never from a model’s arithmetic. hedge.py exposes a JSON-in/JSON-out interface, so an agent invokes stake mathematics the way it invokes any other tool — and the rule exists because the failure mode is documented, not hypothetical: earlier hand calculations produced mis-sized stakes and wrongly transcribed odds — exactly the class of error a deterministic calculator makes impossible. Screening is likewise fenced: the feeds are for discovering candidate events; any number that would be acted on must be re-read at the source, in the moment, by the human whose account it is. Public feeds only; the framework never touches a bookmaker session.

Code

hedge.py (exact):

def to_decimal(o) -> float:
    """Parse American or decimal odds into decimal odds."""
    if isinstance(o, (int, float)):
        v = float(o)
        if abs(v) >= 100:
            return 1 + v / 100 if v > 0 else 1 + 100 / abs(v)
        if v > 1:
            return v
        raise ValueError(f"unparseable odds: {o}")
def overround(ds: Sequence[float]) -> float:
    """Total implied probability minus 1 — the market's vig on the hedge pair."""
    return sum(1 / d for d in ds) - 1

Achievements

  • All five feeds verified live 2026-11-08 and integrated as individual connectors, each with its quirks (keys, league IDs, quotas, failure modes) written into its own connector contract.
  • Twice-daily scans running on a quota-aware schedule; a representative merged board (2026-11-11): 68 unique games, zero split duplicates after canonicalisation.
  • Coverage accounting kept honest in the scan reports themselves: merged coverage stated as a fraction (5 of 9 books), with the uncovered set named.

Lessons

  • Silent success is the worst failure mode in data engineering. Every dangerous bug in this system returned HTTP 200: the wrong league ID, the missing book under a parent key, the duplicated game. Liveness and identity checks are the system; the API calls are the easy part.
  • Never let a language model do arithmetic you can compile. Models are for judgement — which events matter, which offers are real. Stake sizes are a solved equation; route them to a solver.
  • A rule of thumb is a liability with good PR. The (1 − 1/dp) shortcut is simple, popular and wrong by points, not pennies, on realistic prices. The framework’s job is to make the exact computation easier to reach than the approximation.

Status: Active · Python (stdlib only), five API connectors, cron scans, JSON tool interface for agents