CAcardhedger
Pricing & Valuations

Get Fair Market Value (FMV) for a Card

Get the Fair Market Value (FMV) for a card at a specific grade.

Requires a card_id. If you only have a card name/description, call match-card or card-search first to resolve it.

What FMV is

FMV is CardHedge's smoothed valuation for a card at a specific grade, computed by an underlying pricing service that:

  1. Looks for a direct price for this card+grade, and if found, replaces the raw latest_price with a Winsorized-median FMV computed over a 7/15/30/90-day window (the shortest window with enough daily prints wins). Winsorizing trims outlier sales so a single hot/cold day doesn't move the value.
  2. If no direct price exists, falls back through a cascade of related data: other grades of the same card → other graders → grade multipliers → segment baselines.
  3. If the chosen base price is stale, overlays a movement index to project it to today. The index is picked from the most specific level with enough sample density (card+grade → card → player → segment).
  4. Returns the price, a confidence score, and full metadata so callers can decide how much to trust the result.

Compared to price-estimate, the FMV response includes the smoothing window, sample counts, confidence grade, and a human-readable price_explanation.

FMV calculation methods (the method field)

The method field tells you which cascade step produced the price. There are 6 base methods plus an _indexed variant of each non-terminal method (10 indexed + 1 terminal = 11 possible values).

Base methods, in cascade priority:

MethodMeaning
directExact card+grade lookup. The 7/15/30/90-day Winsorized-median FMV is used when enough daily prints exist; otherwise raw latest_price is returned. See fmv_window_days / fmv_sample_count.
card_interpolationNo direct price; isotonic regression in log-space across the card's OTHER same-provider grades, interpolated/extrapolated to the target grade. Requires 2+ supporting grades.
cross_providerNo same-provider data; translates from another grader (e.g., BGS 9 → PSA 9) using a learned price ratio.
anchor_multiplierOne same-provider grade is the anchor; a within-provider grade multiplier projects it to the target. Variants: same-provider, chained (e.g., BGS 8.5 → BGS 9 → PSA 9), raw (Raw → graded).
segment_fallbackLast resort: uses the (set × year × category) segment baseline price and applies a grade multiplier. Lowest confidence — no card-specific data was used.
no_dataTerminal: nothing in the cascade produced a usable price. price and the range bounds are null.

_indexed variants — direct_indexed, card_interpolation_indexed, cross_provider_indexed, anchor_multiplier_indexed, segment_fallback_indexed. The base method produced a stale price (older than the freshness threshold), so a movement index was overlaid to bring it to today. The index is chosen from a cascade of entities:

  • index_level: "card_grade" — most specific: this card at this grade
  • index_level: "card" — blended across all grades of this card
  • index_level: "player" — player-level (all this player's cards)
  • index_level: "segment" — (year × category) segment-level
  • index_level: "none" — stale, but no index met the minimum sample threshold (an un_indexed_penalty was applied to confidence)
  • index_level: null — fresh estimate, no adjustment was needed

Examine raw_price (pre-adjustment) vs price (post-adjustment) and index_pct_change to see exactly what the index changed. Filter low-signal adjustments by requiring index_sample_count >= 10.

Picking a method by use case

  • Pricing UI for end users — Trust confidence_grade A/B; show price_explanation on a "How was this calculated?" tooltip. Hide or caveat C/D and no_data.
  • Portfolio valuation — Use price directly; band it with price_low / price_high for uncertainty visualization.
  • Sensitive financial decisions — On C-grade or any _indexed method, also show raw_price so the user can see what the movement index changed.
  • Bulk analytics — Aggregate by method to see what % of cards have direct data vs are interpolated vs fall back to segments.

Response field reference

See the response schema (CardFMVResponse) for the full field-by-field description. Highlights:

  • price / price_low / price_high — FMV and uncertainty band in USD.
  • confidence (0-1) and bucketed confidence_grade (A/B/C/D) — single trust score folding in method, FMV quality, and index quality.
  • raw_price — pre-adjustment price. Differs from price when a movement index was applied (_indexed), or shows the FMV value for direct when latest_price was replaced.
  • fmv_window_days / fmv_sample_count — FMV smoothing window (7/15/30/90) and sample density.
  • index_level / index_pct_change / index_sample_count / index_truncated / as_of_date — movement-index provenance.
  • cross_grade_fmv_count — for cross-grade methods, how many source grades had their latest_price FMV-substituted before the cascade ran.
  • price_explanation — plain-English derivation (debug/audit only).

Any additional fields the upstream returns are passed through unchanged.

Example curl:

curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "card_id": "1586812246197x228181943611293700",
       "grade": "PSA 9"
     }' \
     "https://api.cardhedger.com/v1/cards/card-fmv"
