Real-Time Stock Market Flash Crash Predictor using Attention-based Deep Learning
FlashGuard is an advanced, real-time stock market crash prediction system. Designed to identify the early warning signs of liquidity sinkholes and algorithmic "flash crashes", it monitors Indian equity markets (NSE/BSE) using live data streams.
Under the hood, FlashGuard leverages a custom Gated Recurrent Unit (GRU) layered with a mathematical Attention Mechanism, processing high-frequency OHLCV (Open, High, Low, Close, Volume) data and sophisticated technical derivatives (volatility, momentum, spreads) to output live probabilistic risk scores.
- 🔴 Real-Time Prediction: Live crash probability scoring utilizing custom Keras algorithms.
- 📡 Upstox API Integration: Tier-1 integration for high-speed live market quoting, with a steady
yFinancefallback. - 🔍 Dynamic Portfolio Scanner: Search through over 5000+ NSE/BSE instruments instantly.
- 📈 Interactive Charting Engine: Immersive, dark-mode terminal UI with interactive candlestick charts showing live market changes.
- 🧠 Explainable AI (XAI) Snapshots: Transparent display of the exact 10 core features (like log returns, rolling volatility, etc.) used to determine current risk bands.
This repository conforms to a professional Machine Learning project standard, explicitly separating the core application from the data engineering pipelines.
flashguard-api/
├── FlashGuard-main/ # 🚀 THE APPLICATION: Flask backend + frontend UI
├── data/ # 📊 DATASETS: Raw minute-level data & historical files
├── docs/ # 📄 RESEARCH: Academic papers & presentation decks
├── legacy/ # 🗑️ ARCHIVE: Sandbox, experimental clones, and old tests
├── models/ # 🧠 MODELS: Pre-trained .keras weight artifacts
├── notebooks/ # 📓 NOTEBOOKS: Jupyter EDA, feature engineering, and analytics
├── scripts/ # ⚙️ SCRIPTS: Model training and standalone anomaly engines
├── .gitignore # GitHub ignores (venv, cache, raw data)
├── LICENSE # MIT License terms
└── README.md # You are here!Running the production FlashGuard server locally is simple.
Ensure you have Python 3.11+ installed on your system.
Navigate directly into the production application folder:
git clone https://github.com/kavanpatel18/flashguard-api.git
cd flashguard-api/FlashGuard-main
# Install all required Python packages
pip install -r requirements.txtStart the real-time API server:
python api_server.py- Landing Page: Access
http://localhost:5000/in your browser. - Active Dashboard: Access
http://localhost:5000/dashboard.htmlto begin predicting.
To experience true real-time parsing, FlashGuard connects to Upstox.
- Create an account at the Upstox Developer Platform.
- Setup a new App and generate an OAuth 2.0 Access Token.
- Paste the token into the FlashGuard Dashboard input field. (Note: If no token is provided, FlashGuard safely falls back to delayed Yahoo Finance quotes or synthetic demonstration data).
For data scientists interested in the underlying algorithms:
- Model Architecture: The core model is an MSA-GRU array (Multi-Scale Attention GRU) built in TensorFlow. It looks across 30 distinct time-steps featuring 10 technical indicators.
- Dataset Generation: Explore
/notebooks/nifty50_flash_crash_dataset_builder.ipynbto see how the raw minute-level datasets (found in/data/) are filtered and engineered. - Retraining: The standalone training files are completely isolated in the
/scripts/folder (e.g.,train_minute.py). Any heavily modified Keras files are outputted directly to the/models/directory for safe versioning.
We welcome contributions to optimize the anomaly detection parameters or expand exchange support.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'feat: Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details. Built natively for highly-efficient stock processing and flash crash detection research.