# Spotrac — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access detailed NFL player contract information, search for specific players, and retrieve complete team rosters with salary data. Covers cap hits, base salaries, bonuses, dead cap figures, and contract lengths across all 32 NFL teams.

**Category:** Sports | **Website:** [spotrac.com/](https://spotrac.com/) | **Docs:** [parse.bot/marketplace/7994a459-31cd-4d12-a28b-5c053246f105/spotrac-com-api](https://parse.bot/marketplace/7994a459-31cd-4d12-a28b-5c053246f105/spotrac-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_league_cap_summary

Get the league-wide salary cap summary for all 32 NFL teams for a given year. Returns each team's rank, abbreviation, and the currently displayed cap metric (defaults to TOP-51 Cap Space). The column name is included in the response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | integer | Yes | Year for the league cap summary (e.g. 2024, 2025, 2026) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/get_league_cap_summary \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```

### get_league_cash_summary

Get the league-wide cash spending summary for all 32 NFL teams for a given year. Returns each team's rank, abbreviation, record, signed player count, average age, active cash, dead cash, and total cash.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | integer | Yes | Year for the league cash summary (e.g. 2024, 2025, 2026) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/get_league_cash_summary \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```

### get_player_contract

Get comprehensive contract and salary data for a player including cap hit, base salary, bonuses, and dead cap tables. Each table contains year-by-year financial breakdowns. The player_slug is optional but speeds up the lookup by avoiding a redirect.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Numeric player ID from search_players or get_team_roster (e.g. '21751') |
| `player_slug` | string | No | Player slug for direct URL construction (e.g. 'patrick-mahomes'). If omitted, the scraper uses a redirect lookup. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/get_player_contract \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>","player_slug":"<string>"}'
```

### get_team_cap_table

Get the salary cap summary and cash spending summary for an NFL team in a given year. Returns the cap maximum breakdown (salary cap, rollover, adjustments, allocations, cap space) and the cash summary (active roster, injured reserve, dead money totals by bonus category). Requires two HTTP requests (cap page + cash page).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team_slug` | string | Yes | Team slug from list_nfl_teams (e.g. 'kansas-city-chiefs', 'buffalo-bills') |
| `year` | integer | Yes | Year for the cap/cash data (e.g. 2024, 2025, 2026) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/get_team_cap_table \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"team_slug":"<string>","year":"<integer>"}'
```

### get_team_contracts

Get comprehensive contract and salary data for every player under contract with an NFL team in a given year. Returns the team's cap context (league cap, rollover, adjustments, allocations), published cap space figures, and per-player contract details including signing bonus total, contract length, void years, and a full season-by-season breakdown of base salary, prorated signing bonus, roster bonus, per-game bonus, option bonus, workout bonus, and restructure bonus. Requires one HTTP request per player on the roster (~90 requests total via concurrent fetches), so response time is proportional to roster size. Accepts either team abbreviation (e.g. 'BUF', 'KC') or team slug (e.g. 'buffalo-bills', 'kansas-city-chiefs').

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team` | string | Yes | Team identifier — either a standard NFL abbreviation (e.g. 'BUF', 'KC', 'SF') or a team slug (e.g. 'buffalo-bills', 'kansas-city-chiefs'). Call list_nfl_teams to discover valid slugs. |
| `year` | integer | Yes | Year for the contract/cap data (e.g. 2024, 2025, 2026). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/get_team_contracts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"team":"<string>","year":"<integer>"}'
```

### get_team_roster

Get the roster of an NFL team for a specific year. Returns player IDs and slugs usable with get_player_contract. The roster reflects the salary cap page for that team-year combination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team_slug` | string | Yes | Team slug from list_nfl_teams (e.g. 'kansas-city-chiefs', 'buffalo-bills') |
| `year` | integer | No | Year for the roster. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/get_team_roster \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"team_slug":"<string>","year":"<integer>"}'
```

### list_nfl_teams

List all 32 NFL teams with their slugs. Each team slug is the stable identifier used to fetch rosters and other team-scoped data. Returns the full league regardless of parameters.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/list_nfl_teams \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_players

Search for players by name on Spotrac. Returns matching players with their IDs and positions. Results may include trending/popular players alongside actual query matches. Works across all sports covered by Spotrac.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Player name to search for (e.g. 'Patrick Mahomes') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-spotrac-com-api-7994a459/search_players \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```