# Card Ladder — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/card-ladder/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/card-ladder/get-card-sales \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/card-ladder/get-card-value \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/card-ladder/search-by-cert \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/card-ladder/search-by-certs-bulk \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/card-ladder/search-cards \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","limit":"<integer>","page":"<integer>","query":"<string>","sort":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.