# Card Ladder — 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.

> Search your favorite trading cards and instantly access current pricing, Card Ladder values, confidence scores, and recent sales history to make informed collecting and trading decisions. Get detailed market data across all three endpoints to track card values and monitor how prices have changed over time.

**Category:** Marketplaces | **Website:** [cardladder.com/](https://cardladder.com/) | **Docs:** [parse.bot/marketplace/5554022d-8a04-46d0-b2c5-56f3b5abcea2/cardladder-com-api](https://parse.bot/marketplace/5554022d-8a04-46d0-b2c5-56f3b5abcea2/cardladder-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-cardladder-com-api-5554022d/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_card_sales

Retrieve aggregated daily sales history for a specific card. Each entry represents one day's sales with the total price and number of transactions on that date. Sales are sorted newest first. The card_id comes from search_cards results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `card_id` | string | Yes | Card Ladder card ID (e.g. 'JvbEFar2vAm92D23yFXU' from search_cards results). |

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

### get_card_value

Retrieve the Card Ladder (CL) value and confidence score for a specific card. Also returns market value, price movement, percent changes, newest sale info, period summaries (1-month and 1-year), and population count. The card_id comes from search_cards results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `card_id` | string | Yes | Card Ladder card ID (e.g. 'JvbEFar2vAm92D23yFXU' from search_cards results). |

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

### search_by_cert

Look up a graded trading card by its grading company and certificate number. Returns matching card(s) with identification, pricing, market data, and up to 5 most recent sales. The cert number is printed on the slab label by the grading company.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cert_number` | string | Yes | Certificate number printed on the graded card's slab label (e.g. '122040380'). |
| `grading_company` | string | Yes | Grading company that issued the certificate. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cardladder-com-api-5554022d/search_by_cert \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cert_number":"<string>","grading_company":"<string>"}'
```

### search_by_certs_bulk

Batch lookup of graded trading cards by certificate numbers. Accepts up to 200 cert/grader pairs, resolves each in parallel, and returns all successfully matched cards alongside per-cert errors for any that failed. One bad cert does not fail the whole batch. Each resolved card carries the same fields as search_by_cert (identification, pricing, newest sale, and up to 5 recent sales).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `certs` | array | Yes | JSON array of objects, each with cert_number (string) and grading_company (string: PSA, BGS, CGC, or SGC). Maximum 200 items. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cardladder-com-api-5554022d/search_by_certs_bulk \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"certs":"<array>"}'
```

### search_cards

Full-text search across Card Ladder's trading card database. Returns cards matching the query with current values, market data, and price trends. Results are ranked by relevance score by default. Each card includes its unique ID for use with get_card_value and get_card_sales.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Filter results by card category. Omitted returns all categories. |
| `limit` | integer | No | Maximum number of results per page. |
| `page` | integer | No | Zero-based page index for pagination. |
| `query` | string | Yes | Search query for card name, player, set, year, or any combination (e.g. 'Michael Jordan', '1986 Fleer', 'Pikachu PSA 10'). |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cardladder-com-api-5554022d/search_cards \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","limit":"<integer>","page":"<integer>","query":"<string>","sort":"<string>"}'
```