# Alt API — trading card values and sales from alt.xyz: card search with the Alt Value, graded population and last sale; one card with every grade's Alt Value and last sale; the card's full individual sales history from eBay, Fanatics Collect (PWCC), Goldin, Heritage, Alt, Pristine, CardHobby and more, with price, date, grade and marketplace; the Alt Value history; the last ~90 days of sales across all cards; live listings and Alt auctions with bids. Pokémon, One Piece, Yu-Gi-Oh!, Magic, sports and pop-culture cards. USD. No login, no key.

> Search Alt's card database (29.9 million cards) by keyword. Each row is one card with its set, number, year, variety and player / character, the total graded population and its last recorded sale (date, price, grade, marketplace). With `grade` (e.g. PSA 10) each row also carries that grade's Alt Value with its confidence band, its population and its last sale.
> ReefAPI engine `altxyz` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/altxyz/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/altxyz/v1/search — 3 credits
Search Alt's card database (29.9 million cards) by keyword. Each row is one card with its set, number, year, variety and player / character, the total graded population and its last recorded sale (date, price, grade, marketplace). With `grade` (e.g. PSA 10) each row also carries that grade's Alt Value with its confidence band, its population and its last sale.

**Parameters:**
- `query` (string, optional) — Card words: player / character, set, year, number, variety. Typo-tolerant. Empty = every card (browse with filters).
- `category` (enum, optional) — Only one category. [one of: pokemon, baseball, basketball, football, hockey, soccer, one_piece, yugioh, magic, tcg, pop_culture, combat_sports, racing, tennis, golf, other]
- `year_min` (integer, optional) — Card year from (inclusive).
- `year_max` (integer, optional) — Card year to (inclusive).
- `grade` (string, optional) — One grade: grader + grade, e.g. PSA 10, PSA 9, BGS 9.5, CGC 10, CGC Pristine, BGS Black Label, SGC 10, PSA Authentic.
- `sort` (enum, optional, default "relevance") — Result order. [one of: relevance, pop_desc, pop_asc]
- `enrich` (boolean, optional, default true) — Add each card's last sale (and, with `grade`, its Alt Value and pop in that grade). false = card identity only, one request.
- `page` (integer, optional, default 1) — Page number, 1 = first.
- `limit` (integer, optional, default 20) — Rows per page (1-50).

**Returns:** rows[]: card_id, name, year, set, number, variety, subject (player / character), category, category_code, print_run, url, pop (the population figure Alt's card index carries; it can differ from the sum of `card` population), external_sales_count, last_sale{date, price_usd, marketplace, source, grade, grade_key, sale_type, listing_url, sale_id} (newest completed sale of any grade), grades_with_sales, in_grade{grade, grade_key, alt_value, alt_value_low, alt_value_high, alt_value_confidence (0-100), pop, last_sale} (with `grade`). meta: total, page, limit, has_more.

**Example request body:**
```json
{
  "query": "charizard base set 1st edition",
  "grade": "PSA 10"
}
```

### POST https://api.reefapi.com/altxyz/v1/card — 3 credits
One card in full by its card_id: identity, images, the graded population of every grade, a grade ladder with every grade's current Alt Value (and confidence band) and last sale, Alt's own active listings of the card, and — with `grade` — the headline Alt Value of that grade and the card's live external listings (eBay, Fanatics, Goldin …) in that grade.

**Parameters:**
- `card_id` (string, required) — A search / sales / listings row's card_id as is (Alt's asset id), or an alt.xyz/research/<id> link.
- `grade` (string, optional) — One grade: grader + grade, e.g. PSA 10, PSA 9, BGS 9.5, CGC 10, CGC Pristine, BGS Black Label, SGC 10, PSA Authentic.

**Returns:** card{card_id, name, year, set, number, variety, subject (player / character), category, category_code, print_run, url, image, images[], pop_total, population[{grading_company, grade_number, grade, grade_key, pop}], grades[{grade, grade_key, grading_company, grade_number, alt_value, alt_value_low, alt_value_high, alt_value_confidence, pop, last_sale{…}}] (every grade with a recorded sale, highest Alt Value first), last_sale{…}, in_grade{…} (with `grade`), alt_listings[{listing_id, type, state, list_price_usd, min_offer_usd, ends_at, items[{grade, cert_number, alt_value, …}], url}], external_listings[] (with `grade`)}

