Cookbook

You are integrating the ParlayAPI sports betting odds feed into a project.

API root:           https://parlay-api.com
Auth:               header `X-API-Key: YOUR_API_KEY`  (or query param `apiKey=YOUR_API_KEY`)
Free tier:          1,000 requests/month, no card required, signup at https://parlay-api.com/signup
Reference:          https://parlay-api.com/docs            (full endpoint docs)
LLM-friendly schema:https://parlay-api.com/llms.txt        (read this first)
OpenAPI spec:       https://parlay-api.com/openapi.json    (auto-generate clients)
Cookbook:           https://parlay-api.com/cookbook        (this page)

Core endpoints (all GET, JSON responses):
  /v1/sports                                  list every supported sport_key
  /v1/sports/{sport_key}/events               upcoming games
  /v1/sports/{sport_key}/odds                 current moneyline / spread / total across 26+ books
  /v1/sports/{sport_key}/props                player props (points, rebounds, hits, etc.)
  /v1/sports/{sport_key}/live                 in-play markets only
  /v1/sports/{sport_key}/compare              side-by-side line comparison + best-line highlight
  /v1/sports/{sport_key}/arbitrage            pre-computed cross-book arb opportunities
  /v1/sports/{sport_key}/ev                   pre-computed +EV bets vs no-vig consensus
  /v1/sports/{sport_key}/line-movement        time-series price moves
  /v1/historical/sports/{sport_key}/odds      historical odds (backtest)
  /v1/historical/sports/{sport_key}/closing-odds   closing lines (CLV)
  /v1/bookmakers                              list of supported books with status
  /ws/odds/{sport_key}                        WebSocket push (Pro tier)

Standard response shape (odds endpoint):
[
  {
    "id": "",
    "sport_key": "baseball_mlb",
    "commence_time": "2026-05-04T19:00:00Z",
    "home_team": "Boston Red Sox",
    "away_team": "Houston Astros",
    "bookmakers": [
      {
        "key": "pinnacle", "title": "Pinnacle", "last_update": "...",
        "markets": [
          { "key": "h2h", "outcomes": [
              {"name": "Boston Red Sox", "price": -135},
              {"name": "Houston Astros", "price": +120}
          ]}
        ]
      },
      ... 24 more books ...
    ]
  }
]

Conventions to respect:
- All odds are real captures from each book's real endpoint. Never derive an Under from an
  Over or interpolate; if a price is missing, it was missing at the source.
- Decimal odds via `oddsFormat=decimal` query param. American is the default.
- Filter to specific books with `bookmakers=pinnacle,fanduel,draftkings`.
- For props use market_key like `player_points`, `player_hits`, `player_pass_yds` (TOA canonical).
- Historical endpoints take a `date=YYYY-MM-DDTHH:MM:SSZ` query param.

When you write code, default to:
- requests/httpx for Python, fetch/axios for JS.
- Cache responses for 30 seconds; the upstream collector polls at 30-60s, so finer caching
  wastes credits without adding freshness.
- Surface the Pinnacle line as the sharp baseline when computing fair odds.
- Use /v1/historical/sports/{sport_key}/closing-odds for CLV (closing line value), not the
  live odds endpoint.
- For agent/AI applications, prefer /v1/sports/{key}/compare or /ev or /arbitrage rather
  than reimplementing those calculations yourself.

Do not assume any specific bookmaker; query /v1/bookmakers to see what is currently active.
The list grows; the schema is stable.

curl 'https://parlay-api.com/v1/sports' -H 'X-API-Key: YOUR_API_KEY'

You are an AI sports analyst. Your job: rank the top 10 player prop bets for tonight's NBA
slate by expected value, given the historical performance of each player and the current
sportsbook lines.

Step 1: GET https://parlay-api.com/v1/sports/basketball_nba/props?markets=player_points,player_rebounds,player_assists
Step 2: For each player, fetch the last 10 games of stats from a reliable source
        (balldontlie.io, NBA stats API, etc.) and compute their season mean and std for
        the relevant stat.
Step 3: Compute the implied probability the prop hits given the player's distribution.
Step 4: Compare to the implied probability from the over_price and under_price. The edge is
        (your_prob - implied_book_prob).
Step 5: Filter to props with edge > 4% AND volume across at least 3 books.
Step 6: Return the top 10 ranked by edge with: player, market, line, your_pick (over/under),
        edge_percent, books_offering, sample_size, confidence_level.

Be conservative: if a player has fewer than 5 games of data this season, exclude. If the
prop is from only one book, flag it as low-confidence.

import os, statistics, requests
KEY = os.environ["PARLAYAPI_KEY"]
H = {"X-API-Key": KEY}

