Quant Regime Probabilities: Short-Horizon Market States via API

Why a Single Regime Label Lies at the Boundary

Most regime tools hand your bot one word — trending, ranging, volatile — and throw away the uncertainty behind it. That's fine deep inside a regime. It's dangerous at the edges, which is exactly where regimes change and where most bad trades happen.

"Range" at 95% conviction and "range" at 38% (a near coin-flip with "squeeze") are completely different risk states, but a single label paints them identically. Quant regime probabilities fix that: instead of a label, you get a calibrated probability across six market states, refreshed every hour, at short 4h and 24h horizons. Your agent can size to its conviction, not to a hard-coded guess.

This is a Hidden Markov Model (HMM) trained on six years of hourly data, served at /api/v1/quant/market — a probabilistic layer that sits on top of the rule-based 14-basket regime taxonomy.

The Six Market Regimes and What Each Means for Positioning

The engine maps the market to one of six canonical states. Each carries a default trading stance — the reason the regime matters at all.

The full taxonomy — ids, labels and stances — is machine-readable at /api/v1/quant/regimes, so an agent can self-describe the contract before it ever places a trade.

What Regime Is the Market in Right Now?

One call answers it. /api/v1/quant/market returns the current market-wide regime, its calibrated confidence, and how many candles it has persisted.

curl -H "X-API-Key: cdk_live_your_key" \
  "https://cryptodataapi.com/api/v1/quant/market?horizon=24h"

{
  "scope": "market",
  "horizon": "24h",
  "regime": {
    "label": "range_low_vol",
    "name": "Range / Low Volatility",
    "id": 2,
    "confidence": 0.9828,
    "candles_in_regime": 20
  },
  "probabilities": {
    "regime_transitions": {
      "stays_same": 0.7326,
      "to_vol_spike": 0.1042,
      "to_strong_trend_bull": 0.0958,
      "to_squeeze": 0.0674
    }
  }
}

Read it as a sentence: the market is in low-volatility range with 98% confidence; over the next 24h there's a 73% chance it stays, but a non-trivial 10% drift toward a volatility spike. That forward regime_transitions distribution is the part a binary label can never give you.

Short-Horizon by Design: 4h and 24h, Refreshed Hourly

This is a short-horizon engine. It is not trying to call the next bull cycle — it answers "what is the tradeable regime over the next few hours to a day?" Pass ?horizon=4h for scalping and intraday risk, or ?horizon=24h for swing positioning.

• Calibrated confidence. confidence is isotonic-calibrated against out-of-sample agreement, so 0.80 actually means ~80% reliable — not a raw softmax number.
• Anti-flap hysteresis. The headline label only switches after a challenger holds for two closed bars (or clears an override threshold on a genuine spike), so your bot isn't whipsawed by one noisy candle.
• Hourly cadence. Inference runs every 15 minutes on closed hourly bars; candles_in_regime tells you how mature the current state is.

Persisted history is queryable at /api/v1/quant/history so you can backtest how the probabilities evolved, not just read the latest snapshot.

Per-Coin Regimes for the Whole Perp Universe

The market regime is the backdrop; each coin gets its own. /api/v1/quant/coins/{symbol} returns a single coin's probabilistic regime, conditioned on the prevailing market state.

curl -H "X-API-Key: cdk_live_your_key" \
  "https://cryptodataapi.com/api/v1/quant/coins/BTC?horizon=24h"

Or pull the entire universe in one shot with /api/v1/quant/coins — ~170 active perps, each with its regime, confidence and directional lean. A simple agent loop:

import httpx
h = {"X-API-Key": "cdk_live_your_key"}
coins = httpx.get(
    "https://cryptodataapi.com/api/v1/quant/coins?horizon=24h", headers=h
).json()["coins"]

# only act on high-conviction squeezes priming for a breakout
primed = [c for c in coins
          if c["regime"]["label"] == "squeeze"
          and c["regime"]["confidence"] > 0.7]

Every coin object carries the same shape as the market object, so one parser handles both scopes.

Probabilities vs Binary Labels

Why a probability vector beats a single classification — the difference an LLM or rules engine can act on directly:

• Binary label: regime = "range". No way to tell a rock-solid range from a 38/35 toss-up with squeeze. Position size is a guess.
• Probability + confidence: range_low_vol @ 0.98 vs range_low_vol @ 0.41. Gate trades on a confidence floor; scale size linearly with conviction.
• Forward transitions: a 10% drift to vol_spike is a pre-emptive de-risk signal a label simply doesn't contain.
• Calibration: because confidence is calibrated, 0.7 means the same thing in a bull market and a bear — thresholds are portable.

Rule of thumb: use the label for display, use the probabilities for decisions.

How AI Agents Should Use Regime Probabilities

Three patterns cover most agent workflows:

• Confidence-gated execution. Only trade a setup when the regime confidence clears a floor (e.g. 0.65). Below that, the market is at a boundary — stand down or halve size.
• Regime-conditioned strategy selection. Map each regime to a stance (see the table above): mean-reversion in range_low_vol, trend-following in strong_trend_bull, flat in vol_spike.
• Pre-emptive de-risking. Watch regime_transitions; when the probability of moving to vol_spike or strong_trend_bear rises, cut leverage before the move, not after.

Start with the live model card at /api/v1/quant/model (version, training window, drift status) so your agent trusts the source, then poll /api/v1/quant/market hourly. Pair it with the rule-based regime taxonomy for the slower structural backdrop — the two answer the same question on different clocks.