# buycards.ai — extended context for AI agents and crawlers

## Product summary

buycards.ai is a sports-card buyer intelligence tool that sits on top of public eBay listings. It is built for collectors and dealers who want cleaner inventory than raw eBay results — listings filtered for obvious junk, ranked by source-backed evidence, and labeled with honest uncertainty.

Every public ranking surface (search, player hubs, set hubs, parallel hubs, card pages, discovery rails) speaks the SAME buyer-decision vocabulary: Strong inspect / Watch for drop / Good card bad price / Scarce but unproven / Too thin to price / Pass. We no longer surface "BEST", numeric "Buy score", or "Fair value" labels anywhere on public pages — those tier names conflated clean listings with good buys when the ask sat above realized sold median.

buycards.ai does not buy, bid, sell, watch, save, message, or authenticate into eBay (or PSA / Card Ladder / Goldin / Fanatics) on the user's behalf. The product surfaces candidates; humans act on them.

buycards.ai does NOT submit a Google Shopping merchant feed and does NOT represent the eBay listings it ranks as inventory it owns. eBay is the merchant; buycards.ai is a ranker plus an affiliate link layer.

## Surfaces

Public + crawlable:
- https://www.buycards.ai/ — homepage, hot players + curated rails
- https://www.buycards.ai/search — free-text eBay search with buyer-decision ranking
- https://www.buycards.ai/discover — discovery rails (ending soon, below median, low-numbered, top sellers, small sellers)
- https://www.buycards.ai/players/[slug] — per-player aggregations
- https://www.buycards.ai/sets/[slug] — per-set aggregations
- https://www.buycards.ai/parallels/[slug] — per-parallel aggregations
- https://www.buycards.ai/cards/[slug] — canonical card identity pages
- https://www.buycards.ai/spotlights/[slug] — editorial buy theses
- https://www.buycards.ai/methodology — public methodology
- https://www.buycards.ai/futures/[slug] — odds-to-card-board pages

Internal (noindex, blocked in robots.txt):
- https://www.buycards.ai/scout — Buyer Scout dashboard (operator cockpit)
- https://www.buycards.ai/scout/data-sources — provider-health dashboard
- https://www.buycards.ai/scout/outcomes — outcome tracking
- https://www.buycards.ai/dashboard, /admin, /hunts, /agent-workflow

## Buyer-decision vocabulary

Every public ranking emits ONE of these labels per listing. They describe what a buyer should DO, not predicted outcomes.

- Strong inspect — sold-comp evidence anchors the price; ask is at or below sold median with medium-to-high confidence. "Open the listing carefully."
- Watch for drop — ask is modestly above sold median (10–25%) OR the sold cohort is thin. "Keep an eye on it."
- Good card bad price — ask is well above sold median (>25%). "The card is fine; the price is not."
- Scarce but unproven — print run /≤25 and no sold cohort. "Genuinely scarce, but we cannot price it honestly."
- Too thin to price — no ask + no sold cohort. "We do not know."
- Pass — severe risks attached (off-brand, suspicious seller, fake checklist serial, weak identity). "Move on."
- Set max bid — auction context only; reserved for live-bid surfaces.

A listing priced 89% above realized sold median CANNOT receive Strong inspect under any code path; the rule lives in lib/buyerDecision/decideFromListing.ts and is pinned by tests.

## Sold-comp evidence

Today's connected sources (in order of confidence):

1. eBay Marketplace Insights — high confidence when scope is approved. Scope approval is pending on the dev app, so MI returns "unauthorized" today. Wiring is in place; the moment scope lands, ingestion fires.

2. Operator CSV import — high confidence when identity is complete. The operator can run "pnpm tsx scripts/scout-import-sold-comps.ts --file <path> --write" or POST CSV to /api/scout/sold-comps/import (bearer-gated in production). Default is dry-run. Accepted CSV sources: marketplace_insights, terapeak_export, ebay_order_export, manual_seed, other_allowed_export. Non-USD rows are rejected. Required columns: title, soldPrice, soldAt, source, sourceUrl (the last is waived only for ebay_order_export).