post/v1/cards/card-fmv

Request

  • Base URL
    https://api.cardhedger.com
  • Auth
    API key in header X-API-Key

Request body

card_idstring required

Unique CardHedge card identifier. If you only have a card name or description, call match-card or card-search first to resolve it.

gradestring required

Card grade label. Supported formats: '<Provider> <Grade>' (e.g., 'PSA 9', 'PSA 10', 'BGS 9.5', 'SGC 9', 'CGC 10'), 'Raw' for ungraded, or '<Provider> Auth' for authenticated-only.

Response

Successful Response

pricenumber nullable

Fair market value in USD (null when no data available)

price_lownumber nullable

Lower bound of the FMV range (null when no data available)

price_highnumber nullable

Upper bound of the FMV range (null when no data available)

confidencenumber nullable

Confidence score (0-1) for the FMV calculation

methodstring nullable

FMV calculation method. One of 11 values from the cascade:

Base methods (in priority order):

  • direct — Exact card+grade lookup. Latest_price is replaced with a Winsorized-median FMV over a 7/15/30/90-day window when enough daily prints exist; otherwise latest_price is used as-is.
  • card_interpolation — No direct price; isotonic regression in log-space across the card's OTHER same-provider grades, then interpolating/extrapolating to the target grade.
  • cross_provider — No same-provider data; translates from another grader (e.g., BGS 9 → PSA 9) using a learned price ratio.
  • anchor_multiplier — Uses one same-provider grade as an anchor and applies a within-provider grade multiplier. Variants include same-provider, chained (e.g., BGS 8.5 → BGS 9 → PSA 9), and raw (Raw card price → graded). See anchor_from_raw / anchor_chained_from_provider.
  • segment_fallback — Last resort: uses the set/year × category baseline price and applies a grade multiplier.
  • no_data — No sale data could produce a value; price is null.

_indexed variants (direct_indexed, card_interpolation_indexed, cross_provider_indexed, anchor_multiplier_indexed, segment_fallback_indexed) — the base method produced a stale price, so a movement index was overlaid to bring it to today. See index_level, index_pct_change, and raw_price for the adjustment details.

freshness_daysinteger nullable

Age of the underlying sale data in days (0 = today). On _indexed methods this reflects the index's as_of_date, not the base price's age. Null on segment_fallback and no_data.

support_gradesinteger nullable

Number of grade data points contributing to the estimate. 1 for direct; 2+ for card_interpolation (other grades of this card); 1 for anchor_multiplier; 0 for segment_fallback / no_data.

grade_labelstring nullable

Normalized grade label the FMV was computed for (e.g., 'PSA 9', 'BGS 9.5', 'Raw').

providerstring nullable

Grading provider (e.g., 'PSA', 'BGS', 'SGC', 'CGC', 'Raw').

grade_valuenumber nullable

Numeric grade value (e.g., 9.0, 9.5, 10.0). 0 for Raw; negative values denote authenticated-only grades (e.g., 'PSA Auth').

as_of_datestring nullable

ISO 8601 date the applied movement index was last computed. Set only on _indexed methods; null otherwise.

index_levelstring nullable

