# Card Kingdom API — Magic: The Gathering singles prices from cardkingdom.com, the largest US MTG store: sell price and stock for every condition (NM, EX, VG, G) of every printing, foil and non-foil, and the buylist — what Card Kingdom pays for a card in cash and in store credit. Search by name, edition, rarity, colour, type, format and price; one card in full; the buylist; every edition. Prices in USD. No login, no key.

> Search Card Kingdom's Magic singles: each row is one printing in one finish with its sell price and stock per condition (NM / EX / VG / G). Give `query` or `edition` (or both). Non-foil by default; foil=true for the foil printings.
> ReefAPI engine `cardkingdom` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/cardkingdom/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/cardkingdom/v1/search — 3 credits
Search Card Kingdom's Magic singles: each row is one printing in one finish with its sell price and stock per condition (NM / EX / VG / G). Give `query` or `edition` (or both). Non-foil by default; foil=true for the foil printings.

**Parameters:**
- `query` (string, optional) — Card name, or any words of it (the site matches partial words: 'shiv drag' finds Shivan Dragon). Optional when `edition` is given.
- `edition` (string, optional) — Only one edition: an `edition_slug` from the `sets` action or a row (2011-core-set, modern-horizons-3, secret-lair). The source treats it as a set family and also returns related printings (promos, commander decks, variants); each row has its own edition_slug and meta counts rows_from_related_editions. An unknown slug is rejected with INVALID_PARAM.
- `rarity` (array, optional) — Only these rarities (one or more): M mythic, R rare, U uncommon, C common, L basic land, S special. [one of: M, R, U, C, L, S]
- `foil` (boolean, optional, default false) — true = the foil printings (the site's Foils tab); false = non-foil.
- `color` (enum, optional) — Only cards of one casting colour (the site's colour box). [one of: W, U, B, R, G, C]
- `card_type` (enum, optional) — Only one card type. [one of: Artifact, Battle, Creature, Enchantment, Instant, Kindred, Land, Legendary, Planeswalker, Sorcery]
- `format` (enum, optional) — Only cards legal in one format. [one of: commander, standard, pioneer, modern, premodern, legacy, vintage, pauper, brawl]
- `in_stock_only` (boolean, optional, default false) — Only cards with at least one condition in stock.
- `min_price` (number, optional) — Only cards priced at or above this many US dollars. The site takes one price bound per search: give min_price OR max_price, not both.
- `max_price` (number, optional) — Only cards priced at or below this many US dollars (one bound per search, see min_price).
- `sort` (enum, optional, default "popularity") — Result order. [one of: popularity, name_asc, name_desc, price_asc, price_desc]
- `per_page` (enum, optional, default 25) — Rows per page: 25, 50 or 100. [one of: 25, 50, 100]
- `page` (integer, optional, default 1) — Page number, from 1. Past the last page the call answers with no rows and `has_more: false`.

**Returns:** rows[]: id (Card Kingdom product id), path (give it to `card`), url, name, variation, edition, edition_slug, rarity, rarity_name, collector_number, foil, listed_as_foil, mana_cost, type_line, power_toughness, rules_text, image, price_nm_usd, in_stock, cheapest_in_stock{condition, price_usd}, conditions[NM, EX, VG, G]: {condition, condition_name, price_usd, price_printed_usd, in_stock, qty_available (the printed 'N available' = the most one order can take; the site caps it at 8 / 20 / 40), stock_qty (the page's uncapped shelf count)}. meta: total (the tab's own count), total_nonfoil, total_foil, page, per_page, has_more, past_last_page, rows_from_related_editions, filters_applied, warnings.

**Example request body:**
```json
{
  "query": "lightning bolt"
}
```

### POST https://api.reefapi.com/cardkingdom/v1/card — 2 credits
One printing in one finish, in full: the sell price and stock of every condition, edition, rarity, collector number, mana cost, type, rules text, power/toughness and the card's other printings at Card Kingdom.

**Parameters:**
- `path` (string, required) — `path` of a search or buylist row, as is (mtg/<edition>/<card>; a foil printing ends in -foil). A cardkingdom.com/mtg/... URL is also accepted.

**Returns:** card{id, name, variation, heading, edition, edition_slug, rarity, rarity_name, collector_number, foil, listed_as_foil, type_line, mana_cost, power_toughness, rules_text, details{}, image, price_nm_usd, in_stock, cheapest_in_stock, conditions[NM, EX, VG, G]: {condition, condition_name, price_usd, price_printed_usd, in_stock, qty_available (the printed 'N available' = the most one order can take; the site caps it at 8 / 20 / 40), stock_qty (the page's uncapped shelf count)}, other_printings[{path, edition, collector_number}]}

**Example request body:**
```json
{
  "path": "mtg/2011-core-set/lightning-bolt"
}
```

### POST https://api.reefapi.com/cardkingdom/v1/buylist — 3 credits
Card Kingdom's buylist: what it pays for a card (Near Mint) in cash and, separately, in store credit, and how many copies it will buy. Give `query` or `edition` (or both).

**Parameters:**
- `query` (string, optional) — Card name, or any words of it (the site matches partial words: 'shiv drag' finds Shivan Dragon). Optional when `edition` is given.
- `edition` (string, optional) — Only one edition: an `edition_slug` from the `sets` action or a row (2011-core-set, modern-horizons-3, secret-lair). The source treats it as a set family and also returns related printings (promos, commander decks, variants); each row has its own edition_slug and meta counts rows_from_related_editions. An unknown slug is rejected with INVALID_PARAM.
- `rarity` (array, optional) — Only these rarities (one or more): M mythic, R rare, U uncommon, C common, L basic land, S special. [one of: M, R, U, C, L, S]
- `finish` (enum, optional, default "both") — Which finishes the buylist covers. [one of: both, nonfoil, foil]
- `format` (enum, optional) — Only cards legal in one format. [one of: commander, standard, pioneer, modern, premodern, legacy, vintage, pauper, brawl]
- `min_price` (number, optional) — Only cards Card Kingdom pays at least this many US dollars cash for (one bound per call: min_price OR max_price).
- `max_price` (number, optional) — Only cards Card Kingdom pays at most this many US dollars cash for.
- `sort` (enum, optional, default "popularity") — Result order. [one of: popularity, name_asc, name_desc, price_asc, price_desc]
- `per_page` (enum, optional, default 25) — Rows per page: 25, 50 or 100. [one of: 25, 50, 100]
- `page` (integer, optional, default 1) — Page number, from 1. Past the last page the call answers with no rows and `has_more: false`.

**Returns:** rows[]: id, path, url, name, variation, edition, edition_slug, rarity, rarity_name, collector_number, foil, listed_as_foil, type_line, power_toughness, rules_text, image, buy_condition (NM), buy_price_cash_usd, buy_price_credit_usd (store credit — not cash), credit_to_cash_ratio, buy_max_qty. meta: total, total_is_capped, page, per_page, has_more, past_last_page, rows_from_related_editions, filters_applied, warnings, price_basis.

**Example request body:**
```json
{
  "query": "lightning bolt"
}
```

### POST https://api.reefapi.com/cardkingdom/v1/sets — 3 credits
Every Magic edition Card Kingdom lists, A-Z, with the slug `search` and `buylist` take as `edition`.

**Parameters:** none

**Returns:** rows[]: edition_slug, name, url, icon

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=cardkingdom
- Human docs page: https://reefapi.com/docs/cardkingdom
- Overview page: https://reefapi.com/cardkingdom-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt