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

> Look up PSA certification details for graded collectible cards and search comprehensive population reports and price guides across all card categories. Browse collectible categories by set to discover grading data, pricing information, and population statistics.

**Category:** Marketplaces | **Website:** [psacard.com/](https://psacard.com/) | **Docs:** [parse.bot/marketplace/e4bff78d-ff22-4603-b9d3-e3cbb455544e/psacard-com-api](https://parse.bot/marketplace/e4bff78d-ff22-4603-b9d3-e3cbb455544e/psacard-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-psacard-com-api-e4bff78d/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### browse_population_categories

Browse available population report categories. Returns all collectible categories available in the PSA Population Report, including their category IDs which can be used with other endpoints.

**Estimated cost:** Metered

_No parameters required._

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

### get_cert_details

Retrieve details for a specific PSA certification number. Returns card name, grade, population data, images, spec ID, and PSA value estimate.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cert_number` | string | Yes | PSA Certification Number (e.g., '69225215') |

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

### get_cert_details_batch

Batch fetch lightweight PSA certification details for multiple cert numbers in parallel. Accepts a JSON array of up to 200 cert numbers and returns one result object per cert preserving request order. Each result contains success=true with card identification fields, or success=false with an error string. Does not fetch population breakdowns, sales, or price data — optimized for high-throughput contiguous cert-number discovery.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cert_numbers` | string | Yes | JSON array of PSA certification numbers as strings (e.g. '["69225215", "92498498"]'). Maximum 200 items per request. |

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

### get_cert_full

Retrieve combined cert details and population breakdown for one or more PSA certification numbers. For each cert, fetches card info (grade, year, brand, subject, etc.) and the full population breakdown (Grade1–Grade10, GradeTotal, Total). Accepts either a single cert_number or a cert_numbers JSON array (up to 200). Returns a single combined record for cert_number, or an array of combined records for cert_numbers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cert_number` | string | No | Single PSA Certification Number (e.g., '69225215'). Provide either this or cert_numbers. |
| `cert_numbers` | string | No | JSON array of PSA Certification Numbers (e.g., '["69225215", "92498498"]'). Up to 200 items. Provide either this or cert_number. |

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

### get_cert_sales

Retrieve recent sales of similar items from a PSA certification page. Returns all sales shown on the public cert page (newest first) with date, price, title, venue, and listing URL. The public page shows a limited window of recent sales; if more exist behind the authenticated 'View All' link, truncated will be true. No pagination is available without authentication.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cert_number` | string | Yes | PSA Certification Number (e.g., '69225215') |

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

### get_population_by_spec

Retrieve the population breakdown for a single card identified by its PSA Spec ID. Returns grade counts from 1 through 10, total graded count, and card metadata. Requires the set_id (HeadingID) and category_id (SportCategoryID) that identify which set the spec belongs to — obtainable from search_population_report or get_population_report_by_set results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | SportCategoryID for the card set (e.g., '156940'). Obtainable from search_population_report results. |
| `set_id` | string | Yes | HeadingID for the card set (e.g., '57801'). Obtainable from search_population_report results. |
| `spec_id` | string | Yes | PSA Spec ID identifying the specific card (e.g., '6839690'). Obtainable from get_cert_details response or get_population_report_by_set rows. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-psacard-com-api-e4bff78d/get_population_by_spec \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","set_id":"<string>","spec_id":"<string>"}'
```

### get_population_report_by_set

Retrieve the full population report for a specific card set. Returns grading data for all cards in the set including counts at each grade level (1-10). Use HeadingID and SportCategoryID from search results as set_id and category_id. When is_psa_dna is true, returns only PSA/DNA certified (autograph/signed) population data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category ID (e.g., '156940') |
| `is_psa_dna` | boolean | No | When true, returns only PSA/DNA certified (autograph/signed) cards, mirroring the 'PSA/DNA Certified' tab on the population report page. Defaults to false (standard population). |
| `length` | integer | No | Number of records to return per page |
| `search` | string | No | Search filter within the set to find specific cards |
| `set_id` | string | Yes | Heading ID for the set (e.g., '57801') |
| `start` | integer | No | Pagination offset |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-psacard-com-api-e4bff78d/get_population_report_by_set \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","is_psa_dna":"<boolean>","length":"<integer>","search":"<string>","set_id":"<string>","start":"<integer>"}'
```

### search_population_report

Search the PSA Population Report by keyword. Returns matching card sets with heading IDs, set names, year issued, and category information. Results can be used with get_population_report_by_set to retrieve detailed population data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | integer | No | Category ID filter. Use 0 (default) to search across all categories. Non-zero values may return empty results depending on the search term. |
| `query` | string | Yes | Search keyword (e.g., set name or player name such as '1999 Pokemon Game' or 'Mickey Mantle') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-psacard-com-api-e4bff78d/search_population_report \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<integer>","query":"<string>"}'
```

### search_price_guide

Search the PSA Price Guide by keyword. Returns matching card sets with links to pricing information.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | integer | No | Category ID filter. Use 0 (default) to search across all categories. Non-zero values may return empty results depending on the search term. |
| `query` | string | Yes | Search keyword (e.g., '1999 Pokemon Game' or 'Mickey Mantle') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-psacard-com-api-e4bff78d/search_price_guide \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<integer>","query":"<string>"}'
```