| =================================================================================== |
| QuantFlux 3.0 XGBoost Trading Model - HuggingFace Package Contents |
| =================================================================================== |
|
|
| RELEASE DATE: 2025-11-19 |
| MODEL ID: trial_244_xgb |
| VERSION: 1.0 |
|
|
| =================================================================================== |
| DOCUMENTATION FILES |
| =================================================================================== |
|
|
| 1. README.md (4.2 KB) |
| - Quick start guide |
| - Model overview and performance summary |
| - Feature descriptions |
| - Usage examples |
| - Risk disclaimers |
|
|
| 2. MODEL_CARD.md (19 KB) - COMPREHENSIVE TECHNICAL DOCUMENTATION |
| - Model Summary & Performance Metrics |
| - Model Architecture (XGBoost specifics) |
| - Training Data Details (2.54B ticks, 5.25 years) |
| - All 17 Features with Formulas |
| - Model Hyperparameters |
| - Input/Output Specifications |
| - Validation Results & Confusion Matrix |
| - Feature Importance Scores |
| - Risk Management Framework |
| - Usage Guide with Code Examples |
| - Limitations & Disclaimers |
| - Performance Interpretation Guide |
|
|
| 3. TECHNICAL_ARCHITECTURE.md (29 KB) - COMPLETE SYSTEM DESIGN |
| - End-to-End System Overview |
| - Dollar Bar Aggregation (algorithm & implementation) |
| - Feature Engineering Pipeline (with Python code) |
| - Model Training & Optimization (Optuna integration) |
| - Signal Generation Logic (entry/exit rules) |
| - Risk Management Framework (6-layer enforcement) |
| - Data Processing Pipeline |
| - Deployment Architecture (AWS specs) |
| - Research references |
|
|
| 4. FEATURE_FORMULAS.json (7.5 KB) - DETAILED FEATURE SPECIFICATION |
| - All 17 feature formulas in mathematical notation |
| - Python implementation for each feature |
| - Feature importance scores |
| - Value ranges and units |
| - Feature category classification |
|
|
| 5. model_metadata.json (6.6 KB) - MACHINE-READABLE METADATA |
| - Model architecture and hyperparameters |
| - Training data specifications |
| - Performance metrics (forward test + historical) |
| - Signal generation parameters |
| - Deployment requirements |
| - Feature list and order |
| - Validation methodology |
| - Risk management configuration |
|
|
| 6. feature_names.json (2.7 KB) - FEATURE NAME INDEX |
| - Feature count and names (in required order) |
| - Feature descriptions |
| - Feature types (continuous vs binary) |
| - Feature importance scores |
| - Expected value ranges |
|
|
| 7. PACKAGE_CONTENTS.txt (this file) |
| - Index of all package contents |
| - File descriptions and sizes |
|
|
| =================================================================================== |
| MODEL FILES |
| =================================================================================== |
|
|
| 1. trial_244_xgb.pkl (79 MB) |
| - Trained XGBoost classifier |
| - 2,000 trees, depth=7 |
| - Binary classification (Buy/Hold) |
| - Serialized format: Python pickle |
| - Load with: pickle.load(open('trial_244_xgb.pkl', 'rb')) |
|
|
| 2. scaler.pkl (983 bytes) |
| - StandardScaler for feature normalization |
| - Mean=0, Std=1 normalization |
| - MUST be used before model prediction |
| - Load with: pickle.load(open('scaler.pkl', 'rb')) |
| - Apply with: scaler.transform(features) |
|
|
| =================================================================================== |
| CONFIGURATION FILES |
| =================================================================================== |
|
|
| 1. .gitattributes |
| - Git LFS configuration for large model files |
| - Ensures proper handling of 79MB pickle file |
|
|
| =================================================================================== |
| MODEL SPECIFICATIONS |
| =================================================================================== |
|
|
| PERFORMANCE (Forward Test: Aug 18 - Nov 16, 2025) |
| - Directional Accuracy: 84.38% |
| - Sharpe Ratio: 12.46 |
| - Win Rate: 84.38% |
| - Profit Factor: 4.78x |
| - Max Drawdown: -9.46% |
| - Total Trades: 224 |
| - Test Duration: 3 months (completely unseen data) |
|
|
| ARCHITECTURE |
| - Type: XGBoost Binary Classifier |
| - Framework: xgboost==2.0.3 |
| - Trees: 2,000 |
| - Max Depth: 7 |
| - Learning Rate: 0.1 |
| - Model Size: 79 MB |
|
|
| TRAINING DATA |
| - Symbol: BTC/USDT perpetual futures |
| - Ticks: 2.54 billion |
| - Period: 2020-08-01 to 2025-11-16 (5.25 years) |
| - Training Samples: 418,410 |
| - Test Samples: 139,467 |
| - Bar Type: Dollar bars ($500k per bar) |
|
|
| FEATURES |
| - Total Count: 17 |
| - Categories: Price (5), Volume (3), Volatility (2), MACD (1), Time (4), Other (2) |
| - Look-Ahead Bias: None (all features use minimum 1-bar lag) |
| - Normalization: StandardScaler (mean=0, std=1) |
|
|
| INPUT SPECIFICATION |
| - Shape: (N, 17) where N = batch size |
| - Data Type: float32 preferred |
| - Scaling: MUST use provided scaler.pkl |
| - Order: CRITICAL - must match feature_names.json order |
|
|
| OUTPUT SPECIFICATION |
| - Predictions: Binary (0 or 1) |
| - Probabilities: Float32 (0.0 to 1.0) |
| - Confidence Threshold: 0.55 minimum recommended |
|
|
| LATENCY |
| - Feature Computation: <20ms |
| - Model Inference: <30ms |
| - Risk Management: <10ms |
| - Target Total: <100ms |
|
|
| DEPLOYMENT REQUIREMENTS |
| - Python: 3.9+ |
| - XGBoost: 2.0.3 |
| - scikit-learn: 1.3.2 |
| - NumPy: 1.20+ |
| - pandas: 1.3+ |
| - Memory: 500MB minimum (model + features) |
| - Disk: 80MB for model files |
|
|
| =================================================================================== |
| VALIDATION METHODOLOGY |
| =================================================================================== |
|
|
| Walk-Forward Validation: |
| - Training Window: 3-6 months rolling |
| - Test Window: 1-2 weeks |
| - Embargo Period: 10 days between train/test |
| - Purged K-Fold: 5 folds with temporal awareness |
| - PBO Score: <0.5 (acceptable threshold <0.7) |
|
|
| Cross-Year Performance: |
| - 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% |
|
|
| Conclusion: Consistent 83-84% accuracy across all market regimes |
|
|
| =================================================================================== |
| SIGNAL GENERATION |
| =================================================================================== |
|
|
| Trial 244 Configuration: |
| - Momentum Threshold: -0.9504 |
| - Volume Threshold: 1.5507x |
| - VWAP Deviation: -0.7815% |
| - Minimum Signals: 2 of 3 required |
| - Holding Period: 42 bars (7 days on 4-hour bars) |
| - Stop Loss: 1.0x ATR |
| - Take Profit: 1.0x ATR |
| - Position Size: 1% of capital (scaled by confidence) |
|
|
| =================================================================================== |
| RISK MANAGEMENT |
| =================================================================================== |
|
|
| 6-Layer Enforcement: |
| 1. Position Sizing: Max 1% per trade, 10% portfolio max |
| 2. Confidence Threshold: 0.55 minimum |
| 3. Volatility Filter: Halt if >10% 1-min ATR |
| 4. In-Trade Monitoring: Stop-loss and take-profit |
| 5. Daily Loss Limit: -5% maximum per day |
| 6. Drawdown Control: -15% maximum from peak |
|
|
| Position Sizing by Confidence: |
| - 0.55-0.60: 25% position |
| - 0.60-0.65: 50% position |
| - 0.65-0.70: 75% position |
| - 0.70+: 100% position |
|
|
| =================================================================================== |
| RESEARCH FOUNDATION |
| =================================================================================== |
|
|
| Academic Papers Incorporated: |
| 1. "Geometric Alpha: Temporal Graph Networks for Microsecond-Scale |
| Cryptocurrency Order Book Dynamics" |
| 2. "Heterogeneous Graph Neural Networks for Real-Time Bitcoin Whale |
| Detection and Market Impact Forecasting" |
| 3. "Discrete Ricci Curvature-Based Graph Rewiring for Latent Structure |
| Discovery in Cryptocurrency Markets" |
|
|
| Books Referenced: |
| - de Prado, M. L. (2018). "Advances in Financial Machine Learning" |
| - Aronson, D. (2007). "Evidence-Based Technical Analysis" |
|
|
| =================================================================================== |
| USAGE WORKFLOW |
| =================================================================================== |
|
|
| Step 1: 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) |
|
|
| Step 2: Compute 17 Features |
| - ret_1, ret_3, ret_5, ret_accel, close_pos (price) |
| - vol_20, high_vol, low_vol (volume) |
| - rsi_oversold, rsi_neutral, macd_positive (volatility/macd) |
| - london_open, london_close, nyse_open, hour (time) |
| - vwap_deviation, atr_stops (additional) |
|
|
| Step 3: Scale Features |
| features_scaled = scaler.transform(features.reshape(1, -1)) |
|
|
| Step 4: Generate Prediction |
| signal = model.predict(features_scaled)[0] |
| confidence = model.predict_proba(features_scaled)[0][1] |
|
|
| Step 5: Check Risk Management |
| if confidence >= 0.55: |
| position_size = calculate_position_size(confidence) |
| # Entry signal with sized position |
|
|
| Step 6: Execute and Monitor |
| - Entry at current price |
| - Stop loss at entry - 1.0x ATR |
| - Take profit at entry + 1.0x ATR |
| - Exit after 42 bars if no TP/SL |
|
|
| =================================================================================== |
| IMPORTANT DISCLAIMERS |
| =================================================================================== |
|
|
| 1. RISK WARNING |
| Cryptocurrency futures trading involves extreme risk of total loss. |
| Past performance does not guarantee future results. |
|
|
| 2. PAPER TRADING REQUIREMENT |
| Minimum 4 weeks paper trading REQUIRED before live money deployment. |
|
|
| 3. CAPITAL REQUIREMENTS |
| Start with 5-10% of total trading capital, not more. |
| Never risk more than you can afford to lose. |
|
|
| 4. MARKET CONDITIONS |
| - Model optimal 13:00-16:00 UTC (London-NYSE overlap) |
| - Avoid 21:00-23:00 UTC (42% liquidity drop) |
| - Requires retraining every 1-2 weeks for regime adaptation |
|
|
| 5. LIMITATIONS |
| - BTC/USDT only (not tested on altcoins) |
| - Binary classification (no price targets) |
| - 4-hour bars optimal (other timeframes untested) |
| - Does NOT predict extreme events or crashes |
|
|
| 6. NO WARRANTY |
| Provided AS-IS without any warranty or guarantee. |
| Users assume all responsibility for trading decisions and outcomes. |
|
|
| =================================================================================== |
| FILE SIZES SUMMARY |
| =================================================================================== |
|
|
| trial_244_xgb.pkl 79.0 MB (Model weights) |
| MODEL_CARD.md 19.0 KB (Comprehensive documentation) |
| TECHNICAL_ARCHITECTURE 29.0 KB (System design) |
| model_metadata.json 6.6 KB (Machine-readable metadata) |
| FEATURE_FORMULAS.json 7.5 KB (Feature specifications) |
| feature_names.json 2.7 KB (Feature index) |
| scaler.pkl 983 B (Feature scaler) |
| README.md 4.2 KB (Quick start) |
| .gitattributes 150 B (Git LFS config) |
| PACKAGE_CONTENTS.txt ~13 KB (This file) |
|
|
| TOTAL: ~165 MB (primarily model file) |
|
|
| =================================================================================== |
| RECOMMENDED READING ORDER |
| =================================================================================== |
|
|
| 1. README.md - Quick overview and usage examples |
| 2. MODEL_CARD.md - Performance metrics and feature descriptions |
| 3. TECHNICAL_ARCHITECTURE.md - System design and implementation |
| 4. FEATURE_FORMULAS.json - Feature computation details |
| 5. model_metadata.json - Hyperparameters and validation results |
|
|
| =================================================================================== |
| SUPPORT & QUESTIONS |
| =================================================================================== |
|
|
| For comprehensive documentation, consult: |
| - MODEL_CARD.md: Full specifications and usage |
| - TECHNICAL_ARCHITECTURE.md: Implementation details |
| - FEATURE_FORMULAS.json: Feature definitions |
| - model_metadata.json: Metadata and hyperparameters |
|
|
| =================================================================================== |
| VERSION HISTORY |
| =================================================================================== |
|
|
| v1.0 (2025-11-19) - Initial Release |
| - Trial 244 XGBoost model |
| - 84.38% accuracy on forward test |
| - Complete documentation package |
| - 2,000 trees, 79MB model file |
| - 17 features, no look-ahead bias |
|
|
| =================================================================================== |
| LICENSE |
| =================================================================================== |
|
|
| Model License: CC-BY-4.0 (Attribution required) |
| Code License: MIT |
| Commercial Use: Permitted with attribution |
| Modification: Encouraged with results sharing |
|
|
| =================================================================================== |
| CONTACT & ATTRIBUTION |
| =================================================================================== |
|
|
| QuantFlux 3.0 Research Team |
| Released: November 19, 2025 |
| Model: Trial 244 XGBoost (Bayesian optimization, 1,000 trials) |
| Forward Test: August 18 - November 16, 2025 (Completely unseen) |
|
|
| =================================================================================== |
| END OF PACKAGE CONTENTS |
| =================================================================================== |
|
|
