OpenAPI-first sports betting odds API for coding agents, with simple REST examples, TypeScript SDK, Python SDK, MCP server, mock mode, arbitrage, positive EV, line movement, and bookmaker comparison.

Collect a free API key from odds-api.net.

30-second REST quickstart · Start simple · Coverage · AI agents · Mock mode · Examples · Safety · Security

Use this when you want the smallest possible odds API request with no SDK, no framework, and no repo setup.

export ODDS_API_KEY="your_api_key"

curl -sS \
  -H "X-API-Key: $ODDS_API_KEY" \
  "https://api.odds-api.net/v1/sports"

No SDK required. No framework required. Plain REST and JSON.

One-file Python example:

python3 examples/minimal-rest/python/odds.py

One-file JavaScript example:

node examples/minimal-rest/javascript/odds.mjs

For typed clients, local mock mode, MCP tools, arbitrage, positive EV, bookmaker comparison, and line movement, continue to the SDK and agent sections below.

Start simple, then move to SDKs, MCP, or OpenAPI when needed.

No SDK required. No framework required. No MCP required. Plain REST and JSON.

curl -sS \
  -H "X-API-Key: $ODDS_API_KEY" \
  "${ODDS_API_BASE_URL:-https://api.odds-api.net/v1}/sports"

import os
import requests

api_key = os.environ["ODDS_API_KEY"]
base_url = os.getenv("ODDS_API_BASE_URL", "https://api.odds-api.net/v1")

response = requests.get(
    f"{base_url.rstrip('/')}/sports",
    headers={"X-API-Key": api_key},
    timeout=20,
)
response.raise_for_status()

print(response.text)

const apiKey = process.env.ODDS_API_KEY;
const baseUrl = process.env.ODDS_API_BASE_URL || "https://api.odds-api.net/v1";

