Grogan-Dev/QuantFlux-Trial244-BTC

---

license: other license_name: proprietary license_link: LICENSE

QuantFlux Alpha (Test Model for 3.0) XGBoost Trading Model

Quick Start

import pickle
import numpy as np
from sklearn.preprocessing import StandardScaler

# Load model and scaler
with open('trial_244_xgb.pkl', 'rb') as f:
    model = pickle.load(f)
with open('scaler.pkl', 'rb') as f:
    scaler = pickle.load(f)

# Prepare features (17-dimensional array)
features = np.array([
    ret_1, ret_3, ret_5, ret_accel, close_pos,
    vol_20, high_vol, low_vol,
    rsi_oversold, rsi_neutral, macd_positive,
    london_open, london_close, nyse_open, hour,
    vwap_deviation, atr_stops
])

# Scale and predict
features_scaled = scaler.transform(features.reshape(1, -1))
signal = model.predict(features_scaled)[0]  # 0 or 1
confidence = model.predict_proba(features_scaled)[0][1]  # 0.0-1.0

print(f"Signal: {signal}, Confidence: {confidence:.2%}")

Model Overview

Trial 244 Alpha Alpha XGBoost - Production-grade cryptocurrency futures trading model

• Accuracy: 84.38% on 3-month out-of-sample forward test (Aug-Nov 2025)
• Sharpe Ratio: 12.46 (annualized)
• Win Rate: 84.38%
• Profit Factor: 4.78x
• Training Data: 2.54 billion ticks (2020-2025)
• Total Trades: 224 in forward test, consistent 83-84% win rate across all years (2020-2024)

Architecture

• Algorithm: XGBoost (2,000 trees, depth=7)
• Framework: xgboost==2.0.3
• Input: 17 features from dollar bars (no look-ahead bias)
• Output: Binary prediction (Buy/Hold) + confidence probability
• Latency: <100ms end-to-end (20ms features + 30ms inference + 10ms risk checks)

Features (17 Total)

Price Action (5)

• ret_1: Lag-1 return (momentum)
• ret_3: 3-bar return (trend confirmation)
• ret_5: 5-bar return (regime identification)
• ret_accel: Return acceleration (reversal detection)
• close_pos: Close position in 20-bar range (0-1 normalized)

Volume (3)

• vol_20: 20-bar volume mean (baseline)
• high_vol: Volume spike flag (binary)
• low_vol: Volume drought flag (binary)

Volatility (2)

• rsi_oversold: RSI < 30 (binary)
• rsi_neutral: 30 <= RSI <= 70 (binary)

MACD (1)

• macd_positive: MACD > 0 (binary)

Time-of-Day (4)

• london_open: London 8:00 UTC (binary)
• london_close: London 16:30 UTC (binary)
• nyse_open: NYSE 13:30 UTC (binary)
• hour: Hour of day UTC (0-23)

Additional (2)

• vwap_deviation: Percent deviation from VWAP
• atr_stops: 14-period ATR * 1.0x (for stop sizing)

Performance Metrics

Forward Test (Out-of-Sample)

• Period: 2025-08-18 to 2025-11-16 (completely unseen)
• Trades: 224
• Win Rate: 84.38%
• Sharpe: 12.46
• Max Drawdown: -9.46%
• Total P&L: +$2.83M on $100k capital

Historical Validation (Cross-Year)

• 2020: Sharpe 7.61, Win 83.35%, DD -32.05%
• 2021: Sharpe 5.93, Win 82.80%, DD -2.26%
• 2022: Sharpe 6.38, Win 83.18%, DD -2.51%
• 2023: Sharpe 6.49, Win 83.27%, DD -0.21%
• 2024: Sharpe 8.11, Win 84.06%, DD -0.12%

Files Included

1. MODEL_CARD.md - Comprehensive model documentation with all technical details
2. TECHNICAL_ARCHITECTURE.md - Complete system architecture and implementation guide
3. FEATURE_FORMULAS.json - All 17 features with formulas and importance scores
4. model_metadata.json - Model hyperparameters, training info, performance metrics
5. feature_names.json - Feature names in required order with descriptions
6. trial_244_xgb.pkl - Trained XGBoost model (79 MB)
7. scaler.pkl - StandardScaler for feature normalization

Key Characteristics

Strengths

• Consistent 84% win rate across all market conditions (2020-2025)
• Exceptional Sharpe ratio (12.46) indicates high risk-adjusted returns
• Dollar bar aggregation eliminates look-ahead bias
• All features use historical data only (minimum 1-bar lag)
• Tested on 5.25 years of data (2.54 billion ticks)
• Walk-forward validation with purged K-fold prevents overfitting

Limitations

• BTC/USDT only: Not tested on altcoins or equities
• Binary classification: Does not predict price targets
• 4-hour bars optimal: Other timeframes untested
• 50-bar warm-up: Requires historical data for feature computation
• Best performance 13:00-16:00 UTC: London-NYSE overlap period
• Market-dependent: Requires retraining every 1-2 weeks for regime adaptation