# 1. get current NBA player-points props
props = requests.get(
    "https://parlay-api.com/v1/sports/basketball_nba/props",
    params={"markets": "player_points"}, headers=H, timeout=10,
).json()

# 2. for each player, pull recent stats and compute distribution mu/sigma
def player_distribution(player_name):
    # TODO: replace with your stats source (balldontlie, nba_api, etc.)
    games = fetch_recent_games(player_name, n=15)
    return statistics.mean(games), statistics.stdev(games)

# 3. compute edge
import math
def normal_cdf(x, mu, sigma):
    return 0.5 * (1 + math.erf((x - mu) / (sigma * math.sqrt(2))))

def implied_prob(odds_american):
    return 100 / (odds_american + 100) if odds_american > 0 else -odds_american / (-odds_american + 100)

picks = []
for p in props:
    mu, sigma = player_distribution(p["player"])
    p_over = 1 - normal_cdf(p["line"], mu, sigma)
    book_p = implied_prob(p["over_price"])
    edge = p_over - book_p
    if edge > 0.04:
        picks.append({**p, "model_p": p_over, "edge": edge})

picks.sort(key=lambda x: -x["edge"])
for pk in picks[:10]:
    print(f"{pk['player']:<22} O{pk['line']} {pk['edge']:+.1%} edge")

curl 'https://parlay-api.com/v1/historical/sports/baseball_mlb/closing-odds?date=2026-05-03T22:00:00Z®ions=us&markets=h2h' \
  -H 'X-API-Key: YOUR_API_KEY'

curl 'https://parlay-api.com/v1/sports/basketball_nba/ev?min_edge=3' \
  -H 'X-API-Key: YOUR_API_KEY' | jq '.[] | {event, book, market, price, ev_percent}'

curl 'https://parlay-api.com/v1/sports/soccer_epl/arbitrage?min_profit=1' \
  -H 'X-API-Key: YOUR_API_KEY'

curl 'https://parlay-api.com/v1/sports/baseball_mlb/line-movement?event_id=...&window_minutes=10' \
  -H 'X-API-Key: YOUR_API_KEY'

import os, requests, time

PARLAY = os.environ["PARLAYAPI_KEY"]
WEBHOOK = os.environ["DISCORD_WEBHOOK"]    # https://discord.com/api/webhooks/...
SEEN = set()

def scan():
    r = requests.get(
        "https://parlay-api.com/v1/sports/basketball_nba/ev",
        params={"min_edge": 4}, headers={"X-API-Key": PARLAY}, timeout=10,
    )
    for bet in r.json():
        bet_id = f'{bet["event_id"]}-{bet["book"]}-{bet["market"]}-{bet["side"]}'
        if bet_id in SEEN: continue
        SEEN.add(bet_id)
        msg = (f'**{bet["matchup"]}** | {bet["book"]} | {bet["market"]} '
               f'{bet["side"]} {bet["price"]} | edge **{bet["edge_percent"]}%**')
        requests.post(WEBHOOK, json={"content": msg}, timeout=5)

while True:
    try: scan()
    except Exception as e: print("err:", e)
    time.sleep(60)

import requests
from datetime import datetime, timedelta

def historical_at(sport_key, date_iso):
    return requests.get(
        f"https://parlay-api.com/v1/historical/sports/{sport_key}/odds",
        params={"date": date_iso, "regions": "us", "markets": "h2h"},
        headers={"X-API-Key": KEY},
    ).json()

# replay every game day in the last 90 days, run your strategy, record P/L
start = datetime(2026, 2, 1)
for d in range(90):
    day = start + timedelta(days=d)
    games = historical_at("baseball_mlb", day.strftime("%Y-%m-%dT19:00:00Z"))
    for g in games:
        pick = your_strategy(g)            # returns {side, price} or None
        if not pick: continue
        result = settled_result(g)         # use /v1/sports/{key}/scores or your own data
        record_pl(pick, result)

// Anthropic Claude SDK with tool use
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

const tools = [{
    name: "parlayapi_get",
    description: "Fetch sports odds from ParlayAPI. Pass any path from /v1/...",
    input_schema: {
        type: "object",
        properties: {
            path:   { type: "string", description: "endpoint path, e.g. /v1/sports/baseball_mlb/odds" },
            params: { type: "object", description: "query params" }
        },
        required: ["path"]
    }
}];

const message = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    tools,
    messages: [{ role: "user", content: "Find the +EV NBA bet with the largest edge tonight." }],
});

// when message.content has a tool_use block, fetch:
async function call_parlayapi(path, params) {
    const url = `https://parlay-api.com${path}?${new URLSearchParams(params)}`;
    const r = await fetch(url, { headers: { "X-API-Key": process.env.PARLAYAPI_KEY }});
    return await r.json();
}