Look up a single graded card by its PSA cert number.

Returns card metadata (year, brand, set, card number, subject, variety), grade (label + numeric), and population data (count at this grade, count graded higher) when PSA exposes them.

Fetch front/back image URLs for a PSA graded card.

NOTE: PSA only attaches images to cards graded after October 2021 — older slabs return an empty list with no error.

Look up a PSA cert AND record it in your local collection in one step.

Workflow tool — combines tcg_psa_get_cert with tcg_collection_add_card. Looks up the cert at PSA, normalizes the response, and writes a row into the local SQLite DB with your cost basis. Returns the new card_id.

If you've already added this exact cert, returns an error rather than duplicating — use tcg_collection_update to change cost basis.

CGC cert lookup — stubbed. CGC has no official public API.

Returns a clear "not supported" error. Implementation deferred.

BGS cert lookup — stubbed. Beckett has no official public API.

Returns a clear "not supported" error. Implementation deferred.

Record a card as owned in the local SQLite DB.

Returns the new card_id (a UUID) on success.

List cards in the local collection, with optional filters and pagination.

Fetch a single owned card by its card_id.

Update mutable fields on a collection card (cost basis, notes, status, ...).

Remove a card. Default is a soft-delete: status -> 'sold' and the row stays.

Pair with sold_price + sold_date to capture the disposition.

Cost-basis summary across the collection.

Returns counts (owned / graded / raw / sold) and total cost basis. For live market valuation that joins against pricing snapshots, see tcg_collection_value_with_market.

Record sealed product as owned.

Behind the scenes, sealed product lives in the same owned_cards table as singles, distinguished by product_type != 'single'. We insert one row per quantity unit so cost basis and disposition track per-unit.

Returns a list of new card_ids (one per unit).

Map an owned card to a pricing listing for live valuation.

After attaching, tcg_pricing_snapshot calls (using the same listing_id) will let tcg_collection_value_with_market compute live market value for this card.

Cost basis + live market value across the collection.

For each owned card with an attached pricing listing, we look up the most recent pricing snapshot (matching the card's grade for graded cards). Cards without an attachment or without a snapshot land in unpriced_count so you know what's missing.

Run tcg_pricing_snapshot periodically to keep the join fresh.

Add a card to the watchlist with a target buy price + thesis.

Returns the new watchlist_id.

List watchlist entries with optional horizon filter.

Fetch a single watchlist entry by id.

Update mutable fields on a watchlist entry.

Mark a watchlist entry closed (bought / thesis_invalidated / manual).

Capture today's PSA pop data for the spec backing this cert.

Looks up the cert via PSA, extracts (SpecID, grade, total_at_grade, population_higher), and inserts a row into pop_snapshots. Repeat over time and tcg_psa_pop_trend will surface the trajectory.

Return the time series of pop snapshots we've captured for a card spec.

Useful for answering "Has PSA 10 pop for this card grown a lot?" — but only works for specs you've snapshotted via tcg_psa_snapshot_pop.

Search a pricing provider for matching products.

Returns a list of CardListing rows. Use tcg_pricing_get afterward with one of the listing_ids to fetch full price data.

Fetch the full PriceQuote for one listing on the chosen provider.

Returns top-level market/low/high (USD or EUR depending on provider), a variants map (Pokemon TCG API), and a graded_levels list (PriceCharting). The full provider payload lives in raw.

Fetch a price quote and write it as a row in the pricing_snapshots table.

For graded providers (PriceCharting), every graded_level becomes its own snapshot row (so you can later track PSA 10 vs PSA 9 separately). The raw provider payload is stored on the FIRST row only to avoid bloat.

Walk the collection and snapshot every owned card with an attached pricing listing, respecting per-provider rate limits.

Skips cards whose most recent snapshot is younger than max_age_hours so repeated calls don't burn API quota redundantly. One card failing does not abort the rest — failures are reported per-card.

Returns a summary with counts (snapshotted / skipped_recent / failed) and a per-provider breakdown.

Return the time series of pricing snapshots saved for one listing.

Useful for answering "is PSA 10 trending up?" or "what was Charizard ex SIR worth a month ago?" — but only works for listings you've snapshotted via tcg_pricing_snapshot or tcg_pricing_snapshot_collection.

Returned snapshots are oldest-first.

Fetch a Pokemon TCG set's metadata (name, total cards, release date, …).

Free — no API key required (Pokemon TCG API).

Search Pokemon TCG sets. Returns set IDs, names, release dates, totals.

List every card in a set (optionally filtered by rarity), with TCGPlayer market price where available. Useful for set-completion analysis and rarity-tier breakdowns.

Compute set-completion progress for a Pokemon TCG set.

For each card in the set (optionally filtered by rarity):

• Owned? Match owned_cards either by attached pricing_listing_id equal to the catalog card's id (precise), or as a fallback by case-insensitive subject match + card_number exact match.

• Watchlist hit? Cross-reference watchlist.card_descriptor for substring matches against the card name + set name.

• Missing? Sum current Pokemon TCG API market price for the gap.

Returns owned/missing counts, completion percentage, gap cost in USD, and per-card breakdown.

Search owned cards across subject, set_name, brand, variety, notes, and tags — richer than tcg_collection_list's subject-only filter.

Smart-routed price lookup. One call, the right provider(s) under the hood.

Strategy:

• Always queries Pokemon TCG API (free) — gives raw/ungraded market.

• If grade is provided AND PriceCharting is enabled (token set), ALSO queries PriceCharting for the graded price level.

• prefer_provider overrides routing entirely.

Designed so an agent can ask "what's Charizard ex Surging Sparks worth" without knowing which provider to call first.

Show which grading / pricing providers are enabled in this process.

Useful as a first call when introspecting the server's capabilities.