https://github.com/AccursedGalaxy/wasserstein-btc
Distributional crypto-return forecasting via Wasserstein-geodesic extrapolation in quantile-function space. WGeo family wins 12/12 (asset × horizon) cells over 6.75y walk-forward CRPS vs GARCH and classical baselines. v0.4.
https://github.com/AccursedGalaxy/wasserstein-btc
backtesting bitcoin caviar crps cryptocurrency diebold-mariano distributional-forecasting econometrics financial-modeling forecasting garch har-rv optimal-transport python quantile-regression research risk-management time-series wasserstein wasserstein-barycenter
Last synced: 29 days ago
JSON representation
Distributional crypto-return forecasting via Wasserstein-geodesic extrapolation in quantile-function space. WGeo family wins 12/12 (asset × horizon) cells over 6.75y walk-forward CRPS vs GARCH and classical baselines. v0.4.
- Host: GitHub
- URL: https://github.com/AccursedGalaxy/wasserstein-btc
- Owner: AccursedGalaxy
- License: mit
- Created: 2026-05-23T13:35:18.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-05-24T10:36:35.000Z (2 months ago)
- Last Synced: 2026-05-29T15:31:26.950Z (2 months ago)
- Topics: backtesting, bitcoin, caviar, crps, cryptocurrency, diebold-mariano, distributional-forecasting, econometrics, financial-modeling, forecasting, garch, har-rv, optimal-transport, python, quantile-regression, research, risk-management, time-series, wasserstein, wasserstein-barycenter
- Language: Python
- Homepage: https://accursedgalaxy.github.io/wasserstein-btc/
- Size: 11.5 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Security: SECURITY.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
- awesome-quant - wasserstein-btc - `Python` - Distributional forecasting of crypto log-returns by tangent-space geodesic extrapolation on the 2-Wasserstein manifold (quantile-function coordinates). Walk-forward CRPS evaluation over 6.75 years across 4 assets × 3 horizons; benchmarked against classical baselines (Static / RW-Drift / HS-Bootstrap / GARCH-N / GARCH-t / GJR-GARCH-t) and a named-econometric panel (HAR-RV, CAViaR-SAV, Markov-switching Normal, FIGARCH, AR(1) Stochastic Volatility, bivariate VAR+GARCH). [Live dashboard](https://accursedgalaxy.github.io/wasserstein-btc/). (Time Series Analysis)
README
# wasserstein-btc
### Distributional forecasting for crypto returns via geodesics on the 2-Wasserstein manifold of probability measures
**A small, falsifiable, interpretable distributional forecaster — ~4 hyperparameters, no learned weights, no neural net.**
[](https://github.com/AccursedGalaxy/wasserstein-btc/actions/workflows/test.yml)
[](pyproject.toml)
[](LICENSE)
[](https://accursedgalaxy.github.io/wasserstein-btc/)
[](docs/RESEARCH_REPORT.md)
[](CITATION.cff)
[**Live dashboard**](https://accursedgalaxy.github.io/wasserstein-btc/) ·
[**Theory**](docs/THEORY.md) ·
[**Research report**](docs/RESEARCH_REPORT.md) ·
[**Results**](docs/RESULTS_LONG.md) ·
[**Roadmap**](ROADMAP.md)
`wasserstein-btc` forecasts the *whole conditional distribution* of future
log-returns — not the mean and not the variance — for liquid crypto
pairs at horizons of 1, 5 and 21 days. The market is modelled as a
trajectory on the 2-Wasserstein manifold of probability measures, the
forecast is the tangent-space extrapolation of recent quantile vectors,
and the result is scored with strictly proper rules (CRPS) against an
explicit panel of baselines (Static, RW-Drift, Historical-Simulation
Bootstrap, GARCH-N, GARCH-t, GJR-GARCH-t).
> **What it is:** a small, falsifiable, interpretable distributional
> forecaster — ~4 hyperparameters, no learned weights, no neural net.
> **What it is not:** a trading-signal generator, a multivariate risk
> system, or a benchmark against state-of-the-art realised-volatility
> models (see [`docs/RESEARCH_REPORT.md §6`](docs/RESEARCH_REPORT.md)
> for what is *not* claimed, and [`ROADMAP.md`](ROADMAP.md) for the
> v0.4 priorities that would close that gap).
## Contents
- [Headline result](#headline-result) · what the panel shows
- [Install](#install) · `uv sync` or `pip install wbtc`
- [Quick start — CLI](#quick-start--cli) · one-line forecasts and backtests
- [Quick start — Python](#quick-start--python) · the `forecast()` API
- [What's novel](#whats-novel) · the four contributions
- [Documents](#documents) · where to read the theory and the numbers
- [Honest limitations](#honest-limitations) · what is *not* claimed
- [Citation](#citation) · how to cite
## Headline result
On the v0.4 panel (BTC + ETH + SOL + BNB × h ∈ {1, 5, 21} × 6.75 years
walk-forward; 1380–2470 test days per cell), the WGeo family beats the
best non-WGeo baseline (best of Static / RW-Drift / HS-Bootstrap /
GARCH-N / GARCH-t / GJR-GARCH-t) in **12 / 12 cells** by 0.1% to 3.2%
mean CRPS.
The v0.4 cycle adds (a) `WGeoEnsemble`, the W₂ barycentre of the v0.3
trio in quantile-function coordinates — guaranteed by Jensen's
inequality on convex CRPS to weakly dominate the component average; and
(b) a residualised Diebold-Mariano test (Giacomini-White 2006) that
projects out shared volatility-clustering noise via |y|, y², y plus
peer-method losses, preserving the EPA null while strictly reducing
HAC variance. Together these lift the panel's statistical evidence:
| | v0.3 | v0.4 |
|---|---:|---:|
| Cells WGeo-family wins on CRPS | 12 / 12 | 12 / 12 |
| Cells with **vanilla DM** p<0.05 | 1 / 12 (8%) | **4 / 12 (33%)** |
| Cells with **residualised DM** p_r<0.05 | — | **8 / 12 (67%)** |
Per-cell headline numbers, regime-conditional DM tables, and the full
falsification verdict against [`docs/THEORY.md §4`](docs/THEORY.md) are
in [`docs/RESULTS_LONG.md`](docs/RESULTS_LONG.md). Methods-paper-style
writeup in [`docs/RESEARCH_REPORT.md`](docs/RESEARCH_REPORT.md).
## Install
The supported workflow uses [`uv`](https://docs.astral.sh/uv/) (fast and
reproducible). The package itself works under any Python ≥3.11.
```bash
git clone https://github.com/AccursedGalaxy/wasserstein-btc
cd wasserstein-btc
uv sync # creates .venv with locked deps
uv run wbtc test # 53 tests, ~10 seconds
```
A PyPI release (`pip install wbtc`) is wired up via
[`.github/workflows/publish-pypi.yml`](.github/workflows/publish-pypi.yml)
and ships on the next signed tag — see [`ROADMAP.md`](ROADMAP.md).
## Quick start — CLI
```bash
uv run wbtc info # what data do I have?
uv run wbtc fetch # fetch / update default panel from Binance
uv run wbtc forecast BTC/USDT -H 5 --plot # forecast & fan-chart PNG
uv run wbtc forecast BTC/USDT -H 5 --json # JSON for scripting
uv run wbtc backtest --quick # fast single-symbol backtest
uv run wbtc backtest-long # full multi-asset (~30 min)
uv run wbtc extended-baselines # HAR-RV/CAViaR/MS/FIGARCH/SV/BVAR vs WGeo on BTC (~2h)
uv run wbtc sweep # hyperparameter robustness
```
## Quick start — Python
```python
from wbtc import forecast, available_symbols, default_forecaster
available_symbols()
# ['BNB/USDT', 'BTC/USDT', 'ETH/USDT', 'SOL/USDT', 'XRP/USDT']
fc = forecast("BTC/USDT", horizon=5)
fc.median, fc.quantile(0.05), fc.quantile(0.95)
fc.to_dict() # JSON-safe summary
# Pick a specific variant explicitly:
from wbtc import WassersteinGeodesicEWMA
fc = forecast("BTC/USDT", horizon=5,
forecaster=WassersteinGeodesicEWMA(window=90, lookback=20))
```
`default_forecaster(horizon)` returns the recommended variant per
horizon (see `RESEARCH_REPORT.md §7`).
## What's novel
- **Per-quantile time-regression on the W₂ manifold.** The 1D-W₂-as-
quantile-function isometry is textbook (Villani 2009 ch. 6); applying
it to *time-series tangent extrapolation* of return distributions
appears to be under-published. The closest published method
(Saluzzi & Soize 2025, [arXiv:2507.07570](https://arxiv.org/abs/2507.07570))
uses a Koopman/EDMD-spectral approach with no regime adaptation,
applied to housing prices.
- **Cosine-curvature gate.** Continuous, non-Markovian gating that
blends geodesic extrapolation with a static-empirical fallback when
consecutive tangent vectors become orthogonal. Pays off at h=1.
- **Theil-Sen robust slope on the tangent.** 29.3% breakdown point;
robust to recent-history outliers without explicit regime modelling.
- **Quantile-coordinate ensemble with GARCH.** Convex combination in
quantile-function space is an *exact W₂-geodesic interpolation*
(McCann 1997) — not a moment-matched or kernel-mixed surrogate.
## Documents
```
docs/
THEORY.md math (§2.6–2.8 are the v0.3 sections, §4 lists
explicit falsification criteria)
RESEARCH_REPORT.md paper-style writeup of the v0.3 contributions
RESULTS_LONG.md auto-regenerated 4-asset × 3-horizon evidence
RESULTS.md legacy v0.1 single-year report (superseded)
INDEX.md one-paragraph orientation to every doc
ROADMAP.md v0.4 + v0.5 priorities (what would make it
competitive vs. production risk systems)
CONTRIBUTING.md the conventions PRs must follow
CHANGELOG.md v0.1 → v0.2 → v0.3 history
```
## Honest limitations
- We have benchmarked against **textbook baselines** as headline (Static
/ RW / HS / GARCH-N / GARCH-t / GJR-GARCH-t across 4 assets × 3
horizons in [`docs/RESULTS_LONG.md`](docs/RESULTS_LONG.md)) and against
a broader **named-econometric panel** on BTC in
[`docs/RESULTS_EXTENDED.md`](docs/RESULTS_EXTENDED.md): HAR-RV (Corsi
2009), CAViaR-SAV (Engle-Manganelli 2004), 2-state Markov-switching
Normal (Hamilton 1989), FIGARCH(1,d,0) (Baillie-Bollerslev-Mikkelsen
1996), AR(1) Stochastic Volatility (Taylor 1982 / Harvey-Ruiz-Shephard
1994 via Kalman QML), and a bivariate VAR+GARCH using BTC + ETH
jointly. Any *production*-risk-system claim is still unsupported —
this rounds out the academic panel.
- **Daily-only.** Intraday volatility dynamics are different.
- **Univariate only.** The 1D-W₂ isometry doesn't extend cleanly to
higher dimensions; multivariate is a v0.5 research item.
- **No trading P&L claim.** Distributional-forecast quality is
necessary but not sufficient for tradeable alpha.
- **Heteroskedastic-dispersion variant (`WGeo-Hetero`) was a
documented dead end** — see `RESEARCH_REPORT.md §4.4` for *why*
(empirical-quantile-based dispersion already encodes the regime;
multiplying by GARCH double-counts). The boundary is reusable.
## Citation
If you use this software in academic work, please cite it.
[`CITATION.cff`](CITATION.cff) is the structured form; the BibTeX-shaped
quick form:
```bibtex
@software{wasserstein_btc_2026,
author = {Robin Bohrer (AccursedGalaxy)},
title = {wasserstein-btc: tangent-space Wasserstein-geodesic
distributional forecasting for crypto returns},
version = {0.4.0},
year = {2026},
url = {https://github.com/AccursedGalaxy/wasserstein-btc}
}
```
## License
[MIT](LICENSE).
## Disclaimer
This is research code. **Not financial advice.** Falsification criteria
are documented in `docs/THEORY.md §4` and tested against the full
long-horizon backtest in `docs/RESULTS_LONG.md`. Documented failures are
in `docs/RESEARCH_REPORT.md §4.2`.