# Pkmn Prices API — LLM Integration Prompt

You are integrating with the Pkmn Prices API for Pokemon TCG card pricing data. Market prices are sourced from TCGPlayer (USD, by condition/variant) and Cardmarket (EUR, by condition/variant) — those two and no others. eBay contributes sold comps (graded and ungraded) through `/listings/ebay` only; comps are individual sales and are never market prices, so eBay appears in no `prices` array and in no price history. Card eBay comps carry their own `currency` field (`"USD"` or `"EUR"`): USD for ebay.com, EUR for German-card comps from ebay.de and Spanish-card comps from ebay.es. Never assume USD there either. Sealed product eBay comps are USD only; there is no German or Spanish sealed-product comp source yet. Every current price row has one `market_price`; the retired Cardmarket Price Guide `low`/`trend`/`avg` fields are not returned. Every price object carries a `currency` field (`"USD"` or `"EUR"`) — never assume USD; read the currency and format the symbol accordingly (`USD`→`$`, `EUR`→`€`). Do not convert between currencies. EUR (Cardmarket) prices require the Pro plan or higher.

## Quick Reference

```
Base URL: https://api.pkmnprices.com/v1
Auth: x-api-key header (data endpoints)
Get a key: https://pkmnprices.com/dashboard
```

## Authentication

Data endpoints (`/cards`, `/sets`, `/sealed`, price history, listings) use API key auth:
```
x-api-key: pk_your_key_here
```

User account endpoints (`/me`, `/usage`, `/keys`, `/billing`) use JWT auth:
```
Authorization: Bearer your_jwt_token
```

`GET /health` requires no authentication.

## Plans

Credits are charged per item returned in the `data` array (minimum 1 per request). Limits reset daily.

| Plan | Daily Credits | Rate Limit | Max Keys | Restrictions |
|------|-------------|------------|----------|-------------|
| Free | 500 | 60/min | 1 | English cards only. USD prices only (no EUR/Cardmarket). No sealed products, price history, listings, or graded population. |
| Pro | 20,000 | 60/min | 5 | All languages (English, Japanese, German, Spanish). Unlocks EUR (Cardmarket) prices, sealed, price history, all listings, and graded population. |
| Scale | 75,000 | 120/min | 10 | Everything in Pro with higher limits, plus the daily catalog export (`/export/cards`) and priority support (a reply within 1 business day). |
| Business | 200,000 | 200/min | Unlimited | Everything in Scale with the highest limits. |

Check credits via response headers: `x-credits-charged` (this request), `x-credits-limit` (daily allowance), `x-credits-remaining` (left today after this request) and `x-credits-reset` (seconds until the allowance refills at 00:00 UTC).
Check the request rate via: `x-rate-limit`, `x-rate-remaining` and `x-rate-reset` (seconds until the minute window closes).

## Prepaid credits

Pro, Scale and Business accounts can add credits to a balance from the dashboard, from $5 to $500 a deposit at $0.08 per 1,000 credits ($5 buys 62,500). The balance never expires and is spent only after the plan's daily allowance is gone, so a request that would have returned `429 credit_limit_exceeded` is served and paid from the balance instead. Free accounts cannot deposit.

A request is paid for whole or not at all: if the allowance left plus the balance cannot cover its cost, it returns `429` and nothing is charged. While an account holds a balance, responses carry `x-credits-balance`, the credits left in it; `x-credits-remaining` still counts only the daily allowance. A refunded or charged-back deposit takes the matching credits back out of the balance, and a refund that later fails or is canceled gives them back. Credits that were already spent cannot be taken back; they are booked as credits owed, and the account's next deposit pays them off before adding anything to the balance. An account holds a balance or owes credits, never both.

## Languages

A card's language is a property of its **set**, and it decides which pricing that card can ever have.

| Language | Sets | Cards | Pricing | Tier |
|----------|------|-------|---------|------|
| English | 215 | 28,383 | USD (TCGplayer) + EUR (Cardmarket) | Free |
| Japanese | 446 | 30,001 | USD (TCGplayer) + EUR (Cardmarket) | Pro+ |
| German | 122 | 17,462 | **EUR (Cardmarket) only** | Pro+ |
| Spanish | 116 | 15,543 | **EUR (Cardmarket) only** | Pro+ |

Counted on 2026-11-01; they grow as sets are added.

`language` is normalised, so spell it however you like: `German`, `german`, `GERMAN`, `Deutsch`, `de` and `DE` all resolve to the same thing. Same for `English`/`en`, `Japanese`/`jp`/`ja` and `Spanish`/`Español`/`espanol`/`spa`/`es`. Responses always return the canonical form (`"English"`, `"Japanese"`, `"German"`, `"Spanish"`).

A value that isn't a language we carry is passed through untouched and simply matches nothing, rather than erroring.

**German and Spanish cards have no USD price and never will.** TCGplayer does not sell either, so their only pricing is Cardmarket in EUR. A request for German or Spanish cards with `currency=usd` correctly returns nothing. That is an empty result, not an error and not a bug. Use `currency=eur` for both.

German coverage runs from Base Set (1999) to current sets. Spanish coverage runs from Black & White (2011) to current sets. Spanish cards that come from WikiDex (promos and subsets) carry `attacks` and `ability` text like the rest, in Spanish; a few basic energies have neither. German cards whose set predates Cardmarket's German product listings may have no EUR price; that is missing data, not a zero.

Spanish price history only goes back to when Spanish pricing started, so it is shorter than the other languages'. A Spanish card with no Cardmarket offer in Spanish yet has no price; that is missing data, not a zero.

Free is restricted to English. A free key asking for `?language=Japanese`, `?language=German` or `?language=Spanish` gets a `403`, and a free key that omits `language` is served English only rather than the whole catalogue.

Do not confuse this with the **listing** language on the Cardmarket listing endpoints. That is the language of an individual marketplace offer, and it is a separate axis: one Cardmarket article carries offers in many languages.

## Currency

Each price object has a `currency` field (`"USD"` or `"EUR"`). Add a `currency` query param (case-insensitive) to any price endpoint to filter:

- omitted → all currencies the caller is allowed to see
- `usd` → USD only (TCGplayer)
- `eur` → EUR only (Cardmarket)

Supported on: `/v1/cards`, `/v1/cards/:id`, `/v1/cards/:id/prices/history`, `/v1/sealed`, `/v1/sealed/:id`, `/v1/sealed/:id/prices/history`. Cardmarket (EUR) prices exist on **cards and sealed**.

