---
license: mit
library_name: xgboost
tags:
  - finance
  - cryptocurrency
  - market-microstructure
  - liquidity-stress
  - time-series
---

# 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.