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."
Code: https://github.com/Goodie-Goody/maic Results, labels, logs: https://huggingface.co/datasets/Goooddy/maic-results
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.