# Rito Dynasty Ballers: League API Guide for Agents This guide is for an AI agent (or script) working on behalf of **one team** in the Rito Dynasty Ballers fantasy football league. Give it the whole file. It covers everything needed to follow the live auction draft, read every roster and budget, submit sealed RFA bids, and file offseason requests. - **Base URL:** `https://rito.grza.com` - **This guide (always current):** `https://rito.grza.com/guide` - **Format:** JSON in and out. Every response is JSON. Times are ISO-8601 UTC. - **Your key:** each team has exactly one API key, shaped like `rito_xxxxxxxxxxxxxxxxxxxxxxxx`. It identifies your team. Don't share it; the commissioner can rotate it. --- ## 1. Thirty-second quick start ```bash KEY=rito_yourkeyhere BASE=https://rito.grza.com curl -s -H "Authorization: Bearer $KEY" $BASE/api/me # who am I, my budget curl -s -H "Authorization: Bearer $KEY" $BASE/api/state # everything about the draft right now curl -sN -H "Authorization: Bearer $KEY" $BASE/api/stream # live events (server-sent events) ``` If your HTTP client can't set headers (for example, a browser `EventSource`), pass the key as a query parameter instead: `?key=$KEY`. --- ## 2. How the draft works (what the API models) 1. **Restricted free agent (RFA) round** runs first. Each RFA gets sealed bids from the other teams. The commissioner reveals all bids at once. The RFA's owner then **matches** the high bid (keeps the player) or **declines** (the high bidder gets him). Either way the contract is **2 years at the high bid**. With no bids, the owner keeps him at $10 for 2 years. 2. **Auction.** Teams take turns **nominating** a player in **reverse order of last season's finish**: last place nominates first and the champion nominates last, then it repeats. Teams with full rosters are skipped. Bidding is **verbal, in the room**, going around the table in seat order. The API does **not** take auction bids. The commissioner enters the result: winning team plus price. You learn about every nomination and signing within about a second through the stream. 3. A winning auction bid signs the player to a **3-year contract** at that price. **Your agent's job during the auction:** watch `player_nominated` events, decide what you'd pay (never more than your `max_bid`), and tell your human. Humans do the bidding out loud. --- ## 3. League rules your agent should know These come from `GET /api/rules`, which is the source of truth. Defaults are shown here. | Rule | Value | |---|---| | Salary cap | $300 (must be at or under it by the end of the draft) | | Roster size | 18 (IR players use a bench slot during the draft) | | Lineup | 1 QB, 2 RB, 2 WR, 1 TE, 2 FLEX (RB/WR/TE), 1 DEF, 1 K, 8 BE (+4 IR after the draft) | | Minimum bid | $1 | | Auction contract | 3 years at the winning price | | In-season FA pickup | $25, 2 years (including the pickup season) | | RFA | one mid-season pickup per team; starts at $10; result is 2 years at the high bid | | Extension | in the final contract year, extend 1–3 years. New price = original + $15 × years added. The new price applies to the current final year and every added year. | | Nomination order | last place → champion, repeating; full rosters skipped | | Keep/drop/extend deadline | one week before the draft (`keeper_deadline` from the commissioner) | | Scoring | 0.5 PPR, ESPN standard circa 2024, 0.1 pt/yd for K, bonuses for 40+ yd TDs | ### Max bid formula (computed for you) ``` remaining_budget = 300 - sum(salaries of active contracts) open_slots = 18 - number of active contracts max_bid = open_slots > 0 ? remaining_budget - (open_slots - 1) * 1 : 0 ``` You must keep $1 for every other empty slot. Every team summary in the API already includes `max_bid`, `remaining_budget` and `open_slots`. Use those numbers rather than recomputing them. --- ## 4. Core objects ### Team summary ```json { "team_id": 3, "team": "Chopper", "owner": "Chopper", "seat": 2, "seat_zone": "table", "last_finish": 9, "roster_count": 15, "roster_size": 18, "open_slots": 3, "open_starting_slots": ["RB"], "committed": 251, "salary_cap": 300, "remaining_budget": 49, "max_bid": 47, "can_bid": true, "rfa_designated": [], "warnings": [] } ``` - `open_starting_slots` lists required starting slots nobody fills yet (for example, the team has no K). It is useful for predicting who will bid on what. - `seat_zone` is `"table"` or `"video"` (dialed in remotely). `last_finish` is last season's finish (1 = champion). - `warnings` can include "Over the $300 cap by $4". ### Contract (one row in a roster) ```json { "slot": "RB", "contract_id": 812, "player_id": "9509", "player": "Bijan Robinson", "pos": "RB", "nfl_team": "ATL", "salary": 80, "years_left": 1, "acquired": "keeper", "rfa": false } ``` - `slot` is the lineup slot the API assigned for display: `QB RB WR TE K DEF FLEX BE`, or `OVER` if the roster has more than 18. - `acquired` is one of `keeper | auction | fa | rfa | trade | manual`. **Only `fa` (in-season pickup) players can be designated RFA.** - `years_left` counts the upcoming season. `1` means this is the last year, so it's extension-eligible. - An empty slot appears as `{ "slot": "WR", "player": null }`. ### Block (the player up for auction) ```json { "player_id": "4984", "player": "Josh Allen", "pos": "QB", "nfl_team": "BUF", "nominated_by": { "team_id": 7, "team": "Chris" }, "opened_at": "2027-08-22T19:04:11.512Z" } ``` `block` is `null` when nobody is up. --- ## 5. Read endpoints (any team key) | Method & path | Returns | |---|---| | `GET /api/me` | Your team id/name and team summary | | `GET /api/state` | **One-call snapshot:** `phase`, `block`, `nomination` (current + upcoming + full order), all team summaries, last 10 signings, `last_event_id` | | `GET /api/block` | Who's up right now, plus which team is nominating | | `GET /api/nominations?upcoming=11` | `mode`, `current` nominator, `upcoming` list, the full nomination `order` (with `last_finish` and `has_open_slots`), and `seat_order` (the bidding order around the room). Full teams are skipped automatically. | | `GET /api/teams` | Summaries for all 12 teams | | `GET /api/teams/{id or name}` | One team's summary plus `roster` (all 18 slots, open ones included) | | `GET /api/rosters` | Every team with full roster (the whole league in one call) | | `GET /api/signings?season=2027` | Every signing this season, in order (`kind`: `auction` or `rfa`) | | `GET /api/players?q=allen&pos=QB&available=true&limit=25` | NFL player search. Each result has `available` and, if taken, `rostered_by {team, salary, years_left}` | | `GET /api/rules` | The rule constants above | | `GET /api/events?since={event_id}` | Event log after an id (polling alternative to the stream) | | `GET /api/rfa` | RFAs in the current round, bid counts, **your own** bid, and after the reveal all bids | | `GET /api/requests` | Your team's offseason requests and their status | `phase` is one of `offseason` (requests open), `rfa` (sealed bidding), `draft` (auction live, requests closed) or `season` (in-season; rosters follow ESPN). --- ## 6. Live updates ### Option A: stream (recommended) `GET /api/stream` is a standard **Server-Sent Events** stream. The first message is `event: hello` with the full `state` snapshot. After that, each event looks like this: ``` id: 4182 event: player_signed data: {"id":4182,"ts":"2027-08-22T19:06:40.001Z","type":"player_signed","data":{ ... }} ``` - To reconnect without missing anything, send the last id you saw as the `Last-Event-ID` header, or as `?since=4182`. Missed events are replayed. - A `: ping` comment arrives every 20 seconds; ignore it. Python: ```python import json, requests r = requests.get(f"{BASE}/api/stream", headers={"Authorization": f"Bearer {KEY}"}, stream=True) event = None for line in r.iter_lines(decode_unicode=True): if line.startswith("event:"): event = line[6:].strip() elif line.startswith("data:"): msg = json.loads(line[5:]) handle(event, msg.get("data", msg.get("state"))) ``` Node: ```js const res = await fetch(`${BASE}/api/stream`, { headers: { Authorization: `Bearer ${KEY}` } }); const dec = new TextDecoder(); let buf = ''; for await (const chunk of res.body) { buf += dec.decode(chunk); let i; while ((i = buf.indexOf('\n\n')) >= 0) { const block = buf.slice(0, i); buf = buf.slice(i + 2); const ev = /^event: (.*)$/m.exec(block)?.[1]; const data = /^data: (.*)$/m.exec(block)?.[1]; if (ev && data) handle(ev, JSON.parse(data)); } } ``` ### Option B: polling Call `GET /api/events?since=` no more than once per second. Start from `last_event_id` in `/api/state`. ### Event types | `type` | `data` | |---|---| | `player_nominated` | `{ block, nominating_team }` | | `block_cleared` | `{}` (nomination withdrawn) | | `player_signed` | `{ signing_id, contract_id, player_id, player, pos, nfl_team, team_id, team, amount, contract_years, team_summary, next_nominator }` | | `signing_undone` | `{ signing_id, player, team_id, team, team_summary, block }` (the commish fixed a mistake; the player is back on the block) | | `nomination_changed` | `{ current, upcoming }` | | `seating_updated` | `{ order, current }` | | `phase_changed` | `{ phase }` | | `rfa_round_opened` | `{ rfas }` | | `rfa_bid_received` | `{ contract_id, player, bid_count }` (never reveals who bid or how much) | | `rfa_revealed` | `{ rfas }` with all bids | | `rfa_resolved` | `{ contract_id, player, outcome: matched\|won\|unbid, team_id, team, amount, contract_years, team_summary, original_owner }` | | `request_resolved` | `{ request_id, team, type, status, player, team_summary }` | | `roster_changed` | Manual commish edits or ESPN sync (`{ reason, changes }`) | **Tip:** `player_signed.data.team_summary` is the winning team's new budget, so you don't need a follow-up call. Teams that didn't sign anyone are unchanged. --- ## 7. RFA round (sealed bids) Flow: the commish opens the round (`phase` becomes `rfa`). You submit or replace sealed bids. The commish reveals. The owner matches or declines. ```bash # See RFAs in play curl -s -H "Authorization: Bearer $KEY" $BASE/api/rfa # Bid (or change your bid; the last one counts) until the reveal curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"contract_id": 812, "amount": 31}' $BASE/api/rfa/bids # Withdraw your bid curl -s -X DELETE -H "Authorization: Bearer $KEY" $BASE/api/rfa/bids/812 ``` Rules the API enforces: - You can't bid on your own RFA (`own_rfa`). - `amount` must be at least $1 and no more than your current `max_bid` (`exceeds_max_bid`). - Bids are hidden from everyone, the commissioner included, until the reveal. Before that, `GET /api/rfa` shows only `bid_count` and your own `my_bid`. - Ties go to the earliest bid. **If you own an RFA,** after the reveal you decide: ```bash curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"match": true}' $BASE/api/rfa/812/decision # true = keep at the high bid; false = let him go ``` The commissioner can also record your decision for you. --- ## 8. Offseason requests (drops, RFA designation, extensions) Requests are open while `phase` is `offseason` (and `rfa`). They close at `keeper_deadline`. Every request is checked against the rules when you submit it, then queued for the commissioner to approve or reject. Nothing changes until it's approved, and approval fires a `request_resolved` event. ```bash # Drop a player (frees his salary and roster slot once approved) curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"type":"drop","contract_id":812}' $BASE/api/requests # Designate your RFA (must be a mid-season pickup, i.e. acquired = "fa"; one per team) curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"type":"rfa_designate","contract_id":933}' $BASE/api/requests # Extend a player entering his final contract year by 2 years curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"type":"extend","contract_id":640,"years":2,"note":"locking him up"}' $BASE/api/requests # My requests / withdraw a pending one curl -s -H "Authorization: Bearer $KEY" $BASE/api/requests curl -s -X DELETE -H "Authorization: Bearer $KEY" $BASE/api/requests/17 ``` The response includes `checks`, a list of `{rule, ok, detail}`, and `passes_checks`. Hard failures, such as a player who isn't yours, a second RFA, or a bad extension length, are rejected immediately with `rule_check_failed`. One soft check passes through to the commish: `mid_season_pickup` for an RFA. Our records may not know how an older player was acquired, so the commish decides. Extension pricing example: a player at $10 with `years_left: 1`, extended by 2 years, becomes $40 per year with `years_left: 3`. The response shows `payload.new_salary`. --- ## 9. Errors Errors look like this, with a stable `code` you can branch on: ```json { "error": { "code": "exceeds_max_bid", "message": "Your max bid is $47.", "max_bid": 47 } } ``` | HTTP | `code` | Meaning | |---|---|---| | 401 | `unauthorized` | Missing or wrong key | | 403 | `team_key_required` / `commish_only` / `not_owner` | Not allowed with this key | | 404 | `not_found` | Bad id or path | | 400 | `invalid_json`, `invalid_field`, `invalid_type` | Malformed request | | 400 | `bid_too_low`, `exceeds_max_bid`, `own_rfa` | RFA bid rejected | | 400 | `not_your_player`, `rule_check_failed` | Request rejected; see `checks` | | 409 | `bidding_closed`, `wrong_phase`, `duplicate`, `not_pending`, `not_revealed`, `already_resolved` | Wrong time or state | --- ## 10. A suggested agent loop for draft day 1. On start, call `GET /api/state`. Cache every team summary, the nomination order, and `last_event_id`. 2. Open `/api/stream?since=`. 3. On `player_nominated`, look up the player (`/api/players?q=`). Compare against your board and your `max_bid`. Note which rivals have the slot need (`open_starting_slots`) and the money (`max_bid`) to compete. Tell your human a ceiling. 4. On `player_signed`, update the winner's summary from the event. Your own `max_bid` changes only when you sign someone. 5. On `nomination_changed` or `player_signed.next_nominator`, if your team is up next, have a nomination ready. The commissioner enters it; you can't nominate through the API. 6. On `signing_undone`, roll back the signing. 7. If the stream drops, reconnect with `Last-Event-ID`; nothing is lost. Be polite to the server: one stream connection per team, or poll at most once per second. --- ## 11. Getting help The whole surface is `/api/*`. Anything not documented here returns `404` with a pointer back to this guide. If something looks wrong, such as a budget that doesn't match your math, tell the commissioner. Every change is logged in `/api/events`.