Guide

every use case, agents first, then the season in order

“My agent can talk about fantasy football but cannot touch my league.”

claude mcp add --transport http open-leagues https://leagues.waits.dev/api/mcp
codex  mcp add open-leagues --url https://leagues.waits.dev/api/mcp

# receipts, week boards, the season ledger, lines, cohorts, grading, staking
# rate-limited per IP · nothing here needs a person

Name          Url                                     Bearer Token Env Var  Status   Auth
open-leagues  https://leagues.waits.dev/api/mcp       OPENLEAGUES_TOKEN      enabled  Bearer token

Then ask it a question. Captured preseason 2026 against the live host, unedited. The first two calls are tools Codex assumed existed.

mcp: open-leagues/getDesk failedmcp: open-leagues/getSchedule failedmcp: open-leagues/listMyLeagues completedmcp: open-leagues/getAgentContext completedmcp: open-leagues/getLeagueBundle completedmcp: open-leagues/getMatchups completedmcp: open-leagues/getSchedule completed

• /api/mcp rejects cookie sessions in every mode. It accepts a bearer token or a proxied user id.
• stdio needs a Postgres DATABASE_URL and OPENLEAGUES_USER, and exits without both.

“Checking whether home dogs with over half the tickets are a signal takes a spreadsheet and a weekend.”

# discover: tune on 2023–24, verify on 2025, freeze only if it clears
sampleGames      { "seasons": [2023, 2024], "filter": { "homeDog": true, "played": true, "splits": [{ "market": "spread", "side": "home", "tickets": [50, 100] }] } }
evaluateBets · summarizeRun                       # read pBreakEven and n
sampleGames      { "seasons": [2025], …same filter }   # the holdout, opened once
evaluateBets · summarizeRun
simulateBankroll { "graded": […], "bankroll": 1000, "policy": { "type": "percent", "pct": 1, "cap": 2 } }
freezeStrategy   { "name": "…", "spec": { words, seasons, filter, bet, staking, bankroll } }   # only if it cleared

# run, every Tuesday, on the frozen rule
getStrategy → getLabRuns → sampleGames (last week) → evaluateBets → summarizeRun
→ simulateBankroll (season) → recordLabRun → the digest

── discover ──────────────────────────────────────────────────────────────
mcp: sampleGames  { "seasons": [2023, 2024], "filter": { "homeDog": true, "played": true,
                    "splits": [{ "market": "spread", "side": "home", "tickets": [50, 100] }] } }
mcp: evaluateBets · summarizeRun
     discovery 2023–24   27-18   roi +0.14   pBreakEven 0.19   n 45

mcp: sampleGames  { "seasons": [2025], … same filter, untouched }        ← the holdout, opened once
mcp: evaluateBets · summarizeRun
     holdout 2025        15-18   roi −0.13   pBreakEven 0.83   n 33

→ does not clear the holdout. The skill reports it and does NOT call freezeStrategy.

…

• Lines and results are nflverse closing numbers. Missing prices default to −110 and the payload says which odds were used.
• Grading is tested against DAL–DET, week 14 2025 (DET −3.5, 44–30), and reports closing-line value when your number differed from the close.
• Ticket and money percentages are opt-in (OPENLEAGUES_SPLITS_SOURCE). Action Network consensus has history from 2023 and is the source backtests use. DraftKings Network handle and bet share and the WiseGuyTeam multi-book read cover the current slate, each kept under its own book. All are undocumented and stored on your box once pulled.
• Tuned on 2023–24 this cohort went 27-18, roi +0.14. On the 2025 holdout it went 15-18, roi −0.13. pBreakEven 0.19 means a 27-18 record comes up by luck one time in five. The skill does not freeze it and says why.
• The staking policy is the caller’s. simulateBankroll compounds it, reports drawdown in dollars, flags when Kelly was fed its own sample, and resamples the bets 1000 times. Here a +$19 result shows as a band from −$108 to +$170 with a 43% chance of a loss.
• Opening lines and line movement are not wired in (free only for 2007–2021). A frozen strategy is stored on your box and never touched by the run skill.
• docs/lab.md in the repo has the full walkthrough, from box to the sentence to say.

“I was winning until the 4pm games.”

https://leagues.waits.dev/r/1255972181892935680/14/9

GET /r/1255972181892935680/14/9

NateBot 129.0 — Roster 14 85.3 · final
Took the lead for good at 3:41pm ET on Trevor Lawrence.
You were 78% to win at 3:11pm ET · 1 lead change this week · 78.78–78.56 at the flip

…

