How to Read Model Predictions
Every row of data includes forecast fields from two model families. None of them call price direction - they measure risk and volatility. Here's what each one actually means, with worked examples. See published accuracy for how reliable each one is.
The Four Horsemen - per-bar risk & volatility classifiers
Each outputs a confidence field, a probability from 0.0 to 1.0 that a specific condition is true for the next single candle. Values near 1.0 mean high confidence "yes", near 0.0 mean high confidence "no", and near 0.5 mean a coin-flip - treat it as no edge.
tail_risk_conf
Predicts: probability the next candle's move is larger than the 90th-percentile absolute move of the prior 20 candles. Direction is not part of the call - it could be up or down.
Low (≤0.1): expect a normal-sized move. Near 0.5: weak signal, low trust.
high_vol_conf
Predicts: probability the next candle's 20-bar rolling volatility sits above its 50-bar median - i.e. a choppier-than-usual bar. This is the Regime State signal.
Low (≤0.1): expect a calmer-than-usual bar relative to the benchmark.
regime_change_conf
Predicts: probability the next candle is the first high-vol bar after a calm stretch - a low-to-high volatility transition, not an ongoing high-vol state.
Low (≤0.1): strong belief the calm stretch continues.
regime_emergence_conf
Predicts: probability that short-horizon (10-bar) volatility is about to spike above its 30-bar median - an earlier, faster-twitch cousin of regime change.
Reads the same scale as the others: near 1.0 is high confidence, near 0.0 is low confidence, near 0.5 is weak.
Core Alpha - volatility magnitude models
A separate model family that forecasts how much the market is likely to move, not a yes/no regime call and not a direction call.
future_vol
Predicts: expected volatility (as a decimal, e.g. 0.018 ≈ 1.8% typical move) over the next few bars. A single continuous number, not a probability.
| Value | Interpretation |
|---|---|
| 0.005-0.010 | Low vol - calm, range-bound |
| 0.010-0.020 | Normal vol - typical daily moves |
| 0.020-0.040 | Elevated vol - active, news-sensitive |
| 0.040+ | High vol - large gaps, macro events |
Example: future_vol: 0.032 with recent realized vol of 0.018 → sharp moves (~3.2%/day) are expected; often paired with a widening stop-loss, not a long/short call.
expansion_probability
Predicts: probability (0.0-1.0) that volatility expands beyond its 20-day realized baseline. Distinct from high_vol_conf above - this is its own model and its own window.
| Probability | Interpretation |
|---|---|
| 0.0-0.25 | Very unlikely to expand |
| 0.25-0.50 | Slight contraction bias |
| 0.50-0.75 | Slight expansion bias |
| 0.75-1.0 | Very likely to expand |
Example: expansion_probability: 0.87 alongside already-elevated realized vol → high chance of a further volatility breakout.
None of these fields predict price direction. They describe risk and volatility regime only - pair them with your own directional thesis or entry signal before sizing a trade. Full field-by-field accuracy is published on the methodology page.
API Documentation
Interactive OpenAPI Specification for all data endpoints.
Intelligence API
Sector-relative analysis built on top of the raw candle data - which sectors are leading or lagging the broader market, and which specific assets inside a hot or cold sector are actually driving that move.
Restricted to Pro and AI plans. Requests from a Free-plan key to either endpoint below return 403 with { "error": "Intelligence Access Restricted", "message": "Access to intelligence endpoints is restricted to Pro and AI plans." }.
/v1/intelligence/sectors
List Sectors & Their Assets
Returns the sector taxonomy used by sectorPerformance below - which tickers are grouped into which sector (Market, AI, DeFi, L1, RWA). Use it to know what to expect back from sectorPerformance, or to build your own sector-relative views.
{
"message": "Current sectors and their assets.",
"data": {
"Market": ["BTC-USD"],
"AI": ["TAO-USD", "ICP-USD", "NEAR-USD"],
"DeFi": ["UNI-USD", "HYPE-USD", "AAVE-USD", "..."],
"L1": ["ETH-USD", "SOL-USD", "ADA-USD", "..."],
"RWA": ["AVAX-USD", "PAXG-USD", "..."]
}
}/v1/intelligence/sectorPerformance
Sector & Asset Relative Performance
For every sector, computes the sector's average 7-day and 1-day performance, then ranks each asset against it. Assets within a sector are returned sorted by perf_7Day descending - leader first, laggard last.
{
"message": "Sector performance data.",
"data": {
"DeFi": {
"sector_7DayAvg": 5.4,
"sector_1DayAvg": 0.8,
"assets": [
{
"asset": "UNI-USD",
"perf_7Day": 8.5,
"perf_1Day": 1.2,
"market_regime_score": 81,
"sector_delta_7Day": 3.1,
"market_delta_7Day": 5.29
}
]
}
}
}Field Reference
| Field | Meaning |
|---|---|
| perf_7Day | % price change over the last 7 days, measured against the latest hourly close. |
| perf_1Day | % price change since the most recently closed daily candle - the move so far "today". |
| sector_delta_7Day / 1Day | This asset's performance minus its own sector's average. Positive = outperforming its sector peers (a sector leader); negative = a laggard. |
| market_delta_7Day / 1Day | This asset's performance minus the Market sector's (BTC-USD) performance - how much it's beating or lagging Bitcoin specifically. Omitted for assets already inside the Market sector, since that would just be zero. |
| market_regime_score | The same 0-100 ML regime score documented above, from that asset's latest daily candle. |
WebSockets
A persistent, real-time push feed of new candles as they're produced - across all 50 tracked tickers, hourly and daily - instead of polling /hourly or /daily on a timer.
Restricted to Pro and AI plans - this is a separate, stricter restriction than the REST endpoints (where Free plan still gets limited access). A Free-plan key is rejected immediately on connect with { "error": "Free plan does not have access to WebSocket connections." }.
1. Connect & Authenticate
Open a WebSocket connection, then send your API key as token in the very first message. You can combine authentication and channel subscription into that same first message, or send channels as a follow-up message afterward - both work.
wss://api.defitheodds.xyz/ws
const ws = new WebSocket('wss://api.defitheodds.xyz/ws');
ws.onopen = () => {
ws.send(JSON.stringify({
token: 'dfo_your_api_key_here',
channels: ['hourly', 'high_confidence_hourly'],
tickers: ['BTC-USD', 'ETH-USD'], // optional - omit for all 50 tickers
}));
};
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
console.log(msg);
};
ws.onclose = () => {
// No built-in auto-reconnect - implement your own
// reconnect-with-backoff and re-authenticate/re-subscribe here.
};
2. Channels & Ticker Filtering
Subscribe to one or more channels. By default a subscribed channel delivers events for all 50 tracked tickers - pass an optional tickers array in the same message to narrow it down, e.g. tickers: ['BTC-USD', 'ETH-USD']. The filter applies to every channel named in that message. Each subscribe message sets the filter for its channels fresh - if you send a later message for the same channel without tickers, it reverts to unfiltered. Send separate messages if you want different filters on different channels.
| Channel | Fires on |
|---|---|
| hourly | Every new hourly candle, for any tracked ticker - the raw enriched row, same shape as GET /hourly. |
| daily | Every new daily candle, for any tracked ticker - same shape as GET /daily. |
| high_confidence_hourly | The same event as hourly, with one field added: msg - a plain-English read of that candle's Four Horsemen signal state. Fires on every hourly candle, not only when a signal crosses a high-confidence threshold; msg ranges from a "Baseline - no strong signal" message up to specific high-confidence trade reads. |
| high_confidence_daily | Same as high_confidence_hourly, for daily candles. |
3. Message Examples
Subscription confirmed
{"message":"Subscribed to API updates"}
{"message":"You are now subscribed to hourly updates (filtered to BTC-USD, ETH-USD)."}Keepalive
Sent to every connected client every 30s - respond to this or just ignore it, but don't treat silence as a disconnect signal before this interval.
{"message":"ping"}high_confidence_hourly candle
Every field from the normal hourly candle, plus msg - one of 16 pre-written reads, keyed off which of the four confidence fields are above 0.9, with an extra volatility sentence appended when future_vol > 0.05 and expansion_probability > 0.9.
{
"ticker": "BTC-USD",
"datetime": "2026-10-24T22:00:00",
"close": 104, "future_vol": 0.06,
"tail_risk_conf": 0.95, "high_vol_conf": 0.95,
"msg": "Big move, already-wide conditions: An outlier move on top of an already-elevated regime... Volatility: Range is predicted to be 6% over the next 3-5 candles."
}Errors
{"error":"Invalid API Key."}
{"error":"Invalid JSON"}
{"error":"Unknown channel \"foo\". Channels are hourly, daily, high_confidence_hourly, high_confidence_daily."}
{"error":"tickers must be a non-empty array of ticker strings, e.g. [\"BTC-USD\", \"ETH-USD\"]."}