baonathor/xtrade-v1

XTrade AI - Event-Driven Price Reaction (EDPR) Model

Overview

This project implements an Event-Driven Price Reaction (EDPR) model designed to predict short-term price movements of cryptocurrency assets following specific social or market events.

Unlike generic trend-following algorithms, this model focuses on the immediate market reaction to a combination of Social Sentiment (tweets, news) and Market Microstructure (volatility, volume, returns). It utilizes a hybrid architecture combining BERT for text analysis and a Multi-Layer Perceptron (MLP) for quantitative data to forecast price direction over 3-minute and 30-minute horizons.

Conceptual Flow

The following diagram illustrates how the model processes information to generate a signal:

[Tweet Input] ──────> [BERT Encoder] ──────> [Text Embeddings] ──────┐
                                                                     │
                                                                     ▼
                                                              [Fusion Layer] ────> [Classifier] ────> [3m & 30m Probs]
                                                              (Cross-Attn)
                                                                     ▲
                                                                     │
[Market Data] ──────> [Scaler] ────────────> [MLP Encoder] ──────────┘

1. Input: The model receives a text string (Tweet) and a vector of 13 market features (Pre-event context).
2. Fusion: It uses an attention mechanism to weigh the importance of the text based on the current market state.
3. Output: It produces probability distributions for "Up", "Down", and "Neutral" outcomes.

Market-Conditioned Attention Mechanism

The core innovation of this model is how it fuses market data with text. Instead of simple concatenation, it uses the market state to "query" the text, focusing on the most relevant parts of the tweet given the current price action.

$$\text{Attention}(Q,K,V)=\text{softmax}\left(\frac{Q{K}^T}{\sqrt{d_k}}\right)V\backslash text\{Attention\}(Q,\; K,\; V)\; =\; \backslash text\{softmax\}\backslash left(\backslash frac\{QK^T\}\{\backslash sqrt\{d\_k\}\}\backslash right)V$$

Where:

• Query ($Q$): Encoded Market Features (MLP Output). The market state asks: "Given this price drop, what part of the text matters?"
• Key ($K$) & Value ($V$): BERT Text Embeddings.

Key Features

• Hybrid Neural Architecture: Integrates textual embeddings with numerical market features using a market-conditioned attention mechanism.
• Multi-Horizon Forecasting: Outputs probability distributions for price direction (Up, Down, Neutral) for both 3-minute and 30-minute intervals.
• Extreme Signal Detection: Identifies high-confidence setups, specifically filtering for "Extreme" probabilities that may indicate significant mean reversion or momentum opportunities.
• GPU-Accelerated Inference: Designed for efficient execution on CUDA-enabled environments.

Training Data & Methodology

The model was trained on a historical dataset of cryptocurrency market events aligned with social media activity. The dataset comprises ~38,000 tweets from official Twitter accounts corresponding to over 500 cryptocurrencies listed on Binance.

The EDPR model is trained as a supervised multi-class classifier, predicting the short-term direction (Up, Down, Neutral) for 3-minute and 30-minute horizons.

To ensure robust generalization, the data was partitioned as follows:

• Training Set (70%): Used for optimizing model weights.
• Validation Set (15%): Used for hyperparameter tuning and preventing overfitting.
• Test Set (15%): Reserved for final performance evaluation on unseen data.

Label Generation & Balancing

• Price Labels: Generated by computing the forward return at exactly +3m and +30m after each tweet, mapped into three classes: Up, Down, and Neutral.
• Class Balancing: Basic class balancing techniques (e.g., weighted loss) were applied to prevent the model from being biased toward majority outcomes (Neutral).

What Makes EDPR Different?

Users should be aware of the specific behavioral biases inherent in this model, which stem from the historical training data. The model functions primarily as a Mean Reversion engine.

Observed Test Scenarios

The following examples show the actual output from the inference engine and how to interpret the results.

Performance Benchmark:

• Hardware: NVIDIA RTX 5080
• Inference Time: ~8–15 ms per sample

Note: The input market features (e.g., feat_ret_1m) represent the price action leading up to the tweet.

