---
name: slabprices-api
description: Fetch current asking prices for graded trading cards (PSA, CGC, BGS, SGC, TAG...) from the Slab Prices API at slabprices.com. Use it when you need the lowest asking price per grader and grade for specific cards, to find which cards have graded listings right now, or to show graded card prices on a website.
---

# Slab Prices API

Current asking prices for graded trading cards, by grader and grade. Prices are
asking prices from live marketplace listings, in US dollars. They are not sale
prices.

- Base URL: `https://slabprices.com`
- Human guide: https://slabprices.com/docs/api
- Full OpenAPI 3 description: https://slabprices.com/docs/api/openapi.yaml

## Setup

The API key is in the `SLABPRICES_API_KEY` environment variable. Never print it,
log it, commit it or put it in code that runs in a browser. The API refuses
browser (CORS) requests, so all calls must come from a server or a script.

Send it on every request:

```
Authorization: Bearer $SLABPRICES_API_KEY
```

Start by calling `GET /v1/me`. It shows the key's scopes and limits
(`perMinute`, `perDay`, `maxPageSize`) and today's usage. Work within those
numbers.

## Workflow: prices for a list of cards

This needs the `graded` scope.

1. **Find card keys once.** `GET /v1/graded/index` lists the cards that have
   graded listings right now. Each card is identified by set and number.
   - Parameters: `limit` (up to `maxPageSize`), `offset`, `q` (search text, e.g.
     `charizard base`), `set` (e.g. `en:sv08.5`), `language`, `game` (default
     `pokemon`), `sort` (`name` by default, or `listings`, `price`, `-price`).
   - Each entry has `key`, `name`, `number`, `language`, `setName`, `setCode`,
     `printing`, `bestAskUsd`, `listingCount`, `url` and `updatedAt`.
   - Match these to the cards you care about by name, set and number, and store
     the `key`. Do not page through the whole index on every run.
2. **Fetch prices in batches.** Call `GET /v1/graded?key=<key>&key=<key>...`
   with as many repeated `key` parameters as `maxPageSize` allows. Do not send
   one request per card.
   - `data` holds one object per card: `key`, `name`, `number`, `setName`,
     `printing`, `url` (the card's page on slabprices.com), `updatedAt` and
     `grades`.
   - Each grade has `grader`, `grade`, `lowestAskUsd`, `listingCount` and
     `marketplaceCount`.
   - `missing` lists the requested keys with no graded listing for sale right
     now (usually the last copy sold, or the key is unknown). That is normal:
     show "no listings right now" rather than an error, and ask again on the
     next refresh.
   - `variantStatus`, when present (`ambiguous`, `conflict`, `unverified`),
     means the printing is not fully verified. Show that price with a caveat.
   - `requestedKey`, when present, means the key you sent was an older alias.
     Store the new `key`.
3. **Cache.** Data refreshes about every 15 minutes and the server caches
   responses for 10. For a page that updates daily, fetch each batch once a
   day and spread the batches across the day. Send the `ETag` back as
   `If-None-Match`. A `304` means nothing changed.

```bash
curl -s -H "Authorization: Bearer $SLABPRICES_API_KEY" \
  "https://slabprices.com/v1/graded/index?q=charizard+base+set&sort=listings&limit=2"
# {"data":[{"key":"en:cel25cc-CC2~holo","name":"Charizard","number":"4","setName":"Celebrations Classic Collection",
#   "printing":"Holo","bestAskUsd":112,"listingCount":94,"url":"https://slabprices.com/card/en:cel25cc-CC2~holo",...}, ...],
#  "meta":{"total":19,"limit":2,"offset":0,"currency":"USD","priceType":"asking"}}

curl -s -H "Authorization: Bearer $SLABPRICES_API_KEY" \
  "https://slabprices.com/v1/graded?key=en:cel25cc-CC2~holo&key=en:base1-200"
# {"data":[{"key":"en:cel25cc-CC2~holo","name":"Charizard",...,"url":"https://slabprices.com/card/en:cel25cc-CC2~holo",
#   "grades":[{"grader":"CGC","grade":"10","lowestAskUsd":221.5,"listingCount":31,"marketplaceCount":4},
#             {"grader":"PSA","grade":"10","lowestAskUsd":449,"listingCount":32,"marketplaceCount":6}, ...]}],
#  "missing":["en:base1-200"],"meta":{"currency":"USD","priceType":"asking"}}
```

```js
// Node 18+, server side only.
const res = await fetch(
  "https://slabprices.com/v1/graded?" + keys.map(k => "key=" + encodeURIComponent(k)).join("&"),
  { headers: { Authorization: `Bearer ${process.env.SLABPRICES_API_KEY}` } },
);
if (res.status === 429 || res.status === 503) {
  const wait = Number(res.headers.get("Retry-After") || 5);
  // wait `wait` seconds, then retry once
}
const { data, missing } = await res.json();
```

## Limits and errors

- Every response has `X-RateLimit-Remaining` (this minute) and
  `X-Quota-Remaining` (today, resets 00:00 UTC). Slow down before they reach 0.
- `429` (`rate_limited`, `daily_quota_exceeded`, `too_many_failed_attempts`):
  wait for `Retry-After` seconds. On `daily_quota_exceeded`, stop until the
  next UTC day.
- `503` (`busy`): wait for `Retry-After` and retry once. It does not use quota.
- `401` (`missing_api_key`, `invalid_api_key`): the key is missing or wrong.
  Stop and report it. Do not retry in a loop.
- `403` (`scope_missing`, `key_disabled`, `key_expired`, `ip_not_allowed`): this
  key cannot make this call. Stop and report the code.
- `400` (`missing_key`, `too_many_keys`): fix the request, for example by
  sending fewer `key` parameters.
- `404` (`not_found`) on a single-card endpoint: no such card right now.

Errors look like `{"error": {"code": "...", "message": "..."}}`.

## Showing the data

Each key's terms are agreed with Slab Prices. Usually they are:

- Label every figure as a **US asking price**.
- Next to the figures, credit **"Graded listings data from Slab Prices"** with
  a link to that card's `url`.
- Use the data for display on your own site only. Do not resell, redistribute
  or bulk-copy it.

## Other endpoints

Keys with other scopes can also read full card pages (`/v1/cards`, scope
`cards`), price history (`/v1/cards/{key}/history`, scope `history`), raw
listings (`/v1/listings`, scope `listings`) and a bulk download of every
listing (`/v1/snapshot`, scope `snapshot`). Check `GET /v1/me` for the key's
scopes before using them, and see the OpenAPI file for their parameters.

Do not scrape the website or its `/api` endpoints. Use `/v1` with the key.