| Caller | `currency` | Result |
|--------|-----------|--------|
| Free | omitted or `usd` | USD only — EUR silently excluded |
| Free | `eur` | `403` — `"Cardmarket (EUR) prices require Pro or higher"` |
| Pro/Scale/Business | omitted | both USD + EUR |
| Pro/Scale/Business | `usd` / `eur` | that currency only |
| any | invalid value | `400` — `"currency must be USD or EUR"` |

Read `currency` per price and format the symbol (`USD`→`$`, `EUR`→`€`). Do not convert between currencies — display as-is.

## Pagination

Most endpoints use page-based pagination:

| Param | Type | Default | Max | Description |
|-------|------|---------|-----|-------------|
| page | integer | 1 |  | Page number |
| per_page | integer | 50 | 100 | Results per page |

Response:
```json
{
  "data": [...],
  "pagination": { "page": 1, "per_page": 50, "total": 1234, "total_pages": 25 }
}
```

`/v1/cards`, `/v1/sets` and `/v1/sealed` also take a `cursor`, which reads the next page without an offset. Every response carries `pagination.next_cursor`: pass it back as `cursor` to continue, and stop when it is `null`.

```
GET /v1/cards?set_id=123&per_page=100
GET /v1/cards?set_id=123&per_page=100&cursor=<pagination.next_cursor>
```

A cursor costs the same on page 500 as on page 1 and cannot repeat or skip a card if one is added mid-walk. Send `cursor` or `page`, not both (`page=1` is fine). `total` and `total_pages` are still returned. Lists filtered or sorted by price (`min_price`, `max_price`, `condition`, `variant`, `sort=price_*`) order by price, so they page by number only: `next_cursor` is `null` and a `cursor` is refused with `400`.

The listings endpoints (`/cards/:id/listings/ebay`, `/cards/:id/listings/cardmarket`, `/cards/:id/listings/tcgplayer`, `/sealed/:id/listings/ebay`, `/sealed/:id/listings/cardmarket`, `/sealed/:id/listings/tcgplayer`) use cursor-based pagination instead (see below). Cards and sealed products carry the same three sources.

### Unknown query parameters

The data endpoints (`/v1/sets`, `/v1/cards`, `/v1/sealed` and everything under them) ignore a query parameter they do not read, and say so: the response carries a `Warning` header naming it and listing the parameters the endpoint accepts, one header per ignored parameter. A misspelled filter therefore returns unfiltered results with a header explaining why, so check for `Warning` when results look wrong.

```
Warning: 299 - "unknown query parameter set_name ignored; this endpoint accepts set_id, tcg_player_id, name, ..."
```

A few common alternate names are accepted and read as the documented one:

| Sent | Read as | On |
|------|---------|----|
| `limit` | `per_page` | `/v1/sets`, `/v1/cards`, `/v1/sealed` |
| `q`, `search` | `name` | `/v1/sets`, `/v1/cards`, `/v1/sealed` |
| `tcgplayer_id` | `tcg_player_id` | `/v1/cards`, `/v1/sealed` |
| `per_page` | `limit` | price history and every listings endpoint |
| `days` | `period` | price history and eBay listings (`days=90` is `period=90d`) |

If both names are sent, such as `per_page` and `limit`, the documented one is used and the other is named in a warning. The cursor-paginated listings endpoints ignore `page`: `page=1` silently, since it is the page they return without a cursor, and any other page with a warning, because they return the first page again. Follow `pagination.next_cursor` instead. `language` on the Cardmarket listings endpoints is ignored without a warning: offers there are already in the card's or product's own language.

A parameter the endpoint does read but with a value it cannot parse, such as `hp=lots`, is still a `400`.

---

## Endpoints

### GET /health (No Auth)

```json
{ "status": "healthy", "database": "connected" }
```
Returns `503` with `"degraded"` / `"unreachable"` if the database is down.

---

### GET /v1/sets
List Pokemon TCG sets.

| Param | Type | Description |
|-------|------|-------------|
| name | string | Filter by set name (substring match) |
| language | string | Filter by language: `English`, `Japanese`, `German`, `Spanish` (Pro+ for all but English) |
| page | integer | Page number (default 1) |
| per_page | integer | Results per page (default 50, max 100) |

Response item:
```json
{ "id": 123, "tcg_player_id": 456, "name": "Obsidian Flames", "language": "English", "card_count": 230 }
```

### GET /v1/sets/:id
Get a single set by ID.

---

### GET /v1/cards
List cards with optional filtering. Does **not** return prices — use `GET /v1/cards/:id` to get a card's prices. Price-related params (`condition`, `variant`, `min_price`, `max_price`, `sort`) still filter/sort server-side.

| Param | Type | Description |
|-------|------|-------------|
| name | string | Filter by card name (substring match) |
| set_id | integer | Filter by set ID |
| tcg_player_id | integer | Get specific card by TCGPlayer ID |
| number | string | Filter by card number. Leading zeros are ignored, so `54` finds `054` |
| total_set_number | string | Filter by total set number. Leading zeros are ignored |
| rarity | string | Filter by rarity, matched exactly as it is spelled in responses (`Double Rare`, not `double rare`) |
| stage | string | Filter by evolution stage (e.g. `Basic`, `Stage 1`, `Stage 2`) |
| card_type | string | Filter by card type (`Pokemon`, `Trainer`, `Energy`) |
| weakness | string | Filter by weakness type code (e.g. `F`, `R`) |
| energy_type | string | Filter by energy type (e.g. `Fire`); matches cards whose energy types include the value |
| artist | string | Filter by illustrator (case-insensitive substring match, e.g. `arita`) |
| hp | integer | Filter by exact HP |
| language | string | Filter by language: `English`, `Japanese`, `German`, `Spanish`. Free plan: English only (any other language returns `403`; omitted means English only). German and Spanish have EUR prices only; see Languages |
| currency | string | Filter prices by currency: `usd` or `eur` (case-insensitive). Omit for all currencies you can access. EUR is Pro+ (Free + `eur` → `403`); invalid value → `400` |
| condition | string | Filter by price condition (e.g. `Near Mint`) |
| variant | string | Filter by price variant (e.g. `Holofoil`) |
| grade | string | Filter by graded tier |
| min_price | number | Minimum market price |
| max_price | number | Maximum market price |
| sort | string | `price_asc` or `price_desc` (requires price-related filter) |
| page | integer | Page number (default 1) |
| per_page | integer | Results per page (default 50, max 100) |