1. FOMO / Strong Uptrend ("Sell the Rip")

--- Scenario: FOMO / Strong Uptrend ---
Tweet: BREAKING: Major exchange listing confirmed! 🚀 #ToTheMoon
Key Feats: feat_ret_1m=0.02, feat_volume_60m=2000000, feat_fear_greed_index=80
Signal: NORMAL
3m Probs: Down=0.674, Neutral=0.066, Up=0.261
Time: 10.42 ms

• Interpretation: The model sees the pre-existing pump (+2%) as an "overbought" signal. Despite the positive news, it predicts a correction (Down probability 67%) rather than a continued breakout.

2. Panic Dump / Crash ("Buy the Dip")

--- Scenario: Panic Dump / Crash ---
Tweet: URGENT: Security breach detected. Do not interact with contracts.
Key Feats: feat_ret_1m=-0.05, feat_volume_60m=5000000, feat_fear_greed_index=10
Signal: EXTREME UP
3m Probs: Down=0.170, Neutral=0.013, Up=0.818
Time: 10.52 ms

• Interpretation: The model observes the massive pre-existing drop (-5%) and predicts a technical rebound (Mean Reversion). It effectively bets that the "dump" has already happened and the price will bounce, overriding the bearish sentiment of the new tweet.

3. Slow Bleed / Bear Market

--- Scenario: Slow Bleed / Bear Market ---
Tweet: Weekly development update. Progress is slow but steady.
Key Feats: feat_ret_1m=-0.001, feat_volume_60m=100000, feat_fear_greed_index=30
Signal: NORMAL
3m Probs: Down=0.333, Neutral=0.030, Up=0.637
Time: 9.70 ms

• Interpretation: In a slow bleed environment with low volatility, the model leans slightly bullish (Up 63%) but remains within the "NORMAL" range, suggesting no strong trade setup.

4. Sideways / Stable

--- Scenario: Sideways / Stable ---
Tweet: Just a normal day building. #Crypto
Key Feats: feat_ret_1m=0.0, feat_volume_60m=50000, feat_fear_greed_index=50
Signal: NORMAL
3m Probs: Down=0.429, Neutral=0.230, Up=0.341
Time: 10.30 ms

• Interpretation: With flat price action and neutral sentiment, the probabilities are mixed (Down 42%, Up 34%, Neutral 23%), correctly indicating a lack of clear direction.

5. Divergence (Good News + Bad Price)

--- Scenario: Divergence: Good News + Bad Price ---
Tweet: Partnership with Google Cloud announced!
Key Feats: feat_ret_1m=-0.02, feat_volume_60m=300000, feat_fear_greed_index=40
Signal: EXTREME UP
3m Probs: Down=0.177, Neutral=0.007, Up=0.815
Time: 10.67 ms

• Interpretation: This is the model's ideal setup: A discounted price (pre-existing drop -2%) combined with positive fundamental news triggers a high-confidence buy signal (Extreme Up).

Summary of Biases

• Contrarian Nature: The model often signals buys during crashes and sells during pumps.
• Data-Driven: These behaviors are not hard-coded rules but patterns learned from real-world market microstructure data, where overreactions are often corrected.

Limitations & Known Failure Modes

While powerful, the EDPR model is not a crystal ball. It is optimized for specific conditions and may fail in others:

1. Illiquid Markets: The model assumes standard liquidity. In low-cap or illiquid markets, "mean reversion" may not occur, and prices can cascade down without bouncing.
2. Sustained Fundamental Shifts: For catastrophic events (e.g., FTX collapse, Luna crash), the "Buy the Dip" logic will fail as the price continues to drop toward zero. The model does not understand the severity of a fundamental failure, only the statistical probability of a bounce.
3. Fake News / Spam: The BERT encoder can be misled by sophisticated fake news or coordinated bot spam that mimics legitimate announcements.
4. Probability ≠ Certainty: An "Extreme Up" signal with 81% probability still implies a 19% chance of failure.
5. Short-Term Focus: The model is blind to long-term trends (days/weeks). It only cares about the next 3 to 30 minutes.

Prerequisites