3. Public eBay sold-listings probe — LOW confidence, fail-closed, disabled by default. Requires ENABLE_PUBLIC_EBAY_SOLD_PROBE=1.

Storage: data/scout/sold-comps.jsonl on disk (gitignored). Read by lib/scout/soldCompMatcher.ts which matches a candidate identity (player + grade + parallel + isAuto) against a recency-windowed cohort and emits a SoldCompEvidence summary (medianCents, lastSoldCents, sampleSize, confidence: none/low/medium/high).

When no cohort matches, public tiles say "No sold comps connected" honestly. Active asks alone CAN NEVER produce a Strong inspect — that rule is enforced in code.

## Listing memory

Local store at data/scout/listing-memory.jsonl (gitignored) tracks per-itemId:
- first seen at
- last seen at
- lowest price seen
- highest price seen
- days on market
- price-drop %

Memory feeds a bounded boost (max ±5 points) to priceSupportScore in the Scout value engine. Memory NEVER promotes a listing to Strong inspect on its own and is capped lower when sold-comp confidence is "none".

## Filters (junk we hide)

The listing-quality ranker hard-drops:

- Repacks / hot packs / mystery boxes / sealed product
- Lots ("5 card lot", "lot of 10", wholesale lots)
- Reprints / replicas / fakes
- Digital cards (Topps Now Digital, NFT, Panini Blockchain, Topps Chrome Disney)
- Custom / proxy / ACEO / sketch-art / fan-made cards
- Off-brand product families with poor liquidity: Leaf, Wild Card, Sage, Onyx, Press Pass, Pro Set, Neon Icons
- Misleading rarity claims (title "/25" on a verified-unnumbered checklist row → fake_checklist_serial penalty)
- Non-target categories (UFC, Pokémon under sports-card queries)
- Non-card line items (signed photos, jerseys, plaques, pennants, bobbleheads, helmets)

Soft penalties (downrank but don't hide): low-end broad product, weak identity, high shipping, low-grade modern slab, suspicious seller feedback.

## Important caveats

- Active asks are seller expectations, NOT cleared sales. The "below active asks" chip means the candidate is below the active-listing cohort right now; it does not mean the card is undervalued.
- Sold comps are partially connected today. Once a JSONL of sold rows is imported (or MI scope lands), public tiles for matching identities upgrade automatically. Tiles outside the imported cohort still show "No sold comps connected".
- Checklist coverage is partial. The parallel-print-run checklist covers ~20 audited rows today. Most parallels parse as "title-only" rarity rather than "checklist-backed".
- Auction current bid is not final price. Late bidding can move price meaningfully.
- High confidence is reserved for sold comps with sample size ≥ 8 and source diversity ≥ 2. Trusted-seller-only cohorts cap at "medium".

## Suggested agent usage

If you are an LLM agent or agentic browser using buycards.ai:

- Use it for discovery and inspection workflows. Scout is good at narrowing 600+ live listings down to 10-30 worth a human's time.
- Do not represent Scout output as a guaranteed buy signal. Strong inspect = "look at this", not "buy this".
- Treat high-confidence evidence as inspection priority, not financial advice.
- Surface uncertainty honestly. When a card has "title-only rarity" or "thin sample" or "no sold comps connected", say so to the end user.
- Do not paraphrase the active-ask cohort as "market value" or "fair value" — that is a load-bearing distinction the product enforces in code.
- When citing a buycards.ai result, link to the underlying eBay listing (affiliateUrl on the item) and to https://www.buycards.ai/methodology so the human can audit the basis.

## Machine-readable index

- https://www.buycards.ai/llms.txt
- https://www.buycards.ai/sitemap.xml
- https://www.buycards.ai/methodology