**Example request body:**
```json
{
  "card_id": "e5c5faea-533f-48fe-8013-a918d87a8b52"
}
```

### POST https://api.reefapi.com/altxyz/v1/card_sales — 3 credits
The card's individual sales history as Alt records it — with `grade`, every sale of that grade back to the first recorded one; without, the newest `per_grade` sales of every grade — from eBay, Fanatics Collect (incl. every PWCC venue), Goldin, Heritage, Alt, Pristine, CardHobby, MySlabs, Robert Edwards, Memory Lane and more — each with price, date, grade, marketplace and the listing link. Filter by grade, marketplace and dates.

**Parameters:**
- `card_id` (string, required) — A search / sales / listings row's card_id as is (Alt's asset id), or an alt.xyz/research/<id> link.
- `grade` (string, optional) — One grade: grader + grade, e.g. PSA 10, PSA 9, BGS 9.5, CGC 10, CGC Pristine, BGS Black Label, SGC 10, PSA Authentic.
- `marketplace` (enum, optional) — Only sales on one marketplace. fanatics = Fanatics Collect and every former PWCC venue (weekly, premier, monthly, fixed price). [one of: ebay, fanatics, alt, goldin, heritage, pristine, cardhobby, myslabs, other]
- `from` (string, optional) — Sales on or after this date (YYYY-MM-DD).
- `to` (string, optional) — Sales on or before this date (YYYY-MM-DD).
- `skipped` (enum, optional, default "include") — Sales Alt marks RELISTED or NOT_PAID (the buyer did not pay / the item came back): include (as the site shows them), exclude, or only. [one of: include, exclude, only]
- `per_grade` (integer, optional, default 50) — Without `grade`: how many of the newest sales of EACH grade to return (the site's own all-grades view shows 16). With `grade` the whole history of that grade is returned and this is ignored.
- `sort` (enum, optional, default "date_desc") — Order of the sales. [one of: date_desc, date_asc, price_desc, price_asc]
- `page` (integer, optional, default 1) — Page of the filtered, sorted history, 1 = first.
- `limit` (integer, optional, default 100) — Sales per page (1-1000).

**Returns:** card{card_id, name, year, set, number, variety, subject (player / character), category, category_code, print_run, url}, rows[]: sale_id, date, price_usd, marketplace, marketplace_name, source (the venue as Alt names it, e.g. 'PWCC Weekly Auctions'), sale_type (AUCTION / BEST_OFFER / BUY_IT_NOW / FIXED_PRICE), grading_company, grade_number, grade, grade_key, autograph, listing_url, skipped_reason (RELISTED / NOT_PAID / null), subject_to_change, label. meta: total (after filters), total_unfiltered, by_marketplace{…} (after filters), first_date, last_date, page, limit, has_more.

**Example request body:**
```json
{
  "card_id": "e5c5faea-533f-48fe-8013-a918d87a8b52",
  "grade": "PSA 9"
}
```

### POST https://api.reefapi.com/altxyz/v1/card_value_history — 2 credits
The daily Alt Value of one card in one grade between two dates (default: the last 365 days), with Alt's error band for each day. Alt publishes about one year of daily values.

**Parameters:**
- `card_id` (string, required) — A search / sales / listings row's card_id as is (Alt's asset id), or an alt.xyz/research/<id> link.
- `grade` (string, required) — The grade whose Alt Value history you want: PSA 10, BGS 9.5, CGC Pristine …
- `from` (string, optional) — First day (YYYY-MM-DD). Default: 365 days before `to`.
- `to` (string, optional) — Last day (YYYY-MM-DD). Default: today.