Risk Management

6-layer enforcement:

1. Position sizing (1% per trade, max 10% portfolio)
2. Confidence threshold (minimum 0.55)
3. Volatility filters (halt if >10% 1-min ATR)
4. Stop-loss enforcement (1.0x ATR)
5. Daily loss limits (5% max)
6. Drawdown monitoring (15% max)

Usage Examples

Basic Prediction

import numpy as np
import pickle

# Load model and scaler
with open('trial_244_xgb.pkl', 'rb') as f:
    model = pickle.load(f)
with open('scaler.pkl', 'rb') as f:
    scaler = pickle.load(f)

# Create features (17-dim array)
features = np.array([...])  # Your computed features
features_scaled = scaler.transform(features.reshape(1, -1))

# Get prediction and confidence
signal = model.predict(features_scaled)[0]
confidence = model.predict_proba(features_scaled)[0][1]

if signal == 1 and confidence >= 0.55:
    print(f"BUY signal with {confidence:.2%} confidence")

Batch Processing

# Process multiple bars
features_batch = np.array([...])  # Shape: (N, 17)
features_scaled = scaler.transform(features_batch)

predictions = model.predict(features_scaled)
confidences = model.predict_proba(features_scaled)[:, 1]

# Filter by confidence
valid_trades = confidences >= 0.55
buy_signals = predictions[valid_trades]

Position Sizing by Confidence

def position_size(confidence):
    if confidence < 0.55:
        return 0      # Skip
    elif confidence < 0.60:
        return 0.25   # 25% position
    elif confidence < 0.65:
        return 0.50   # 50% position
    elif confidence < 0.70:
        return 0.75   # 75% position
    else:
        return 1.0    # Full position

Model Selection: Why Trial 244 Alpha Alpha?

Extensive hyperparameter optimization (1,000 trials with Bayesian search) identified Trial 244 Alpha Alpha as optimal:

• Maximizes Sharpe ratio on walk-forward test set
• 84.38% win rate on completely unseen 3-month forward period
• 2,000 trees with depth=7 balances complexity and generalization
• 0.1 learning rate with 0.8 subsample prevents overfitting

Documentation

For comprehensive technical details, see:

• MODEL_CARD.md: Full model specifications, validation results, usage guide
• TECHNICAL_ARCHITECTURE.md: System design, dollar bar aggregation, feature engineering, training pipeline
• FEATURE_FORMULAS.json: All 17 feature formulas with importance scores
• model_metadata.json: Hyperparameters, training data, performance metrics

Research Foundation

Built on academic research:

• "Geometric Alpha: Temporal Graph Networks for Microsecond-Scale Cryptocurrency Order Book Dynamics"
• "Heterogeneous Graph Neural Networks for Real-Time Bitcoin Whale Detection and Market Impact Forecasting"
• "Discrete Ricci Curvature-Based Graph Rewiring for Latent Structure Discovery in Cryptocurrency Markets"
• de Prado, M. L. (2018). "Advances in Financial Machine Learning"
• Aronson, D. (2007). "Evidence-Based Technical Analysis"

Requirements

pip install xgboost==2.0.3 scikit-learn==1.3.2 numpy pandas

Important Disclaimers

Risk Warning

Trading cryptocurrency futures involves extreme risk. This model:

• Does NOT guarantee profitability
• Has NOT been tested on all market conditions
• Requires proper risk management implementation
• Should undergo 4+ weeks paper trading before live deployment

Performance Caveats

• Forward test period (Aug-Nov 2025) represents only 3 months
• Backtest assumes perfect execution and no slippage
• Market regime changes require model retraining
• Regulatory changes can invalidate assumptions

Responsible Use

• Start with paper trading (minimum 4 weeks)
• Begin with small capital (5-10% of total trading capital)
• Implement all 6 risk management layers
• Monitor daily and adjust position sizes
• Never override risk limits

License

• Model: CC-BY-4.0 (Attribution required for commercial use)
• Code: MIT (included implementation files)
• Commercial Use: Permitted with attribution
• Modification: Encouraged with results sharing

Support

For technical questions or issues:

1. Review MODEL_CARD.md for comprehensive documentation
2. Check TECHNICAL_ARCHITECTURE.md for implementation details
3. Verify feature computation against FEATURE_FORMULAS.json
4. Ensure models are loaded correctly (pickle format)

Citation

If you use this model in research or publication, cite:

QuantFlux Alpha (Test Model for 3.0) XGBoost Trading Model (Trial 244 Alpha Alpha)
Released: November 19, 2025
Trained on: 2.54 billion Bitcoin futures ticks (2020-2025)
Forward Test Sharpe: 12.46 (Aug-Nov 2025, out-of-sample)

---

Version: 1.0 Updated: 2025-11-19 Status: Production-Ready (Paper Trading) Confidence: 84.38% directional accuracy

Disclaimer: Past performance does not guarantee future results. Use at your own risk with appropriate position sizing and risk management.