🚀 CrashGuard AI - Enterprise Market Surveillance Platform

pump-and-dump detector + bullish stock predictor**
Real time anomaly detection, social sentiment analysis, and AI powered trading signals

📊 Overview

CrashGuard AI is an enterprise grade market surveillance platform designed to detect fraudulent trading patterns, identify pump-and-dump schemes, and provide AI powered buy/sell recommendations based on:

📈 Technical Analysis: Candlestick patterns, moving averages, volume anomalies, volatility metrics
📱 Social Sentiment: Real time X (Twitter) feeds, Reddit discussions, sentiment scoring
🔍 Anomaly Detection: ML powered Isolation Forest algorithm detecting unusual price/volume behavior
⚠️ Crash Detection: Historical analysis flagging stocks that crashed >70% with visual warnings
💡 AI Signals: Composite scoring engine combining technical + social + momentum indicators
📊 Backtesting: Historical strategy validation with Sharpe ratio, max drawdown, win rate metrics

Target Use Case: Retail traders, risk managers, and institutional investors who need to identify market manipulation before it happens.

✨ Key Features

🎯 Real-Time Market Intelligence

Live Price Monitoring: Current price, 52 week high/low, market cap, volume ratios
Stock Search: Search any publicly traded symbol with instant data retrieval
Professional Dashboard: Dark-themed UI with cyan accents and metric cards

🔴 Crash & Anomaly Detection

Historical Crash Warnings: Flags stocks that lost >70% of value with peak/trough analysis
Real time Anomalies: Detects unusual price jumps (>10%), volume spikes (>3x), gaps (>5%), volatility shifts
Visual Highlighting: Annotated candlestick charts showing crash periods, peaks, and anomaly points
Severity Scoring: Risk stratification (HIGH/MEDIUM/LOW alerts)

📱 Multi Source Social Analysis

X/Twitter Integration: Connects to 8 target accounts (@unusual_whales, @deltaone, @StockMKTNewz, etc.)
Reddit Monitoring: 9 target communities (r/wallstreetbets, r/pennystocks, r/stocks, etc.)
Sentiment Scoring: VADER based compound sentiment (-1 to +1) on all posts
Hype Metrics: Mention volume, engagement rate, author diversity, positive bias tracking

🤖 AI Powered Trading Signals

Composite Scoring: BUY/HOLD/SELL recommendations with confidence % (0-100%)
Bullish Candidates: Ranks stocks by: hype (35%) + sentiment (25%) + momentum (15%) + price (15%) + volume (10%)
Backtesting Engine: Test strategies on historical data; calculate returns, Sharpe ratio, max drawdown, win rate

📊 Technical Indicators

Moving Averages: 20-day, 50-day, 200-day tracking
Volatility Analysis: Daily standard deviation, Bollinger Bands
Volume Ratios: Current vs 20-day average; spike detection
Correlation Analysis: Social sentiment vs price movement correlation

🛠️ Tech Stack

Component	Technology	Purpose
Frontend	Streamlit 1.52.2	Web dashboard UI
Data Collection	yfinance 1.0	Stock price & company data
Social APIs	Tweepy 4.14, PRAW (pending)	X/Twitter & Reddit feeds
ML/Analytics	scikit learn 1.8, pandas 2.3	Anomaly detection, predictions
Visualization	Plotly 6.5	Interactive candlestick charts
Sentiment	VADER (nltk 3.8)	Social post sentiment analysis
Database	SQLite	Historical data persistence
Environment	Python 3.10+	Runtime

📦 Installation

Prerequisites

Python 3.10+
pip (Python package manager)
Git

Clone & Setup

# Clone repository
git clone https://github.com/munadirkhan/CrashGuard-AI.git
cd CrashGuard-AI

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r Setup&Testing/requirements.txt

Environment Configuration

Create a .env file in the root directory:

# Required: X/Twitter API (get from https://developer.twitter.com/)
TWITTER_BEARER_TOKEN=your_bearer_token_here

# Optional: Reddit API (get from https://www.reddit.com/prefs/apps)
REDDIT_CLIENT_ID=your_client_id_here
REDDIT_CLIENT_SECRET=your_client_secret_here
REDDIT_USER_AGENT=CrashGuardAI/0.9

# Optional: NewsAPI (get from https://newsapi.org/)
NEWS_API_KEY=your_api_key_here

Obtaining API Credentials:

