# Tcdb — 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.

> Browse and retrieve detailed trading card information from the Trading Card Database (TCDB), including set listings, checklists, parallel variants, and special notations such as rookie cards, short prints, and variations. Search across sports and years to access comprehensive card and set metadata.

**Category:** Sports | **Website:** [tcdb.com/](https://tcdb.com/) | **Docs:** [parse.bot/marketplace/bc218db9-7d58-420a-858f-0c86440986f5/tcdb-com-api](https://parse.bot/marketplace/bc218db9-7d58-420a-858f-0c86440986f5/tcdb-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-tcdb-com-api-bc218db9/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_checklist

Get the card checklist for a specific set ID. Returns all cards in the set with automatic pagination across multiple pages. Each card includes number, name, team, and any notations (RC, SP, AU, etc.).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sid` | string | Yes | Set ID from tcdb.com, obtained from list_sets results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tcdb-com-api-bc218db9/get_checklist \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sid":"<string>"}'
```

### get_set_details

Get comprehensive details for a specific card set, including metadata, base checklist, and insert/parallel checklists. Fetches the set overview page, base checklist, and up to limit_inserts insert/parallel checklists. Expensive: each insert fetched is a separate round-trip.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit_inserts` | integer | No | Maximum number of insert/parallel checklists to fetch. |
| `sid` | string | Yes | Set ID from tcdb.com, obtained from list_sets results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tcdb-com-api-bc218db9/get_set_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit_inserts":"<integer>","sid":"<string>"}'
```

### get_set_prices

Get card prices for a specific trading card set. Returns paginated results (up to 100 cards per page) with each card's number, player name, notations, variation text, card detail URL, card image URL, and all listed prices (Median Raw, Avg. Grade 9, Avg. Grade 10). Only cards with at least one listed price are included; cards showing only 'Add' (no reported price) are omitted.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. Each page returns up to 100 cards that have prices. |
| `sid` | string | Yes | Set ID from tcdb.com, obtained from list_sets results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tcdb-com-api-bc218db9/get_set_prices \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","sid":"<string>"}'
```

### list_sets

List all trading card sets for a specific year and sport, optionally filtered by name. Returns an array of set summaries including set IDs usable with get_set_details and get_checklist. Results are not paginated; the full list for the given year/sport is returned in one response. When query is provided, only sets whose name contains the query (case-insensitive) are returned.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | No | Optional search query to filter sets by name (case-insensitive substring match). When omitted, all sets for the year/sport are returned. |
| `sport` | string | No | Sport name to filter sets. |
| `year` | string | No | Year to list sets for (e.g. '2025', '2024', '2023'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tcdb-com-api-bc218db9/list_sets \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>","sport":"<string>","year":"<string>"}'
```

### search_cards

Search for individual trading cards using TCDB's advanced search. Returns paginated results (100 per page) with card details parsed from the search listing. At least one of query or set_name must be provided. When both are given, results match both filters. Each result includes the card's year, set name, manufacturer, card number, player name, parallel/variation name, and TCDB URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. Each page returns up to 100 results. |
| `query` | string | No | Player or character name to search for. At least one of query or set_name must be provided. |
| `set_name` | string | No | Set name filter (substring match, e.g. 'Topps Chrome'). When omitted, searches across all sets. |
| `sport` | string | No | Sport category to search within. |
| `year` | string | No | Year to filter results (e.g. '2024'). When omitted, searches across all years. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tcdb-com-api-bc218db9/search_cards \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>","set_name":"<string>","sport":"<string>","year":"<string>"}'
```