Odds-API.io case study: from API key to AI-agent market analysis (and what happens at the betting step)

Step 1: How do you get an Odds-API.io API key?

As of 2 November 2026, Odds-API.io says new free API keys are paused indefinitely. Free keys issued before the pause keep working. If free keys return, the company says it will announce this in its changelog ^[1]. Today the route to a key is:

1. Pick a plan on the Odds-API.io pricing page Partner link. Solo (£49/month) is the entry plan ^[2].
2. Pay by card, Apple Pay, Google Pay or PayPal. Monthly plans can also be paid in 10+ cryptocurrencies. Annual plans are card only ^[2].
3. Check your email. The docs say the key goes to the address you signed up with. The MCP page says it also appears on your dashboard once payment clears ^{[6] [3]}.
4. Choose your bookmakers in the dashboard. Your plan decides how many you can choose, and you can change them later with the same key ^[2].
5. Keep the key secret. The docs warn never to commit it to version control and to store it in an environment variable such as ODDS_API_KEY ^[6].

You can test some endpoints before paying. GET https://api.odds-api.io/v3/sports needs no key ^[6]:

curl "https://api.odds-api.io/v3/sports"
# → [{"name": "Football", "slug": "football"}, {"name": "Basketball", "slug": "basketball"}, ...]

Referral discount: according to Odds-API.io's partner page, customers who come through a partner link get 30% off their first 3 months. The pricing FAQ adds that promo codes and affiliate discounts apply to monthly plans only. Check the final price at checkout before you pay ^{[7] [2]}.

Choose a plan and get your key → Partner link

Step 2: What is the difference between the free and paid Odds-API.io plans?

Paid plans differ only in how many bookmakers you can choose. Requests, sports and markets are the same on every paid plan. The free tier is separate: it has a much lower request limit, is limited to recreational bookmakers, and is closed to new sign-ups ^{[2] [1]}.

Prices as published on 2 Nov 2026 ^{[2] [1]}.

• Annual billing costs 10× the monthly price, so you get two months free. Annual plans are card only and cannot be combined with extra-request packages ^[2].
• WebSocket streaming is an add-on that costs the plan price again (2× in total), e.g. Solo + WebSocket is £98/month. Odds-API.io recommends it for the lowest latency ^[2].
• More requests: you can raise the limit to 10,000/hour (+£139/month), 20,000/hour (+£229/month) or 30,000/hour (+£309/month) ^[2].
• Currency: prices are in GBP, but checkout charges your local currency (GBP, USD, EUR, BRL, CNY, JPY or KRW) ^[2].
• Paid-only features: the docs mark native id mappings (Polymarket/Kalshi ids) and dropping odds as paid-plan features ^{[8] [9]}.

Which plan fits this case study? To compare one sportsbook with Polymarket and Kalshi you need three bookmakers, which means Starter (5). To compare two sportsbooks with both prediction markets you need four, which is still Starter. Solo only fits a two-source comparison.

Compare Odds-API.io plans → Partner link

Step 3: How do you let an AI agent fetch Odds-API.io data?

There are two routes. You can give the agent the docs so it writes REST code, or give it live tools through the official MCP server. Odds-API.io notes that most people use both ^{[3] [9]}.

Option A: the official MCP server (Claude, Codex, Cursor, VS Code)

The server is the npm package odds-api-mcp-server, and it is MIT-licensed open source. It runs on your machine over stdio and sends your key only to api.odds-api.io. Each tool call is a normal API request and counts toward your 5,000/hour ^[3].

# Claude Code
claude mcp add odds-api --env ODDS_API_KEY="your-api-key" -- npx -y odds-api-mcp-server

# Codex CLI
codex mcp add odds-api --env ODDS_API_KEY="your-api-key" -- npx -y odds-api-mcp-server

For Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json), add this block ^[9]:

{
  "mcpServers": {
    "odds-api": {
      "command": "npx",
      "args": ["-y", "odds-api-mcp-server"],
      "env": { "ODDS_API_KEY": "your-api-key" }
    }
  }
}

VS Code uses .vscode/mcp.json with a top-level "servers" key instead of "mcpServers". A Docker image (oddsapi/odds-api-mcp-server) and a one-click .mcpb file for Claude Desktop are also available ^[3].

The 25 tools include get_events, search_events, get_odds, get_multi_odds, get_odds_movements, get_value_bets, get_arbitrage_bets, get_historical_odds and grade_bets. The server only reads data. It cannot log in to a bookmaker or place a bet ^[3].

What about ChatGPT?

ChatGPT connects to remote MCP servers over SSE or streaming HTTP, so it cannot launch a local stdio server like odds-api-mcp-server directly. OpenAI offers a Secure MCP Tunnel for private or local servers ^[10]. The simpler route in ChatGPT is the docs approach: Odds-API.io suggests asking it to read https://docs.odds-api.io/llms-full.txt, or pasting its copy-paste context block ^[9]. If you want MCP tools in an OpenAI product, the Codex CLI command above is the supported way.

