Use case: AI agents

Sports odds API built for AI agents and LLM tool calls

Q: How do I keep responses small enough for a context window?

Filter at the source with markets and bookmakers , leave alternate lines off, and reshape the response on your server to just the fields the model needs, as in the handler above.

Agents do best with dull, predictable APIs: one GET, stable IDs, fields that say what they mean, and a spec they can read. That is how this one is built, and honest timestamps matter even more when a model is the one reading the response.

Spec

OpenAPI 3.1

The full specification is at sockodds.com/openapi.json, and every page on this site and sockodds.com points to it with rel="service-desc".

Docs for models

llms.txt and the docs

An index at llms.txt and the documentation, with every endpoint and field in the spec beside them.

Plain keys

Keys a model can look up

Leagues, markets and bookmakers have plain keys such as afl, player_disposals_over_under and sportsbet, listed by /v1/leagues, /v1/markets and /v1/bookmakers, so a model looks them up instead of guessing.

Tool definition

One tool is usually enough

Expose a single get_odds tool that calls your own backend, which holds the key and calls the API. Most agent frameworks accept a JSON schema like this one.

get_odds.tool.json

{
  "name": "get_odds",
  "description": "Pre-match odds from Australian bookmakers for one league. Prices refresh about every five minutes. Always report each price's observed_at time and never describe prices as live.",
  "input_schema": {
    "type": "object",
    "properties": {
      "league": { "type": "string", "description": "Exact league key, e.g. afl, nrl, nrlw, epl" },
      "markets": { "type": "string", "description": "Optional comma-separated market keys, e.g. winner,handicap" },
      "bookmakers": { "type": "string", "description": "Optional comma-separated bookmaker keys, e.g. sportsbet,tab" }
    },
    "required": ["league"]
  }
}

Handler

Keep the key behind your server

The handler passes the arguments through and trims the response, so the model reads less and you spend fewer tokens.

handler.py

import os
import requests

def get_odds(league: str, markets: str = "winner", bookmakers: str | None = None) -> list:
    params = {"league": league, "markets": markets}
    if bookmakers:
        params["bookmakers"] = bookmakers
    r = requests.get("https://api.sockodds.com/v1/odds", params=params,
                     headers={"Authorization": f"Bearer {os.environ['SOCKODDS_KEY']}"}, timeout=20)
    r.raise_for_status()
    return [
        {
            "game": e["name"],
            "starts": e["scheduled_start"],
            "status": e["status"],
            "prices": [
                {"book": b["key"], "market": m["key"], "period": m["period"], "outcome": o["name"],
                 "line": o["line"], "decimal": o["decimal_odds"], "seen": o["observed_at"]}
                for b in e["bookmakers"] for m in b["markets"] for o in m["outcomes"]
                if o.get("available")
            ],
        }
        for e in r.json()["data"]
    ]

Guardrails

Rules worth giving the model

Prices are recent, not live. Have the agent quote each price's age from observed_at.
Respect the flags. Use only quotes with available: true. A price not seen for ten minutes is held back, never passed off as current.
Data, not bets. The API cannot place a bet and an agent built on it should not pretend to.
No promises. An edge is an estimate over many bets, never a sure thing. Keep the agent's language that way.

Coding assistants

Building with Claude Code, Cursor or Copilot

Point the assistant at the OpenAPI file or the docs before it writes a line. Real field names in context stop it from inventing plausible ones, which is the usual failure with any odds API. SockOdds keeps a page of copy-ready context for exactly this.

This site has its own llms.txt and plain-text copy of every page too.

Questions

Agents and the API

Can an agent call the API straight from the browser?

It should not. A key in client-side code can be copied by anyone. Route the tool call through your server, which also lets you trim responses before they reach the model.

How do I keep responses small enough for a context window?

Filter at the source with markets and bookmakers, leave alternate lines off, and reshape the response on your server to just the fields the model needs, as in the handler above.

Which docs should I give a coding assistant?

The OpenAPI specification and the SockOdds documentation. Between them they hold every endpoint, parameter and field name.

Start now

Your first Australian price is one request away.

Free key, no card, AFL and NRL included. Keys are issued on sockodds.com.

Get a free key See the quickstart