Measurement primitives for perp microstructure research. Reference implementations of the metrics we use at Xylem Group, published as a runnable companion to our research notes. If you read a method described in prose, you can run it on your own data.
Three primitives — markout, vpin, if_stress — each in kos/<name>.py with a synthetic notebook demo in examples/ and tests in tests/. Real-data demos and applied research live in the sister repo paros, which builds on these primitives.
How much does the mid move against you after a fill? Computed in basis points across log-spaced horizons from sub-millisecond to one minute. Three normalizations: by half-spread, by realized volatility, by an impact prior. The foundation for any signal-toxicity measurement.
Easley/López de Prado/O'Hara's classic toxicity proxy. Bulk volume classification with a normal CDF, fixed-volume buckets, rolling toxicity score. Plus notes on what doesn't translate cleanly to crypto perps.
Given a population of leveraged longs and a price shock, walks the liquidation cascade: surplus to the IF, depletion timing, ADL queue. Sweep if_initial to find the smallest IF that survives a given shock with target probability.
The headline cross-venue demo (Hyperliquid BTC vs Binance USDT-M BTCUSDT, mid-path overlay + cross-venue basis + 500-fill markout distribution per venue) lives in paros, our applied research repo. paros imports kos for the primitives and adds the data adapters, real-data notebooks, governance specs, and benchmark tables. Treat kos as the library; paros as the applied book.
uv sync # installs kos + dev deps
uv run jupyter lab examples/ # opens the synthetic-demo notebooksOr render the README plots from a clean checkout:
uv run python scripts/render_plots.pyTests:
make test- kos is a primitives library. Every demo here runs on synthetic data with zero external-data dependencies. Reproducibility on a fresh clone is
uv sync && make demo. - Real-data work lives in
paros. That keeps kos honest about what it is (algorithms + their unit tests) and pushes data-source coupling, venue calibrations, and applied research into a separate repo where it belongs. - VPIN crypto-perp caveats (volume clock × funding events, liquidation-driven one-sided volume, maker-taker fee asymmetries) are documented in
kos/vpin.py. They affect interpretation, not the implementation.
CC BY-NC 4.0 — read, share, cite, run on your own data. No commercial redistribution. See LICENSE.
If you use these primitives in published work, please cite the repo. See CITATION.cff for the canonical record.