X/Twitter: Developer Portal - Create an app, generate Bearer Token
Reddit: App Registration - Create "script" app, use client ID/secret
NewsAPI: NewsAPI Dashboard - Free tier available

🚀 Quick Start

Run the Dashboard

cd "Main Components"
python -m streamlit run app.py

Dashboard will open at: http://localhost:8505

Example Workflows

1. Detect if a Stock Crashed

Search → "OST" or "PHH" → 🔴 CRASH BANNER appears with 70%+ warning

2. Check Real Time Social Sentiment

Tab: "Social Feed" → See latest X posts from monitored accounts + sentiment

3. Get Buy/Sell Signal

Right panel: "🎯 AI Recommendation" → BUY/HOLD/SELL with confidence score

4. Analyze Technical Setup

Chart: Candlestick + moving averages → Spot trends, anomalies, volume spikes

📊 Project Structure

CrashGuard-AI/
├── Main Components/
│   ├── app.py                      # 🎯 Main Streamlit dashboard (PRODUCTION)
│   ├── data_fetcher.py             # Yahoo Finance data collection
│   ├── anomaly_detector.py         # ML-based anomaly detection (Isolation Forest)
│   ├── sentiment_analyzer.py       # NewsAPI sentiment analysis
│   ├── social_data_fetcher.py      # X/Twitter & Reddit data fetching
│   ├── target_sources.py           # Target X accounts & Reddit communities
│   ├── hype_analyzer.py            # Social hype score calculation
│   ├── correlation_engine.py       # Price-to-sentiment correlation & signals
│   └── backtest_engine.py          # Historical strategy backtesting
├── Setup&Testing/
│   ├── requirements.txt            # All dependencies
│   ├── setup_local.py              # Local setup script
│   └── test_system.py              # Validation tests
├── Documentation/
│   ├── README.md                   # (This file)
│   └── deploy.md                   # Deployment guide (Streamlit Cloud)
├── .env                            # API credentials (DO NOT COMMIT)
├── .gitignore                      # Exclude sensitive files
└── setup.py                        # Package configuration

🔑 Core Components Explained

1️⃣ Anomaly Detector (`anomaly_detector.py`)

Detects suspicious trading patterns using:

Rule based checks: Price jumps >10%, volume >3x, gaps >5%, volatility spikes
ML (Isolation Forest): Unsupervised learning on normalized OHLCV features
Output: Severity score (0-100), alert type (pump/dump/volatility), date

2️⃣ Social Data Fetcher (`social_data_fetcher.py`)

Real time social signal collection:

X/Twitter v2 API: Searches tweets from 8 target accounts using symbol filters
Reddit PRAW: Searches 9 target subreddits for discussions
Sentiment: VADER analysis on each post (-1 to +1 compound score)
Fallback: Auto generates realistic mock data if APIs unavailable

3️⃣ Hype Analyzer (`hype_analyzer.py`)

Quantifies social media momentum:

Formula: (post_volume × 0.1) + (sentiment × 0.1) + (engagement × 0.1) + (author_diversity × 0.1) + (time_concentration × 0.02) + (positive_bias × 0.03)
Output: 0-100 hype score; alerts if >60 (suspicious spike)

4️⃣ Correlation Engine (`correlation_engine.py`)

Bridges social signals → price predictions:

Correlation: Computes R-squared between hype trends and price momentum
ML Prediction: Linear/Random Forest regression predicts 2-day price move
Signals: STRONG/MODERATE/WEAK based on predictive score + social metrics
Ranking: Scores stocks for buy/hold/sell based on composite metrics

5️⃣ Crash Detection (in `app.py`)

Historical pattern recognition:

Peak Finding: Identifies all-time high from available data
Drawdown: Calculates % loss from peak to lowest point
Alert: Flags if max drawdown >70% with visual markers on chart
Context: Shows peak date, crash date, severity

📈 How It Works - Complete Flow

User Input (Stock Symbol)
        ↓
yfinance Data Fetch (OHLCV + Company Info)
        ↓
        ├─→ Anomaly Detection (ML + Rules)
        ├─→ Crash Detection (Historical Analysis)
        ├─→ Social Data Fetch (X/Reddit APIs)
        │       ├─→ VADER Sentiment Analysis
        │       └─→ Hype Score Calculation
        └─→ Technical Indicators (MAs, Volatility)
        ↓
Correlation Engine
        ├─→ Price-Sentiment Correlation
        ├─→ ML Price Prediction
        └─→ Trading Signal Generation
        ↓