• Python 3.8+
• NVIDIA GPU (Recommended for optimal performance)

Dependencies

Install the required Python packages:

pip install torch transformers pandas numpy scikit-learn

Important Setup Notes

1. PyTorch Version

It is highly recommended to use PyTorch version 2.10 (pytorch-nightly) to avoid potential compatibility errors.

2. Git LFS & Checkpoints

The model checkpoint file (checkpoints_market_event_multitask/best_model_extreme.pt) is stored using Git Large File Storage (LFS).

• Warning: When cloning the repository, if you do not have Git LFS installed or configured, you may only download a small pointer file instead of the actual model.
• Verification: Check the file size of best_model_extreme.pt. It should be over 400MB.
• Fix: If the file is small (a few KB), please install Git LFS and pull the file, or download the original best_model_extreme.pt manually and replace the pointer file.

Setup & Installation

1. Directory Structure: Ensure your project folder follows this structure:

   /project_root
   ├── public_inference_extreme.py          # Main inference script
   ├── README.md                            # This documentation
   └── checkpoints_market_event_multitask/  # Model artifacts folder
       ├── config.json
       ├── best_model_extreme.pt            # PyTorch model weights
       ├── scaler.pkl                       # Feature scaler
       ├── vocab.txt                        # Tokenizer vocabulary
       └── ... (other tokenizer files)
   

2. Model Weights: Place your trained model files (best_model_extreme.pt, scaler.pkl, etc.) inside the checkpoints_market_event_multitask directory.

Usage

You can run the inference script directly to test various market scenarios:

python public_inference_extreme.py

Integration Example

To use the model in your own trading bot or application:

from public_inference_extreme import ExtremeModelPredictor

# 1. Initialize
predictor = ExtremeModelPredictor("checkpoints_market_event_multitask")

# 2. Prepare Data
tweet_text = "Partnership announcement coming soon! #BTC"
market_features = {
    "feat_ret_1m": -0.005,          # 1-min return (-0.5%)
    "feat_ret_5m": -0.008,          # 5-min return
    "feat_ret_15m": -0.01,          # 15-min return
    "feat_volatility_60m": 0.02,    # Volatility
    "feat_num_trades_60m": 200,     # Number of trades
    "feat_volume_60m": 800000,      # Volume
    "feat_tweet_freq_24h": 20,      # Tweet frequency
    "feat_time_since_prev_tweet": 30,
    "feat_btc_ret_60m": -0.005,     # BTC 1h return
    "feat_btc_ret_24h": -0.02,      # BTC 24h return
    "feat_fear_greed_index": 30,    # Macro: Fear & Greed
    "feat_btc_dominance": 52,       # Macro: BTC Dominance
    "feat_altseason_index": 15      # Macro: Altseason Index
}

# 3. Predict
result = predictor.predict("ProjectName", "SYMBOL", tweet_text, market_features)

print(f"Signal: {result['extreme_signal']}")
print(f"Probabilities: {result['3m_probs']}")

Input Features Explained

The model requires 13 specific features to function correctly.

Important: All numerical features should be passed as raw values. They will be transformed internally using scaler.pkl before inference. Do not manually normalize them.

Feature Name	Description
feat_ret_1m	Price return over the last 1 minute.
feat_ret_5m	Price return over the last 5 minutes.
feat_ret_15m	Price return over the last 15 minutes.
feat_volatility_60m	Standard deviation of returns over the last hour.
feat_num_trades_60m	Total number of trades in the last hour.
feat_volume_60m	Total trading volume in the last hour.
feat_tweet_freq_24h	Number of tweets about the project in the last 24h.
feat_time_since_prev_tweet	Time (seconds) since the last tweet.
feat_btc_ret_60m	Bitcoin price return over the last hour.
feat_btc_ret_24h	Bitcoin price return over the last 24 hours.
feat_fear_greed_index	Crypto Fear & Greed Index (0-100).
feat_btc_dominance	Bitcoin Dominance percentage.
feat_altseason_index	Altcoin Season Index.

Disclaimer: This software is for educational and research purposes only. It does not constitute financial advice. Trading cryptocurrencies involves significant risk.