• Rebuilt from nflverse play-by-play under your league’s scoring settings, to the second.
• Where the play log and Sleeper’s official stats disagree, the difference is booked at the final whistle. Finals match Sleeper to the cent, 84 of 84 team-weeks checked on this league. A correction that decides a week is named as one.
• The current week appears once the play log publishes; until then the receipt says so.

“I have the Sleeper app and no league id.”

ryanwaits

type: ryanwaits

[
  { "name": "SDIFFL", "league_id": "1255972181892935680", "total_rosters": 14, "season": "2025" }
]

→ pick one → /r/1255972181892935680

• Read from Sleeper’s public user and league endpoints. Nothing about you is stored.
• Team names only: a team named after its manager’s username renders as Roster N.

“I should have started him.”

https://leagues.waits.dev/r/1255972181892935680/14/9#bench

Left 6.5 on the bench. Saquon Barkley 20.2 sat behind Omarion Hampton 13.7.

  Sleeper projection   start   15.0 / 9.7
  Last 3 weeks         start    8.0 / 0.0
  Season average       start   12.8 / 5.9
…

• Sleeper projection, last three weeks, and season average, each valued under your league’s book. No paid source appears, even as a comparison.
• The receipt grades in hindsight and names which source was right.

“I think I overpaid on waivers.”

https://leagues.waits.dev/r/1255972181892935680/14/9#wire

"wire": {
  "moves": [
    { "kind": "waiver", "add": "Stefon Diggs", "bid": 26, "won": false,
      "budget": 200, "bidPct": 13, "medianPct": null, "leagues": null }
  ],
  "spent": 0
}
…

• Only leagues that asked for a receipt contribute; nothing is crawled. No league id, manager, or roster appears in the file.
• Each price is a share of the bidder’s league budget, with the share of their remaining budget beside it. Raw dollars appear only inside a single-budget cohort. Filters by roster count, scoring format, and superflex keep formats apart.
• n is the number of winning bids behind a price. With one league it is one bid; the receipt shows a median only once a second league has cleared a claim.

“Every site tells me who to start and none tells me if it was right.”

https://leagues.waits.dev/r/1255972181892935680/14/9#ledger

GET /r/1255972181892935680/14/9  →  season ledger, below the receipt
mcp: getSourceLedger { "leagueId": "1255972181892935680", "rosterId": 9 }

NateBot · 2025 · 16 weeks
You set lineups worth 1874.3 and left 151.0 on the bench.
Following Sleeper projection every week would have added +2.1.

  source               beat · tied · lost     vs you
  Sleeper projection      5  ·  5  ·  6         +2.1
  Last 3 weeks            1  ·  1  · 13       -236.4
…

• Each source’s lineup is filled the same way yours is, from its pre-kickoff numbers under your league’s book, then scored on the box score.
• Settled weeks are computed once and kept. The first ask for a team takes about half a minute; later asks are cached.
• Two of the three sources lose to this manager by over 230 points, and the ledger reports it.

“I want to see every matchup in the league this week.”

https://leagues.waits.dev/r/1255972181892935680?week=14

GET /r/1255972181892935680?week=14

