Docs
Everything to connect Benchd users to your app: sign-in, the API, webhooks and the TypeScript SDK.
Quickstart
- Register an app and add your redirect URI. You get a client ID right away.
- While it is pending review, connect it to your own Benchd account to build and test.
- Send people through sign-in, then call the API with their token:
import { BenchdClient, buildAuthorizeUrl, createPkcePair,
exchangeAuthorizationCode, randomToken } from '@benchd/sdk-js';
// 1. Send the user to Benchd to approve your app.
const pkce = await createPkcePair(); // keep pkce.verifier + state in the session
const state = randomToken(16);
const url = buildAuthorizeUrl({
clientId: 'bl_app_...',
redirectUri: 'https://yourapp.com/auth/callback',
scopes: ['profile.read', 'league.read'],
state,
codeChallenge: pkce.challenge,
});
// 2. Back on your redirect URI (?code=...&state=...), swap the code for tokens.
const tokens = await exchangeAuthorizationCode({
clientId: 'bl_app_...', code, redirectUri: 'https://yourapp.com/auth/callback',
codeVerifier: pkce.verifier,
});
// 3. Call the API as that user.
const benchd = new BenchdClient({ accessToken: tokens.access_token });
for await (const league of benchd.allLeagues()) console.log(league.name);The SDK goes on npm as @benchd/sdk-js when the Open API opens to everyone.
OAuth 2.1 with PKCE
Benchd uses the authorization code flow with PKCE (S256) for every app. There are no passwords to handle and no implicit flow.
- Consent: send the user to
https://benchdfantasy.com/oauth/authorizewithresponse_type=code,client_id,redirect_uri,scope(space-separated),stateandcode_challenge. - Redirect URIs must match one you registered exactly. Codes live 60 seconds and work once.
- Access tokens are short-lived (10 minutes). Refresh tokens last 30 days and rotate: every refresh returns a new one and the old one stops working. Using an old one again signs the user out of your app.
- Server apps also send their client secret. Public apps (mobile, browser, CLI) have none.
- People can disconnect your app any time from their account. Their tokens then fail with
auth.consent_revoked.
POST /v1/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=...&redirect_uri=... &client_id=bl_app_...&code_verifier=... (+ client_secret=... for server apps)
Scopes
Ask only for what you need. People see each scope in plain words on the consent screen, and can say no.
Read
| Scope | What people see |
|---|---|
profile.read | See your Benchd name. Your display name and handle. Never your email or password. |
league.read | See your leagues. League names, settings, members, matchups, standings and transactions for leagues you are in. |
roster.read | See rosters. Who is on each team in your leagues. |
lineup.read | See lineups. Weekly starting lineups in your leagues. |
draft.read | See drafts. Draft boards, picks and your draft queue. |
waiver.read | See waiver results. Waiver runs and who got which player. |
waiver.claims.read | See your private waiver bids. Read your own team claims, bid amounts, conditional groups and priority order. |
trade.read | See trades. Trades proposed, accepted and completed in your leagues. |
keeper.read | See your keeper options. Read the keeper board and your own eligible keeper choices. |
Act for the user
| Scope | What people see |
|---|---|
lineup.write | Set your lineup. Move your players between starters and bench. Game-time locks still apply. |
draft.pick | Make draft picks for you. Pick a player when you are on the clock. Every pick follows your league rules. |
draft.queue.write | Edit your draft queue. Add, remove and reorder players in your queue. |
roster.write | Move players on your roster. Add and drop free agents, and move your players between bench, IR and taxi. |
waiver.write | Make waiver claims for you. Submit, edit, cancel and reorder your waiver claims, FAAB bids and conditional bid groups. |
trade.propose | Propose trades for you. Send, counter and withdraw trade offers from your team. |
draft.auction.write | Manage your auction bids. Nominate, bid and manage your own hidden maximum bids within your team budget. |
draft.autopick.write | Control your autopick. Enable or disable automatic drafting for your own team. |
keeper.write | Choose your keepers. Set your own keeper choices before the deadline. |
team.write | Edit your team identity. Change your own team name and avatar. |
trade.vote | Vote on league trades for you. Cast your team approval or veto vote when your league allows manager voting. |
trade.accept | Answer trades for you. Accept or reject trade offers sent to you. |
Updates
| Scope | What people see |
|---|---|
webhook.manage | Get updates from your leagues. Be told when picks, trades, waivers and scores happen in leagues you are in. |
Manager permissions cover roster moves, waivers, trades, drafting and keepers. Adding scopes to an approved app requires another app review and fresh user consent for those permissions. Existing tokens keep their original permissions.
The API at a glance
Base URL https://api.benchdfantasy.com/public/v1. Send Authorization: Bearer <access token>. Responses are { data, meta }; lists add page with a next_cursor. You only ever see the user's own leagues, apart from the anonymous site-wide reads below.
GET /public/v1/meThe connected user · profile.readGET /public/v1/leaguesTheir leagues (paged) · league.readGET /public/v1/leagues/{id}Settings, teams, managers · league.readGET …/rostersEvery roster · roster.readGET …/matchups?week=Matchups; points once the week is final · league.readGET …/standingsStandings · league.readGET …/transactionsAdds, drops, trades (paged) · league.readGET / PUT …/teams/{id}/lineupRead league lineups; edit your own · lineup.read / lineup.writeGET /public/v1/drafts/{id}Draft state and the clock · draft.readGET …/drafts/{id}/availablePlayers the user can draft (paged) · draft.readPOST /public/v1/drafts/{id}/picksPick when on the clock · draft.pickGET / PUT …/drafts/{id}/queueDraft queue · draft.read / draft.queue.writeGET /public/v1/players?ids=Players by id (max 100) · league.readGET /public/v1/players/trendingMost added and dropped across Benchd (24h, 7d) · league.readGET /public/v1/trades/feedCompleted trades across Benchd, anonymous (paged) · trade.readGET …/leagues/{id}/playersSearch player identities and free-agent availability · league.readGET / PATCH …/teams/{id}/rosterRoster versions; move your players between bench, IR and taxi · roster.read / roster.writePOST …/teams/{id}/transactionsAdd, drop or atomically swap free agents · roster.writeGET …/leagues/{id}/waiversWaiver settings, budgets and results · waiver.readGET …/leagues/{id}/waiver-claimsYour private claims, bids and groups · waiver.claims.readPOST …/leagues/{id}/waiver-claimsSubmit a claim or conditional bid · waiver.writePATCH / DELETE …/waiver-claims/{id}Edit or cancel your claim · waiver.writePUT …/waiver-claims/orderReorder all your pending claims · waiver.writeGET …/leagues/{id}/trades / trades/{trade_id}Your offers and public league trades · trade.readGET …/leagues/{id}/trade-picksTradable draft picks and their owners · trade.readPOST …/leagues/{id}/tradesPropose a trade · trade.proposePOST …/trades/{id}/accept / rejectAnswer an offer sent to your team · trade.acceptPOST …/trades/{id}/counter / cancelCounter an incoming offer or withdraw your offer · trade.proposePOST …/trades/{id}/voteCast your manager vote during league review · trade.voteGET …/drafts/{id}/auctionAuction board and public budgets · draft.readPOST …/auction/nominations / bidsNominate or bid for your team · draft.auction.writeGET / PUT …/auction/proxy-bidsRead, set or clear your hidden maximum bids · draft.auction.writeGET / PUT …/drafts/{id}/teams/{team_id}/autopickRead or change your autopick setting · draft.read / draft.autopick.writeGET / PUT …/leagues/{id}/keepersRead keeper options; choose your own keepers · keeper.read / keeper.writePATCH …/leagues/{id}/teams/{team_id}Change your team name and avatar · team.write
Send an Idempotency-Key on writes (POST, PUT, PATCH and DELETE). It is required for draft picks and all manager actions below, and recommended for lineup and queue writes. Retry the same action with the same key and body; use a new key for a new action. League rules, roster limits, deadlines, budgets and locks still apply.
Personal keys
Building something only you will use, like a spreadsheet, a script or a local draft helper? Skip app registration and OAuth: make a personal key, pick what it can do, and send it as Authorization: Bearer bk_key_…. It works on every route above, as you, with the same rules and rate limits as an app token.
- Read only by default. Turn on write permissions only if the tool sets your lineup or drafts for you.
- You see the key once. Benchd keeps only a hash; lose it and you revoke it and make another.
- Up to 5 keys per account. Revoking one, or deleting your account, stops it at once.
- Building for other people? Register an app instead, so each person connects with their own consent.
# Your leagues, as you, from a terminal or a spreadsheet's web query
curl -H "Authorization: Bearer bk_key_..." https://api.benchdfantasy.com/public/v1/leagues
# A live draft board for a local draft tool (poll every few seconds while you are drafting)
curl -H "Authorization: Bearer bk_key_..." https://api.benchdfantasy.com/public/v1/drafts/{draft_id}/picksSite-wide data
Two reads cover all of Benchd, not only the user's leagues. Both are anonymous by design: no league, team or manager names or ids, ever. A commissioner can take their league out (League settings), which also removes its past trades and moves. Computer-managed teams are left out.
No key? Both are also open on the sync address, with Sleeper player ids: /sync/v1/trades/feed and /sync/v1/players/nfl/trending/add (or drop).
Completed trades
GET /public/v1/trades/feed (trade.read): every completed trade, newest first, with the settings of the league it happened in (format, team count, scoring, superflex, roster slots), so you can value trades in context. Page with cursor; pass since to fetch only what is new. A reversed trade drops out of the feed.
GET /public/v1/trades/feed?since=2026-10-01T00:00:00Z&limit=50
{ "data": [{
"trade_ref": "tr_Qm9vZ2llV29vZ2llMTIz",
"executed_at": "2026-10-21T14:02:11.000Z", "season": 2026, "week": 7,
"league": { "format": "dynasty", "team_count": 12, "scoring_format": "head_to_head",
"reception_scoring": "full_ppr", "best_ball": false, "superflex": true,
"roster_slots": { "QB": 1, "RB": 2, "WR": 3, "TE": 1, "FLEX": 1, "SUPER_FLEX": 1, "BENCH": 15 } },
"sides": [
{ "receives": [{ "kind": "player", "player": { "player_id": "…", "full_name": "…", "position": "WR", "nfl_team": "CIN" }, … }] },
{ "receives": [{ "kind": "draft_pick", "pick_season": 2027, "pick_round": 1, … }] }
] }],
"page": { "next_cursor": "…", "has_more": true } }Trending adds and drops
GET /public/v1/players/trending (league.read): the most added or dropped players in the last 24 hours or 7 days. count is how many teams made the move, so one team churning a player counts once.
GET /public/v1/players/trending?type=add&window=24h&position=RB&limit=10
{ "data": { "type": "add", "window": "24h", "as_of": "2026-10-25T12:00:00.000Z",
"players": [{ "player_id": "…", "full_name": "…", "position": "RB", "nfl_team": "DET", "count": 412 }] } }What the Open API never carries: live stats, play-by-play, projections or news. Matchup points read 0 until the week is final (status: final).
Sync guide for rankings, draft and trade tools
The usual shape of a league sync, for services like FantasyPros and DraftSharks and for your own local tools.
- Connect. Register an app and ask for profile.read league.read roster.read draft.read trade.read. Add draft.queue.write to push your rankings into a user's draft queue. A single user's tool can use a personal key instead.
- Import leagues.
GET /leagues, then for each leagueGET /leagues/{id}(scoring, roster slots, teams, which team is the user's),/rostersand/players?ids=for names, positions and NFL teams. Players from/playersand/drafts/{id}/availablecarryexternal_ids(Sleeper, ESPN and NFL ids, from nflverse, CC BY 4.0): match on those, and fall back to full name, position and NFL team only when they are null. - Stay current. Subscribe to webhooks (picks, trades, waivers, final matchups) instead of polling, and refetch the object each event points at. Without webhooks, poll
/transactionsno more than every few minutes. - Draft day. Read
/drafts/{id}for the clock and order,/picksfor the board and/availablefor who is left. Push a ranked queue withPUT /drafts/{id}/queue; the user still makes the pick unless they gave your app draft.pick. - Trade analysis. Use the user's league trades for their own leagues, and the anonymous
/trades/feedplus/players/trendingfor site-wide values and add/drop trends.
Manager actions
Apps act only for teams the connected user manages—even when that person is also a commissioner. These permissions do not allow changing league settings, starting or pausing drafts, forcing transactions, or changing account security.
Free agents and trades
Search league players by availability, then read your roster version before adding or dropping. Use an add_drop transaction to swap players atomically. For trades, send player, draft-pick or FAAB assets, then read the offer version before accepting, rejecting, canceling or countering it. Acceptance still follows your league’s review policy.
Conditional bid groups
Create claims with the same condition_group value to make a bid group. Each claim has its own FAAB bid and optional drop player. Reorder the complete list of pending claim IDs to set priority; when one claim in a group wins, the remaining claims in that group are skipped. Use waiver.claims.read to read your private bids; waiver.read alone does not reveal them.
// Each request needs its own stable key. Save keys before sending.
await benchd.createWaiverClaim(leagueId, {
team_id: teamId, add_player_id: firstChoice,
drop_player_id: dropPlayer, faab_bid: 12, condition_group: 'backup-rb',
}, { idempotencyKey: firstClaimKey });
await benchd.createWaiverClaim(leagueId, {
team_id: teamId, add_player_id: secondChoice,
drop_player_id: dropPlayer, faab_bid: 7, condition_group: 'backup-rb',
}, { idempotencyKey: secondClaimKey });Drafting and keepers
Alongside picks and queues, apps can nominate players, place auction bids, manage your hidden proxy maximum, toggle your autopick, and choose your keepers before the deadline. Auction maxima stay private; draft.read never reveals them. A commissioner’s app receives the same manager limits.
The TypeScript SDK includes a typed method for every endpoint. The repository’s public-v1.yaml is the complete request and response reference. Chat, account settings and commissioner operations are outside this manager API.
Rate limits
Limits apply per app and user, and per app overall, with a tighter budget for writes. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Over the limit you get 429 rate_limit.exceeded with Retry-After in seconds: wait that long, then retry. Prefer webhooks to polling.
Webhooks
Add endpoints on your app's page. We POST a small JSON event when something happens in a league of someone who connected your app and granted webhook.manage plus the event's read scope. Events carry ids, not details: fetch what you need with the API.
{
"id": "5f0c2a7e-...",
"type": "trade.accepted",
"api_version": "v1",
"created_at": "2026-10-04T18:02:11.000Z",
"league_id": "0d6f...",
"object": { "type": "trade", "id": "a41b..." },
"data": { "trade_id": "a41b...", "proposer_team_id": "...", "counterparty_team_id": "..." }
}Verify every request
Each request has webhook-id, webhook-timestamp and webhook-signature headers. Check the signature against the raw body and reject timestamps more than 5 minutes off:
import { verifyWebhook } from '@benchd/sdk-js';
app.post('/webhooks/benchd', express.text({ type: 'application/json' }), async (req, res) => {
try {
const event = await verifyWebhook({
secret: process.env.BENCHD_WEBHOOK_SECRET, // whsec_...
headers: req.headers,
body: req.body, // the raw body, not re-serialized JSON
});
if (await alreadyHandled(event.id)) return res.sendStatus(200);
queue.push(event); // answer fast, work later
res.sendStatus(200);
} catch {
res.sendStatus(400);
}
});Without the SDK:
signed = webhook-id + "." + webhook-timestamp + "." + raw_body
key = base64_decode(secret without "whsec_")
valid = "v1," + base64(hmac_sha256(key, signed)) is one of the
space-separated values in webhook-signature
fresh = |now - webhook-timestamp| <= 300 secondsDelivery and retries
- Answer with any 2xx within 10 seconds. Redirects are not followed.
- Anything else is retried 7 times, after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h. Then the delivery is marked failed; you can resend it from the delivery log.
- Delivery is at least once and not in order: dedupe on the event id.
- After 50 failed attempts in a row we turn the endpoint off and email you. Turn it back on from your app's page.
- When you rotate a secret, we sign with both the old and new secret for 24 hours.
Event types
| Type | When |
|---|
TypeScript SDK
@benchd/sdk-js works in Node 18+, browsers and edge runtimes, with no dependencies. It has three parts:
- Sign-in:
createPkcePair,buildAuthorizeUrl,exchangeAuthorizationCode,refreshAccessToken, andTokenStoreto refresh automatically. - API:
BenchdClientwith a typed method per endpoint, cursor paging (allLeagues()) andBenchdApiErrorwith the error code. Pass a personal key asaccessTokenfor your own tools;listTradeFeedandlistTrendingPlayersread the site-wide data. Every model is typed underPublicV1Schemas. - Webhooks:
verifyWebhook.
Errors
Errors are { error: { code, message, status, request_id, details } }. Branch on code, and include request_id when you contact us.
401 auth.invalid_token | The access token expired or is wrong: refresh it. |
401 auth.consent_revoked | The user disconnected your app: ask them to connect again. Also while your app is suspended or back in review after an edit; connections resume by themselves once it is approved. |
403 auth.insufficient_scope | The token lacks a scope; details.required_scopes says which. |
404 resource.not_found | Not there, or not one of the user's leagues. |
409 draft.not_on_clock | League rules said no (other codes: lineup locked, version conflict). |
429 rate_limit.exceeded | Wait Retry-After seconds. |