Alt API & Scraper
The Alt API turns alt.xyz into JSON in eight actions.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
search finds cards in Alt's database of 29.9 million cards by keyword (Pokémon, One Piece, Yu-Gi-Oh!, Magic, baseball, basketball, football, soccer, hockey, pop culture and more), filtered by category and year; each row carries the card's set, number, year, variety and player or character, its last recorded sale, and with a grade such as PSA 10 that grade's Alt Value with its confidence band, population and last sale. card returns one card in full: images, the population of every grade, a grade ladder with each grade's Alt Value and last sale, and Alt's own listings of the card. card_sales returns the card's individual sales as Alt records them: price, date, grade, the marketplace (eBay, Fanatics Collect including every former PWCC venue, Goldin, Heritage, Alt, Pristine, CardHobby, MySlabs, Robert Edwards, Memory Lane and more) and the listing link, filtered by grade, marketplace and dates. card_value_history returns the daily Alt Value of one grade. sales searches the last 90 days of sold listings across all cards by marketplace, category, grade, price and date; listings searches live listings, Alt's own auctions and fixed-price listings plus eBay, Fanatics, Goldin, Pristine and CardHobby; listing returns one listing with its bid history, and sale one recorded sale with currency, fees and shipping. Values are in US dollars. One ReefAPI key, the standard { ok, data, meta, error } envelope, no Alt account.
Which Alt number is which
Alt publishes a value and the sales behind it; they answer different questions. Field names as the API returns them, measured 2026-10-31 on the 1999 Pokémon Base Set 1st Edition Holo Charizard #4.
| field | what it is | example (PSA 9) |
|---|---|---|
| alt_value | Alt's estimated value of the card in this grade | 86,128.91 |
| alt_value_low / alt_value_high | Alt's error band around that value | 50,349.43 – 147,334.12 |
| alt_value_confidence | Alt's confidence in the value, 0-100 | 10 |
| pop | Graded population of this grade | 727 |
| last_sale | Newest sale Alt counts in this grade | 78,000.00 on 2026-10-25, Fanatics Collect |
| card_sales rows | Every recorded sale of the grade, with marketplace and link | 270 sales |
| alt_value_at_listing | The Alt Value stored on a listing when it was indexed | see listing_indexed_at |
alt_value is per grade: the same card has a different value in PSA 9, PSA 10 or CGC Pristine. On listings, alt_value_at_listing is the value stored with the listing (listing_indexed_at says when); card returns today's value. Measured: equal on 8 of 8 Alt listings indexed within the hour, different on 15 of 17 listings indexed earlier, by up to 45 %.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/altxyz/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "charizard base set 1st edition",
"grade": "PSA 10"
}
}{
"ok": true,
"meta": {
"api": "altxyz",
"endpoint": "search",
"mode": "live",
"latency_ms": 2857.6,
"record_count": 9,
"bytes": 231308,
"cache_hit": false,
"total": 9,
"page": 1,
"limit": 20,
"has_more": false,
"rows_without_id_dropped": 0,
"enriched": true,
"grade": "PSA 10",
"upstream_requests": 2,
"charged_credits": 3,
"version": "1.0.0",
"request_id": "b1604e521bfb406b",
"fetched_at": "2026-10-31T00:09:17.917Z"
},
"data": {
"rows": [
{
"card_id": "bf1dfec4-5477-4e84-936a-fb2df0232fde",
"name": "1999 Pokemon Base Set Korean 1st Edition Holo Charizard #4",
"year": 1999,
"set": "Pokemon Base Set Korean",
"number": "4",
"variety": "1st Edition Holo",
"subject": "Charizard",
"category": "pokemon",
"category_code": "POKEMON_CARDS",
"print_run": null,
"url": "https://alt.xyz/research/bf1dfec4-5477-4e84-936a-fb2df0232fde",
"pop": 201,
"external_sales_count": null,
"last_sale": {
"date": "2026-10-15",
"price_usd": 7580.4,
"marketplace": "alt",
"source": "Alt",
"grade": "PSA 9",
"grade_key": "PSA-9",
"sale_type": "AUCTION",
"listing_url": "https://alt.xyz/itm/862835ec-017c-47f2-9ada-6d7bfacef65a",
"sale_id": "cd0d7a43-15d9-468a-84ca-6b146fa59683"
},
"grades_with_sales": 12,
"in_grade": {
"grade": "PSA 10",
"grade_key": "PSA-10",
"alt_value": 91618.68,
"alt_value_low": 46479.23,
"alt_value_high": 180596.45,
"alt_value_confidence": 10,
"pop": 6,
"last_sale": {
"date": "[trimmed-depth]",
"price_usd": "[trimmed-depth]",
"marketplace": "[trimmed-depth]",
"source": "[trimmed-depth]",
"grade": "[trimmed-depth]",
"grade_key": "[trimmed-depth]",
"sale_type": "[trimmed-depth]",
"listing_url": "[trimmed-depth]",
"sale_id": "[trimmed-depth]"
}
}
},
{
"card_id": "675083d4-5580-41d4-b833-1bdcfc64f941",
"name": "2000 Pokemon Base Set Italian 1st Edition Holo Charizard #4",
"year": 2000,
"set": "Pokemon Base Set Italian",
"number": "4",
"variety": "1st Edition Holo",
"subject": "Charizard",
"category": "pokemon",
"category_code": "POKEMON_CARDS",
"print_run": null,
"url": "https://alt.xyz/research/675083d4-5580-41d4-b833-1bdcfc64f941",
"pop": 1125,
"external_sales_count": null,
"last_sale": {
"date": "2026-10-22",
"price_usd": 2104.8,
"marketplace": "alt",
"source": "Alt",
"grade": "BGS 7",
"grade_key": "BGS-7",
"sale_type": "AUCTION",
"listing_url": "https://alt.xyz/itm/749e493c-e7f5-4f0b-8a94-46a49dd6d0e4",
"sale_id": "8a574248-db4f-49c8-9f62-4318a9b0fe45"
},
"grades_with_sales": 16,
"in_grade": {
"grade": "PSA 10",
"grade_key": "PSA-10",
"alt_value": 45543.07,
"alt_value_low": 21682.09,
"alt_value_high": 95662.9,
"alt_value_confidence": 10,
"pop": 1,
"last_sale": null
}
},
{
"card_id": "bfb1a1e7-9076-4dd5-ae40-a4abe09b3eed",
"name": "1999 Pokemon Base Set Spanish 1st Edition Holo Charizard #4",
"year": 1999,
"set": "Pokemon Base Set Spanish",
"number": "4",
"variety": "1st Edition Holo",
"subject": "Charizard",
"category": "pokemon",
"category_code": "POKEMON_CARDS",
"print_run": null,
"url": "https://alt.xyz/research/bfb1a1e7-9076-4dd5-ae40-a4abe09b3eed",
"pop": 607,
"external_sales_count": null,
"last_sale": {
"date": "2026-10-25",
"price_usd": 2010,
"marketplace": "fanatics",
"source": "PWCC Weekly Auctions",
"grade": "PSA 7",
"grade_key": "PSA-7",
"sale_type": "AUCTION",
"listing_url": "https://www.fanaticscollect.com/weekly/e56fe854-c807-11f1-bd86-02fff3d6ca81",
"sale_id": "11582ba0-f246-4e85-a03e-f1ec1316f4de"
},
"grades_with_sales": 28,
"in_grade": {
"grade": "PSA 10",
"grade_key": "PSA-10",
"alt_value": 165862.28,
"alt_value_low": 111157.59,
"alt_value_high": 247489.13,
"alt_value_confidence": 20,
"pop": 7,
"last_sale": {
"date": "[trimmed-depth]",
"price_usd": "[trimmed-depth]",
"marketplace": "[trimmed-depth]",
"source": "[trimmed-depth]",
"grade": "[trimmed-depth]",
"grade_key": "[trimmed-depth]",
"sale_type": "[trimmed-depth]",
"listing_url": "[trimmed-depth]",
"sale_id": "[trimmed-depth]"
}
}
}
]
}
}What the Alt API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | 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. | Pricing teams call search to search Alt's card database (29.9 million cards) by keyword. | query, category, year_min, year_max, grade, ... |
| card | 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. | Marketplace operators call card to get one card in full by its card_id. | card_id, grade |
| card_sales | 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. | Catalog enrichment teams call card_sales to get the card's individual sales history as Alt records it. | card_id, grade, marketplace, from, to, ... |
| card_value_history | 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. | Retail analysts call card_value_history to get the daily Alt Value of one card in one grade between two dates (default. | card_id, grade, from, to |
| sales | 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. | Pricing teams call sales to get sold listings across ALL cards from the last ~90 days (Alt's sold-listings feed). | query, marketplace, category, grade, grading_company, ... |
| listings | 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. | Marketplace operators call listings to get live listings Alt indexes. | query, marketplace, listing_type, category, grade, ... |
| listing | 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. | Catalog enrichment teams call listing to get one listing by its listing_id. | listing_id |
| sale | 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. | Retail analysts call sale to get one recorded sale by its sale_id. | sale_id |
Call search from your stack
curl -X POST https://api.reefapi.com/altxyz/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"charizard base set 1st edition","grade":"PSA 10"}'import requests
r = requests.post(
"https://api.reefapi.com/altxyz/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "charizard base set 1st edition",
"grade": "PSA 10"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/altxyz/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "charizard base set 1st edition",
"grade": "PSA 10"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.altxyz.search with {"query":"charizard base set 1st edition","grade":"PSA 10"}.Who uses this API and why
- Price a Pokémon or sports card in the exact grade: search with grade=PSA 10 gives the Alt Value, population and last sale.
- Pull comparable sales: card_sales returns every sale of the grade with marketplace and link, from eBay, Goldin, Fanatics and Heritage.
- Track auction houses: sales with marketplace=goldin or fanatics returns the last 90 days of their sales across all cards.
- Watch a card's value: card_value_history gives the daily Alt Value of one grade over the last year.
- Find live auctions under value: listings with listing_type=alt_auction and the Alt Value on every row.
Questions developers ask before integrating
Does it include Goldin and Fanatics auction results?
Yes. card_sales returns each sale with its marketplace and the venue as Alt names it. Fanatics Collect covers every former PWCC venue (weekly, premier, monthly and fixed price). On the 1999 Base Set 1st Edition Charizard, 3,252 recorded sales since 2018 come from eBay, the PWCC / Fanatics venues, Goldin, Alt, Heritage, Robert Edwards, Memory Lane, Mile High and MySlabs. sales with marketplace=goldin or fanatics returns the last 90 days of those sales across all cards.
How far back does the sales history go?
card_sales with a grade returns every recorded sale of that grade back to the first one Alt has (2018 for the Base Set Charizard). Without a grade it returns the newest sales of every grade, 50 per grade by default and up to 100 with per_grade, because the full history of the most traded cards runs to tens of thousands of sales. The sales action searches across all cards and covers the last 90 days.
What are relisted and not-paid sales?
Alt keeps sales where the item came back (RELISTED) or the buyer did not pay (NOT_PAID) and shows them on its research view; they are not completed sales. They carry skipped_reason. skipped=exclude returns only the sales Alt counts, skipped=only returns just those.
Is the Alt Value a sale price?
No. alt_value is Alt's own estimate for the card in one grade, with alt_value_low, alt_value_high and a 0-100 confidence. The sales it rests on are in card_sales, and card_value_history gives the daily value of one grade for about the last year, which is how far back Alt keeps it.
Which grades are covered?
Every grade Alt records for PSA, BGS, CGC, SGC, TAG, CSG, BVG and others, including half grades, CGC and SGC Pristine 10, BGS Black Label and Authentic. Pass grade as text: PSA 10, BGS 9.5, CGC Pristine, BGS Black Label, PSA Authentic.
Which live listings are included?
Alt's own weekly auctions and fixed-price listings, plus listings Alt indexes from eBay, Fanatics Collect, Goldin, Pristine Auction and CardHobby: price or current bid, bids, watchers, end time, grade and population. listing returns one Alt listing with its full bid history, or one external listing with its current bid.
Why does a listing say price_not_published?
Some Fanatics fixed-price listings carry no public price on Alt (6 live on 2026-10-30). price_usd is null for them, and they are left out when you sort by highest price.
How do I go from a search row to the card and its sales?
Pass the row's card_id to card, card_sales or card_value_history as it is; an alt.xyz/research link works too. sales and listings rows carry card_id as well, and their sale_id and listing_id open sale and listing.
What is the Alt API?
Alt API is a ReefAPI endpoint group for alt (alt.xyz) trading card data as json: the alt value of every card in every grade, each card's individual sales from ebay, fanatics collect, goldin, heritage, alt and more, the last 90 days of sales across all cards, and live listings and alt auctions. It returns live JSON through POST requests under /altxyz/v1.
Is the Alt API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Alt calls use the same shared credit balance as every other ReefAPI engine.
Do I need an Alt login or account?
No login to Alt is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Alt data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Alt API use?
Alt actions currently cost 1-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Alt from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call altxyz actions with the same key, credit pool and JSON envelope used by normal REST requests.