model_metadata.json

{
  "model_name": "QuantFlux 3.0 Trial 244 XGBoost",
  "model_version": "1.0",
  "model_id": "trial_244_xgb",
  "release_date": "2025-11-19",
  "task": "binary_classification",
  "domain": "cryptocurrency_futures_trading",
  "description": "XGBoost classifier for Bitcoin futures direction prediction with 84.38% accuracy on out-of-sample forward test",

  "architecture": {
    "type": "XGBClassifier",
    "framework": "xgboost==2.0.3",
    "hyperparameters": {
      "n_estimators": 2000,
      "max_depth": 7,
      "learning_rate": 0.1,
      "subsample": 0.8,
      "colsample_bytree": 0.8,
      "min_child_weight": 1,
      "gamma": 0,
      "objective": "binary:logistic",
      "eval_metric": "logloss",
      "random_state": 42,
      "tree_method": "hist"
    },
    "optimization": {
      "algorithm": "Bayesian Optimization (Optuna)",
      "n_trials": 1000,
      "objective": "Maximize Sharpe Ratio",
      "trial_winner": 244
    }
  },

  "training_data": {
    "symbol": "BTC/USDT",
    "exchange": "Binance",
    "contract_type": "perpetual_futures",
    "time_period": "2020-08-01 to 2025-11-16",
    "duration_years": 5.25,
    "total_ticks": "2.54 billion",
    "bar_type": "dollar_bars",
    "dollar_threshold": 500000,
    "training_samples": 418410,
    "test_samples": 139467,
    "total_samples": 557877,
    "features": 17,
    "classes": 2
  },

  "performance": {
    "forward_test": {
      "period": "2025-08-18 to 2025-11-16",
      "test_type": "out_of_sample_unseen",
      "accuracy": 0.8438,
      "precision": 0.4767,
      "recall": 0.4918,
      "f1_score": 0.4840,
      "sharpe_ratio": 12.4618,
      "win_rate": 0.8438,
      "profit_factor": 4.78,
      "max_drawdown": -0.0946,
      "total_trades": 224,
      "total_pnl_usd": 2833018,
      "avg_win_percent": 0.0154,
      "avg_loss_percent": -0.0032
    },
    "historical_validation": {
      "2020": {"sharpe": 7.61, "win_rate": 0.8335, "max_dd": -0.3205},
      "2021": {"sharpe": 5.93, "win_rate": 0.8280, "max_dd": -0.0226},
      "2022": {"sharpe": 6.38, "win_rate": 0.8318, "max_dd": -0.0251},
      "2023": {"sharpe": 6.49, "win_rate": 0.8327, "max_dd": -0.0021},
      "2024": {"sharpe": 8.11, "win_rate": 0.8406, "max_dd": -0.0012}
    }
  },

  "signal_generation": {
    "trial_number": 244,
    "parameters": {
      "momentum_threshold": -0.9504030908713968,
      "volume_threshold": 1.5506670658436892,
      "vwap_dev_threshold": -0.78153009100896,
      "min_signals_required": 2,
      "holding_period_bars": 42,
      "atr_multiplier": 1.0002479688950294,
      "position_size_percent": 0.01
    },
    "signals": [
      {
        "name": "Momentum",
        "condition": "ret_1 <= momentum_threshold",
        "interpretation": "Mean reversion opportunity"
      },
      {
        "name": "Volume",
        "condition": "volume > vol_20 * volume_threshold",
        "interpretation": "Confirmation of conviction"
      },
      {
        "name": "VWAP Deviation",
        "condition": "vwap_deviation <= vwap_dev_threshold",
        "interpretation": "Price discount from fair value"
      }
    ]
  },

  "deployment": {
    "model_file": "trial_244_xgb.pkl",
    "model_size_mb": 79,
    "scaler_file": "scaler.pkl",
    "scaler_type": "StandardScaler",
    "feature_names_file": "feature_names.json",
    "expected_latency_ms": {
      "feature_computation": 20,
      "model_inference": 30,
      "risk_checks": 10,
      "total": 100
    },
    "required_dependencies": [
      "xgboost==2.0.3",
      "scikit-learn==1.3.2",
      "numpy>=1.20",
      "pandas>=1.3"
    ],
    "input_shape": [null, 17],
    "output_shape": [null],
    "output_dtype": "int64",
    "confidence_dtype": "float32"
  },

  "features": {
    "total": 17,
    "categories": {
      "price_action": 5,
      "volume": 3,
      "volatility": 2,
      "macd": 1,
      "time_of_day": 4,
      "vwap": 1,
      "atr": 1
    },
    "look_ahead_bias": "None - all features use minimum 1-bar lag",
    "normalization": "StandardScaler (mean=0, std=1)",
    "feature_order": [
      "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"
    ]
  },

  "validation": {
    "method": "Walk-forward validation with purged K-fold",
    "folds": 5,
    "training_window_months": "3-6 rolling",
    "test_window_weeks": "1-2",
    "embargo_period_days": 10,
    "pbo_score": "<0.5",
    "cross_validation": "Temporal aware, no future data in training"
  },

  "risk_management": {
    "layers": 6,
    "max_position_size_percent": 1.0,
    "max_daily_loss_percent": -5.0,
    "max_drawdown_percent": -15.0,
    "stop_loss_atr_multiplier": 1.0,
    "take_profit_atr_multiplier": 1.0,
    "min_confidence_threshold": 0.55,
    "position_sizing": {
      "confidence_0.55_0.60": "0.25x base position",
      "confidence_0.60_0.65": "0.50x base position",
      "confidence_0.65_0.70": "0.75x base position",
      "confidence_0.70_plus": "1.00x base position"
    }
  },

  "limitations": {
    "task": "Binary classification only - does not predict magnitude or price targets",
    "instruments": "BTC/USDT only - not tested on altcoins or traditional assets",
    "timeframe": "Designed for 4-hour equivalent bars - other timeframes untested",
    "data_currency": "Training data ends November 2025 - market microstructure evolves",
    "lookback_requirement": "Requires 50-bar history for feature computation",
    "market_conditions": "Not stress-tested on extreme events (>2σ moves)",
    "trading_hours": "Optimal 13:00-16:00 UTC (London-NYSE overlap) - degraded performance in twilight zone",
    "live_deployment": "Paper trading assumptions may differ from live slippage/fills"
  },

  "research_references": [
    "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"
  ],

  "compliance": {
    "license": "CC-BY-4.0",
    "code_license": "MIT",
    "commercial_use": "Permitted with attribution",
    "warranty": "None - provided as-is",
    "risk_disclaimer": "Cryptocurrency futures trading involves extreme risk. Past performance does not guarantee future results.",
    "min_paper_trading_weeks": 4,
    "recommended_capital_start": 5000
  }
}