Response item (no `prices` — see `/v1/cards/:id`):
```json
{
  "id": 789,
  "tcg_player_id": 519184,
  "name": "Charizard ex",
  "image_url": "https://...",
  "number": "006",
  "total_set_number": "197",
  "rarity": "Double Rare",
  "artist": "PLANETA CG Works",
  "hp": 330,
  "set": { "id": 123, "name": "Obsidian Flames" }
}
```

### GET /v1/cards/:id
Get a single card by ID with all its prices.

Response includes the full card attributes, Cardmarket mapping identifiers,
and a `prices` array. `cardmarket_url` is the absolute Cardmarket product URL
and `cardmarket_product_id` is its stable numeric product ID. Both may be
`null` until a mapping has been established. Attribute fields are populated
from TCGplayer and may be `null`/empty for older cards, Trainers, or Energy:
`stage`, `card_type` (`Pokemon`/`Trainer`/`Energy`),
`weakness`, `resistance`, `retreat_cost`, `energy_type` (array), `ability`,
`flavor_text`, `attacks` (array of attack text):
```json
{
  "id": 789,
  "name": "Charizard ex",
  "cardmarket_url": "https://www.cardmarket.com/en/Pokemon/Products/Singles/Obsidian-Flames/Charizard-ex-OBF006",
  "cardmarket_product_id": 733537,
  "stage": "Stage 2",
  "card_type": "Pokemon",
  "weakness": "R",
  "resistance": null,
  "retreat_cost": 2,
  "energy_type": ["Fire"],
  "ability": "<strong>Ability — Infernal Reign</strong> ...",
  "flavor_text": null,
  "attacks": ["[2RR] Burning Darkness (180+) ..."],
  "set": { "id": 123, "name": "Obsidian Flames" },
  "prices": [
    {
      "source": "tcgplayer",
      "currency": "USD",
      "condition": "Near Mint",
      "variant": "Holofoil",
      "market_price": 42.50,
      "created_at": "2025-01-15T08:30:00Z"
    },
    {
      "source": "cardmarket",
      "currency": "EUR",
      "condition": "Near Mint",
      "variant": "Holofoil",
      "market_price": 35.00,
      "created_at": "2025-01-15T08:30:00Z"
    }
  ]
}
```

