MAIC — Liquidity Stress Detection (XGBoost, Pooled, Binary)
Production model from "An Early Warning System for Liquidity Stress in
Cryptocurrency Markets Using Trade Flow Analysis and Machine Learning."
What this model does
Given seven market-microstructure features (OFI, RV, Kyle's lambda, ILLIQ,
VWAP deviation, trade intensity, TCI) plus fractionally differenced price,
computed on 300-second bars of Binance BTC/ETH/SOL trade data, predicts the
probability the current bar reflects a liquidity-stress regime.
Performance (Fold 4, 18.8M training rows, held-out test set)
| Metric | Score |
|---|
| F1 (weighted) | 0.9706 |
| Seed variance | 0.0006 |
56-108 minutes of advance warning before externally documented crisis
timestamps (FTX bankruptcy, Terra-Luna collapse), measured against reference
definitions the model never saw during training.
Files
xgb_binary_pooled_fold4_seed42.pkl -- production model, pooled across
BTC/ETH/SOL with an asset identifier feature. Recommended default.xgb_multiclass_pooled_fold4_seed42.pkl -- multiclass variant (calm /
elevated / stress), backs Table 2's multiclass row.lr_binary_pooled_fold4_seed42.pkl, lr_multiclass_pooled_fold4_seed42.pkl
-- logistic regression baselines used for comparison in the paper.
No Random Forest pickle is published. 06d_train_production.py
deliberately saves {"model": None, "scaler": scaler} for RF rather than the
fitted model object, since the underlying cuML RF classifier doesn't reliably
reload across different GPU sessions/driver versions. RF's metrics and
predictions are still valid and included in the results dataset -- only the
serialized model artifact itself doesn't exist in a usable form.
Asset-specific models at the same 5-seed production rigor don't exist:
06d_train_production.py trains pooled only by design (see code comment).
Single-seed asset-specific models exist in the results dataset repo under
v2/results_run1/ but are exploratory, not production-grade.
Usage
Load with pickle.load(). Expects a dict with model (XGBoost classifier)
and scaler (fitted feature scaler). See scripts/12_inference.py in the
code repo for the full feature-construction and inference pipeline --
loading the pickle alone is not sufficient without matching feature
engineering.
Important caveats
- Stress probability reflects liquidity conditions, not a price prediction.
Price impact is not guaranteed.
- Labels are HMM-derived (see paper Section 3.3) with a documented
look-ahead in retrospective Viterbi decoding, justified empirically via a
three-tier external validation framework (Section 3.4/4.4).
- Live inference reconstructs features on a single 300s window; this differs
from the multi-scale rolling-window construction used in training. See the
code repo for details on this known gap.
