# bet365 API docs: bet365 odds API and odds feed reference

> Independent. Not affiliated with, endorsed by or sponsored by bet365.

Canonical: https://thebet365api.com/docs


thebet365api.com is an independent, unofficial bet365 odds API: bet365 prices as republished by public odds aggregators, served as JSON over REST and MCP, each price stamped with the UTC time our collector observed it.

**Free plan: 100 requests a month, no card.** Sign up: https://thebet365api.com/sign-up?ref=ai-md. No key yet? The keyless preview:

```bash
curl -s "https://thebet365api.com/api/mcp" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"preview_bet365_odds","arguments":{"league":"nba"}}}'
```

Updated 2026-11-20. The same reference as the HTML page.

## Getting started

### What this API is

The self-serve bet365 odds feed: free key in 30 seconds, first bet365 prices on your first call, no sales call. Get a key at [/sign-up](https://thebet365api.com/sign-up), then copy the quickstart below.

bet365 API is an independent, unofficial API for bet365 odds, with prices republished from public odds aggregators. It serves bet365 prices as JSON over REST and over a remote MCP server, so the same data reaches a Python script, a spreadsheet job and an AI agent. Independent. Not affiliated with, endorsed by or sponsored by bet365.

There are two lanes of data, and every response says which one an event came from in its `feed` field:

- **US main lines** (`feed: "us"`): bet365 US main lines: moneyline, point spread and total, plus team totals on some games, for the NFL, NBA, NHL, college football, college basketball and MLB while each league is in season. Prices are American odds with a decimal conversion.
- **Soccer** (`feed: "soccer"`): bet365 soccer prices for the European competitions where our source carries bet365: match result (1X2), double chance, goal line and first, anytime and last goalscorer, in the fractional odds as published plus an exact decimal conversion.

Every price carries `observed_at`, the UTC time our collector last read it, `price_since`, when it took its current value, and `age_seconds`. bet365 publishes no update time through the sources we read, so we never call the data real time. You judge freshness from the data, not from a claim. See [Freshness](https://thebet365api.com/docs#freshness).

We do not read bet365 directly. Its sites block scripted clients, and it offers no public developer API we can find. bet365 prices reach us through public odds aggregators that republish them, and a republished price can lag or differ from what bet365 shows at that moment. See [Where the prices come from](https://thebet365api.com/docs#provenance).

### # What is not here

- US player props (NFL, NBA, MLB, NHL).
- Alternate lines and futures.
- State-by-state bet365 prices.
- In-play prices.
- Sports and leagues other than those listed on the coverage page.
- History from before our collector started.
- Placing bets or reading a bet365 account.

If one of those is what you need, the [alternatives page](https://thebet365api.com/bet365-api-alternatives) compares the providers that do carry it.

### # Base URLs

| Surface | URL |
| --- | --- |
| REST | `https://thebet365api.com/api/v1` |
| MCP (JSON-RPC over POST) | `https://thebet365api.com/api/mcp` |
| OpenAPI 3.1 | [`https://thebet365api.com/openapi.json`](https://thebet365api.com/openapi.json) |
| Full reference as text | [`https://thebet365api.com/llms-full.txt`](https://thebet365api.com/llms-full.txt) |
| This page as markdown | [`https://thebet365api.com/docs.md`](https://thebet365api.com/docs.md) |

### Quickstart

Three steps from nothing to a bet365 price in your terminal. The free plan needs no card.

1. [Create a free account](https://thebet365api.com/sign-up) and open **Dashboard → API keys**. Create a key. It starts with `bt_` and is shown once, so copy it then.
2. Put it in an environment variable, so it never lands in your code or shell history: `export THEBET365API_KEY=bt_...`
3. Make a first call. This one returns the next Premier League matches with every bet365 price we hold for them:

curl:

```bash
curl "https://thebet365api.com/api/v1/odds?league=epl&limit=2" \
  -H "Authorization: Bearer $THEBET365API_KEY"
```

Python (standard library only):

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

req = urllib.request.Request(
    "https://thebet365api.com/api/v1/odds?league=epl&limit=2",
    headers={"Authorization": "Bearer " + os.environ["THEBET365API_KEY"]},
)
with urllib.request.urlopen(req, timeout=20) as resp:
    body = json.load(resp)

for event in body["data"]:
    print(event["home"], "v", event["away"], event["starts_at"])
    for price in event["prices"]:
        if price["market"] == "match_result":
            print("  ", price["side"], price["price"]["fractional"], price["price"]["decimal"], "seen", price["observed_at"])
```

JavaScript:

```javascript
// Node 18+ (global fetch). Run as an ES module: node first-call.mjs
const res = await fetch("https://thebet365api.com/api/v1/odds?league=epl&limit=2", {
  headers: { Authorization: `Bearer ${process.env.THEBET365API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const body = await res.json();
for (const event of body.data) {
  console.log(event.home, "v", event.away, event.starts_at);
  for (const p of event.prices.filter((p) => p.market === "match_result")) {
    console.log("  ", p.side, p.price.fractional, p.price.decimal, "seen", p.observed_at);
  }
}
```

The response is a list of events, each with a `prices` array. Here is the first event of a real Premier League response, trimmed to one price per market:

Response (captured 20 November 2026, 02:09 UTC):

```json
{
  "data": [
    {
      "event_id": "espn-401879233",
      "league": "epl",
      "league_name": "Premier League",
      "sport": "soccer",
      "feed": "soccer",
      "region": null,
      "region_note": "The source does not state which bet365 region these soccer prices are from.",
      "home": "Manchester City",
      "away": "Fulham",
      "starts_at": "2026-11-21T12:30:00.000Z",
      "status": "scheduled",
      "markets": [
        "anytime_goalscorer",
        "double_chance",
        "first_goalscorer",
        "goal_line",
        "last_goalscorer",
        "match_result"
      ],
      "first_observed_at": "2026-11-19T23:58:08.613Z",
      "last_observed_at": "2026-11-20T01:59:34.462Z",
      "prices": [
        {
          "selection_id": "sel_82ee19f52ef5caf78265",
          "market": "match_result",
          "period": "full_time",
          "side": "away",
          "team": null,
          "player": null,
          "line": null,
          "price": {
            "american": 600,
            "decimal": 7,
            "fractional": "6/1"
          },
          "published_format": "fractional",
          "is_live": false,
          "line_status": null,
          "observed_at": "2026-11-20T01:59:34.462Z",
          "price_since": "2026-11-19T23:58:08.613Z",
          "age_seconds": 611
        },
        {
          "selection_id": "sel_91806b4c98bdf0f9bd11",
          "market": "double_chance",
          "period": "full_time",
          "side": "draw_or_away",
          "team": null,
          "player": null,
          "line": null,
          "price": {
            "american": 175,
            "decimal": 2.75,
            "fractional": "7/4"
          },
          "published_format": "fractional",
          "is_live": false,
          "line_status": null,
          "observed_at": "2026-11-20T01:59:34.462Z",
          "price_since": "2026-11-19T23:58:08.613Z",
          "age_seconds": 611
        },
        {
          "selection_id": "sel_ab7cd88abdce283a5a25",
          "market": "goal_line",
          "period": "full_time",
          "side": "over",
          "team": null,
          "player": null,
          "line": 3.25,
          "price": {
            "american": 102,
            "decimal": 2.025,
            "fractional": "41/40"
          },
          "published_format": "fractional",
          "is_live": false,
          "line_status": null,
          "observed_at": "2026-11-20T01:59:34.462Z",
          "price_since": "2026-11-19T23:58:08.613Z",
          "age_seconds": 611
        },
        {
          "selection_id": "sel_ec46e0240ebbf64525de",
          "market": "first_goalscorer",
          "period": "full_time",
          "side": "yes",
          "team": null,
          "player": "Abduqodir Khusanov",
          "line": null,
          "price": {
            "american": 3300,
            "decimal": 34,
            "fractional": "33/1"
          },
          "published_format": "fractional",
          "is_live": false,
          "line_status": null,
          "observed_at": "2026-11-20T01:59:34.462Z",
          "price_since": "2026-11-19T23:58:08.613Z",
          "age_seconds": 611
        },
        {
          "selection_id": "sel_ed8d715833009cdf884a",
          "market": "anytime_goalscorer",
          "period": "full_time",
          "side": "yes",
          "team": null,
          "player": "Abduqodir Khusanov",
          "line": null,
          "price": {
            "american": 1000,
            "decimal": 11,
            "fractional": "10/1"
          },
          "published_format": "fractional",
          "is_live": false,
          "line_status": null,
          "observed_at": "2026-11-20T01:59:34.462Z",
          "price_since": "2026-11-19T23:58:08.613Z",
          "age_seconds": 611
        },
        {
          "selection_id": "sel_e804dd8d4d7bcdfec841",
          "market": "last_goalscorer",
          "period": "full_time",
          "side": "yes",
          "team": null,
          "player": "Abduqodir Khusanov",
          "line": null,
          "price": {
            "american": 3300,
            "decimal": 34,
            "fractional": "33/1"
          },
          "published_format": "fractional",
          "is_live": false,
          "line_status": null,
          "observed_at": "2026-11-20T01:59:34.462Z",
          "price_since": "2026-11-19T23:58:08.613Z",
          "age_seconds": 611
        }
      ]
    }
  ],
  "meta": {
    "limit": 1,
    "offset": 0,
    "from": "2026-11-19T20:09:45.682Z",
    "count": 1,
    "source_note": "Unofficial. bet365 prices as republished by public odds aggregators and read by our collector; not affiliated with, endorsed by or sponsored by bet365. observed_at is when we read the price, not a bet365 update time.",
    "plan": "free",
    "remaining": 98
  }
}
```

`meta.remaining` is what is left of your monthly allowance after this call. The free plan includes 100 requests a month and 20 a minute; [plans and limits](https://thebet365api.com/docs#limits) has the rest.

### # Where to go next

- [Filters](https://thebet365api.com/docs#filters): league, market, pre-match or in-play, time window, paging.
- [Line history](https://thebet365api.com/docs#history): every price change since collection began.
- [MCP](https://thebet365api.com/docs#mcp): connect Claude, Cursor or any MCP client.
- [Recipes](https://thebet365api.com/docs#recipe-line-movement): line movement, closing lines, alerts, pandas.

### Authentication

Every REST data call and every MCP data tool needs an API key, sent as a bearer token in the `Authorization` header. Keys start with `bt_`. Query-string keys are not accepted, so a key never ends up in a log line or a browser history.

```http
GET /api/v1/odds?league=nba HTTP/1.1
Host: thebet365api.com
Authorization: Bearer bt_your_key_here
```

- Create, name and revoke keys under **Dashboard → API keys**. A key is shown in full once, when you create it; we store only a hash.
- Keys belong to your account, and limits are counted per account: two keys on one account share the same per-minute and monthly allowance.
- Revoking a key stops it at once. Other keys keep working.
- Keep the key in an environment variable such as `THEBET365API_KEY`, never in front-end code. Browser code would publish it to everyone who opens the page.

### # The X-User-Request header

Optional on REST: send the task your user asked for, in one sentence, as `X-User-Request`. We read these to decide which data to add next. On MCP the same thing is the required `user_request` argument of every data tool. Leave out secrets and personal data.

```bash
curl "https://thebet365api.com/api/v1/odds?league=nfl&market=spread" \
  -H "Authorization: Bearer $THEBET365API_KEY" \
  -H "X-User-Request: Compare tonight's NFL spreads with my model"
```

### # When authentication fails

| Status | code | Meaning |
| --- | --- | --- |
| 401 | `INVALID_API_KEY` | No `Authorization: Bearer bt_...` header, a key we do not know, or a revoked key. |
| 403 | `ACCOUNT_SUSPENDED` | The account is suspended. The message names the address to contact (support@thebet365api.com). |

401 body (real):

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Send a valid key in the Authorization: Bearer header. Free keys: https://thebet365api.com/sign-up."
  }
}
```

### MCP server

The MCP server at `https://thebet365api.com/api/mcp` exposes the same data as REST, with the same parameters, limits and errors, so an agent can read bet365 prices without you writing a client. It is stateless JSON-RPC over HTTP POST: each request gets one JSON response, there is no session and no server-sent event stream (a GET returns 405). For prices pushed as they change, use the [WebSocket stream](https://thebet365api.com/docs#websocket). Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 are accepted.

Authenticate with the same bearer key. Two tools, `get_bet365_coverage` and `preview_bet365_odds`, also work with no key, so an agent can show its user real data before anyone signs up.

### # Claude Code

```bash
claude mcp add --transport http bet365-odds https://thebet365api.com/api/mcp \
  --header "Authorization: Bearer $THEBET365API_KEY"
```

Then ask in plain words, for example: *What are bet365's current moneylines for tonight's NBA games, and when were they observed?*

### # Cursor, Windsurf and other clients that take a JSON config

Add this to the client's MCP config (for Cursor, `~/.cursor/mcp.json` or `.cursor/mcp.json` in a project). The key is read from your environment:

```json
{
  "mcpServers": {
    "bet365-odds": {
      "type": "http",
      "url": "https://thebet365api.com/api/mcp",
      "headers": { "Authorization": "Bearer ${THEBET365API_KEY}" }
    }
  }
}
```

### # VS Code

```json
// .vscode/mcp.json
{
  "inputs": [{ "type": "promptString", "id": "bet365-key", "description": "bet365 API key", "password": true }],
  "servers": {
    "bet365-odds": {
      "type": "http",
      "url": "https://thebet365api.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:bet365-key}" }
    }
  }
}
```

### # Clients that only run local (stdio) servers

For a client that cannot call a remote server with a header, such as Claude Desktop's config file, bridge it with `mcp-remote`:

```json
{
  "mcpServers": {
    "bet365-odds": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://thebet365api.com/api/mcp", "--header", "Authorization:Bearer ${THEBET365API_KEY}"],
      "env": { "THEBET365API_KEY": "bt_your_key_here" }
    }
  }
}
```

### # Tools

Every tool that needs a key also needs `user_request`, the user's task in one sentence; without it the call returns an error and costs nothing. Tools marked as costing quota count one request each, exactly like a REST call.

| Tool | Arguments | Key | Costs quota | What it returns |
| --- | --- | --- | --- | --- |
| `get_bet365_coverage` | None | No | No | Leagues and markets captured, collection start date, age of the latest price per league. Call it first. |
| `preview_bet365_odds` | `league` | No | No | Delayed preview: moneyline or match result for up to 3 events, 15 minutes behind, 25 calls per network per UTC day. |
| `get_bet365_odds` | `league`, `event_id`, `market`, `live`, `from`, `to`, `limit` (1-100), `offset`, `user_request` | Yes | Yes | Same as `GET /api/v1/odds`. |
| `list_bet365_events` | `league`, `event_id`, `market`, `live`, `from`, `to`, `limit` (1-200), `offset`, `user_request` | Yes | Yes | Same as `GET /api/v1/events`. |
| `get_bet365_line_history` | `event_id`, `market`, `selection_id`, `user_request` | Yes | Yes | Same as `GET /api/v1/history`. |
| `list_watchlists`, `get_watchlists`, `create_watchlists`, `update_watchlists`, `delete_watchlists` | Record fields, `id`, `limit`, `offset`, `user_request` | Yes | Yes | Your saved [watchlists](https://thebet365api.com/docs#watchlists). |
| `send_feedback` | `kind` (missing_feature, missing_data, bug, other), `message`, `contact` | No | Only if you send a key | Tell us what is missing. The team reads every one. |
| `get_onboarding_questions` | None | No | No | The account setup questions, with any answers already given. |
| `answer_onboarding` | `answers`, `client` | Yes | No | Answer the setup questions for your user. |

### # Calling it by hand

Useful for checking a key or debugging a client. List the tools:

```bash
curl -s "https://thebet365api.com/api/mcp" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Call one with a key. The result is a JSON string in `result.content[0].text`; `result.isError` is true when the tool refused:

```bash
curl -s "https://thebet365api.com/api/mcp" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THEBET365API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_bet365_odds","arguments":{"league":"nhl","market":"moneyline","limit":3,"user_request":"Show NHL moneylines"}}}'
```

### # MCP errors

| Where | What you see | Meaning |
| --- | --- | --- |
| Tool result | `isError: true`, text `user_request is required...` | A data tool was called without `user_request`. Costs no quota. |
| Tool result | `isError: true`, JSON with `INVALID_API_KEY` | Missing or bad key on a tool that needs one. |
| Tool result | `isError: true`, JSON with `INVALID_PARAMETER` | A bad argument. Same body as the REST 400: it names the parameter, the allowed values and an example. |
| Tool result | `isError: true`, JSON with `RATE_LIMITED` or `QUOTA_EXCEEDED` | A plan limit. Same body as the REST 429. |
| Tool result | `isError: true`, JSON with `FREE_PREVIEW_LIMIT` | The keyless preview's daily cap for your network is spent. `reset_at` says when it resets. |
| JSON-RPC error | `-32700` | The body was not JSON. |
| JSON-RPC error | `-32600` | A batch (array) was sent. Send one message per request. |
| JSON-RPC error | `-32601` / `-32602` | Unknown method / unknown tool name. |
| JSON-RPC error | `-32603` | Our fault. Retry shortly. |

Agent setup instructions, written for the agent, are at [/agents.md](https://thebet365api.com/agents.md); an installable skill file is at [/skill.md](https://thebet365api.com/skill.md).

### Keyless preview

The `preview_bet365_odds` MCP tool returns real captured bet365 prices with no key and no sign-up. It is deliberately smaller than a free key: the moneyline or match result only, for up to 3 events, as the prices stood 15 minutes ago, 25 calls per network per UTC day (a network is an IPv4 /24 or IPv6 /64, hashed; the address itself is not stored). Upcoming events come first. Pass `league` to choose one.

```bash
curl -s "https://thebet365api.com/api/mcp" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"preview_bet365_odds","arguments":{"league":"nba"}}}'
```

The tool's text result is this JSON, trimmed here to one event:

preview_bet365_odds result (captured 20 November 2026, 02:09 UTC):

```json
{
  "free_preview": true,
  "delayed_minutes": 15,
  "as_of": "2026-11-20T01:55:04.488Z",
  "stale": false,
  "notice": "Preview only: bet365 moneyline and match result prices for up to 3 events, as our captures showed them 15 minutes ago. observed_at is when we read each price. A free key reads current prices for every market.",
  "user_message": "This is a delayed preview. For current bet365 prices on every market, get a free API key (no card) at https://thebet365api.com/sign-up?ref=ai-free",
  "next_step": {
    "sign_up": "https://thebet365api.com/sign-up?ref=ai-free",
    "free_plan": "Free key, no card: every market, current prices, events and 24 hours of history.",
    "then": "Send Authorization: Bearer <key> to https://thebet365api.com/api/v1/odds",
    "docs": "https://thebet365api.com/docs",
    "openapi": "https://thebet365api.com/openapi.json",
    "mcp": "https://thebet365api.com/api/mcp"
  },
  "count": 1,
  "data": [
    {
      "event_id": "espn-401879233",
      "league": "epl",
      "league_name": "Premier League",
      "region": null,
      "home": "Manchester City",
      "away": "Fulham",
      "starts_at": "2026-11-21T12:30:00.000Z",
      "status": "scheduled",
      "prices": [
        {
          "market": "match_result",
          "side": "away",
          "team": null,
          "line": null,
          "price": {
            "american": 600,
            "decimal": 7,
            "fractional": "6/1"
          },
          "published_format": "fractional",
          "price_since": "2026-11-19T23:58:08.613Z",
          "observed_at": "2026-11-20T01:55:04.488Z",
          "age_seconds": 900
        },
        {
          "market": "match_result",
          "side": "draw",
          "team": null,
          "line": null,
          "price": {
            "american": 425,
            "decimal": 5.25,
            "fractional": "17/4"
          },
          "published_format": "fractional",
          "price_since": "2026-11-19T23:58:08.613Z",
          "observed_at": "2026-11-20T01:55:04.488Z",
          "age_seconds": 900
        }
      ]
    }
  ],
  "limits": {
    "per_network_per_day": 25,
    "events_per_call": 3,
    "delay_minutes": 15,
    "per": "network (IPv4 /24, IPv6 /64), UTC day"
  },
  "source_note": "Unofficial. bet365 prices as republished by public odds aggregators and read by our collector; not affiliated with, endorsed by or sponsored by bet365. observed_at is when we read the price, not a bet365 update time."
}
```

- `as_of` is the delayed cut-off: prices are shown as they stood then, and `observed_at` is capped at it.
- `stale` is true when even the newest preview price is more than 2 hours old, for example in a league between games.
- `user_message` is written for the agent to pass to its user.

`get_bet365_coverage` is also keyless and costs nothing, so an agent can check what exists before it asks for a key. The same numbers are on the [coverage page](https://thebet365api.com/coverage).

## Endpoints

### Endpoints

| Method | Path | Returns | Quota |
| --- | --- | --- | --- |
| GET | `/api/v1/odds` | Events, each with its current bet365 prices | 1 request |
| GET | `/api/v1/events` | Events with bet365 prices, without the prices | 1 request |
| GET | `/api/v1/events/{id}` | One event with every current price | 1 request |
| GET | `/api/v1/history` | Price and line changes for an event or selection | 1 request |
| GET, POST | `/api/v1/watchlists` | Your saved watchlists | 1 request |
| GET, PATCH, DELETE | `/api/v1/watchlists/{id}` | One watchlist | 1 request |
| POST | `/api/v1/feedback` | Tell us what is missing | Free, no key needed |
| GET, POST | `/api/v1/onboarding` | Account setup questions and answers | Free |
| POST | `/api/mcp` | MCP server: all of the above as tools | As the tool |
| WSS | `wss://stream.thebet365api.com/v1/stream` | [WebSocket stream](https://thebet365api.com/docs#websocket): every price change, pushed | 1 request per connection, +1 each 5 min |

All responses are JSON, UTF-8, with `Cache-Control: no-store`. Times are ISO 8601 in UTC with milliseconds (`2026-11-20T02:08:29.503Z`). Every data response has a `data` field and a `meta` field; errors have a single `error` object. Fields are never silently omitted: a value the source does not give is `null`.

### WebSocket stream: live price changes

`wss://stream.thebet365api.com/v1/stream` pushes every bet365 price or line change the collector stores, as it is stored, so you stop polling `/odds` and diffing. Same API key, same plans. Each change arrives once, in order, with the previous price, and carries an `id` you can resume from after a disconnect.

|  |  |
| --- | --- |
| URL | `wss://stream.thebet365api.com/v1/stream` |
| Auth | `Authorization: Bearer <key>` on the upgrade request, or (browsers cannot set headers) the first message `{"op":"auth","key":"bt_..."}` within 10 seconds. Never put the key in the URL: that is refused with `400 KEY_IN_URL`. |
| Filters (query string) | `league` (one or more codes, comma-separated: `nba,epl`), `event_id` (up to 50), `market` (one or more of the [markets](https://thebet365api.com/docs#markets)), `live` (`true` or `false`). All optional; none means every change. |
| Resume | `after=<id>`: replays the changes after that id (up to 24 hours back, at most 5,000), sends `replay_done`, then continues live with no gap and no duplicate. |
| Cost | 1 request when the connection opens, then 1 more for each further 5 minutes it stays open (about 288 a day), from the same monthly allowance as REST. A connection refused for the connection limit costs nothing. |
| Connections at a time | Free 1, Developer 2, Pro 3, Production 5, Scale 10. One connection can carry every league: widen its filters before opening another. |
| Delay | None on any plan. Every key reads current prices on REST too. |
| Heartbeat | A WebSocket ping and a `heartbeat` message every 25 seconds. A client that answers nothing for about a minute is disconnected, which frees its connection slot. |

### # Messages

| type | When | Fields |
| --- | --- | --- |
| `welcome` | Once, after auth | `plan`, `cursor` (start id), `filters`, `connections_allowed`, `requests` (`charged`, `window_seconds`, `remaining_this_month`), `heartbeat_seconds`, `replay`, `freshness`. |
| `price.changed` | Each stored change | `id`, `event_id`, `league`, `sport`, `region`, `home`, `away`, `starts_at`, `event_status`, `selection_id`, `market`, `period`, `side`, `team`, `player`, `is_live`, `line`, `price` {`american`, `decimal`, `fractional`}, `published_format`, `previous` {`line`, `price`, `observed_at`} or `null` for a new selection, `observed_at`. |
| `replay_done` | After an `after=` replay | `cursor`, `events`, `truncated`. |
| `heartbeat` | Every 25 s | `at`, `cursor`, `last_change_at`. |
| `request_charged` | Every 5 min | `charged`, `total`, `remaining_this_month`. |
| `subscribed` | After a `subscribe` | `filters`, `cursor`. |
| `limit`, `error` | Before a close, or for a bad message | `code`, `message`, and for limits `cursor` to resume from. |
| `reconnect` | Before a planned restart | `cursor`. Reconnect with `after=<cursor>`. |

Client messages: `{"op":"subscribe","league":"nba","market":"spread"}` replaces the filters (same fields as the query string; an empty subscribe means everything), `{"op":"ping"}` answers `pong`.

price.changed, as received from production on 20 Nov 2026 (3 seconds after observed_at):

```json
{"type":"price.changed","id":"5190","event_id":"an-290162","league":"ncaaf","sport":"football","region":"US",
 "home":"Baylor Bears","away":"Texas Tech Red Raiders","starts_at":"2026-11-21T20:30:00.000Z","event_status":"scheduled",
 "selection_id":"sel_a7e4d41b1dfea7b1f863","market":"moneyline","period":"event","side":"home","team":"Baylor Bears",
 "player":null,"is_live":false,"line":null,"price":{"american":165,"decimal":2.65,"fractional":null},"published_format":"american",
 "previous":{"line":null,"price":{"american":163,"decimal":2.63,"fractional":null},"observed_at":"2026-11-19T23:57:54.984Z"},
 "observed_at":"2026-11-20T03:55:41.437Z"}
```

### # Node.js

```javascript
// Node 22+: the built-in WebSocket. No dependency.
const URL_ = "wss://stream.thebet365api.com/v1/stream?league=nba,nfl&market=spread,total";
let last = null, wait = 1000;

function connect() {
  const ws = new WebSocket(last ? URL_ + "&after=" + last : URL_);
  ws.onopen = () => ws.send(JSON.stringify({ op: "auth", key: process.env.THEBET365API_KEY }));
  ws.onmessage = (e) => {
    const m = JSON.parse(e.data);
    if (m.type === "welcome") { wait = 1000; console.log("connected on", m.plan, "from cursor", m.cursor); }
    if (m.type === "price.changed") {
      last = m.id;
      const was = m.previous ? `${m.previous.line ?? ""} ${m.previous.price.american ?? m.previous.price.decimal}` : "new";
      console.log(m.league, m.away, "at", m.home, m.market, m.team ?? m.side, was, "->", m.line ?? "", m.price.american ?? m.price.decimal, m.observed_at);
    }
    if (m.type === "error" || m.type === "limit") console.error(m.code, m.message);
  };
  ws.onclose = (e) => {
    if (e.code === 4001 || e.code === 4003) return console.error("key refused, not reconnecting");
    setTimeout(connect, wait); wait = Math.min(wait * 2, 30000);  // back off, resume from the last id
  };
}
connect();
```

### # Python

```python
# pip install websockets  (14 or later)
import asyncio, json, os, websockets

URL = "wss://stream.thebet365api.com/v1/stream?league=epl&market=match_result,anytime_goalscorer"
HEADERS = {"Authorization": "Bearer " + os.environ["THEBET365API_KEY"]}

async def main():
    last, wait = None, 1
    while True:
        url = URL + (f"&after={last}" if last else "")
        try:
            async with websockets.connect(url, additional_headers=HEADERS, ping_interval=20) as ws:
                wait = 1
                async for raw in ws:
                    m = json.loads(raw)
                    if m["type"] == "price.changed":
                        last = m["id"]
                        prev = m["previous"]["price"]["decimal"] if m["previous"] else None
                        print(m["league"], m["home"], "v", m["away"], m["market"], m["player"] or m["team"] or m["side"],
                              prev, "->", m["price"]["decimal"], m["observed_at"])
                    elif m["type"] in ("error", "limit"):
                        print(m["code"], m["message"])
        except websockets.InvalidStatus as e:
            if e.response.status_code in (401, 403):
                raise  # bad key: fix it rather than retry
        except (OSError, websockets.ConnectionClosed):
            pass
        await asyncio.sleep(wait)
        wait = min(wait * 2, 30)

asyncio.run(main())
```

### # Refusals and close codes

| When | Status or close code | code | What to do |
| --- | --- | --- | --- |
| Upgrade with a bad, unknown or revoked key | HTTP 401 / close 4001 | `INVALID_API_KEY` | Fix the key; do not retry. |
| Suspended account | HTTP 403 / close 4003 | `ACCOUNT_SUSPENDED` | Write to support@thebet365api.com. |
| Bad filter or `after` | HTTP 400 | `INVALID_PARAMETER` | Fix the named parameter. |
| Too many open connections | HTTP 429 / close 4029 | `STREAM_CONNECTION_LIMIT` | Close one or widen one connection's filters; `upgrade_url` for more. |
| Month spent or minute limit | HTTP 429 / close 4029 | `QUOTA_EXCEEDED`, `RATE_LIMITED` | Same as REST: wait for the reset or upgrade. |
| No auth message within 10 s | close 4008 | `AUTH_TIMEOUT` | Send the auth message first. |
| Restart, or reading too slowly | close 1012 / 1013 | `reconnect`, `SLOW_CONSUMER` | Reconnect with `after=<last id>`, backing off 1 to 30 s. |

> Freshness: changes are pushed within about 2 seconds of being stored. The collector reads each league as often as every 60 seconds (see [freshness](https://thebet365api.com/docs#freshness)), so a move reaches you about 1 to 3 minutes after the aggregator shows it. Quiet periods with no games send only heartbeats. Health: [stream.thebet365api.com/health](https://stream.thebet365api.com/health) and the [status page](https://thebet365api.com/status).

### Filters

`/api/v1/odds`, `/api/v1/events` and their MCP tools take the same filters. All are optional and combine with AND. Unknown parameters are ignored; a known parameter with a bad value is a 400 that names it.

| Parameter | Type | Allowed values | Default | What it does |
| --- | --- | --- | --- | --- |
| `league` | string | `nfl`, `nba`, `nhl`, `ncaaf`, `ncaab`, `mlb`, `mls`, `epl`, `serie-a`, `bundesliga`, `ligue-1`, `ucl`, `laliga`, plus any league the collector has captured | all | Only events in this league. Case-insensitive. |
| `market` | string | `moneyline`, `spread`, `total`, `team_total`, `match_result`, `double_chance`, `goal_line`, `first_goalscorer`, `anytime_goalscorer`, `last_goalscorer` | all | Only events that have this market; on `/odds`, also only those prices. |
| `live` | boolean | `true`, `false` | both | `true`: in-play prices only. `false`: pre-match only. Filters events and, on `/odds`, prices. |
| `event_id` | string | `an-…` or `espn-…`, as returned by `/events` | none | Exactly this event, whatever its start time or status. |
| `from` | ISO 8601 time | any parseable time, up to 40 characters | 6 hours ago | Events starting at or after this time. Passing it also includes finished games. |
| `to` | ISO 8601 time | as `from` | none | Events starting strictly before this time. |
| `limit` | integer | 1-100 on /odds, 1-200 on /events | 25 | Events per page. Prices are not limited: each event comes with all of its prices. |
| `offset` | integer | 0-100,000 | 0 | Events to skip, for paging. |

### # The default time window, and finished games

With no `from`, a list returns events whose start time is no more than 6 hours ago, soonest first, and leaves out games whose status is `final`. That keeps the default answer to "what can I bet on now". Two ways to see more:

- Pass `from` (for example `from=2026-11-19T00:00:00Z`). The window then starts there and finished games are included.
- Ask for one event with `event_id`, or use `/api/v1/events/{id}`. A single event is always returned, finished or not.

Events with no start time from the source are placed by when we last saw them. Start times are the source's scheduled times, not when play actually began.

### # League codes

The `league` filter accepts every code we poll plus every league the collector has ever captured. A wrong value returns the allowed list, so you never have to guess:

400 for league=xyz (real):

```json
{
  "error": {
    "parameter": "league",
    "allowed": [
      "bundesliga",
      "epl",
      "laliga",
      "ligue-1",
      "mlb",
      "mls",
      "nba",
      "ncaab",
      "ncaaf",
      "nfl",
      "nhl",
      "serie-a",
      "ucl"
    ],
    "example": "https://thebet365api.com/api/v1/odds?league=nba",
    "code": "INVALID_PARAMETER",
    "message": "league must be one of: bundesliga, epl, laliga, ligue-1, mlb, mls, nba, ncaab, ncaaf, nfl, nhl, serie-a, ucl."
  }
}
```

A league being accepted does not mean it has prices today. [Leagues](https://thebet365api.com/docs#leagues) and the live [coverage page](https://thebet365api.com/coverage) show what is actually captured.

### GET /api/v1/odds

Events with their current captured bet365 prices, soonest first. This is the call most integrations need: one request returns a page of games and every price we hold for each.

Parameters: all of the [filters](https://thebet365api.com/docs#filters). `limit` is 1 to 100, default 25.

### # Examples

```bash
# Tonight's NBA board, pre-match only
curl "https://thebet365api.com/api/v1/odds?league=nba&live=false" \
  -H "Authorization: Bearer $THEBET365API_KEY"

# Every bet365 spread we hold for the NFL
curl "https://thebet365api.com/api/v1/odds?league=nfl&market=spread" \
  -H "Authorization: Bearer $THEBET365API_KEY"

# Anytime goalscorer prices for Champions League matches
curl "https://thebet365api.com/api/v1/odds?league=ucl&market=anytime_goalscorer" \
  -H "Authorization: Bearer $THEBET365API_KEY"

# In-play prices, any league
curl "https://thebet365api.com/api/v1/odds?live=true" \
  -H "Authorization: Bearer $THEBET365API_KEY"

# One event, every price, even after it finished
curl "https://thebet365api.com/api/v1/odds?event_id=an-295471" \
  -H "Authorization: Bearer $THEBET365API_KEY"
```

### # Response

A real NBA response for `?league=nba&limit=1`, trimmed from 12 prices to 5 (pre-match moneyline both sides, one spread side, one total side and one in-play moneyline):

200 (captured 20 November 2026, 02:09 UTC):

```json
{
  "data": [
    {
      "event_id": "an-295471",
      "league": "nba",
      "league_name": "NBA",
      "sport": "basketball",
      "feed": "us",
      "region": "US",
      "home": "Minnesota Timberwolves",
      "away": "New York Knicks",
      "starts_at": "2026-11-20T01:00:00.000Z",
      "status": "live",
      "markets": [
        "moneyline",
        "spread",
        "total"
      ],
      "first_observed_at": "2026-11-19T23:57:52.779Z",
      "last_observed_at": "2026-11-20T02:08:29.503Z",
      "prices": [
        {
          "selection_id": "sel_c481710023580ad3cada",
          "market": "moneyline",
          "period": "event",
          "side": "away",
          "team": "New York Knicks",
          "player": null,
          "line": null,
          "price": {
            "american": -117,
            "decimal": 1.8547,
            "fractional": null
          },
          "published_format": "american",
          "is_live": false,
          "line_status": "normal",
          "observed_at": "2026-11-20T02:08:29.503Z",
          "price_since": "2026-11-20T01:04:19.117Z",
          "age_seconds": 76
        },
        {
          "selection_id": "sel_2cfb2a9c95ac6c01951d",
          "market": "moneyline",
          "period": "event",
          "side": "home",
          "team": "Minnesota Timberwolves",
          "player": null,
          "line": null,
          "price": {
            "american": -103,
            "decimal": 1.9709,
            "fractional": null
          },
          "published_format": "american",
          "is_live": false,
          "line_status": "normal",
          "observed_at": "2026-11-20T02:08:29.503Z",
          "price_since": "2026-11-20T01:04:19.117Z",
          "age_seconds": 76
        },
        {
          "selection_id": "sel_26238f2da94e2cec67a2",
          "market": "spread",
          "period": "event",
          "side": "away",
          "team": "New York Knicks",
          "player": null,
          "line": -1.5,
          "price": {
            "american": -105,
            "decimal": 1.9524,
            "fractional": null
          },
          "published_format": "american",
          "is_live": false,
          "line_status": "normal",
          "observed_at": "2026-11-20T02:08:29.503Z",
          "price_since": "2026-11-20T01:04:19.117Z",
          "age_seconds": 76
        },
        {
          "selection_id": "sel_ee730b7943fcf2981ba6",
          "market": "total",
          "period": "event",
          "side": "over",
          "team": null,
          "player": null,
          "line": 216.5,
          "price": {
            "american": -110,
            "decimal": 1.9091,
            "fractional": null
          },
          "published_format": "american",
          "is_live": false,
          "line_status": "normal",
          "observed_at": "2026-11-20T02:08:29.503Z",
          "price_since": "2026-11-19T23:57:52.779Z",
          "age_seconds": 76
        },
        {
          "selection_id": "sel_e2fd83b6b3f795494880",
          "market": "moneyline",
          "period": "event",
          "side": "away",
          "team": "New York Knicks",
          "player": null,
          "line": null,
          "price": {
            "american": -500,
            "decimal": 1.2,
            "fractional": null
          },
          "published_format": "american",
          "is_live": true,
          "line_status": "normal",
          "observed_at": "2026-11-20T02:08:29.503Z",
          "price_since": "2026-11-20T02:03:29.070Z",
          "age_seconds": 76
        }
      ]
    }
  ],
  "meta": {
    "limit": 1,
    "offset": 0,
    "from": "2026-11-19T20:09:45.459Z",
    "count": 1,
    "source_note": "Unofficial. bet365 prices as republished by public odds aggregators and read by our collector; not affiliated with, endorsed by or sponsored by bet365. observed_at is when we read the price, not a bet365 update time.",
    "plan": "free",
    "remaining": 99
  }
}
```

Things worth noticing in it:

- The game had started (`status: "live"`), so the event has both pre-match prices (`is_live: false`) and in-play prices (`is_live: true`) for the same sides. They are separate selections with separate `selection_id`s.
- US prices are published in American odds: `published_format: "american"` and `fractional: null`. `decimal` is our conversion.
- `line` is null on a moneyline and is the handicap or total on a spread or total. A spread line is from the named team's point of view: `-1.5` on the Knicks means they must win by 2.
- `price_since` is when the price took this value; `observed_at` is the last time our collector saw it unchanged.

Fields are described in [Objects](https://thebet365api.com/docs#object-event). `meta` is described in [Meta](https://thebet365api.com/docs#object-meta).

### # Errors

| Status | code | When |
| --- | --- | --- |
| 400 | `INVALID_PARAMETER` | A filter has a bad value. `error.parameter` names it, `error.allowed` lists values where there is a fixed list, `error.example` is a URL that works. |
| 401 | `INVALID_API_KEY` | Missing, unknown or revoked key. |
| 403 | `ACCOUNT_SUSPENDED` | The account is suspended. |
| 429 | `RATE_LIMITED` / `QUOTA_EXCEEDED` | Per-minute or monthly plan limit. See [limits](https://thebet365api.com/docs#limits). |
| 503 | `SERVICE_UNAVAILABLE` | Our side. Retry after `Retry-After` seconds; quote `X-Request-ID` if you write to us. |

400 for market=props (real):

```json
{
  "error": {
    "parameter": "market",
    "allowed": [
      "moneyline",
      "spread",
      "total",
      "team_total",
      "match_result",
      "double_chance",
      "goal_line",
      "first_goalscorer",
      "anytime_goalscorer",
      "last_goalscorer"
    ],
    "example": "https://thebet365api.com/api/v1/odds?market=moneyline",
    "code": "INVALID_PARAMETER",
    "message": "market must be one of: moneyline, spread, total, team_total, match_result, double_chance, goal_line, first_goalscorer, anytime_goalscorer, last_goalscorer."
  }
}
```

400 for limit=500 (real):

```json
{
  "error": {
    "parameter": "limit",
    "example": "https://thebet365api.com/api/v1/odds?limit=10",
    "code": "INVALID_PARAMETER",
    "message": "limit must be a whole number from 1 to 100."
  }
}
```

### GET /api/v1/events

Games and matches that have at least one captured bet365 price, soonest first, without the prices. Use it to find event ids, to see which markets each event has before asking for them, or to build a schedule. It is lighter than `/odds` and pages further.

Parameters: all of the [filters](https://thebet365api.com/docs#filters). `limit` is 1 to 200, default 25. `market` and `live` keep only events that have a matching price.

```bash
curl "https://thebet365api.com/api/v1/events?league=nhl" \
  -H "Authorization: Bearer $THEBET365API_KEY"

# Every event of the last day, finished ones included
curl "https://thebet365api.com/api/v1/events?from=2026-11-19T00:00:00Z&limit=200" \
  -H "Authorization: Bearer $THEBET365API_KEY"

# Matches that have first goalscorer prices
curl "https://thebet365api.com/api/v1/events?market=first_goalscorer" \
  -H "Authorization: Bearer $THEBET365API_KEY"
```

200 for ?limit=2 (captured 20 November 2026, 02:09 UTC):

```json
{
  "data": [
    {
      "event_id": "an-293645",
      "league": "nhl",
      "league_name": "NHL",
      "sport": "hockey",
      "feed": "us",
      "region": "US",
      "home": "Washington Capitals",
      "away": "Buffalo Sabres",
      "starts_at": "2026-11-20T00:00:00.000Z",
      "status": "live",
      "markets": [
        "moneyline",
        "spread",
        "total"
      ],
      "first_observed_at": "2026-11-19T23:57:53.882Z",
      "last_observed_at": "2026-11-20T02:08:30.605Z"
    },
    {
      "event_id": "an-293646",
      "league": "nhl",
      "league_name": "NHL",
      "sport": "hockey",
      "feed": "us",
      "region": "US",
      "home": "Carolina Hurricanes",
      "away": "Montreal Canadiens",
      "starts_at": "2026-11-20T00:00:00.000Z",
      "status": "live",
      "markets": [
        "moneyline",
        "spread",
        "total"
      ],
      "first_observed_at": "2026-11-19T23:57:53.882Z",
      "last_observed_at": "2026-11-20T02:08:30.605Z"
    }
  ],
  "meta": {
    "limit": 2,
    "offset": 0,
    "from": "2026-11-19T20:09:46.049Z",
    "count": 2,
    "plan": "free",
    "remaining": 97
  }
}
```

`markets` lists every market the event has prices for, pre-match or in-play, sorted. Errors are the same as [/odds](https://thebet365api.com/docs#odds-errors).

### GET /api/v1/events/{id}

One event with every current captured price: all markets, pre-match and in-play. No filters, no time window: a finished game is returned too, which makes this the call for settling or reviewing one game.

```bash
curl "https://thebet365api.com/api/v1/events/an-295471" \
  -H "Authorization: Bearer $THEBET365API_KEY"
```

200, prices trimmed to 2 (captured 20 November 2026, 02:09 UTC):

```json
{
  "data": {
    "event_id": "an-295471",
    "league": "nba",
    "league_name": "NBA",
    "sport": "basketball",
    "feed": "us",
    "region": "US",
    "home": "Minnesota Timberwolves",
    "away": "New York Knicks",
    "starts_at": "2026-11-20T01:00:00.000Z",
    "status": "live",
    "markets": [
      "moneyline",
      "spread",
      "total"
    ],
    "first_observed_at": "2026-11-19T23:57:52.779Z",
    "last_observed_at": "2026-11-20T02:09:45.917Z",
    "prices": [
      {
        "selection_id": "sel_c481710023580ad3cada",
        "market": "moneyline",
        "period": "event",
        "side": "away",
        "team": "New York Knicks",
        "player": null,
        "line": null,
        "price": {
          "american": -117,
          "decimal": 1.8547,
          "fractional": null
        },
        "published_format": "american",
        "is_live": false,
        "line_status": "normal",
        "observed_at": "2026-11-20T02:09:45.917Z",
        "price_since": "2026-11-20T01:04:19.117Z",
        "age_seconds": 1
      },
      {
        "selection_id": "sel_2cfb2a9c95ac6c01951d",
        "market": "moneyline",
        "period": "event",
        "side": "home",
        "team": "Minnesota Timberwolves",
        "player": null,
        "line": null,
        "price": {
          "american": -103,
          "decimal": 1.9709,
          "fractional": null
        },
        "published_format": "american",
        "is_live": false,
        "line_status": "normal",
        "observed_at": "2026-11-20T02:09:45.917Z",
        "price_since": "2026-11-20T01:04:19.117Z",
        "age_seconds": 1
      }
    ]
  },
  "meta": {
    "source_note": "Unofficial. bet365 prices as republished by public odds aggregators and read by our collector; not affiliated with, endorsed by or sponsored by bet365. observed_at is when we read the price, not a bet365 update time."
  }
}
```

### # Errors

400 for /api/v1/events/foo (real):

```json
{
  "error": {
    "parameter": "id",
    "code": "INVALID_PARAMETER",
    "message": "The event id looks like an-295471 or espn-401879233, as returned by /api/v1/events."
  }
}
```

404 for an id with no captured prices (real):

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "No captured bet365 prices for event an-1. List events at /api/v1/events."
  }
}
```

Event ids are stable: `an-` ids are US main-line games and `espn-` ids are soccer matches. The number is the source's own game id, so an id never changes while the game exists.

### GET /api/v1/history

How a bet365 price or line moved. We store a row each time a price or line changes; while it stays the same we only move that row's `last_seen_at` forward. So each row is an interval: the price held from `observed_at` until at least `last_seen_at`.

| Parameter | Type | Required | What it does |
| --- | --- | --- | --- |
| `event_id` | string | This or `selection_id` | Every selection of this event. |
| `market` | string | No | Only this market. One of `moneyline`, `spread`, `total`, `team_total`, `match_result`, `double_chance`, `goal_line`, `first_goalscorer`, `anytime_goalscorer`, `last_goalscorer`. |
| `selection_id` | string | This or `event_id` | Exactly one selection: `sel_` plus 20 hex characters, from `/odds`. |

```bash
# Every moneyline change for one game
curl "https://thebet365api.com/api/v1/history?event_id=an-295471&market=moneyline" \
  -H "Authorization: Bearer $THEBET365API_KEY"

# One selection only
curl "https://thebet365api.com/api/v1/history?selection_id=sel_c481710023580ad3cada" \
  -H "Authorization: Bearer $THEBET365API_KEY"
```

A real response for the first call, trimmed to the first 4 of 40 rows. Those 4 rows are the Knicks' pre-match moneyline moving -115, -113, -115, -117 over the hour before tip-off:

200 (captured 20 November 2026, 02:09 UTC):

```json
{
  "data": [
    {
      "selection_id": "sel_c481710023580ad3cada",
      "event_id": "an-295471",
      "market": "moneyline",
      "side": "away",
      "team": "New York Knicks",
      "player": null,
      "is_live": false,
      "line": null,
      "price": {
        "american": -115,
        "decimal": 1.8696,
        "fractional": null
      },
      "observed_at": "2026-11-19T23:57:52.779Z",
      "last_seen_at": "2026-11-20T00:32:39.632Z"
    },
    {
      "selection_id": "sel_c481710023580ad3cada",
      "event_id": "an-295471",
      "market": "moneyline",
      "side": "away",
      "team": "New York Knicks",
      "player": null,
      "is_live": false,
      "line": null,
      "price": {
        "american": -113,
        "decimal": 1.885,
        "fractional": null
      },
      "observed_at": "2026-11-20T00:33:48.781Z",
      "last_seen_at": "2026-11-20T00:52:55.754Z"
    },
    {
      "selection_id": "sel_c481710023580ad3cada",
      "event_id": "an-295471",
      "market": "moneyline",
      "side": "away",
      "team": "New York Knicks",
      "player": null,
      "is_live": false,
      "line": null,
      "price": {
        "american": -115,
        "decimal": 1.8696,
        "fractional": null
      },
      "observed_at": "2026-11-20T00:54:07.532Z",
      "last_seen_at": "2026-11-20T01:03:05.151Z"
    },
    {
      "selection_id": "sel_c481710023580ad3cada",
      "event_id": "an-295471",
      "market": "moneyline",
      "side": "away",
      "team": "New York Knicks",
      "player": null,
      "is_live": false,
      "line": null,
      "price": {
        "american": -117,
        "decimal": 1.8547,
        "fractional": null
      },
      "observed_at": "2026-11-20T01:04:19.117Z",
      "last_seen_at": "2026-11-20T02:09:45.917Z"
    }
  ],
  "window": {
    "from": "2026-11-19T02:09:46.884Z",
    "full_history": false,
    "collection_started_at": "2026-11-19T23:57:51.246Z",
    "note": "Free keys read the last 24 hours of history. Paid plans read every change since collection began on 2026-11-19."
  },
  "meta": {
    "plan": "free",
    "remaining": 94,
    "count": 40
  }
}
```

### # How much history you can read

| Plan | Window | Rows per call |
| --- | --- | --- |
| Free | Intervals that were still current at some point in the last 24 hours | 2,000 |
| Every paid plan | Every change since collection began | 2,000 |

- `window.collection_started_at` is the first capture we hold. Collection began on 19 November 2026; nothing before it exists, and we do not backfill. For older European soccer seasons, football-data.co.uk publishes free CSV files that include bet365 odds columns.
- `window.from` is where your plan's window starts; `window.full_history` says which window you got.
- Rows are ordered by event, market, side, team, player, selection, then time. A call returns at most 2,000 rows and has no paging, so narrow a busy event with `market` or `selection_id`.
- Pre-match and in-play prices are separate selections, so their histories never mix. Each row has `is_live`.
- A line move (a spread going from -1.5 to -2.5) and a price move (from -110 to -115) both start a new row: the selection is the same, its `line` and `price` change.

### # Errors

400 with neither event_id nor selection_id (real):

```json
{
  "error": {
    "parameter": "event_id",
    "example": "https://thebet365api.com/api/v1/history?event_id=an-295471&market=moneyline",
    "code": "INVALID_PARAMETER",
    "message": "Send event_id (optionally with market) or selection_id."
  }
}
```

### POST /api/v1/feedback and onboarding

Tell us a league, market or field you need, or report a bug. No key needed and it costs no quota; with a key, the note is attached to your account so we can reply.

```bash
curl -X POST "https://thebet365api.com/api/v1/feedback" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THEBET365API_KEY" \
  -d '{"kind":"missing_data","message":"Need bet365 NBA player points props"}'
```

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `kind` | string | Yes | `missing_feature`, `missing_data`, `bug` or `other`. |
| `message` | string | Yes | 3 to 4,000 characters. |
| `contact` | string | No | Where to reply, up to 320 characters. |

Returns `201 {"received": true}`, or `422 INVALID_FEEDBACK` when `kind` or `message` is missing.

`GET /api/v1/onboarding` returns the account setup questions and `POST /api/v1/onboarding` answers them, so an agent can finish setting up its user's account. Neither costs quota. The MCP tools `get_onboarding_questions` and `answer_onboarding` do the same.

### Watchlists

A watchlist is a saved set of teams, players or events whose bet365 prices you want to follow, stored on your account. It is plain storage: the API does not alert on it. Your own job reads a watchlist, then calls `/odds` for what is on it (see [the alert recipe](https://thebet365api.com/docs#recipe-alerts)).

```text
GET    https://thebet365api.com/api/v1/watchlists          list (limit 1-200, default 50; offset)
POST   https://thebet365api.com/api/v1/watchlists          create
GET    https://thebet365api.com/api/v1/watchlists/{id}     read one
PATCH  https://thebet365api.com/api/v1/watchlists/{id}     change some fields
DELETE https://thebet365api.com/api/v1/watchlists/{id}     delete (204)
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | text | Yes | What this watchlist tracks |
| `league` | text | No | League code such as NFL or EPL |
| `targets` | long_text | Yes | Team names |
| `notes` | long_text | No | Anything you want to remember about this list |

```bash
curl -X POST "https://thebet365api.com/api/v1/watchlists" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $THEBET365API_KEY" \
  -d '{"name":"Premier League top six","league":"epl","targets":"Arsenal\nManchester City\nLiverpool"}'
```

Errors: `400 INVALID_JSON` when the body is not a JSON object, `422 INVALID_RECORD` when a field is missing or wrong (the message lists each one), `404 NOT_FOUND` for an id that is not yours. Each call counts one request.

## Objects

### Event

| Field | Type | Description |
| --- | --- | --- |
| `event_id` | string | Stable id. `an-<n>` for US main-line games, `espn-<n>` for soccer matches. |
| `league` | string | League code, as used by the `league` filter, such as `nba` or `serie-a`. |
| `league_name` | string | Display name, such as `College basketball` or `Premier League`. |
| `sport` | string | `football`, `basketball`, `hockey`, `baseball` or `soccer`. |
| `feed` | string | `us` (US main lines) or `soccer` (soccer lane). MLS games can arrive through the US lane, with US markets. |
| `region` | string or null | `US` on the US lane. `null` on the soccer lane, where the source does not say which bet365 region the price is from. |
| `region_note` | string | Present on soccer events only; says why `region` is null. |
| `home`, `away` | string or null | Team names as the source publishes them. |
| `starts_at` | time or null | Scheduled start, UTC. |
| `status` | string or null | `scheduled`, `live` or `final`; any other value is passed through as the source wrote it. |
| `markets` | string[] | Every market the event has prices for, sorted. |
| `first_observed_at` | time | First capture of any price for this event. |
| `last_observed_at` | time | Latest capture of any price for this event. |
| `prices` | Price[] | On `/odds` and `/events/{id}` only. Ordered by market, pre-match before in-play, then player and side. |

### Price (selection)

One bettable outcome and its current price. A selection is one event, market, period, side, team or player, and pre-match or in-play; its `selection_id` stays the same while the price and line change.

| Field | Type | Description |
| --- | --- | --- |
| `selection_id` | string | `sel_` plus 20 hex characters. Stable for the life of the selection. Use it with `/history`. |
| `market` | string | See [Markets](https://thebet365api.com/docs#markets). |
| `period` | string | `event` (whole game, US lane) or `full_time` (90 minutes plus stoppage time, soccer lane). |
| `side` | string | `home`, `away`, `draw`, `over`, `under`, `yes`, `home_or_draw`, `draw_or_away` or `home_or_away`. See [Markets](https://thebet365api.com/docs#markets). |
| `team` | string or null | The team the side refers to, on US moneyline, spread and team total prices. Null on soccer and on totals. |
| `player` | string or null | The player, on goalscorer markets. Null otherwise. |
| `line` | number or null | Spread handicap from `team`'s point of view, total or goal line. Null on moneyline, match result, double chance and goalscorer markets. Soccer goal lines can be quarter lines such as `3.25`. |
| `price.american` | integer or null | American odds. As published on the US lane; converted from fractional on the soccer lane (rounded to a whole number). |
| `price.decimal` | number | Decimal odds, 4 decimal places. Always present. |
| `price.fractional` | string or null | Fractional odds as published (`17/4`) on the soccer lane. Null on the US lane. |
| `published_format` | string | `american` or `fractional`: the format the source published. The other formats are our conversions. |
| `is_live` | boolean | `true` for an in-play price, `false` for pre-match. |
| `line_status` | string or null | The source's status for the line on the US lane (for example `normal`). Null on soccer. |
| `observed_at` | time | The last capture that saw this exact price. See [Freshness](https://thebet365api.com/docs#freshness). |
| `price_since` | time | When our captures first showed this price and line. |
| `age_seconds` | integer | Seconds from `observed_at` to the moment we answered. |

### History row

| Field | Type | Description |
| --- | --- | --- |
| `selection_id`, `event_id`, `market`, `side`, `team`, `player`, `is_live` |  | As on a [Price](https://thebet365api.com/docs#object-price). |
| `line`, `price` |  | The line and price during this interval. |
| `observed_at` | time | When this price was first captured. |
| `last_seen_at` | time | The last capture that still showed it. On the newest row of a selection that is still listed, this keeps moving forward. |

The response also has `window` (`from`, `full_history`, `collection_started_at`, `note`) and `meta` (`plan`, `remaining`, `count`).

### Meta

| Field | On | Description |
| --- | --- | --- |
| `limit`, `offset` | `/odds`, `/events` | The page you got, after defaults and caps. |
| `from` | `/odds`, `/events` | The start of the time window used: your `from`, or 6 hours before the request. |
| `count` | all lists | Items in `data` on this page. |
| `source_note` | `/odds`, `/events/{id}` | The unofficial-source statement. Show it, or its gist, wherever you display these prices. |
| `plan` | all keyed calls | Your plan id: `free`, `developer`, `pro`, `production` or `scale`. |
| `remaining` | all keyed calls | Requests left this calendar month (UTC) after this call. |

## Data

### Markets

| market | Lane | Sides | line | Notes |
| --- | --- | --- | --- | --- |
| `moneyline` | US | `home`, `away` | null | Who wins the game. `team` names the side. |
| `spread` | US | `home`, `away` | handicap | Point spread (run line, puck line). `line` is from `team`'s point of view. |
| `total` | US | `over`, `under` | total | Combined score over or under `line`. |
| `team_total` | US | `over`, `under` | total | One team's score over or under `line`; `team` says which. On some games only (seen on college football and MLS). |
| `match_result` | Soccer | `home`, `draw`, `away` | null | 1X2 at full time. |
| `double_chance` | Soccer | `home_or_draw`, `draw_or_away`, `home_or_away` | null | Two of the three results. |
| `goal_line` | Soccer | `over`, `under` | goals | Total goals over or under `line`, including quarter lines (2.25, 3.25) that split the stake across two lines. |
| `first_goalscorer` | Soccer | `yes` | null | `player` scores the first goal. |
| `anytime_goalscorer` | Soccer | `yes` | null | `player` scores at any time. |
| `last_goalscorer` | Soccer | `yes` | null | `player` scores the last goal. |

Only main lines are carried on the US lane: alternate spreads and totals are left out. When bet365 moves its main spread from -1.5 to -2.5, the same selection's `line` changes and `/history` records it.

Settlement rules (what counts as a goal, overtime, own goals, void conditions) are bet365's, not ours. We serve prices, not results.

### Odds formats

Every price has all three formats. One of them is what the source published (`published_format`); the others are converted with these rules, the same in every response:

| From | To | Rule | Example |
| --- | --- | --- | --- |
| American | Decimal | +A: 1 + A/100. -A: 1 + 100/A. Rounded to 4 places. | -117 → 1.8547, +350 → 4.5 |
| Fractional | Decimal | 1 + n/d, rounded to 4 places. | 17/4 → 5.25, 41/40 → 2.025 |
| Fractional | American | n/d ≥ 1: +100·n/d. Below 1: -100·d/n. Rounded to a whole number. | 17/4 → +425, 2/5 → -250 |

US-lane prices have `fractional: null`, because we do not invent a fraction for an American price. Because American odds from fractions are rounded, recompute from `decimal` or `fractional` when you need exact implied probabilities: implied probability = 1 / decimal.

```python
def implied(decimal_odds: float) -> float:
    return 1 / decimal_odds

def no_vig(prices: list[float]) -> list[float]:
    """Fair probabilities for one market's sides, with bet365's margin removed (proportional method)."""
    raw = [1 / d for d in prices]
    book = sum(raw)  # > 1: the overround
    return [r / book for r in raw]

# Real match result prices for Manchester City v Fulham: home 2/5 (1.4), draw 17/4 (5.25), away 6/1 (7.0)
print(no_vig([1.4, 5.25, 7.0]))  # about [0.68, 0.18, 0.14]
```

### Leagues

These are the leagues the collector polls. A league appears in responses only once a bet365 price for it has actually been captured; the [coverage page](https://thebet365api.com/coverage) and the `get_bet365_coverage` tool list what is captured right now, with the age of the latest price.

| Code | League | Lane | Markets | Status on 20 Nov 2026 |
| --- | --- | --- | --- | --- |
| `nfl` | NFL | US | moneyline, spread, total | Captured |
| `nba` | NBA | US | moneyline, spread, total | Captured, including in-play |
| `nhl` | NHL | US | moneyline, spread, total | Captured |
| `ncaaf` | College football | US | moneyline, spread, total, team total | Captured |
| `ncaab` | College basketball | US | moneyline, spread, total | Captured, including in-play |
| `mlb` | MLB | US | moneyline, spread, total | Offseason; one game captured |
| `mls` | MLS | US (and polled on soccer) | moneyline, total, team total | Captured through the US lane |
| `epl` | Premier League | Soccer | all six soccer markets | Captured |
| `serie-a` | Serie A | Soccer | all six soccer markets | Captured |
| `bundesliga` | Bundesliga | Soccer | all six soccer markets | Captured |
| `ligue-1` | Ligue 1 | Soccer | all six soccer markets | Captured |
| `ucl` | Champions League | Soccer | all six soccer markets | Captured |
| `laliga` | LaLiga | Soccer | none yet | Polled; the source has shown no bet365 prices |

Our source lists bet365 separately for 16 US states, but on 2026-11-19 every state listing carried identical prices on all 36 games we compared. So we label these prices bet365 (US) and do not sell state-by-state differences.

The source does not state which bet365 region these soccer prices come from; its links point at bet365.com.

### Freshness and observed_at

bet365 does not publish when it changed a price, and the aggregators we read do not either. So we publish the only times we know for certain, our own capture times:

- `observed_at`: the last capture that saw this exact price.
- `price_since`: the first capture that saw it. The real change happened between the previous capture and this time.
- `age_seconds`: how old `observed_at` was when we answered.

### # How often we capture

The collector runs a pass every minute and asks only for what is due:

| Lane | What | How often |
| --- | --- | --- |
| US | League scoreboard (all games, all markets) | Every 60 seconds while the league has a game in the next 24 hours or in play; every 10 minutes otherwise; every 30 minutes when it has no games |
| Soccer | League schedule | Every 10 minutes |
| Soccer | One match's prices | Every 30 seconds in play; every 3 minutes inside 24 hours of kick-off; hourly before that |

Requests are spaced at least 1.1 seconds apart, one at a time, with a fixed budget per pass, so a busy slate can push some captures a little later. A source that refuses us is paused for 15 minutes rather than retried. The [status page](https://thebet365api.com/status) shows the age of the latest capture per lane and the last 24 hours of requests and errors.

### # Reading age_seconds

- Prices of one event usually share an `observed_at`, because one capture reads the whole event.
- If one selection's `age_seconds` keeps growing while the rest of its event refreshes, the source has stopped listing it: the market was pulled or suspended. We keep the last price we saw rather than deleting it, so check the age before you act.
- In-play prices move fast and our capture interval is 30 to 60 seconds. Treat them as an observation, not a quote you can bet into.

### Where the prices come from

We do not read bet365. Its websites block scripted clients, and it publishes no self-serve developer API we can find. Instead:

- US main lines come from a public US odds aggregator's scoreboard, which lists bet365 as a separate book per state. We read those listings and serve a price only when the states agree; a game where they disagree is left out, so the `US` label never sits on one state's price.
- Soccer prices come from a public sports data API that lists bet365 as one of its odds providers. It does not say which bet365 region they are from.

A republished price can lag bet365 or differ from what bet365 shows in your state at that moment. Every response carries `meta.source_note` saying so; please keep that meaning wherever you show the prices. This API is unofficial and not affiliated with, endorsed by or sponsored by bet365. It does not place bets or read a bet365 account.

### Pagination

Lists page by event with `limit` and `offset`. There is no cursor: keep asking with a larger `offset` until a page returns fewer events than `limit`. Each event on `/odds` comes with all of its prices, however many there are.

```python
import os, requests

S = requests.Session()
S.headers["Authorization"] = "Bearer " + os.environ["THEBET365API_KEY"]

def all_events(**params):
    offset = 0
    while True:
        r = S.get("https://thebet365api.com/api/v1/events", params={**params, "limit": 200, "offset": offset}, timeout=20)
        r.raise_for_status()
        page = r.json()["data"]
        yield from page
        if len(page) < 200:
            return
        offset += 200

for e in all_events(league="ncaaf"):
    print(e["event_id"], e["away"], "at", e["home"], e["starts_at"])
```

Each page is one request against your quota. The order is start time then event id, so pages are stable while you read them, apart from new events the collector adds.

## Limits and errors

### Plans and rate limits

| Plan | Price | Requests a month | Requests a minute | Line history |
| --- | --- | --- | --- | --- |
| Free | $0 | 100 | 20 | Last 24 hours |
| Developer | $49/month | 10,000 | 60 | Since collection began |
| Pro | $99/month | 30,000 | 90 | Since collection began |
| Production | $149/month | 50,000 | 120 | Since collection began |
| Scale | $499/month | 250,000 | 180 | Since collection began |

- Every keyed REST call and every keyed MCP data tool call counts one request, whatever it returns, including a 400 or a 404. Calls refused with a 429 do not count toward the month.
- Free: `get_bet365_coverage`, `preview_bet365_odds`, `send_feedback`, `POST /api/v1/feedback`, onboarding.
- The minute limit counts calls in each calendar minute (UTC), across all keys on the account. The monthly allowance resets at 00:00 UTC on the 1st.
- `meta.remaining` on every response tells you what is left this month.
- The [WebSocket stream](https://thebet365api.com/docs#websocket) counts 1 request per connection and 1 per further 5 minutes open. Connections at a time: Free 1, Developer 2, Pro 3, Production 5, Scale 10.
- All plans read every endpoint, league and market. Paid plans add full history and higher limits. Change plan or cancel under **Dashboard → Billing**; see [pricing](https://thebet365api.com/pricing).

### # The 429 body

RATE_LIMITED (sent with Retry-After: 30):

```json
{
  "error": {
    "plan": "free",
    "limit": 20,
    "reset_at": "2026-11-20T02:11:00.000Z",
    "upgrade_url": "https://thebet365api.com/pricing",
    "code": "RATE_LIMITED",
    "message": "Limit is 20 requests per minute on Free. Retry in under a minute."
  }
}
```

`QUOTA_EXCEEDED` has the same shape, with the monthly limit, `reset_at` on the 1st of next month, and the message `Free includes 100 requests a month. Upgrade at https://thebet365api.com/pricing.`

### # Budgeting a polling job

Polling once a minute is 1,440 calls a day, about 43,200 a month, which fits Production. Every 2 minutes is about 21,600 (Pro); every 5 minutes about 8,640 (Developer). One `/odds` call returns up to 100 events with all their prices, so poll per league rather than per game, and filter by `market` when you need one.

### Errors

Every error is JSON with one `error` object holding a stable `code` and a human `message`, plus details where they help. Branch on `code`, not on `message`.

| Status | code | Meaning | What to do |
| --- | --- | --- | --- |
| 400 | `INVALID_PARAMETER` | A bad query parameter or id. Has `parameter`, often `allowed` and `example`. | Fix the named parameter; `example` is a URL that works. |
| 400 | `INVALID_JSON` | A watchlist body that is not a JSON object. | Send JSON with `Content-Type: application/json`. |
| 401 | `INVALID_API_KEY` | Missing, unknown or revoked key. | Send `Authorization: Bearer <key>`. |
| 403 | `ACCOUNT_SUSPENDED` | The account is suspended. | Write to support@thebet365api.com. |
| 404 | `NOT_FOUND` | No such event, or no such watchlist on your account. | List events with `/api/v1/events`. |
| 422 | `INVALID_RECORD` | A watchlist field is missing or wrong. | The message lists each field. |
| 422 | `INVALID_FEEDBACK` | Feedback without a valid `kind` or `message`. | Send both. |
| 429 | `RATE_LIMITED` | Over the plan's per-minute limit. | Wait for `Retry-After` (30 s). |
| 429 | `QUOTA_EXCEEDED` | Monthly allowance used. | Upgrade, or wait for `reset_at`. |
| 503 | `SERVICE_UNAVAILABLE` | Our fault, usually brief. | Retry after `Retry-After`; quote `X-Request-ID`. |

Retrying the right errors:

```python
import os, time, requests

def get(path, **params):
    for attempt in range(4):
        r = requests.get("https://thebet365api.com" + path, params=params, timeout=20,
                         headers={"Authorization": "Bearer " + os.environ["THEBET365API_KEY"]})
        if r.status_code in (429, 503) and r.json()["error"]["code"] != "QUOTA_EXCEEDED":
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        if not r.ok:
            err = r.json()["error"]
            raise RuntimeError(f'{r.status_code} {err["code"]}: {err["message"]}')
        return r.json()
    raise RuntimeError("gave up after retries")
```

### # Empty results are not errors

A filter that matches nothing returns `200` with `data: []` and `meta.count: 0`. That is normal for a league between games, for `live=true` when nothing is in play, or for a soccer league before its next round is priced. Check the [coverage page](https://thebet365api.com/coverage) for when a league was last captured. An empty page still counts one request.

## Recipes

### Recipe: track line movement

Show how bet365's moneyline moved before a game. One call to `/history` returns every change; each row is an interval, so you can plot it as steps.

```python
import os, requests

KEY = os.environ["THEBET365API_KEY"]
r = requests.get("https://thebet365api.com/api/v1/history",
                 params={"event_id": "an-295471", "market": "moneyline"},
                 headers={"Authorization": "Bearer " + KEY}, timeout=20)
r.raise_for_status()

for row in r.json()["data"]:
    if row["is_live"]:
        continue  # pre-match only
    print(f'{row["team"]:<24} {row["price"]["american"]:>5}  from {row["observed_at"][11:19]} to {row["last_seen_at"][11:19]} UTC')
```

Output for the Knicks side of the real game in the [history example](https://thebet365api.com/docs#history): `-115` until 00:32, `-113` until 00:52, `-115` until 01:03, then `-117`. To compare spreads, use `market=spread` and watch `line` as well as `price`.

For a whole slate, call `/events` for the day, then `/history` per event. On the free plan you get the last 24 hours, which covers the run-up to tonight's games; paid plans read back to the start of collection.

### Recipe: capture closing lines

The closing line is the last pre-match price before the game started. Pre-match and in-play prices are separate selections, so the closing price of a selection is simply the last history row with `is_live: false`.

```python
import os, requests
from datetime import datetime, timezone, timedelta

S = requests.Session()
S.headers["Authorization"] = "Bearer " + os.environ["THEBET365API_KEY"]
BASE = "https://thebet365api.com/api/v1"

def closing_lines(event_id: str, market: str) -> dict:
    rows = S.get(f"{BASE}/history", params={"event_id": event_id, "market": market}, timeout=20).json()["data"]
    close = {}
    for row in rows:            # ordered by selection, then time
        if not row["is_live"]:
            close[row["selection_id"]] = row  # the last one wins
    return close

# Games that started in the last 12 hours, finished ones included
since = (datetime.now(timezone.utc) - timedelta(hours=12)).isoformat()
events = S.get(f"{BASE}/events", params={"league": "nba", "from": since, "limit": 200}, timeout=20).json()["data"]
for e in events:
    if e["status"] not in ("live", "final"):
        continue
    for row in closing_lines(e["event_id"], "spread").values():
        print(e["away"], "at", e["home"], "|", row["team"], row["line"], row["price"]["american"], "last seen", row["last_seen_at"])
```

- Start times are scheduled times, and some sources keep listing the pre-match line for a few minutes after the scheduled start. Taking the last pre-match row, not the row at `starts_at`, gets the true close.
- Our close is accurate to the capture interval: within about a minute for US games on a game day, about 3 minutes for soccer.
- Run it after games start and store the result. On the free plan history covers 24 hours, so a daily job is enough; paid plans can rebuild closes for any game since collection began.

### Recipe: compare bet365 with another book

bet365 is the only book in this API. To compare it with prices you already have from another source, match on teams and start time, then compare implied probabilities rather than raw odds.

```python
import os, requests

bet365 = requests.get("https://thebet365api.com/api/v1/odds", params={"league": "nfl", "market": "moneyline", "live": "false"},
                      headers={"Authorization": "Bearer " + os.environ["THEBET365API_KEY"]}, timeout=20).json()["data"]

def norm(name: str) -> str:
    return "".join(ch for ch in name.lower() if ch.isalnum())

# other_book: your own rows, e.g. [{"home": "Kansas City Chiefs", "away": "...", "team": "...", "decimal": 1.62}, ...]
def compare(other_book):
    index = {(norm(e["home"]), norm(e["away"])): e for e in bet365}
    for row in other_book:
        e = index.get((norm(row["home"]), norm(row["away"])))
        if not e:
            continue
        mine = next((p for p in e["prices"] if p["team"] and norm(p["team"]) == norm(row["team"])), None)
        if not mine:
            continue
        diff = 1 / row["decimal"] - 1 / mine["price"]["decimal"]
        print(f'{row["team"]:<24} bet365 {mine["price"]["decimal"]:.3f} vs other {row["decimal"]:.3f} '
              f'({diff:+.1%} implied) bet365 seen {mine["age_seconds"]}s ago')
```

- Team names are the source's full names (`New York Knicks`, `Manchester City`). Keep a small alias table for books that abbreviate.
- Compare prices observed at about the same time: `age_seconds` tells you how old ours is. A two-minute gap can be the whole edge on a moving line.
- Use [no-vig probabilities](https://thebet365api.com/docs#odds-formats) when comparing books with different margins.

### Recipe: alert on line moves

The simplest way is the [WebSocket stream](https://thebet365api.com/docs#websocket): it pushes each change with its previous price, so there is nothing to diff, and a connection costs about 288 requests a day instead of 1,440 for polling once a minute. To poll instead, call `/odds` and diff against the last answer, keyed on `selection_id`, which stays stable while the price and line change:

```python
import os, time, requests

S = requests.Session()
S.headers["Authorization"] = "Bearer " + os.environ["THEBET365API_KEY"]
last = {}  # selection_id -> (line, american)

def poll(league: str, market: str, min_cents: int = 10):
    r = S.get("https://thebet365api.com/api/v1/odds", params={"league": league, "market": market, "live": "false", "limit": 100}, timeout=20)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "30")))
        return
    r.raise_for_status()
    for e in r.json()["data"]:
        for p in e["prices"]:
            now = (p["line"], p["price"]["american"])
            before = last.get(p["selection_id"])
            last[p["selection_id"]] = now
            if before is None or before == now:
                continue
            line_moved = before[0] != now[0]
            price_moved = before[1] is not None and now[1] is not None and abs(now[1] - before[1]) >= min_cents
            if line_moved or price_moved:
                who = p["team"] or p["player"] or p["side"]
                print(f'MOVE {e["away"]} at {e["home"]}: {market} {who} {before} -> {now} (seen {p["observed_at"]})')

while True:
    poll("nfl", "spread")
    time.sleep(120)  # about 21,600 calls a month: the Pro plan
```

- Polling faster than the collector captures gains nothing: US lines are captured about every 60 seconds on game days, soccer every 3 minutes before kick-off.
- Comparing American odds in cents is rough across the -100/+100 boundary; compare `decimal` or implied probability for a cleaner threshold.
- To alert only on teams you care about, store them in a [watchlist](https://thebet365api.com/docs#watchlists) and filter on `team` or `player`.

### Recipe: export to CSV or pandas

Flatten events and prices into one row per price. `pandas.json_normalize` does the nesting for you:

```python
# pip install requests pandas
import os, requests, pandas as pd

r = requests.get("https://thebet365api.com/api/v1/odds", params={"league": "epl", "limit": 100},
                 headers={"Authorization": "Bearer " + os.environ["THEBET365API_KEY"]}, timeout=30)
r.raise_for_status()

df = pd.json_normalize(
    r.json()["data"], record_path="prices",
    meta=["event_id", "league", "home", "away", "starts_at", "status"],
)
# columns: selection_id, market, period, side, team, player, line, published_format, is_live, line_status,
#          observed_at, price_since, age_seconds, price.american, price.decimal, price.fractional, event_id, ...
df["observed_at"] = pd.to_datetime(df["observed_at"])
df.to_csv("bet365_epl.csv", index=False)

# Anytime goalscorer board, shortest price first
scorers = df[df.market == "anytime_goalscorer"].sort_values("price.decimal")
print(scorers[["home", "away", "player", "price.fractional", "price.decimal", "observed_at"]].head(20))
```

For history, the same works on `/history` with `record_path` left out, since each row is already flat apart from `price`:

```python
h = requests.get("https://thebet365api.com/api/v1/history", params={"event_id": "an-295471"},
                 headers={"Authorization": "Bearer " + os.environ["THEBET365API_KEY"]}, timeout=30).json()
hist = pd.json_normalize(h["data"])
hist.to_csv("bet365_an-295471_history.csv", index=False)
```

Command line only? `jq` turns a response into CSV:

```bash
curl -s "https://thebet365api.com/api/v1/odds?league=nba&market=total" -H "Authorization: Bearer $THEBET365API_KEY" \
  | jq -r '.data[] as $e | $e.prices[] | [$e.event_id, $e.away, $e.home, .side, .line, .price.american, .is_live, .observed_at] | @csv'
```

### Recipe: ask an AI agent

Once the [MCP server](https://thebet365api.com/docs#mcp) is connected, an agent picks the tools itself. Prompts that work well, because they map onto what the API holds:

- *Which NFL games this week has bet365 moved the spread on, and by how much?* (events, then history per game)
- *What does bet365 have Erling Haaland at to score anytime this weekend, and when was it observed?*
- *Pull bet365's closing totals for last night's NBA games into a table.*
- *Is bet365 covering Ligue 1 today? How old is the latest price?* (coverage, no key needed)

Agents are told to quote `observed_at` with every price and to say the price is republished, not read from bet365. If yours does not, ask it to.

## More

### FAQ

### # Is this the official bet365 API?

No. It is an independent, unofficial API, not affiliated with, endorsed by or sponsored by bet365. bet365 offers no public, self-serve developer API that we can find. We serve bet365 prices as republished by public odds aggregators.

### # Can I place bets or read my bet365 account with it?

No. It is read-only price data. It never logs in to bet365 and holds no bet365 account data.

### # How fresh are the prices?

Each price has observed_at, our capture time. US games on a game day are captured about every 60 seconds, soccer matches every 3 minutes inside 24 hours of kick-off and every 30 seconds in play. The status page shows the latest capture age per lane.

### # Do you have bet365 player props?

Soccer goalscorer markets (first, anytime and last) yes. US player props (NFL, NBA, MLB, NHL) no: the sources we read do not republish bet365's US props. The feedback endpoint is the place to ask for them.

### # Do you have in-play odds?

Some. When the source republishes bet365 in-play prices we capture them, marked is_live: true (seen on NBA and college basketball). Coverage is partial, and with a 30 to 60 second capture interval they are observations, not tradable quotes.

### # How far back does history go?

To the first capture on 19 November 2026, on paid plans. Free keys read the last 24 hours. There is no backfill before collection began.

### # Which US state are the US prices from?

The source lists bet365 separately for 16 states; we serve a game only when every listed state has the same price, and label it bet365 (US). State-by-state differences are not sold.

### # Why does LaLiga return nothing?

We poll it, but the source has shown no bet365 prices for LaLiga so far. The coverage page will list it as soon as a price is captured.

### # Is there a bet365 odds WebSocket or stream?

Yes. wss://stream.thebet365api.com/v1/stream pushes every bet365 price and line change as the collector stores it, with the previous price, on every plan including Free, with the same API key. It costs 1 request per connection plus 1 per 5 minutes connected. There are no webhooks.

### # Is there an SDK?

Not yet. The API is small enough that the standard-library examples here are the client, and /openapi.json generates one in any language with openapi-generator or similar.

### # Can I show these prices in my app?

Yes, under the terms of service. Show observed_at with each price, and keep the meaning of the source note: unofficial, republished bet365 prices.

### Changelog and machine-readable reference

| Resource | What it is |
| --- | --- |
| [/openapi.json](https://thebet365api.com/openapi.json) | OpenAPI 3.1 for every endpoint on this page, with operationIds, for client generators and agent frameworks. |
| [/llms-full.txt](https://thebet365api.com/llms-full.txt) | This reference plus the agent guide as one text file. |
| [/llms.txt](https://thebet365api.com/llms.txt) | The short index for language models. |
| [/agents.md](https://thebet365api.com/agents.md) | Instructions written for an AI agent using the API on someone's behalf. |
| [/skill.md](https://thebet365api.com/skill.md) | An Agent Skill file to install the API into an agent. |
| [/docs.md](https://thebet365api.com/docs.md) | This page as markdown. |
| [/coverage](https://thebet365api.com/coverage) | Leagues and markets captured right now. |
| [/status](https://thebet365api.com/status) | Collector and WebSocket stream health: latest capture age and 24-hour errors per lane. |

### # Changes

- **20 Nov 2026**: [WebSocket stream](https://thebet365api.com/docs#websocket) at `wss://stream.thebet365api.com/v1/stream`: every price change pushed live, on every plan.
- **20 Nov 2026**: docs rebuilt as a full reference. Finished games leave the default lists; pass `from` to include them. Paid plans opened.
- **19 Nov 2026**: collection began, and the API launched with `/odds`, `/events`, `/events/{id}`, `/history` and the MCP server.

We add fields without notice but never rename or remove one without a dated entry here. Questions: support@thebet365api.com.