const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/sports`, {
  headers: { "X-API-Key": apiKey }
});

console.log(await response.text());

Full files live in:

examples/minimal-rest/curl
examples/minimal-rest/python
examples/minimal-rest/javascript

odds-api/odds-api supports both minimal REST examples and full agent-native workflows.

Simple sample repos are useful when you only need one HTTP request.

odds-api/odds-api includes the same plain REST starting point, plus the pieces needed when the project grows:

• one-file REST examples
• curl quickstart
• Python REST quickstart
• JavaScript REST quickstart
• OpenAPI contract
• TypeScript SDK
• Python SDK
• MCP server for coding agents
• mock mode for local development and tests
• Postman collection
• arbitrage examples
• positive EV examples
• bookmaker comparison helpers
• line movement examples

Start with plain REST. Upgrade only when you need more structure.

This repo is designed to be easy for AI coding agents to use.

Agents should use:

• openapi.yaml as the canonical public API contract
• sdks/typescript for TypeScript, Node.js, Next.js, and full-stack TypeScript projects
• sdks/python for Python scripts, notebooks, and data pipelines
• mcp-server for Claude, Cursor, Windsurf, Cline, and other MCP-compatible coding agents
• examples/minimal-rest when the user asks for raw REST, one curl command, or the smallest possible setup
• ODDS_API_MOCK=1 for local examples without a live API key

Common agent tasks supported:

• search sports events
• get odds
• compare bookmakers
• find arbitrage
• find positive EV bets
• track line movement
• build odds dashboards, alerts, bots, and betting research tools

See AGENTS.md, llms.txt, and agents/AGENTS.md for agent-specific instructions.

Use the SDKs when you want ergonomic helpers, typed app integration, and reusable workflows.

npm install @odds-api/client

import { OddsApiClient } from "@odds-api/client";

const client = new OddsApiClient({
  apiKey: process.env.ODDS_API_KEY
});

const events = await client.searchEvents({
  sport: "rugby-league",
  league: "NRL"
});

const best = await client.findBestOdds(events.items[0].event_id);
console.log(best);

python3 -m pip install odds-api-client

Published package: odds-api-client on PyPI.

import os
from odds_api import OddsApiClient

client = OddsApiClient(api_key=os.environ["ODDS_API_KEY"])
events = client.search_events(sport="rugby-league", league="NRL")
best = client.find_best_odds(events["items"][0]["event_id"])
print(best)

For local SDK development from the repo:

python3 -m pip install -e sdks/python

SDK helpers include:

searchEvents        findBestOdds        compareBookmakers
findArbitrage      findPositiveEv      getLineMovement
getEvent           getEventBookmakers  getRacingEvent
getApiMetadata     getMe               getUsage
getLimits          getMarketSchema

The Odds API MCP server is an MCP server for sports odds and betting odds workflows. Use it when an AI coding agent needs tool access to events, odds, bookmaker comparison, arbitrage, positive EV, line movement, racing odds, account usage/limits, bookmaker country catalogs, results, market schema data, and persistent SSE/WebSocket stream inspection.

{
  "mcpServers": {
    "odds-api": {
      "command": "npx",
      "args": ["@odds-api/mcp"],
      "env": {
        "ODDS_API_KEY": "your_api_key",
        "ODDS_API_BASE_URL": "https://api.odds-api.net/v1"
      }
    }
  }
}

Use mock mode for local demos and agent tests:

ODDS_API_MOCK=1 npx @odds-api/mcp

See mcp-server/README.md and docs/mcp.md.

Use ODDS_API_MOCK=1 for local demos, generated apps, smoke tests, and agent workflows without live credentials.

ODDS_API_MOCK=1 npm test
ODDS_API_MOCK=1 node examples/javascript/arbitrage-scanner/index.mjs
ODDS_API_MOCK=1 python3 examples/python/positive-ev-scanner/main.py

openapi.yaml is the canonical public API contract. openapi.json is the JSON export.

Use the OpenAPI spec to generate clients, validate requests, inspect schemas, build agent workflows, and understand endpoint parameters, response shapes, and errors.

• openapi.yaml
• openapi.json
• Runtime reference UI
• Postman collection

Production base URL:

https://api.odds-api.net/v1

Authenticate server-side requests with:

X-API-Key: <your_api_key>

Minimal REST examples:

examples/minimal-rest/curl
examples/minimal-rest/python
examples/minimal-rest/javascript

Advanced JavaScript examples:

examples/javascript/arbitrage-scanner
examples/javascript/positive-ev-scanner
examples/javascript/odds-comparison-widget
examples/javascript/line-movement-chart
examples/javascript/betting-dashboard
examples/javascript/bookmaker-price-monitor
examples/javascript/discord-bot
examples/javascript/telegram-bot

Advanced Python examples:

examples/python/arbitrage-scanner
examples/python/positive-ev-scanner
examples/python/line-movement-chart

Every advanced example supports:

ODDS_API_KEY
ODDS_API_BASE_URL
ODDS_API_MOCK=1

Run all mock-mode smoke tests:

npm install
npm run build
ODDS_API_MOCK=1 npm test

.
├── AGENTS.md
├── llms.txt
├── openapi.yaml
├── openapi.json
├── examples/
│   ├── minimal-rest/
│   ├── javascript/
│   └── python/
├── sdks/
│   ├── typescript/
│   └── python/
├── mcp-server/
├── agents/
└── postman/

• docs/README.md
• docs/mcp.md
• docs/npm-publishing.md
• docs/pypi-publishing.md
• docs/discovery-pages
• SECURITY.md
• openapi.yaml
• Runtime reference UI

Contributions are welcome for examples, SDKs, MCP tooling, OpenAPI docs, and agent-friendly workflows. Keep public docs focused on the API contract, REST examples, SDKs, MCP tools, examples, and safety caveats.

Odds can move, markets can suspend, accounts can be limited, selections can void, and execution can fail. Do not describe arbitrage, positive EV, or any betting workflow as risk-free or guaranteed profit without execution-risk caveats.

This is a read-only data and tooling package. It does not place bets.

SDKs, reference examples, and tooling in this repository are released under Apache-2.0. API access and data usage are governed by the terms published at odds-api.net.