AI Recommendation Engine
        ├─→ Composite Score (40% sentiment + 30% anomaly + 30% momentum)
        └─→ BUY/HOLD/SELL with % confidence
        ↓
Visualization (Streamlit Dashboard)
        ├─→ Candlestick Chart (with anomalies, crash zones)
        ├─→ Metrics Cards (price, volatility, volume ratio)
        ├─→ Social Feed (latest X/Reddit posts)
        ├─→ Risk Alerts (crash warnings, volume spikes)
        └─→ Backtest Results (historical performance)

🎯 Current Status & Roadmap

✅ Completed (MVP - v0.9)

🔄 In Progress (v1.0)

Reddit API full integration (awaiting user approval)
Real Reddit data collection from 9 target subreddits
Email/SMS alert system (UI ready, backend pending)
Portfolio tracker persistence (session → SQLite)
Advanced technical indicators (RSI, MACD, Bollinger Bands)
News sentiment integration (NewsAPI)
Mobile-responsive UI improvements

🚀 Planned (v1.1+)

Perplexity AI integration (market narrative analysis)
Discord bot for alerts
Telegram bot integration
Options data & Greeks analysis
Institutional fund tracking
Custom watchlist management (persistent storage)
Historical trade logging & performance tracking
Machine learning model fine-tuning (user feedback loop)

📅 Demo Timeline

v0.9 (Current): MVP with core anomaly detection + social signals
v1.0 (Late January): Full Reddit integration + email alerts + backtesting validation
v1.1+ (February+): AI chat, advanced ML models, deployment to Streamlit Cloud

🔐 API Rate Limits & Data Sources

API	Rate Limit	Free Tier	Status
yfinance	~2000/day	✅ Unlimited	✅ Working
X v2 API	450/15min	✅ Included	✅ Connected
Reddit PRAW	60/min	✅ Unlimited	⏳ Awaiting setup
NewsAPI	100/day	✅ Free tier	⚠️ Optional

Note: All APIs have auto-fallback to mock data if unavailable—dashboard never breaks.

💻 Development

Running Tests

cd Setup&Testing
python test_system.py

Local Development

# Install in editable mode
pip install -e .

# Run with debug logging
streamlit run app.py --logger.level=debug

Code Organization

Modular Design: Each analyzer is independent; easy to swap/extend
Caching: yfinance data cached for 5 min; reduces API calls
Error Handling: Graceful degradation with mock data fallback
Type Hints: Python 3.10+ with type annotations for clarity

🌍 Deployment

Streamlit Cloud (Coming Soon)

# 1. Push to GitHub (done ✅)
# 2. Connect GitHub repo to Streamlit Cloud
# 3. Add secrets in Streamlit dashboard:
#    TWITTER_BEARER_TOKEN=...
#    REDDIT_CLIENT_ID=...
#    REDDIT_CLIENT_SECRET=...
# 4. Deploy at: https://crashguard-ai.streamlit.app

See deploy.md for detailed instructions.

📞 Support & Contact

GitHub Issues: Create an issue
Email: rdetonate@gmail.com
Status: Active Development—expect frequent updates & improvements

🙏 Acknowledgments

yfinance: Yahoo Finance data fetching
Streamlit: Rapid web app development
Plotly: Interactive charting
scikit-learn: Machine learning algorithms
VADER: Sentiment analysis
X API & Reddit PRAW: Social data access

📊 Performance Metrics (Backtested)

Metric	7-Day	30-Day	90-Day
Win Rate	65%	58%	62%
Total Return	+3.2%	+7.8%	+11.5%
Max Drawdown	-2.1%	-4.3%	-5.8%
Sharpe Ratio	1.2	1.5	1.8
Trades Generated	3	12	28

Note: Backtested on historical data with simulated social metrics. Past performance ≠ future results.

🚨 Disclaimer

CrashGuard AI is for educational and research purposes only. It is NOT financial advice. Always conduct your own due diligence before trading. The creators are not responsible for financial losses. Use at your own risk.

Made by Munadir Khan
Active Development 2026 | Demo Coming Soon™

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
Documentation		Documentation
Main Components		Main Components
Setup&Testing		Setup&Testing
.gitignore		.gitignore
README.md		README.md
setup.py		setup.py
test_imports.py		test_imports.py

munadirkhan/CrashGuard-AI

Folders and files

Latest commit

History

Repository files navigation