Option B: REST code the agent writes (Python / TypeScript)

The base URL is https://api.odds-api.io/v3, and the key goes in the apiKey query parameter ^[9]. The official SDKs are pip install odds-api-io and npm install odds-api-io ^[11].

# Python — official SDK (pip install odds-api-io)
import os
from odds_api import OddsAPIClient

client = OddsAPIClient(api_key=os.environ["ODDS_API_KEY"])
events = client.get_events(sport="football", league="england-premier-league")
odds = client.get_event_odds(event_id=events[0]["id"],
                             bookmakers="Bet365,Polymarket,Kalshi")
for bookie, markets in odds["bookmakers"].items():
    ml = next((m for m in markets if m["name"] == "ML"), None)
    if ml:
        o = ml["odds"][0]
        print(bookie, o["home"], o.get("draw"), o["away"])
print(odds.get("urls", {}))   # direct links to the event at each bookmaker

// TypeScript — official SDK (npm install odds-api-io)
import { OddsAPIClient } from "odds-api-io";

const client = new OddsAPIClient({ apiKey: process.env.ODDS_API_KEY! });
const events = await client.getEvents({ sport: "football", league: "england-premier-league" });
const odds = await client.getEventOdds({ eventId: events[0].id, bookmakers: "Bet365,Polymarket,Kalshi" });
for (const [bookie, markets] of Object.entries(odds.bookmakers)) {
  const ml = markets.find((m) => m.name === "ML");
  if (ml?.odds?.[0]) console.log(bookie, ml.odds[0].home, ml.odds[0].draw, ml.odds[0].away);
}

Example agent prompt from Odds-API.io's MCP page: “Which Premier League matches this weekend have the biggest gap between Bet365 and Unibet on the match result?” The agent answers it with get_events plus get_multi_odds ^[3].

Get a key for the MCP server → Partner link

Step 4: The case study: how do you analyse one match across sportsbooks and prediction markets?

Illustrative example data. The Polymarket and Kalshi prices below are the sample values in Odds-API.io's prediction-markets guide (Leeds United v Arsenal, ML market) ^[12]. The two sportsbook rows are invented for illustration. None of these are live prices, and nothing here is a result, a tip or a profit.

4.1 The data shape

GET /v3/odds?eventId=…&bookmakers=Polymarket,Kalshi,Bet365,Unibet returns one object per event. It has a bookmakers map of markets, a urls map with a link to the event at each bookmaker, and, for prediction markets, bookmakerIds plus back/lay prices and depth in USD ^{[12] [6]}:

"Polymarket": [{ "name": "ML", "odds": [{ "home": "6.67", "draw": "4.35", "away": "1.56",
  "layHome": "1.61", "layAway": "7.14", "layDraw": "4.55",
  "depthHome": "12128", "depthAway": "331", "depthDraw": "26086" }] }]

4.2 Implied probability and overround

Implied probability is 1 ÷ decimal odds. Prediction-market prices in cents convert the same way: 60¢ is 60%, which is odds of 1.67 ^[12]. Summing the three outcomes shows each source's margin (overround):

4.3 Removing the vig (fair probabilities)

The simplest de-vig method divides each implied probability by the total. Bookmaker A's 16.7 / 23.8 / 65.4 (sum 105.8) becomes about 15.7% / 22.5% / 61.8%, which is fair odds of about 6.35 / 4.45 / 1.62. Proportional de-vigging is only one method. Odds-API.io's own value-bet engine instead builds fair odds from a panel of sharp bookmakers, because soft books' padded margins skew the baseline ^[13].

4.4 Line shopping

The best price per outcome across the four sources is home 6.67 (Polymarket), draw 4.35 and away 1.56 (Polymarket and Kalshi). Those best prices sum to 102.1%, which is above 100%, so this illustrative match has no arbitrage. Odds-API.io's definition requires the best prices to sum below 100% ^[14].

4.5 Sportsbook vs prediction market: is there “value”?

Using the average of the two illustrative bookmakers' de-vigged probabilities as a stand-in fair line (home ≈15.5%), Polymarket's home price of 6.67 gives EV = 0.155 × 6.67 − 1 ≈ +3%. This is the docs' formula, EV = fair probability × odds − 1 ^[13]. In practice that figure would shrink or disappear because:

• the baseline is two invented soft-book prices, not a sharp consensus ^[13];
• Polymarket and Kalshi charge fees, which Odds-API.io's arbitrage engine handles with netOdds ^{[14] [15] [16]};
• depth matters: the docs warn that a price with little liquidity behind it can't take meaningful size ^[12];
• prices move between the snapshot and your order. The docs call value bets theoretical and note that not all of them win ^[13].

# Python: de-vig, line shopping and EV on an /v3/odds response (illustrative)
def implied(o): return 1 / float(o)

