Reference

Docs

Everything to connect Benchd users to your app: sign-in, the API, webhooks and the TypeScript SDK.

Quickstart

  1. Register an app and add your redirect URI. You get a client ID right away.
  2. While it is pending review, connect it to your own Benchd account to build and test.
  3. 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/authorize with response_type=code, client_id, redirect_uri, scope (space-separated), state and code_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

ScopeWhat people see
profile.readSee your Benchd name. Your display name and handle. Never your email or password.
league.readSee your leagues. League names, settings, members, matchups, standings and transactions for leagues you are in.
roster.readSee rosters. Who is on each team in your leagues.
lineup.readSee lineups. Weekly starting lineups in your leagues.
draft.readSee drafts. Draft boards, picks and your draft queue.
waiver.readSee waiver results. Waiver runs and who got which player.
waiver.claims.readSee your private waiver bids. Read your own team claims, bid amounts, conditional groups and priority order.
trade.readSee trades. Trades proposed, accepted and completed in your leagues.
keeper.readSee your keeper options. Read the keeper board and your own eligible keeper choices.

Act for the user

ScopeWhat people see
lineup.writeSet your lineup. Move your players between starters and bench. Game-time locks still apply.
draft.pickMake draft picks for you. Pick a player when you are on the clock. Every pick follows your league rules.
draft.queue.writeEdit your draft queue. Add, remove and reorder players in your queue.
roster.writeMove players on your roster. Add and drop free agents, and move your players between bench, IR and taxi.
waiver.writeMake waiver claims for you. Submit, edit, cancel and reorder your waiver claims, FAAB bids and conditional bid groups.
trade.proposePropose trades for you. Send, counter and withdraw trade offers from your team.
draft.auction.writeManage your auction bids. Nominate, bid and manage your own hidden maximum bids within your team budget.
draft.autopick.writeControl your autopick. Enable or disable automatic drafting for your own team.
keeper.writeChoose your keepers. Set your own keeper choices before the deadline.
team.writeEdit your team identity. Change your own team name and avatar.
trade.voteVote on league trades for you. Cast your team approval or veto vote when your league allows manager voting.
trade.acceptAnswer trades for you. Accept or reject trade offers sent to you.

Updates

ScopeWhat people see
webhook.manageGet 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.read
  • GET /public/v1/leaguesTheir leagues (paged) · league.read
  • GET /public/v1/leagues/{id}Settings, teams, managers · league.read
  • GET …/rostersEvery roster · roster.read
  • GET …/matchups?week=Matchups; points once the week is final · league.read
  • GET …/standingsStandings · league.read
  • GET …/transactionsAdds, drops, trades (paged) · league.read
  • GET / PUT …/teams/{id}/lineupRead league lineups; edit your own · lineup.read / lineup.write
  • GET /public/v1/drafts/{id}Draft state and the clock · draft.read
  • GET …/drafts/{id}/availablePlayers the user can draft (paged) · draft.read
  • POST /public/v1/drafts/{id}/picksPick when on the clock · draft.pick
  • GET / PUT …/drafts/{id}/queueDraft queue · draft.read / draft.queue.write
  • GET /public/v1/players?ids=Players by id (max 100) · league.read
  • GET /public/v1/players/trendingMost added and dropped across Benchd (24h, 7d) · league.read
  • GET /public/v1/trades/feedCompleted trades across Benchd, anonymous (paged) · trade.read
  • GET …/leagues/{id}/playersSearch player identities and free-agent availability · league.read
  • GET / PATCH …/teams/{id}/rosterRoster versions; move your players between bench, IR and taxi · roster.read / roster.write
  • POST …/teams/{id}/transactionsAdd, drop or atomically swap free agents · roster.write
  • GET …/leagues/{id}/waiversWaiver settings, budgets and results · waiver.read
  • GET …/leagues/{id}/waiver-claimsYour private claims, bids and groups · waiver.claims.read
  • POST …/leagues/{id}/waiver-claimsSubmit a claim or conditional bid · waiver.write
  • PATCH / DELETE …/waiver-claims/{id}Edit or cancel your claim · waiver.write
  • PUT …/waiver-claims/orderReorder all your pending claims · waiver.write
  • GET …/leagues/{id}/trades / trades/{trade_id}Your offers and public league trades · trade.read
  • GET …/leagues/{id}/trade-picksTradable draft picks and their owners · trade.read
  • POST …/leagues/{id}/tradesPropose a trade · trade.propose
  • POST …/trades/{id}/accept / rejectAnswer an offer sent to your team · trade.accept
  • POST …/trades/{id}/counter / cancelCounter an incoming offer or withdraw your offer · trade.propose
  • POST …/trades/{id}/voteCast your manager vote during league review · trade.vote
  • GET …/drafts/{id}/auctionAuction board and public budgets · draft.read
  • POST …/auction/nominations / bidsNominate or bid for your team · draft.auction.write
  • GET / PUT …/auction/proxy-bidsRead, set or clear your hidden maximum bids · draft.auction.write
  • GET / PUT …/drafts/{id}/teams/{team_id}/autopickRead or change your autopick setting · draft.read / draft.autopick.write
  • GET / PUT …/leagues/{id}/keepersRead keeper options; choose your own keepers · keeper.read / keeper.write
  • PATCH …/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}/picks

Site-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.

  1. 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.
  2. Import leagues. GET /leagues, then for each league GET /leagues/{id} (scoring, roster slots, teams, which team is the user's), /rosters and /players?ids= for names, positions and NFL teams. Players from /players and /drafts/{id}/available carry external_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.
  3. Stay current. Subscribe to webhooks (picks, trades, waivers, final matchups) instead of polling, and refetch the object each event points at. Without webhooks, poll /transactions no more than every few minutes.
  4. Draft day. Read /drafts/{id} for the clock and order, /picks for the board and /available for who is left. Push a ranked queue with PUT /drafts/{id}/queue; the user still makes the pick unless they gave your app draft.pick.
  5. Trade analysis. Use the user's league trades for their own leagues, and the anonymous /trades/feed plus /players/trending for 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 seconds

Delivery 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

TypeWhen

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, and TokenStore to refresh automatically.
  • API: BenchdClient with a typed method per endpoint, cursor paging (allLeagues()) and BenchdApiError with the error code. Pass a personal key as accessToken for your own tools; listTradeFeed and listTrendingPlayers read the site-wide data. Every model is typed under PublicV1Schemas.
  • 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_tokenThe access token expired or is wrong: refresh it.
401 auth.consent_revokedThe 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_scopeThe token lacks a scope; details.required_scopes says which.
404 resource.not_foundNot there, or not one of the user's leagues.
409 draft.not_on_clockLeague rules said no (other codes: lineup locked, version conflict).
429 rate_limit.exceededWait Retry-After seconds.