Cascade level used for movement adjustment. One of:

  • card_grade — most specific: this card at this grade
  • card — blended across all grades of this card
  • player — player-level index (all cards of this player)
  • segment — (year × category) segment-level index
  • none — stale price, but no index met the minimum sample threshold (an un_indexed_penalty is applied to confidence)
  • null — fresh estimate, no movement adjustment needed
index_pct_changenumber nullable

Cumulative percent change applied by the movement index over the FMV's lookback window (decimal, e.g., 0.157 = +15.7%). Set only on _indexed methods.

raw_pricenumber nullable

Pre-adjustment price in USD. For direct: the chosen FMV value (or the original latest_price when no FMV qualified). For other cascade methods: the original method result before any movement adjustment. Compare price vs raw_price to see what the movement index changed.

index_truncatedboolean nullable

True if the FMV's lookback window was capped at the maximum (730 days) because the underlying price was extremely stale. Treat truncated movement adjustments as lower-confidence.

fmv_window_daysinteger nullable

FMV smoothing window used for the base price. One of 7, 15, 30, or 90 — the upstream picks the shortest window with enough samples. Null when no FMV smoothing was applied (the lookup fell back to card_grade_prices.latest_price, or the method is not direct).

fmv_sample_countinteger nullable

Number of distinct daily prints that fed the chosen FMV's Winsorized median. Higher = more reliable. Null when no FMV was applied.

base_sample_countinteger nullable

Number of sales behind the base latest_price (90-day sale count on the source grade row). Only set on direct lookups that did NOT substitute a Winsorized-median FMV — where fmv_sample_count is present it describes the FMV instead. Use to tell a well-backed latest_price from a single-sale print; null means the source reported no sale count.

index_sample_countinteger nullable

Number of observations at the chosen movement-index window. Useful for filtering low-signal adjustments — e.g., ignore index_pct_change when index_sample_count < 10.

confidence_gradestring nullable

Bucketed confidence grade — a quick proxy for the numeric confidence:

  • A — confidence ≥ 0.42 (~86% of prices within 2× of the actual sale). Trust for valuations.
  • B — confidence ≥ 0.25 (~74% within 2×). Usable; consider showing raw_price too.
  • C — confidence ≥ 0.10 (~63% within 2×). Borderline; consider falling back to latest_price for sensitive decisions.
  • D — confidence < 0.10 (~49% within 2×). Likely noisy; show with disclaimer.

Cutoffs are calibrated to measured accuracy on held-out sales and may be re-tuned as the model improves — rely on the letter grade rather than hard-coding numeric thresholds.

Null on no_data. The numeric confidence already folds in cascade method, FMV signal strength, and movement-index quality, so this single grade reflects total trust in the returned price.

price_explanationstring nullable

Human-readable description of how the FMV was derived — e.g., 'Used 7d FMV ($416.25, Winsorized median of 3 daily prints) in place of latest_price $416.25. Fresh (1d) — no movement adjustment applied.' Useful for debug UIs and audit trails; not intended for programmatic parsing (wording may change).

cross_grade_fmv_countinteger nullable

For cross-grade methods (card_interpolation, cross_provider, anchor_multiplier): count of source grades whose latest_price was replaced with a Winsorized-median FMV before the cascade ran. Higher = more smoothing applied. Null when the method wasn't used; 0 when used but no FMV qualified for any source.

Example response

{
  "confidence": 0.3499,
  "confidence_grade": "B",
  "fmv_sample_count": 3,
  "fmv_window_days": 7,
  "freshness_days": 1,
  "grade_label": "PSA 9",
  "grade_value": 9,
  "index_truncated": false,
  "method": "direct",
  "price": 416.25,
  "price_explanation": "Used 7d FMV ($416.25, Winsorized median of 3 daily prints) in place of latest_price $416.25. Fresh (1d) — no movement adjustment applied.",
  "price_high": 435.24,
  "price_low": 397.26,
  "provider": "PSA",
  "raw_price": 416.25,
  "support_grades": 1
}

Changes

No recorded changes to this operation across all 14 revisions of this API.