def devig(prices):                       # prices = {"home": "6.00", "draw": "4.20", "away": "1.53"}
    p = {k: implied(v) for k, v in prices.items() if k in ("home", "draw", "away")}
    total = sum(p.values())
    return {k: v / total for k, v in p.items()}, total - 1   # fair probs, overround

def best_prices(event):
    best = {}
    for book, markets in event["bookmakers"].items():
        ml = next((m for m in markets if m["name"] == "ML"), None)
        if not ml: continue
        for side in ("home", "draw", "away"):
            price = float(ml["odds"][0][side])
            if side not in best or price > best[side][0]:
                best[side] = (price, book, event.get("urls", {}).get(book))
    return best

def ev(fair_prob, odds): return fair_prob * float(odds) - 1   # docs formula

4.6 Let the API do it: /value-bets and /arbitrage-bets

Odds-API.io also calculates these for you. /v3/value-bets?bookmaker=… returns expectedValue, betSide and bookmakerOdds.href (a link to the bet). Value bets are recalculated every 5 seconds ^[13]. /v3/arbitrage-bets?bookmakers=… returns profitMargin, legs[] (with netOdds and maxStake when known) and optimalStakes[]. It covers pre-match only, and margins are “calculations at the quoted prices, not guaranteed returns” ^[14].

Docs note: the REST guide's example shows expectedValue as a fraction (0.0523 = 5.23%), while one SDK snippet subtracts 100 as if it were a percentage-style value. Check a live response before you set thresholds ^{[13] [11]}.

Run this analysis with your own Odds-API.io key → Partner link

Step 5: After the analysis, how are bets placed on different platforms?

Odds-API.io is a data service. Neither the API nor the MCP server places bets ^[3]. What happens next depends on the platform, and on whether it is legal for you at all.

Sportsbooks (e.g. bet365): manual, through the deep link

Responses include links to the event at each bookmaker: urls in /v3/odds, bookmakerOdds.href in value bets and legs[].href in arbitrage, where it shows "N/A" if no link is known ^{[6] [13] [14]}. Open the link, log in to an account you hold legally, and check that the price is still there before confirming. Do not automate this step. bet365's General Terms (effective 28 Sep 2026) list as “Prohibited Activities” arbitrage betting (§16.2(e)), using a VPN to disguise your location (§16.2(k)), scraping (§16.2(w)) and “artificial intelligence, automated players (bots) and/or player assistance software” (§16.2(z)). bet365 may also void bets it believes automated systems placed (§14.5(c)) ^[17]. Odds-API.io itself warns that bookmakers may limit accounts that consistently find value ^[13].

Polymarket (international): official SDK, with geoblocking

Use /v3/mappings?bookmaker=Polymarket to turn an Odds-API.io selection into Polymarket's conditionId and CLOB token id (paid plans) ^[8]. Then use Polymarket's official SDK (pip install polymarket-client or npm install @polymarket/client) ^[18]:

# Polymarket docs pattern (Python, async)
from polymarket import AsyncSecureClient
client = await AsyncSecureClient.create(private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
                                        wallet=os.environ["POLYMARKET_WALLET_ADDRESS"])
response = await client.place_market_order(asset_id=asset_id, side="BUY", amount="10")  # spend up to 10 pUSD

Polymarket says orders from blocked regions are rejected and tells builders to check GET https://polymarket.com/api/geoblock first. Its list makes the US, UK, France, Germany, Italy, Taiwan, Singapore and Australia, among others, close-only ^{[4] [19]}. Its help centre says using a VPN to get around this breaks its terms ^[20]. US users have a separate CFTC-regulated exchange, Polymarket US ^[21].

Kalshi: signed API requests, demo first

Use /v3/mappings?bookmaker=Kalshi to get the contract ticker and the yes/no side ^[8]. Kalshi API requests carry KALSHI-ACCESS-KEY, KALSHI-ACCESS-TIMESTAMP and KALSHI-ACCESS-SIGNATURE headers. The signature covers timestamp + method + path, made with your private key ^[22]. Orders are a POST to /portfolio/events/orders. Test against the demo environment (external-api.demo.kalshi.co) first ^{[23] [24]}.

# Kalshi docs pattern (demo): 1 YES contract, limit order
order = {"ticker": market_ticker, "side": "bid", "count": "1", "price": "0.0100",
         "time_in_force": "good_till_canceled", "client_order_id": str(uuid.uuid4())}
r = post(private_key, API_KEY_ID, "/portfolio/events/orders", order)   # signed POST, see Kalshi auth guide

Kalshi requires users to be 18+ and may ask for identity documents ^[25]. Its 22 June 2026 Exchange Notice bars event-contract trading from restricted jurisdictions including the UK, Canada, Australia, France, Italy, Ireland, Poland, Portugal, Switzerland, Taiwan, Singapore, Thailand and the People's Republic of China ^[5]. In the US, Kalshi's sports contracts are being contested in state and federal courts ^[26].

Is it legal where you are?

Insider trading rules apply to event contracts too. The CFTC has brought enforcement cases ^{[33] [34]}.

Frequently asked questions