The Quant Model Card: Provenance & Walk-Forward Validation API

Would You Let a Black Box Size Your Trades?

Every other quant endpoint hands your agent a regime label and a probability. The obvious question — the one a careful trader asks before wiring anything to capital — is "says who?" What is the model, when was it trained, how did it validate, and is it still behaving?

The /api/v1/quant/model endpoint answers all of that. It's a full model card plus live runtime health, and unlike the data endpoints it works with any valid key — transparency shouldn't be paywalled.

What's on the Model Card

The card describes the model and its provenance:

Nothing about the engine is hidden — you can read its feature list and its hash before you trust a single call.

Can I Trust This Model?

The honest answer is in validation. The metrics are walk-forward — measured on data the model didn't see during fitting, fold by fold — not in-sample numbers that always look good. Combined with sha256 you get a reproducible chain:

• The sha256 pins the exact artifact serving live.
• validation tells you how that artifact scored out-of-sample.
• feature_version matches the features documented for that version — no silent schema drift.
• approval records the human sign-off on the deploy.

You're not taking the label on faith; you're taking it with its receipts.

Pulling the Model Card

curl -H "X-API-Key: cdk_live_your_key" \
  "https://cryptodataapi.com/api/v1/quant/model"

{
  "loaded": true,
  "model_version": "fv2", "model_family": "hmm",
  "feature_version": "fv2",
  "n_states": {"market": 9, "coin": 6},
  "sha256": "3f9c...a1", "last_retrain": "2026-06-21",
  "validation": {"folds": 6, "mean_balanced_accuracy": 0.58},
  "runtime": {"warmed_up": 172, "universe": 187, "drift": "nominal"}
}

If loaded is false, the data endpoints are returning 503 — no model deployed yet, or stub plumbing only.

Live Runtime Health and Drift

A model that validated well can still go stale. The runtime block reports live health:

• Universe coverage — how many coins are warmed_up vs the full universe (low right after a deploy, then climbs).
• Drift monitor — current feature distribution vs the training baseline, so you're warned when live data wanders from what the model learned.
• loaded — the master switch; gate everything on it.

Coverage warms over ~45–60 minutes after each deploy — expected, not a fault.

How Often Does It Retrain, and What Changes?

last_retrain and created_at tell you how fresh the model is, and model_version tells you which model you're reading. When the feature set changes, feature_version bumps (e.g. fv1 → fv2) and the features list changes with it.

• Version your logic. If you depend on a specific feature, assert feature_version before trusting downstream fields.
• Watch the hash. A changed sha256 with the same version means a re-fit on fresh data — same contract, new parameters.
• Re-read the card on a schedule. Cache it, but refresh daily so a silent retrain doesn't surprise your agent.

The model card is the contract; treat a version bump as a release note.

How AI Agents Use the Model Card

import httpx
m = httpx.get("https://cryptodataapi.com/api/v1/quant/model",
              headers={"X-API-Key": "cdk_live_your_key"}).json()

ok = (m.get("loaded")
      and m["runtime"].get("drift") == "nominal"
      and m["runtime"]["warmed_up"] / m["runtime"]["universe"] > 0.8)
if not ok:
    use_quant_signals = False   # don't trade a cold or drifting model

• Startup gate: refuse to trade quant signals unless loaded is true.
• Drift kill-switch: de-risk when the drift monitor leaves nominal.
• Version pinning: log sha256 + model_version with every decision for auditability.

It's the endpoint that makes the rest safe to automate.