{ "league": { "id": "1255972181892935680", "name": "SDIFFL", "season": "2025", "hosted": false },
  "week": 14, "currentWeek": 17,
  "rows": [
    { "matchupId": 1, "home": { "rosterId": 3, "name": "My Toe Hurts", "points": 9 },   "away": { "rosterId": 6,  "name": "BBQ BRISSKET", "points": 4 },    "outcome": "home" },
…

“Screenshots get argued with.”

https://leagues.waits.dev/r/1255972181892935680/14/9

curl -I https://leagues.waits.dev/api/og/r/1255972181892935680/14/9

HTTP/1.1 200
content-type: image/png
cache-control: public, max-age=300, s-maxage=900

→ a 1200×630 card: both scores, the flip line, the bench line, the wire line, the URL.

• Rendered server-side from the receipt; nothing appears that is not on the page.
• To have a league’s receipts taken down, open an issue on the repo with the league id.

“Every side project starts by hand-building the same Sleeper-to-ESPN-to-nflverse id table.”

curl -s https://leagues.waits.dev/api/players.json

curl -s https://leagues.waits.dev/api/players.json | jq '.players[] | select(.sleeper_id=="4866")'

{
  "sleeper_id": "4866",
  "gsis_id": "00-0034844",
  "espn_id": "3929630",
  "yahoo_id": "30972",
  "rotowire_id": "12507",
  "sportradar_id": "9811b753-347c-467a-b3cb-85937e71e2b9",
  "name": "Saquon Barkley",
  "team": "PHI",
  "position": "RB"
}

"count": 11826 · access-control-allow-origin: * · cache-control: public, max-age=3600, s-maxage=86400

• Sleeper’s player file plus the dynastyprocess id table. Sleeper alone has a GSIS id for a fifth of active players; the join gives every active player one.
• Sleeper stays the authority on its own ids; the id table only fills what Sleeper leaves blank.

“Paid tools predict FAAB prices, and nobody publishes what cleared.”

curl -s https://leagues.waits.dev/api/wire/2025/14.json | jq '.prices[:3]'

GET /api/wire/2025/14.json
{
  "season": "2025", "week": 14, "leagues": 1,
  "budgets": { "200": 1 },
  "cohort": {},
  "prices": [
    { "player_id": "2449", "name": "Stefon Diggs",       "position": "WR",  "n": 1, "median_pct": 39.5, "p25_pct": 39.5, "p75_pct": 39.5, "max_pct": 39.5, "median_pct_remaining": 76.7, "dollars": { "budget": 200, "median": 79 } },
    { "player_id": "CIN",  "name": "Cincinnati Bengals", "position": "DEF", "n": 1, "median_pct": 1,    "p25_pct": 1,    "p75_pct": 1,    "max_pct": 1,    "median_pct_remaining": 8.3,  "dollars": { "budget": 200, "median": 2 } },
    { "player_id": "3678", "name": "Wil Lutz",           "position": "K",   "n": 1, "median_pct": 0,    "p25_pct": 0,    "p75_pct": 0,    "max_pct": 0,    "median_pct_remaining": 0,    "dollars": { "budget": 200, "median": 0 } }
  ]
}

Full field shapes for both files are on Open data.

“Our league’s history belongs to an app that sells ads against it.”

git clone https://github.com/ryanwaits/open-leagues.git
cd open-leagues
docker compose up -d

# http://localhost:8080

• With no DATABASE_URL the box uses the embedded PGLite database and still keeps a league.
• Players, stats, and projections come from Sleeper and nflverse over outbound requests. No member needs an account anywhere else.

“We would switch, but not if it means re-typing ten rosters and a scoring table.”

/new → Import → Sleeper → paste 1255972181892935680
review teams, scoring, rosters → Commit

importLeague without confirm
  → Error: importLeague requires confirm: true

• No manager emails are pulled from any source. The commissioner types the invite allowlist, which is not on MCP.
• exportLeague returns a JSON snapshot at any time.

“I don’t want to be the one who forgets to process waivers.”

OPENLEAGUES_SELF_TICK=1      # a long-lived box ticks itself; on Vercel, vercel.json's cron is the clock

advanceWeek without confirm
  → Error: advanceWeek requires confirm: true

tick over MCP
  → Error: tick is a cron clock, not a tool

# what the clock does on its own, every hour
#   scoring refresh · week advances with the NFL schedule · waivers clear Wednesday

“I want my agent to set lineups without the power to wreck the league.”

bun scripts/ledger.mjs mintToken --write --user usr_… --name codex --scope read

{
  "id": "…",
  "token": "ol_…",          ← shown once; only its hash is stored
  "prefix": "ol_…",
  "scope": "read",
  "note": "Copy the token now — only its hash is stored. Revoke from /account or by id."
}

bun scripts/ledger.mjs --help

Ledger CLI. Reads by default; writes need --write (placeWager, mintToken).

Usage:
  bun scripts/ledger.mjs --list
  bun scripts/ledger.mjs getEvents --league <id> [--limit n] [--sinceWeek n]
  bun scripts/ledger.mjs getLeagueFacts --league <id> --week <n>
…

• Your box issues and checks tokens against its own table; nothing is central. They are hashed at rest and shown once. An act token cannot fade its own team.
• OPENLEAGUES_MCP_AUTH=proxy trusts a user-id header from your edge instead, and x-openleagues-scope: read narrows a caller.

“The agent says it set a good lineup, and I have only its word.”

getAgentContext { "leagueId": "lg_…" }     # start every session here: seat, purse, week, the tools you may call
startPlayer     { "leagueId": "lg_…", "playerId": "4866", "slot": "RB" }

startPlayer with a read token
  → Error: startPlayer is a write; this token is read-only

importLeague without confirm
  → Error: importLeague requires confirm: true

asking the clock to run
  → Error: tick is a cron clock, not a tool

reading a league-box league without a seat
  → Unauthorized · 401

• Two checks gate every call: a user id on every write and a seat check on every hosted read. Browser, CLI, and agent get the same rule.
• Raw Sleeper ids need no seat. That data is already public.

“I don’t want to learn 99 verbs to set a lineup.”

npx skills add ryanwaits/open-leagues -g                 # all six, Claude Code
npx skills add ryanwaits/open-leagues --skill open-leagues-lab-discover -g
npx skills add ryanwaits/open-leagues --agent codex -g   # Codex