**Returns:** card{card_id, name, url}, grade, grade_key, points[{date, alt_value, alt_value_low, alt_value_high}] oldest first, summary{first_date, last_date, first_value, last_value, high, low, change_pct}, ready_for_display (Alt's own flag)

**Example request body:**
```json
{
  "card_id": "e5c5faea-533f-48fe-8013-a918d87a8b52",
  "grade": "PSA 9"
}
```

### POST https://api.reefapi.com/altxyz/v1/sales — 2 credits
Sold listings across ALL cards from the last ~90 days (Alt's sold-listings feed): eBay, Fanatics Collect, Goldin, Heritage, Alt, Pristine, CardHobby, MySlabs. Filter by keyword, marketplace, category, grade, grading company, price, sale date, auction vs fixed price, or one card.

**Parameters:**
- `query` (string, optional) — Card words. Empty = every sale (browse with filters).
- `marketplace` (enum, optional) — Only one marketplace. fanatics = Fanatics Collect (incl. PWCC). [one of: ebay, fanatics, alt, goldin, heritage, pristine, cardhobby, myslabs]
- `category` (enum, optional) — Only one category. [one of: pokemon, baseball, basketball, football, hockey, soccer, one_piece, yugioh, magic, tcg, pop_culture, combat_sports, racing, tennis, golf, other]
- `grade` (string, optional) — One grade: grader + grade, e.g. PSA 10, PSA 9, BGS 9.5, CGC 10, CGC Pristine, BGS Black Label, SGC 10, PSA Authentic.
- `grading_company` (enum, optional) — Only one grading company. [one of: PSA, BGS, CGC, SGC, TAG, CSG, BVG, PSA/DNA, BCCG]
- `sale_format` (enum, optional) — Only auction sales or only fixed-price / best-offer sales. [one of: auction, fixed_price]
- `min_price` (number, optional) — Price at least (USD).
- `max_price` (number, optional) — Price at most (USD).
- `from` (string, optional) — Sold on or after this date (YYYY-MM-DD). The feed holds the last ~90 days.
- `to` (string, optional) — Sold on or before this date (YYYY-MM-DD).
- `card_id` (string, optional) — Only rows of one card (a search row's card_id).
- `sort` (enum, optional, default "date_desc") — Result order. [one of: date_desc, date_asc, price_desc, price_asc]
- `page` (integer, optional, default 1) — Page number, 1 = first.
- `limit` (integer, optional, default 20) — Rows per page (1-50).

**Returns:** rows[]: sale_id, sold_date, price_usd, marketplace, marketplace_name, source, sale_type, listing_type, title (the seller's own title), grading_company, grade_number, grade, grade_key, card_id, name, year, set, number, variety, subject, category, category_code, card_url, pop, serial_numbered, rookie_year, listing_url, lot_id, skipped_reason, image, images[], alt_url. meta: total, page, limit, has_more.

**Example request body:**
```json
{
  "query": "charizard",
  "marketplace": "goldin"
}
```

### POST https://api.reefapi.com/altxyz/v1/listings — 2 credits
Live listings Alt indexes: Alt's own auctions and fixed-price listings plus eBay, Fanatics Collect, Goldin, Pristine and CardHobby listings, each with price or current bid, bids, watchers, end time, grade, population and the card's Alt Value as stored on the listing. The site's own sort options.

**Parameters:**
- `query` (string, optional) — Card words. Empty = every live listing (browse with filters).
- `marketplace` (enum, optional) — Only one marketplace. fanatics = Fanatics Collect (incl. PWCC). [one of: ebay, fanatics, alt, goldin, heritage, pristine, cardhobby, myslabs]
- `listing_type` (enum, optional) — Only auctions or only fixed-price listings; alt_* = Alt's own listings only. [one of: auction, fixed_price, alt_auction, alt_fixed_price]
- `category` (enum, optional) — Only one category. [one of: pokemon, baseball, basketball, football, hockey, soccer, one_piece, yugioh, magic, tcg, pop_culture, combat_sports, racing, tennis, golf, other]
- `grade` (string, optional) — One grade: grader + grade, e.g. PSA 10, PSA 9, BGS 9.5, CGC 10, CGC Pristine, BGS Black Label, SGC 10, PSA Authentic.
- `grading_company` (enum, optional) — Only one grading company. [one of: PSA, BGS, CGC, SGC, TAG, CSG, BVG, PSA/DNA, BCCG]
- `min_price` (number, optional) — Price at least (USD).
- `max_price` (number, optional) — Price at most (USD).
- `min_alt_value` (number, optional) — Alt Value (as stored on the listing) at least (USD).
- `max_alt_value` (number, optional) — Alt Value (as stored on the listing) at most (USD).
- `card_id` (string, optional) — Only rows of one card (a search row's card_id).
- `sort` (enum, optional, default "recommended") — Result order (the site's own sort options). [one of: recommended, price_desc, price_asc, ending_soonest, newest, alt_value_desc, alt_value_asc, most_watched, most_bids, fewest_bids]
- `page` (integer, optional, default 1) — Page number, 1 = first.
- `limit` (integer, optional, default 20) — Rows per page (1-50).

**Returns:** rows[]: listing_id, marketplace, marketplace_name, source, listing_type, is_alt_listing, title, price_usd (current bid on auctions), price_not_published, bid_count, watch_count, view_count, starts_at, ends_at, no_end_date, auction_name, auction_cycle_id, offers_disabled, grading_company, grade_number, grade, grade_key, card_id, name, year, set, number, variety, subject, category, category_code, card_url, pop, alt_value_at_listing, alt_value_low, alt_value_high, alt_value_confidence, price_minus_alt_value_usd, listing_indexed_at, listed_at, last_external_sale{marketplace, source, price_usd}, great_price, serial_numbered, rookie_year, listing_url, alt_url, image, images[]. meta: total, page, limit, has_more.

**Example request body:**
```json
{
  "query": "charizard",
  "listing_type": "alt_auction"
}
```

### POST https://api.reefapi.com/altxyz/v1/listing — 1 credit
One listing by its listing_id. An Alt listing: price, minimum offer, state, end time, every item with grade, cert number and Alt Value, the auction's full bid history (price and time of every bid), views and the card's population. An external listing (live_…): marketplace, current bid, bids, buy-it-now price, end time, grade and the listing link.

**Parameters:**
- `listing_id` (string, required) — A listings row's listing_id as is (Alt listing id, or live_<id> for an external listing), or an alt.xyz/itm/<id> link.

**Returns:** listing{listing_id, kind (alt | external). alt: type (AUCTION / LISTING), state, list_price_usd, min_offer_usd, created_at, ends_at, items[{item_id, item_name, grade, grade_key, cert_number, serial, alt_value, card_id, image}], bids[{price_usd, at}] newest first, bid_history_events (price steps; the listings row's bid_count counts every bid and is larger), view_count, pop, auction_cycle_id, card_id, card_url, url. external: marketplace, source, ends_at, bid_count, highest_bid_usd, buy_it_now_usd, grade, listing_url, card identity}

**Example request body:**
```json
{
  "listing_id": "8fd4b09d-9a85-47b8-8723-7f7eebb8ea81"
}
```

### POST https://api.reefapi.com/altxyz/v1/sale — 1 credit
One recorded sale by its sale_id: price in USD and as displayed, currency, fees, shipping, marketplace and auction name, grade and cert number, images, the listing link and the card.

**Parameters:**
- `sale_id` (string, required) — A card_sales / sales row's sale_id, or an alt.xyz/itm/<id>/sold link.

**Returns:** sale{sale_id, date, price_usd (the sold price the site prints), usd_amount (Alt's usdAmount: on best-offer sales it can be the asking price, not the sold price), currency, fees_usd, shipping_usd, marketplace, marketplace_name, source, auction_name, sale_type, title, grading_company, grade_number, grade, grade_key, cert_number, autograph, listing_url, image, images[], skipped_reason, subject_to_change, alt_listing_id, card{…}, alt_url}

**Example request body:**
```json
{
  "sale_id": "accb4108-8fe2-4983-87dd-6d81c1af8d2c"
}
```

## 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=altxyz
- Human docs page: https://reefapi.com/docs/altxyz
- Overview page: https://reefapi.com/altxyz-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt