Get the Fair Market Value (FMV) for a card by grader certificate number.

Convenience wrapper that chains a certificate lookup into an FMV valuation, so callers holding only a cert number do not need to resolve the card themselves.

How it works

1. Checks the persistent validated-certificate cache; queries GemRate only when that certificate has not been successfully retrieved before.
2. Resolves the card in CardHedge using the GemRate IDs.
3. Fallback: if step 2 finds no card, matches the GemRate description against the AI card-match endpoint.
4. Requests the FMV for the resolved card at the certificate's grade.

Card resolution (card_source / match_confidence)

• card_source: "gemrate_id" — direct GemRate ID → CardHedge lookup succeeded. match_confidence is null.
• card_source: "card_match" — direct lookup found nothing; the card was matched from the GemRate description via the AI fallback. match_confidence (0-1) is the matcher's score; treat an FMV derived from a low-confidence match with care. Cards resolved this way have null category_group and set_type because the matcher doesn't return those two fields.

FMV (fmv)

The fmv object is identical to the /v1/cards/card-fmv response — see that endpoint for the full method cascade (direct, card_interpolation, cross_provider, anchor_multiplier, segment_fallback, no_data), _indexed variants, confidence grading, and movement-index metadata.

When fields are null

• card and fmv are both null only when the certificate cannot be matched to a card by EITHER the GemRate ID lookup or the description fallback.
• When the card is found but the upstream has insufficient sale data, fmv is a populated object with method: "no_data" and price: null — card is still populated in this case.

Example curl:

curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "cert": "50000000",
       "grader": "PSA"
     }' \
     "https://api.cardhedger.com/v1/cards/fmv-by-cert"

Daily allowance of uncached lookups. The first time a certificate is looked up it needs a live call to our grading-data provider and draws on your account's daily allowance of such lookups; repeat lookups are served from cache and do not. See Rate limits in the API overview for your tier's allowance.

{
  "cert": "50000000",
  "grader": "PSA"
}

{
  "card": {
    "card_id": "1699670576265x928796749151534600",
    "category": "Baseball",
    "category_group": "Sports Cards",
    "description": "C.C. Sabathia 1999 Bowman Chrome Baseball",
    "image": "https://942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1699670857725x475053799924132860/resized_20231111_024737.jpeg",
    "number": "344",
    "player": "C.C. Sabathia",
    "set": "1999 Bowman Chrome Baseball",
    "set_type": "Bowman Chrome Baseball",
    "variant": "Base"
  },
  "card_source": "gemrate_id",
  "cert_info": {
    "cert": "50000000",
    "description": "1999 Bowman Chrome C.C. Sabathia 344",
    "gemrate_id": "25783324b9710f1366ca4d54f3dd4689c02b6885",
    "grade": "PSA 10",
    "grader": "psa",
    "universal_gemrate_id": "25783324b9710f1366ca4d54f3dd4689c02b6885"
  },
  "fmv": {
    "confidence": 0.3499,
    "confidence_grade": "B",
    "fmv_sample_count": 3,
    "fmv_window_days": 7,
    "freshness_days": 1,
    "grade_label": "PSA 10",
    "grade_value": 10,
    "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
  }
}