Cryptocurrency Orderflow Analysis

Research project for detecting breakouts and anomalies in cryptocurrency markets using orderflow analysis.

Quick Start

# Activate virtual environment
source .venv/bin/activate

# Install all dependencies (already done)
# pip install -r requirements.txt

# Launch Jupyter
jupyter notebook notebooks/

Project Structure

crypt/
├── notebooks/                      # Research notebooks
│   ├── 01_data_collection.ipynb   # Live orderbook data collection
│   ├── 02_metric_optimization.ipynb  # Threshold tuning
│   ├── 03_backtest_signals.ipynb  # Strategy backtesting
│   └── 04_strategy_validation.ipynb  # Statistical validation
├── src/                            # Custom orderflow analysis
│   └── orderflow/                  # Metrics and utilities
│       ├── metrics.py              # All orderflow calculations
│       └── __init__.py
├── data/                           # Cached data and results
├── results/                        # Figures and analysis outputs
├── pyproject.toml                  # Package configuration
└── requirements.txt                # Dependencies

## Research Questions

1. Can we detect abnormal volume/orderflow before price breakouts?
2. What orderflow metrics best predict directional price moves?
3. Can we build a profitable strategy based on orderflow signals?

## Dependencies

All packages are properly installed in `.venv`:

- **wrdata**: Coinbase data + Level2 orderbook streaming
- **fracTime**: Time series forecasting models
- **wrtrade**: Fast portfolio backtesting + permutation testing
- **crypt-orderflow**: This package (orderflow metrics)

## Research Workflow

### Phase 1: Research (Current)

**Notebook 1: Data Collection**
- Connect to Coinbase Level2 orderbook stream
- Collect live orderbook snapshots
- Calculate basic orderflow metrics
- Visualize volume patterns and imbalances

**Notebook 2: Metric Optimization**
- Test different orderflow metrics
- Optimize detection thresholds
- Compare metric effectiveness
- Identify optimal parameters

**Notebook 3: Backtesting**
- Collect larger dataset for testing
- Generate trading signals from orderflow
- Backtest strategy with wrtrade
- Analyze signal quality and timing

**Notebook 4: Statistical Validation**
- Grid search parameter optimization
- Calculate risk-adjusted metrics
- Permutation testing for statistical significance
- Final production readiness assessment

### Phase 2: Formalization (If Phase 1 Succeeds)

If research validates the strategy (p < 0.05, Sortino > 1.0):
1. Create production-ready orderflow module
2. Implement live orderbook collection service
3. Build real-time signal generation
4. Paper trade for 2-4 weeks
5. Deploy live trading system

## Key Features

- **Real-time Level2 orderbook streaming** from Coinbase
- **Volume spike detection** using z-score anomaly detection
- **Bid/ask imbalance tracking** for pressure identification
- **Statistical validation** with permutation testing
- **Fast backtesting** using Polars and wrtrade

## Package Additions

### wrdata enhancements:
- ✅ `subscribe_depth()` method for Level2 orderbook streaming
- ✅ Full snapshot and incremental update handling
- ✅ Orderbook state management
- ✅ Unit tested and verified

### crypt-orderflow additions:
- ✅ `OrderflowSnapshot` dataclass
- ✅ Comprehensive orderflow metrics calculation
- ✅ Rolling statistics and z-score detection
- ✅ Volume anomaly detection
- ✅ Liquidity analysis