# Odds API for AI Agents and LLM Tools

Plain HTTP tool calls, and docs written to be read by a model.

An AI agent needs a tool it can call and answers it can stand behind: a price, the bookmaker that showed it, and when. SockOdds v1 is a plain REST API with one response shape, and every price carries `observed_at`, so an agent can quote a number with its source and time instead of guessing.

## Why SockOdds

- **A contract a model can read.** [/openapi.json](https://sockodds.com/openapi.json) describes every route, parameter and field in OpenAPI 3.1, ready to turn into tool definitions.
- **Docs as plain text.** [/llms.txt](https://sockodds.com/llms.txt) is an index of the docs written for models, and every page has a Markdown twin: replace the trailing slash with `.md`, as in `/docs/odds.md`.
- **Grounded answers.** Each quote has the bookmaker key, `decimal_odds` and `observed_at`, and quotes older than 10 minutes are withheld, so an agent does not repeat stale prices.
- **Readable keys.** Leagues, teams, markets and bookmakers have plain keys such as `rlwc`, `australia_rugby_league`, `winner` and `sportsbet`, which a model can use without a lookup table.
- **Errors an agent can act on.** Problems come back as `application/problem+json` with a `title` and a `detail` that say what went wrong.

## What you can build

### A one-tool agent

Give the agent a single tool that makes a GET request to the API, with your key added on your server, and let it choose the route from the OpenAPI file. Keep the key out of the prompt and out of anything the model can echo.

### A research assistant

Let the agent find a game with `/events?league=`, fetch its odds, and answer with each price, its bookmaker and its `observed_at` time.

### Context for a coding assistant

Point your coding tool at /llms.txt or a page's Markdown twin, so the code it writes uses v1 routes and fields as documented. The [AI tools guide](https://sockodds.com/docs/ai-tools/) has the details.

## Try it

This request lists the Rugby League World Cup games, usually the first call an agent makes.

```bash
curl -sS "https://api.sockodds.com/v1/events?league=rlwc" \
  -H "Authorization: Bearer $SOCKODDS_API_KEY"
```

```javascript
const response = await fetch("https://api.sockodds.com/v1/events?league=rlwc", {
  headers: { Authorization: `Bearer ${process.env.SOCKODDS_API_KEY}` },
});
console.log(JSON.stringify(await response.json(), null, 2));
```

```python
import json, os, urllib.request

request = urllib.request.Request(
    "https://api.sockodds.com/v1/events?league=rlwc",
    headers={"Authorization": "Bearer " + os.environ["SOCKODDS_API_KEY"]},
)
with urllib.request.urlopen(request) as response:
    print(json.dumps(json.load(response), indent=2))
```

Response (from a local copy of the API with invented test prices):

```json
{
  "data": [
    {
      "id": "ev_000ckk0nc1tg",
      "name": "Australia v New Zealand",
      "league": {
        "key": "rlwc",
        "name": "Rugby League World Cup"
      },
      "scheduled_start": "2026-10-15T09:05:00.000Z",
      "status": "scheduled",
      "participants": [
        {
          "role": "away",
          "identity": {
            "key": "new_zealand_rugby_league",
            "name": "New Zealand"
          }
        },
        {
          "role": "home",
          "identity": {
            "key": "australia_rugby_league",
            "name": "Australia"
          }
        }
      ]
    }
  ],
  "meta": {
    "count": 1,
    "cursor": null
  },
  "links": {
    "next": null
  }
}
```

Each game has an `id` the agent passes to `/events/{event_id}/odds`, plus `scheduled_start`, `status` and both participants with readable keys, which is enough for it to match a user's question to the right game.

## Related

- [AI tools guide](https://sockodds.com/docs/ai-tools/)
- [llms.txt](https://sockodds.com/llms.txt)
- [OpenAPI file](https://sockodds.com/openapi.json)
- [Quickstart](https://sockodds.com/docs/quickstart/)
- [Sports odds API for betting apps](https://sockodds.com/use-cases/sports-betting-app-api/)