**Price sources:**
- `tcgplayer` — USD market prices with `condition` (Near Mint, Lightly Played, etc.) and `variant` (Holofoil, Reverse Holofoil, 1st Edition, etc.)
- `cardmarket` — EUR marketplace prices with native Cardmarket conditions (`Mint`, `Near Mint`, `Excellent`, `Good`, `Light Played`, `Played`, `Poor`) and printing variants. `market_price` is the lowest trusted current offer for that exact condition/variant; conditionless legacy Price Guide rows are excluded, as are signed, altered, graded and (on sealed products) opened offers (see [Special attributes](#special-attributes-signed-altered-graded-opened)), and as is any offer from a seller with no completed sales (see [`sell_count`](#sell_count)) — so the cheapest row in `/listings/cardmarket` is not always the `market_price`. **Pro+ only** — Free tier never receives these; a Free caller passing `?currency=eur` gets `403`.

Those are the only two. eBay is **not** a price source: its sold comps are individual sales rather than market prices, so they appear in no `prices` array and in no price history. They are on `/listings/ebay` only.

---

### GET /v1/cards/:id/prices/history (Pro+)
Price history for a card. Free plan returns `403`. Cardmarket history is condition-specific, so group EUR series by both `variant` and `condition`. History fields `avg`, `low`, and `high` are daily aggregates of saved condition prices; they are separate from the retired current-price Price Guide fields.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| period | string | `30d` | Time range in days, 1–365: `90d`, or a bare `90` |
| currency | string |  | `usd` or `eur`. EUR is Pro+ (Free + `eur` → `403`); invalid → `400` |
| condition | string |  | Exact match, e.g. `Near Mint` (TCGplayer) or `Excellent` (Cardmarket) |
| variant | string |  | Exact match, e.g. `Holofoil` |
| limit | integer | 30 | **Rows** per page, not days (max 365) |
| page | integer | 1 | Page number |

A row is one `(date, source, currency, condition, variant)` group, **not one
day**. A card with five TCGplayer conditions produces five rows per day, so the
default `limit` of 30 returns about six days of a 30-day window. Read
`pagination.total_pages` and page through, or raise `limit`, or narrow with
`condition`/`variant`. `pagination.total` counts every row the period holds
after filtering, not just the current page.

No source in this API reports how many copies sold across the market;
TCGplayer's "sold in the last month" figures are not collected. For how often a
card trades on eBay, see `GET /v1/cards/:id/sales/volume` below. (A `sale_count` field used to be
returned here. It was the number of price snapshots behind the row, normally
1, and was removed on 2026-09-11 because it was read as sales volume.)

Response item:
```json
{
  "date": "2025-01-15",
  "source": "tcgplayer",
  "currency": "USD",
  "condition": "Near Mint",
  "variant": "Holofoil",
  "avg": 42.50,
  "low": 38.00,
  "high": 48.00
}
```

---

### GET /v1/cards/:id/sales/volume (Pro+)
How many eBay sold comps we recorded for a card each day. Free plan returns `403`.

This counts **eBay comps only**. It is not total market volume: TCGplayer and Cardmarket sales are not recorded, so a day with no row means no eBay comp that day, not that nothing sold. It is the same feed as `/listings/ebay`, counted by day instead of listed one by one, so it is a fair read of how liquid a card is on eBay and a poor one of how many copies exist or sold elsewhere.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| period | string | `30d` | Time range in days, 1–365: `90d`, or a bare `90` |
| graded | boolean |  | `true` for graded slabs only, `false` for raw cards only. Omit for both |
| currency | string |  | `usd` or `eur`. Invalid → `400` |
| variant | string |  | Exact match, e.g. `Holofoil` |
| limit | integer | 30 | **Rows** per page, not days (max 365) |
| page | integer | 1 | Page number |

A row is one `(date, currency, variant, graded)` group, newest day first. A card sold both raw and graded produces two rows for a day, so read `pagination.total_pages` or narrow with `graded` and `variant`. Each row costs one credit.

Response item:
```json
{
  "date": "2026-10-20",
  "currency": "USD",
  "variant": "Holofoil",
  "graded": false,
  "sales": 7,
  "priced_sales": 6,
  "median": 41.5
}
```

`sales` counts every comp. `priced_sales` and `median` leave out accepted Best Offers, because eBay shows the struck-through list price for those, not what the buyer paid. `variant` is `null` when the listing title did not narrow the sale to one printing; keep that bucket apart from named printings. To sum a period, add `sales` across the rows you want.

---

### GET /v1/cards/:id/listings/ebay (Pro+)
Individual sold eBay card comps (graded and ungraded). Every row carries its own `currency` (`"USD"` or `"EUR"`) — read it per comp rather than assuming USD, the same rule price rows follow. Free plan returns `403`. Uses cursor pagination. There is no bare `/v1/cards/:id/listings` endpoint — always specify the source (`/listings/ebay`, `/listings/cardmarket`, or `/listings/tcgplayer`).

**Two grades can print the same number.** A CGC Pristine 10 requires all four subgrades at ten and sells well above a CGC Gem Mint 10; a BGS Black Label 10 sits the same way against a plain BGS 10. Both carry `"grade": "10"` and are told apart by `grade_qualifier` (`"Pristine"`, `"Black Label"`, or `null` for the tier with no name of its own — which is nearly every comp). Filtering `grade=10` returns all tiers, as it always has. To get one tier, add `grade_qualifier`: `grader=BGS&grade=10&grade_qualifier=black_label` for Black Labels, `grade_qualifier=none` for plain BGS 10s. It is `null` on comps collected before the tier was recorded, and on older comps where the tier can no longer be determined.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| graded | boolean |  | `true` = graded only; `false` = ungraded only; omit = both |
| grader | string |  | Filter by grading company, e.g. `PSA`, `BGS`, `CGC`. Case-insensitive. See the list below |
| grade | string |  | Filter by grade (1–10) |
| min_price | number |  | Minimum sale price |
| max_price | number |  | Maximum sale price |
| variant | string |  | Filter by the printing the comp was collected under, e.g. `Holofoil` |
| seller_country | string |  | Only comps from sellers in these countries, as comma-separated ISO 3166-1 alpha-2 codes such as `US,JP`. Case-insensitive, at most 30. Comps with no known seller country are left out |
| exclude_seller_country | string |  | Leave out comps from sellers in these countries, in the same format, such as `CN,HK`. Comps with no known seller country stay in |
| grade_qualifier | string |  | Only comps in this tier of their grade: `pristine`, `black_label`, or `none` for the tier with no name of its own (a plain CGC or BGS 10, and every other grade). Case-insensitive. `none` also returns comps whose tier was never recorded |
| sale_type | string |  | Only comps that sold this way, as comma-separated values from `auction`, `fixed_price` and `best_offer_accepted`. Case-insensitive. Comps with no known sale type are left out |
| since | string |  | Only comps ingested after this instant. RFC 3339 timestamp or `YYYY-MM-DD` (midnight UTC). A malformed value is a `400`, never silently ignored |
| updated_since | string |  | Only comps corrected after this instant, in the same format. Bounds `updated_at`, not `ingested_at`. See "Keeping a copy" below |
| period | string |  | Only comps sold in the last N days: `90d`, or a bare `90` (1–365), the same form as price history. Bounds `sold_at`, where `since` bounds `ingested_at` |
| sort | string | date_desc | `date_desc`, `date_asc`, `price_asc`, `price_desc` |
| limit | integer | 20 | Results per page (max 20) |
| cursor | string |  | Base64 cursor from previous response |

**Graders recognised on eBay comps.** `grader` is read from the sale title when a grading company is followed by its grade. The codes are `PSA`, `CGC`, `BGS` (also written Beckett), `SGC`, `TAG`, `ACE`, `AGS`, `PCG`, `RPA`, `MNT`, `GMA`, `KSA`, `PGA`, `CGA`, `DSG`, `MGC`, `BCG`, `ARK`, `HGA`, `ACG`, `RCG`, `SCG`, `ISA`, `BGA`, `UGS`, `AOG`, `GSG`, `PGS`, `PCA`, `SFG`, `CGS`, `EGS` and `GCG`. A title naming a company we do not list, or a grade with no company, comes back with `grader` and `grade` `null` and `graded=false`.

Response:
```json
{
  "data": [
    {
      "id": 5678,
      "title": "PSA 10 Charizard ex 006/197 Obsidian Flames",
      "price": 275.00,
      "currency": "USD",
      "seller_country": "US",
      "sale_type": "fixed_price",
      "grader": "PSA",
      "grade": "10",
      "grade_qualifier": null,
      "variant": "Holofoil",
      "attribution": "exact",
      "sold_at": "2025-01-14",
      "ingested_at": "2025-01-16T04:12:07Z",
      "updated_at": null,
      "listing_url": "https://www.ebay.com/itm/..."
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null, "count": 1 }
}
```

`grade` carries half grades as written (`"9.5"`, `"1.5"`), so treat it as an opaque string rather than an integer — a filter of `grade=9` matches PSA 9 and not BGS 9.5. Historic rows may still read `"9"` for a title that says 9.5 until the recovery sweep has passed over them.

`grader`, `grade`, `variant`, and `listing_url` are nullable (`null` for ungraded rows, comps with no recorded printing, or when no marketplace URL is available).

`seller_country` is the eBay seller's location as an uppercase ISO 3166-1 alpha-2 code, such as `"US"`, `"JP"` or `"GB"`. Puerto Rico is `"PR"`, so `seller_country=US,PR` covers both. It is `null` when we don't know the location, which is the case for older comps, some comps mirrored from PriceCharting, and eBay locations we can't match to a country. A malformed code in either country filter returns `400`.

`sale_type` is how the item sold: `"auction"`, `"fixed_price"` or `"best_offer_accepted"`. `"fixed_price"` includes listings that allowed offers but sold at the listed price. For `"best_offer_accepted"`, `price` is the amount the buyer paid. eBay's search page shows only the list price for these, so the collector reads the accepted amount off the item page, and skips multi-quantity listings, whose page shows only the list price. `sale_type` is `null` for comps collected before this field existed, comps mirrored from PriceCharting, and sealed comps. Accepted offers among the older comps may still carry the list price in `price`, and nothing marks them yet. To leave those rows out, pass `sale_type=auction,fixed_price,best_offer_accepted`: any `sale_type` filter drops comps whose sale type is `null`. An unknown value returns `400`.

**`attribution` — read this before pricing a variant.** Comps are collected per source page, and that catalogue is coarser than TCGplayer's: a Pokemon Center stamp, a deck exclusive or a promo reprint often has no page of its own. When several card entities map to one page, every one of them serves the same sold listings, with titles describing whichever printing the seller actually sold.

| Value | Meaning |
|-------|---------|
| `exact` | Collected under a page mapped to this card and no other. Safe to price from. |
| `shared` | Collected under a page shared with at least one other card. The same sale appears in those cards' feeds too, and the title may describe the other printing. |
| `unknown` | No printing is recorded for this row, so sharing cannot be determined. Either it was ingested before printings were recorded, or the listing title did not narrow the sale to one printing. |

A feed that is entirely `shared` is the other card's evidence, not this one's. Treat those rows as a price signal for the group rather than for the specific entity — or filter them out, which is what `attribution` exists to make possible.

**Polling for new comps — checkpoint on `ingested_at`, not `sold_at`.** `sold_at` is when the sale happened; `ingested_at` is when we collected it. A collection run routinely brings in sales that are weeks old, so a comp added today can carry a `sold_at` far behind the newest row you already hold. Filtering on sale date would step over those permanently.

The loop is: keep the highest `ingested_at` you have seen for a card, and pass it back as `since`.

```
GET /v1/cards/31194/listings/ebay?since=2026-09-01T02:40:15.126147Z&sort=date_desc
```

`ingested_at` and `snapshot_at` end in `Z` rather than `+00:00` precisely so they can go into a query string unescaped. If you build the value yourself and it carries a `+`, percent-encode it as `%2B` or the server reads it as a space and rejects the timestamp.

**`period` is not `since`.** `period=90d` is for pricing: comps that sold in the last 90 days, under any sort, so `grader=PSA&grade=10&period=90d&sort=price_asc` is the cheapest recent PSA 10. `since` is for syncing: comps we collected after your last pull, whenever they sold. Comps often arrive days after the sale, so do not poll on `period`; a late-arriving sale would fall outside your next window. The two combine: `since=<checkpoint>&period=90d` is new comps that also sold recently.

`since` composes with every other filter and with `cursor`. A card with nothing new returns an empty `data` array, which is the cheap outcome the parameter exists for — you are billed one credit per row returned, so a quiet card costs nothing rather than a full page of comps you have already seen. Re-passing the exact `ingested_at` string you were given is safe: the bound is exclusive, so the row you checkpointed on is not returned again.

**Keeping a copy: corrections.** We sometimes fix comps after they go in. We regrade a slab the title was misread for, replace an accepted offer's list price with what the buyer paid, or move a sale to the card it was really for. A fix doesn't move `ingested_at`, so `since` never returns it. If you store comps instead of reading them live, also poll `updated_since=<checkpoint>` per card. It returns comps where any served field changed after that instant, and `updated_at` on each row says when. Replace your copy by `id`, and keep a second checkpoint: the highest `updated_at` you've seen.

`updated_at` is `null` on comps that haven't changed since we began recording fixes on 2026-10-20, and on every sealed comp. Fixes made before that date aren't recorded. A comp moved to another card shows up in that card's `updated_since`. Removed comps aren't reported: a comp we delete simply stops appearing.

---

### GET /v1/cards/:id/listings/cardmarket (Pro+)
Live Cardmarket marketplace offers for a card. Prices are EUR. Free plan returns `403`. Results are automatically restricted to the card's set language, so an English card cannot return German or Spanish listings. Uses `(price, id)` cursor pagination and returns current seller offers cheapest first by default.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| condition | string |  | Native Cardmarket condition (`Mint`, `Near Mint`, `Excellent`, `Good`, `Light Played`, `Played`, `Poor`) |
| variant | string |  | Printing variant. `Reverse Holo` and `Reverse Holofoil` are equivalent. |
| min_price | number |  | Minimum offer price (EUR) |
| max_price | number |  | Maximum offer price (EUR) |
| seller_country | string |  | Only offers from sellers in these countries, as comma-separated ISO 3166-1 alpha-2 codes such as `IT,DE`. Case-insensitive, at most 30. Offers with no known seller country are left out |
| exclude_seller_country | string |  | Leave out offers from sellers in these countries, in the same format, such as `CN,HK`. Offers with no known seller country stay in |
| graded | boolean |  | `true` = graded offers only; `false` = raw offers only; omit = both |
| grader | string |  | Only graded offers from this grader, e.g. `PSA`, `CGC`, `BGS`. Case-insensitive |
| grade | string |  | Only graded offers at this grade, e.g. `10` or `9.5` |
| signed | boolean |  | `true` = signed offers only; `false` = leave signed offers out |
| altered | boolean |  | `true` = altered offers only; `false` = leave altered offers out |
| min_sell_count | integer |  | Only offers from sellers with at least this many completed sales. Offers with no recorded `sell_count` are left out |
| sort | string | price_asc | `price_asc`, `price_desc` |
| limit | integer | 20 | Results per page (max 20) |
| cursor | string |  | Opaque cursor from the previous response |

Response:
```json
{
  "data": [
    {
      "id": 3456,
      "article_id": 1789012345,
      "price": 38.50,
      "variant": "Reverse Holofoil",
      "condition": "Near Mint",
      "seller": "CardKingdomEU",
      "quantity": 2,
      "language": "EN",
      "comment": "Pack fresh, sleeved immediately",
      "updated_at": "2026-08-11T14:22:00+00:00",
      "signed": false,
      "altered": false,
      "graded": false,
      "grader": null,
      "grade": null,
      "opened": false,
      "sell_count": 2022,
      "seller_country": "IT"
    }
  ],
  "pagination": { "has_more": true, "next_cursor": "cDozOC41OjM0NTY=", "count": 20 }
}
```

#### Special attributes: `signed`, `altered`, `graded`, `opened`

Cardmarket sellers flag copies that are not a plain card: signed by the artist or a player, altered/customised, or encapsulated by a grading company. These three booleans are always present on every listing, and `grader`/`grade` carry the slab details when they are known.

**A listing with any of the three set is excluded from market price derivation.** It is a real offer you can still show and link to, but it is not evidence of what the card is worth. This is why a card's Cardmarket listings can look wildly inconsistent with its prices:

```json
{
  "id": 3457,
  "price": 200.00,
  "condition": "Near Mint",
  "language": "JP",
  "comment": "signed by the artist at Worlds",
  "signed": true,
  "altered": true,
  "graded": false,
  "grader": null,
  "grade": null
}
```

A Japanese Poncho-wearing Pikachu can show a Near Mint offer at €200.00 while its Near Mint `market_price` is €3,800.00, because that €200 copy is signed and altered, so it is priced as a defaced card. Without the flags it is indistinguishable from a clean copy, and it would drag the derived price with it. **Do not compute your own "lowest Near Mint price" from these listings without first dropping rows where `signed`, `altered`, `graded`, or `opened` is true**. That is exactly the mistake the flags exist to prevent. `graded=false&signed=false&altered=false` drops them server-side (add `opened=false` on sealed products).

`graded` rows are the mirror image: a slabbed card is priced for the slab, usually far above the raw market price. `grader` and `grade` use the same shape and values as the graded eBay comps from `/listings/ebay` (`"PSA"` / `"10"`), so one renderer handles both. Both are `null` on ungraded rows, and either may be `null` on a graded row when Cardmarket's icon says the card is slabbed without naming the grader. Graded Cardmarket listings were not returned at all before this (they were dropped during scraping), so their appearance in a listings page is new, not a change in what is for sale.

`opened` is the sealed-product member of the set: the seller's own comment says the item is not sealed, such as an opened wrapper or a display missing its shrink. It is always `false` on a card listing, where the distinction does not exist. A Jungle booster pack whose every other offer sits between €799 and €950 carries one at €10.00 reading *"Not Sealed (open, just the booster)"*; that is a real offer for an opened pack, not a €10 Jungle booster pack.

#### `sell_count`

The seller's completed sales, as Cardmarket reports them. It is the reason a market price can sit **above** the cheapest listing you can see: an offer from a seller with no completed sales does not set a price, so the cheapest row in a listings page is not always the `market_price`.

`null` is not zero. `null` means no count was recorded for that row: every listing stored before the field existed, and any row whose badge could not be read. `0` means Cardmarket reports the seller as having sold nothing. If you are reimplementing the price rule, treat only `0` as disqualifying and leave `null` alone. `min_sell_count` filters on this field, and because it cannot tell an unrecorded count from a low one, it leaves `null` rows out.

#### `seller_country`

The seller's location as an uppercase ISO 3166-1 alpha-2 code, such as `"IT"` or `"DE"`, taken from the item-location flag on the Cardmarket offer. It means the same as `seller_country` on eBay comps, so `seller_country=DE,AT` works the same way on both. It is `null` when we don't know the location: offers scraped before the field existed (listings refresh on each scrape, so these clear over time), offers that show no location, and countries we can't match. `seller_country` leaves those rows out; `exclude_seller_country` keeps them. A malformed code in either filter returns `400`.

---

### GET /v1/cards/:id/listings/tcgplayer (Pro+)
Live TCGplayer marketplace offers for a card. All prices are USD. Free plan returns `403`. Uses cursor pagination. Like Cardmarket listings, these are current seller offers (cheapest first by default), not sold sales.

**Depth cap.** A snapshot holds at most the **500 cheapest** in-stock, English-language listings for the product, taken once a day from TCGplayer's own listings feed sorted by price + shipping (shipping computed for a US address). A product with more listings than that is truncated, so a sum of `quantity` is the quantity across those 500, not TCGplayer's "Current Quantity". The default `price_asc` order pages by item price; use `sort=total_asc` to match the site's order.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| condition | string |  | Filter by condition (e.g. `Near Mint`, `Lightly Played`, `Damaged`) |
| language | string |  | Filter by listing language |
| printing | string |  | Filter by printing/variant (e.g. `Unlimited Holofoil`, `1st Edition Holofoil`) |
| min_price | number |  | Minimum item price (USD, excludes shipping) |
| max_price | number |  | Maximum item price (USD, excludes shipping) |
| sort | string | price_asc | `price_asc`, `price_desc`, `total_asc`, `total_desc` (see below) |
| limit | integer | 20 | Results per page (max 20) |
| cursor | string |  | Base64 cursor from previous response |

**Sorting.** The `price` sorts order by item price alone. The `total` sorts order by `price + shipping_price`, which is what a buyer pays, how TCGplayer's own site orders offers, and the order the snapshot was collected in — so `total_asc` reproduces TCGplayer's list and its first row is the true cheapest offer, which under `price_asc` can sit several rows down behind a low-price, high-shipping listing. A cursor is bound to the sort family it was issued under: a `total_*` cursor replayed under a `price_*` sort (or the reverse) is a `400`. `min_price`/`max_price` filter item price under every sort.

Response:
```json
{
  "data": [
    {
      "id": 4567,
      "listing_id": 274183167,
      "printing": "1st Edition Holofoil",
      "condition": "Near Mint",
      "language": "English",
      "price": 4650.00,
      "shipping_price": 0.00,
      "seller_name": "Cash Cow Games",
      "seller_id": "120594",
      "seller_rating": 100.0,
      "seller_sales": "50000+",
      "quantity": 1,
      "listing_type": "standard",
      "direct_seller": false,
      "gold_seller": true,
      "verified_seller": false,
      "custom_title": null,
      "updated_at": "2026-06-17T03:44:00+00:00",
      "snapshot_at": "2026-09-03T02:41:12Z"
    }
  ],
  "pagination": { "has_more": true, "next_cursor": "NDU2Nw==", "count": 20 }
}
```

**`updated_at` is not a freshness signal — read `snapshot_at` instead.**

| Field | Answers |
|-------|---------|
| `updated_at` | When this listing's own fields (price, quantity, seller data) last changed. A listing that has been live and unchanged for a month keeps a month-old `updated_at`, however recently we confirmed it. |
| `snapshot_at` | When this product's listings were last confirmed against TCGplayer. Identical across every row of a response, because a snapshot replaces a product's listings wholesale. `null` if no successful snapshot has been recorded since the field was introduced. |

Listings are re-snapshotted daily. If `snapshot_at` is well over a day old, that product's last fetch did not succeed and you are looking at the previous snapshot — the rows are real offers as of `snapshot_at`, not as of now.

One thing `snapshot_at` cannot tell you: we collect from a US vantage point with no shipping-destination filter, so a snapshot can legitimately contain offers that TCGplayer's own site hides from you when you browse it from outside the US. A listing in the response that you cannot find on the site is more often that than staleness.

---

### GET /v1/cards/:id/population (Pro+)
How many copies of a card PSA, BGS, SGC and CGC have graded, per variant, from their population reports. One credit per request. Free plan returns `403`.

Population is per printing, and a printing is a variant here: a card's `Holofoil` and `Reverse Holofoil` are two entries with their own counts, spelled as in `prices`. Two variants that are one physical print (a shadowless set's `Normal` and `Unlimited`) carry the same counts. A variant we could not tie to its population records is left out rather than guessed, as is a variant only Cardmarket lists (a EUR `Normal` row on a card TCGplayer sells only as `Holofoil`), so `variants` can be shorter than the card's variant list, or empty. An empty list is not a population of zero.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| variant | string |  | Only this variant (e.g. `Reverse Holofoil`) |

Response:
```json
{
  "card_id": 12927,
  "variants": [
    {
      "variant": "Holofoil",
      "total_population": 133526,
      "total_gems": 1043,
      "gem_rate": 0.78,
      "grades": { "1": 4665, "1.5": 244, "8": 19977, "8.5": 4614, "9": 11158, "9.5": 408, "10": 781 },
      "pristine": 12,
      "black_label": 1,
      "authentic": 873,
      "percent_higher": { "8": 12.83, "8.5": 9.34, "9": 0.91, "9.5": 0.6, "10": 0.01 },
      "graders": {
        "PSA": {
          "total": 107747,
          "gems": 490,
          "gem_rate": 0.45,
          "grades": { "8": 16518, "8.5": 572, "9": 8538, "10": 490 },
          "pristine": null,
          "black_label": null,
          "authentic": 799,
          "altered": null,
          "qualified": 206,
          "last_population_change": "2026-10-18",
          "pop_report_url": "https://www.psacard.com/pop/tcg-cards/1999/pokemon-game/57801",
          "spec_id": "544027",
          "description": "1999 Pokemon Game Charizard-Holo Base 4"
        }
      },
      "last_population_change": "2026-10-18",
      "updated_at": "2026-10-18T19:29:42+00:00"
    }
  ]
}
```
(Grade maps shortened; every grade with at least one copy is present.)

| Field | Meaning |
|-------|---------|
| `total_population` | Every graded copy across all graders, authentic and qualified included. |
| `total_gems` / `gem_rate` | Copies at each grader's gem grade or higher (PSA 10, BGS 9.5 and up, SGC 10 and up, CGC 10 and up), and that as a percentage of `total_population`. |
| `grades` | Numeric grades summed across graders, keyed `"1"` to `"10"` with halves as `"8.5"`. Pristine and Black Label are separate fields and sit above `"10"`. |
| `percent_higher` | For each grade, the percentage of numerically graded copies that graded higher. `percent_higher["8.5"]` is the share that came back a 9 or better: the usual input to a grading ROI estimate. |
| `graders` | Each grader's own counts. A grader with no copies on record is absent. `pristine`, `black_label` (BGS Black Label, CGC Perfect 10) and `altered` (CGC) are `null` for graders that do not issue them, not zero. `description` is how the grader names the card in its own report. |
| `updated_at` | When these counts were last refreshed. `last_population_change` is the last day any grader's count moved. |

---

### GET /v1/export/cards (Scale+)
The whole price catalog as one gzipped CSV, so a job that needs every card can download a file instead of paging `/cards`. Pro and Free return `403`.

It is not charged in credits. Each account can download it twice per UTC day, so a dropped connection can be retried once; the `x-export-downloads-remaining` header says how many are left, and a third request returns `403` until 00:00 UTC. It still counts against the per-minute rate limit.

One row per card, currency, condition and variant, with the current raw (ungraded) market price. Graded prices, listings and sold comps are not included. Prices update once a day, so a second download the same day returns the same numbers.

Columns: `card_id, tcgplayer_id, name, number, set_number, rarity, set_id, set, language, currency, condition, variant, market_price`. `condition` and `variant` are empty when the source does not split by them. Fields with commas or quotes are quoted per RFC 4180.

The response is `application/gzip` with a `Content-Disposition` filename like `pkmnprices-cards-2026-10-26.csv.gz`. It streams, so the first bytes arrive before the file is finished; a download that fails before sending anything is not counted.

```bash
curl -H "x-api-key: $KEY" -o cards.csv.gz https://api.pkmnprices.com/v1/export/cards
```

---

### GET /v1/sealed (Pro+)
List sealed products (booster boxes, ETBs, etc.). Does **not** return prices — use `GET /v1/sealed/:id` to get a product's prices. Free plan returns `403`.

| Param | Type | Description |
|-------|------|-------------|
| set_id | integer | Filter by set |
| tcg_player_id | integer | Get a specific product by TCGPlayer ID |
| name | string | Filter by product name (substring match) |
| language | string | Filter by language: `English`, `Japanese`, `German`, `Spanish` (Pro+ for all but English) |
| min_price | number | Minimum price |
| max_price | number | Maximum price |
| sort | string | `price_asc` or `price_desc` |
| page | integer | Page number (default 1) |
| per_page | integer | Results per page (default 50, max 100) |

Response item (no `prices` — see `/v1/sealed/:id`):
```json
{
  "id": 101,
  "tcg_player_id": 987654,
  "name": "Obsidian Flames Booster Box",
  "image_url": "https://...",
  "set": { "id": 123, "name": "Obsidian Flames" }
}
```

### GET /v1/sealed/:id (Pro+)
Get a single sealed product by ID, including its `prices` array. Response includes
nullable Cardmarket mapping identifiers (`cardmarket_url` is the absolute
Cardmarket product URL; `cardmarket_product_id` is its stable numeric product
ID). Both may be `null` until a mapping has been established. List endpoints
omit these fields. Prices come from TCGPlayer (USD) and Cardmarket (EUR) —
use `?currency=` to filter.

### GET /v1/sealed/:id/prices/history (Pro+)
Price history for a sealed product. Same parameters and response shape as card price history.

### GET /v1/sealed/:id/listings/tcgplayer (Pro+)
Live TCGplayer marketplace offers for a sealed product. Same parameters, response shape, and cursor pagination as `/v1/cards/:id/listings/tcgplayer`. All prices are USD. Free plan returns `403`. Sealed offers normally carry `condition: "Unopened"` and an empty `printing`, so the `condition`/`printing` filters are rarely useful here.

### GET /v1/sealed/:id/listings/ebay (Pro+)
Individual sold eBay comps for a sealed product. `currency` is always `"USD"` here. Same response shape and cursor pagination as `/v1/cards/:id/listings/ebay`, minus the grading filters: sealed products are not graded, so `graded`, `grader`, and `grade` are not accepted and `grader`/`grade`/`seller_country`/`sale_type` are always `null` in the response. Accepts `min_price`, `max_price`, `since`, `period`, `sort` (`date_desc` default, plus `date_asc`, `price_desc`, `price_asc`), `limit` (max 20), and `cursor`. Free plan returns `403`.

`attribution` is returned here too and means the same thing, but sealed products map one source page each with no printing to distinguish, so it is a property of the product rather than of the row: every comp in one response carries the same value, and `variant` is always `null`. There is no `variant` filter.

### GET /v1/sealed/:id/listings/cardmarket (Pro+)
Live Cardmarket marketplace offers for a sealed product. Prices are EUR. Free plan returns `403`. Uses `(price, id)` cursor pagination and returns current seller offers cheapest first by default. Response shape matches `/v1/cards/:id/listings/cardmarket`, including `seller_country` and the `seller_country` / `exclude_seller_country` filters.

`opened` is meaningful here and nowhere else: it marks an offer whose seller says the product is not sealed, and like `signed`/`altered`/`graded` it is returned as a real offer but excluded from price derivation. Sealed products are single-language — the offers returned are the ones in the set's own language, so a Cardmarket product page showing offers in other languages will list more than this endpoint does.

`signed`, `altered`, `graded`, `grader` and `grade` behave exactly as on the card endpoint, including their exclusion from price derivation. They are almost always `false`/`null` here: a sealed product is unopened, so a flagged sealed offer is an oddity rather than the norm.

Two differences from the card endpoint. It is **not** language-scoped: a card shares one Cardmarket article across languages and has to be narrowed to its own, while a sealed product owns its rows outright, so every offer already belongs to it. And there is no `variant` filter — sealed rows are stored with an empty `variant`, so filtering on it could only ever match nothing.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| condition | string |  | Native Cardmarket condition. Sealed offers usually carry none. |
| min_price | number |  | Minimum offer price (EUR) |
| max_price | number |  | Maximum offer price (EUR) |
| seller_country | string |  | Same as on the card endpoint |
| exclude_seller_country | string |  | Same as on the card endpoint |
| graded | boolean |  | Same as on the card endpoint |
| grader | string |  | Same as on the card endpoint |
| grade | string |  | Same as on the card endpoint |
| signed | boolean |  | Same as on the card endpoint |
| altered | boolean |  | Same as on the card endpoint |
| min_sell_count | integer |  | Same as on the card endpoint |
| opened | boolean |  | `true` = only offers whose seller says the product is not sealed; `false` = leave those out |
| sort | string | price_asc | `price_asc`, `price_desc` |
| limit | integer | 20 | Results per page (max 20) |
| cursor | string |  | Opaque cursor from the previous response |

---

### GET /v1/me (JWT Auth)
Get your profile.
```json
{ "id": 1, "email": "user@example.com", "tier": "pro", "avatar_url": "https://...", "has_password": true, "email_verified": true, "created_at": "2025-01-01T00:00:00Z" }
```

Password signups start with `email_verified: false` until the magic link is used. OAuth signups and existing accounts are verified by default. `/me`, `/auth/refresh`, and `/auth/resend-verification` work while unverified; `/usage`, `/keys`, `/billing`, and password routes require a verified email.

### POST /v1/auth/verify-email (No Auth)
Confirm a password signup via the magic-link token. Body: `{ "token": "..." }`. On success returns `{ "ok": true }`, sets `email_verified`, and sends the welcome email. Idempotent if already verified.

### POST /v1/auth/resend-verification (JWT Auth)
Re-send the verification email for the authenticated user. Only applies when `email_verified` is false. Returns `{ "ok": true }`. Rate-limited to 3 requests per hour per IP.

### GET /v1/usage (JWT Auth)
Get credit usage across all your API keys.
```json
{
  "keys": [
    { "key_id": 1, "key_prefix": "pk_abc123...", "label": "my-app", "credits_used": 450 }
  ],
  "total_credits_used": 450,
  "total_daily_limit": 20000,
  "credit_balance": 62500,
  "credits_owed": 0,
  "days_at_cap_7d": 0,
  "days_over_80_14d": 1,
  "deposits_30d_cents": 500
}
```

`credit_balance` is the prepaid balance and `credits_owed` what a refund or chargeback could not take back. `days_at_cap_7d` counts days in the last 7 (today included) on which usage reached the daily limit, `days_over_80_14d` days in the last 14 that reached 80% of it, and `deposits_30d_cents` the prepaid deposits of the last 30 days.

---

## Errors

All errors follow this format:
```json
{ "error": { "code": "not_found", "message": "card not found" } }
```

| Status | Code | Meaning |
|--------|------|---------|
| 400 | `bad_request` | Invalid parameters |
| 401 | `unauthorized` | Missing or invalid JWT (session/login routes) |
| 401 | `missing_api_key` | No `x-api-key` header was sent |
| 401 | `invalid_api_key` | `x-api-key` header does not match a known key |
| 403 | `forbidden` | Feature requires a higher plan |
| 403 | `email_unverified` | Email address is not verified (gated account/API-key routes) |
| 404 | `not_found` | Resource does not exist |
| 409 | `conflict` | Resource conflict (e.g. duplicate key) |
| 429 | `credit_limit_exceeded` | Daily credit limit reached |
| 429 | `rate_limit_exceeded` | Per-minute rate limit hit |
| 500 | `internal_error` | Server error |

Every 429 carries a `Retry-After` header in whole seconds, and the error object gains three fields (four on a daily limit):

```json
{
  "error": {
    "code": "credit_limit_exceeded",
    "message": "daily credit limit exceeded",
    "docs_url": "https://www.pkmnprices.com/docs/rate-limits",
    "limit_type": "daily",
    "retry_after": 41230,
    "resets_at": "2026-10-26T00:00:00Z",
    "upgrade_url": "https://www.pkmnprices.com/dashboard?view=billing"
  }
}
```

`limit_type` is `daily` or `per_minute`. They clear on different clocks: a per-minute 429 clears within 60 seconds, a daily one not until 00:00 UTC, so retrying a daily 429 on a short loop cannot succeed. Wait `Retry-After` seconds. The three fields appear on 429 responses only. A daily 429 also carries `upgrade_url`, the dashboard page for moving up a plan or adding prepaid credits; a per-minute one does not.

---

## Typical Workflow

1. `GET /v1/cards?name=charizard&per_page=10` — search for cards
2. `GET /v1/cards/789` — get full pricing for a specific card
3. `GET /v1/cards/789/prices/history?period=30d` — view price trends (Pro+)
4. `GET /v1/cards/789/listings/ebay?grader=PSA&grade=10` — browse graded sales (Pro+)
5. `GET /v1/cards/789/listings/cardmarket?condition=Near%20Mint&variant=Reverse%20Holo` — browse language-matched live Cardmarket offers (Pro+)
6. `GET /v1/cards/789/listings/tcgplayer?condition=Near%20Mint` — browse live TCGplayer offers (Pro+)
7. `GET /v1/sealed?set_id=123` — check sealed product prices (Pro+)
8. `GET /v1/sealed/5678/listings/tcgplayer` — browse live sealed offers, cheapest first (Pro+)
