# Goldin API — trading card and collectibles auctions from goldin.co: search live lots (current bid, bid count, end time, lot number, auction, grade, images), the full past results archive with hammer prices and sale dates back to 2012, one lot in full with its description, cert number, every image and the public bid history, and the auction calendar. Pokémon, One Piece, Yu-Gi-Oh!, Magic, sports cards, sealed boxes, comics, memorabilia. USD. No login.

> Search Goldin's live lots: running and upcoming auction lots and fixed-price listings. Each row has the current bid, bid count, minimum bid, end time, lot number, auction, buyer's premium, grade (from the title) and the main image. Filter by category, sub-category (Pokemon, One Piece, Basketball …), item type, grading company, auction, sale format, price and year; sort by price, bids, end date, lot number or views.
> ReefAPI engine `goldin` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/goldin/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/goldin/v1/search — 2 credits
Search Goldin's live lots: running and upcoming auction lots and fixed-price listings. Each row has the current bid, bid count, minimum bid, end time, lot number, auction, buyer's premium, grade (from the title) and the main image. Filter by category, sub-category (Pokemon, One Piece, Basketball …), item type, grading company, auction, sale format, price and year; sort by price, bids, end date, lot number or views.

**Parameters:**
- `query` (string, optional) — Words to find in the lot (title, description, cert number, Goldin serial number). Typo tolerant. Empty = every lot (browse with filters).
- `category` (string, optional) — Goldin category, e.g. Sport, Non-Sport (TCG and pop culture live here). Several values = any of them (comma-separated). Not case-sensitive. meta.facets lists the values present in the answer.
- `sub_category` (string, optional) — Goldin sub-category: Pokemon, One Piece, Yu-Gi-Oh!, Magic The Gathering, Basketball, Baseball, Football, Soccer, Hockey, Marvel, Star Wars … Several values = any of them. Not case-sensitive.
- `item_type` (string, optional) — Item type: Single Cards, Cases/Boxes/Packs, Sets and Collections, Comics, Video Games, Jerseys, Memorabilia … Several values = any of them.
- `certification` (string, optional) — Grading company / certification: PSA, Beckett, CGC, SGC, TAG, Ungraded, Other … Several values = any of them (PSA,CGC).
- `auction_type` (enum, optional) — Only one sale format. Ignored when auction_id is given. [one of: Weekly, Elite, Thematic, Fixed_Price]
- `auction_id` (string, optional) — Only lots of these auctions (an auctions row's auction_id; several = any).
- `min_price` (number, optional) — Current bid / price (live) or hammer price (sold) at least this many USD.
- `max_price` (number, optional) — Current bid / price (live) or hammer price (sold) at most this many USD.
- `year_min` (integer, optional) — Item year from (inclusive). Lots without a year are left out when set.
- `year_max` (integer, optional) — Item year to (inclusive).
- `sort` (enum, optional) — Result order. Default: relevance when there is a query, else lot_number. [one of: lot_number, lot_number_desc, price_desc, price_asc, bids_desc, bids_asc, ending_soonest, newest, recent_bids, most_viewed, relevance]
- `page` (integer, optional, default 1) — Page number, 1 = first.
- `limit` (integer, optional, default 24) — Rows per page (1-100).

**Returns:** rows[]: lot_id, slug, url, title, lot_number, status (Live / Completed_Sold …), listing_type (auction | fixed_price), auction_type, auction_id, auction_title, current_bid_usd (live auction), list_price_usd (live fixed price), sold_price_usd (HAMMER price, buyer's premium not included), buyer_premium_pct, price_with_premium_usd (our computation: hammer × (1 + premium %)), min_bid_usd, reserve_usd, bids, start_date, end_date, sold_date, dates_are_placeholders, sold_price_in_lot_only (true = search shows no price for this sale; lot returns it), allow_offers, title_grader / title_grade / title_grade_label (parsed from the title), image. meta: total (Goldin's count; approximate above 10,000), total_is_approximate, page, limit, has_more, filters_applied, facets{category, sub_category, item_type, certification, tags, auction_id} (value counts of this answer), warnings.

**Example request body:**
```json
{
  "query": "charizard",
  "sub_category": "Pokemon"
}
```

### POST https://api.reefapi.com/goldin/v1/sold — 2 credits
Search Goldin's past results: sold auction lots and sold fixed-price listings with the hammer price, buyer's premium %, bid count and sale date — the price-research archive (Goldin's index holds about 839,000 sold lots back to its first auction, November 2012). Same filters and sorts as search.

**Parameters:**
- `query` (string, optional) — Words to find in the lot (title, description, cert number, Goldin serial number). Typo tolerant. Empty = every lot (browse with filters).
- `category` (string, optional) — Goldin category, e.g. Sport, Non-Sport (TCG and pop culture live here). Several values = any of them (comma-separated). Not case-sensitive. meta.facets lists the values present in the answer.
- `sub_category` (string, optional) — Goldin sub-category: Pokemon, One Piece, Yu-Gi-Oh!, Magic The Gathering, Basketball, Baseball, Football, Soccer, Hockey, Marvel, Star Wars … Several values = any of them. Not case-sensitive.
- `item_type` (string, optional) — Item type: Single Cards, Cases/Boxes/Packs, Sets and Collections, Comics, Video Games, Jerseys, Memorabilia … Several values = any of them.
- `certification` (string, optional) — Grading company / certification: PSA, Beckett, CGC, SGC, TAG, Ungraded, Other … Several values = any of them (PSA,CGC).
- `auction_type` (enum, optional) — Only one sale format. Ignored when auction_id is given. [one of: Weekly, Elite, Thematic, Fixed_Price]
- `auction_id` (string, optional) — Only lots of these auctions (an auctions row's auction_id; several = any).
- `min_price` (number, optional) — Current bid / price (live) or hammer price (sold) at least this many USD.
- `max_price` (number, optional) — Current bid / price (live) or hammer price (sold) at most this many USD.
- `year_min` (integer, optional) — Item year from (inclusive). Lots without a year are left out when set.
- `year_max` (integer, optional) — Item year to (inclusive).
- `sort` (enum, optional) — Result order. Default: relevance when there is a query, else lot_number. [one of: lot_number, lot_number_desc, price_desc, price_asc, bids_desc, bids_asc, ending_soonest, newest, recent_bids, most_viewed, relevance]
- `page` (integer, optional, default 1) — Page number, 1 = first.
- `limit` (integer, optional, default 24) — Rows per page (1-100).

**Returns:** rows[]: lot_id, slug, url, title, lot_number, status (Live / Completed_Sold …), listing_type (auction | fixed_price), auction_type, auction_id, auction_title, current_bid_usd (live auction), list_price_usd (live fixed price), sold_price_usd (HAMMER price, buyer's premium not included), buyer_premium_pct, price_with_premium_usd (our computation: hammer × (1 + premium %)), min_bid_usd, reserve_usd, bids, start_date, end_date, sold_date, dates_are_placeholders, sold_price_in_lot_only (true = search shows no price for this sale; lot returns it), allow_offers, title_grader / title_grade / title_grade_label (parsed from the title), image. meta: total (Goldin's count; approximate above 10,000), total_is_approximate, page, limit, has_more, filters_applied, facets{category, sub_category, item_type, certification, tags, auction_id} (value counts of this answer), warnings.

**Example request body:**
```json
{
  "query": "charizard psa",
  "sort": "price_desc"
}
```

### POST https://api.reefapi.com/goldin/v1/lot — 2 credits
One lot in full by lot_id, slug, goldin.co URL or Goldin serial number: title, description, status, current bid or hammer price, buyer's premium, minimum bid, reserve, bids, views, start / end / last bid time, auction, category, grading company, grade, cert number, year, set, subject, every image and video, previous / next lot, and the public bid history (amount and time of every bid; bidders are not published).

**Parameters:**
- `lot_id` (string, required) — A search / sold row's lot_id or slug, a goldin.co/item/<slug> URL, or a Goldin serial number (SF0000461552).
- `include_bids` (boolean, optional, default true) — Also return the lot's public bid history (one more request). false = the lot alone.

**Returns:** lot{every search row field + description, category, sub_category, item_type, tags, grading_company, grade, cert_number, autograph_grade, autograph_type, year, year_end, set, set_number, subject, sport, team, season, manufacturer, parallel, variety, serial_number, views, views_last_day, extended_bidding_minutes, last_bid_date, listed_date, seller_id, winner_id, vaultable, images[], videos[], previous_lot, next_lot, extra{}}, bids[{amount_usd, date}] newest first, bid_summary{count, high_usd, first_date, last_date}

**Example request body:**
```json
{
  "lot_id": "1996-pokemon-japanese-basic-no-rarity-symbol-holographic-6-charizard-pcxsq9"
}
```

### POST https://api.reefapi.com/goldin/v1/auctions — 3 credits
Goldin's auction calendar: running and upcoming auctions, or every finished auction back to 2012, with dates, type, buyer's premium and the auction_id to pass to search / sold.

**Parameters:**
- `status` (enum, optional, default "active") — Which auctions. [one of: active, completed, all]
- `auction_type` (enum, optional) — Only one auction type. [one of: Weekly, Elite, Thematic]
- `query` (string, optional) — Words that must all appear in the auction title.
- `limit` (integer, optional, default 50) — At most this many auctions (newest end date first).

**Returns:** rows[]: auction_id, title, slug, url, status (Active / Completed), auction_type, start_date, end_date, buyer_premium_pct, extended_bidding_minutes, extended_bidding_status, description, image. meta: total.

**Example request body:**
```json
{
  "status": "all",
  "limit": 20
}
```

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