Market manipulation is not a victimless crime. It erodes the foundational trust that financial markets depend on to function efficiently, and its consequences ripple far beyond the trading floor.
-
Retail investors lose billions annually to pump-and-dump schemes, where coordinated social media campaigns inflate stock prices before insiders sell off, leaving ordinary investors holding worthless shares. The U.S. Securities and Exchange Commission estimates that microcap fraud alone costs investors $3–5 billion per year.
-
The GameStop saga (January 2021) demonstrated how social media-driven momentum on platforms like Reddit's r/WallStreetBets can create extreme volatility. While some profited, many retail investors who bought at the peak lost over 80% of their investment within weeks.
-
Cryptocurrency pump-and-dump schemes have become rampant, with researchers at the University of Texas finding that 80%+ of ICOs in 2017–2018 showed signs of manipulation, resulting in estimated losses exceeding $1 billion.
-
Confidence erosion: A CFA Institute survey found that 56% of retail investors believe markets are rigged against them, leading to reduced market participation and a widening wealth gap.
Traditional manipulation detection relies on regulatory bodies with limited resources. By the time enforcement actions are taken, the damage is already done. Real-time, AI-powered screening tools like Sussy Scanner aim to give everyday investors the ability to see the same red flags that institutional risk managers monitor, before they become casualties.
"Sunlight is said to be the best of disinfectants." — Louis Brandeis, U.S. Supreme Court Justice
Sussy Scanner is a full-stack market manipulation detector that cross-references real-time stock data with social media activity to flag suspicious behavior patterns. Built for the Hack Brooklyn hackathon, it combines multi-source data ingestion, statistical feature engineering, and Google Gemini–powered AI analysis to produce an explainable, composite risk score for any publicly traded stock.
| Feature | Description |
|---|---|
| 📊 Multi-Score Risk Engine | Five independent sub-scores (Pump Risk, Social Hype, Liquidity Stress, Technical Fragility, Squeeze Pressure) combined into a weighted composite |
| 🤖 AI-Powered Analysis | Google Gemini analyzes social media posts for promotional language, hype signals, and coordinated campaigns |
| 📈 Interactive Charts | TradingView lightweight charts for candlestick/line visualization + Recharts for risk signals and narrative breakdowns |
| 🔍 Similarity Engine | Compares current stock behavior against a database of known historical pump events (GME, AMC, DWAC, BBBY, SMCI) |
| 🧠 Explainable Scoring | Every score includes top contributing features and AI-generated natural language narratives |
| 📰 News Cross-Referencing | Checks whether price moves are backed by credible news or appear "unexplained" |
| 💬 Social Media Aggregation | Aggregates posts from multiple sources (Tavily search, Reddit) with sentiment and hype classification |
| ⏱️ Smart Caching | SQLite-backed caching layer with TTL to avoid redundant API calls and speed up repeat analyses |
| 🗂️ Preset Historical Events | One-click analysis of famous manipulation events (GameStop squeeze, AMC rally, Trump SPAC, etc.) |
The following diagram traces the complete data flow from the moment a user enters a stock ticker to the final rendered analysis dashboard:
flowchart TB
User["👤 User"]
subgraph Frontend ["🌐 Frontend — React + Vite"]
direction LR
FE1["🔍 Ticker Search"]
FE2["📡 API Client<br/>(Axios)"]
FE3["📊 Dashboard Grid<br/>Charts + Panels"]
FE4["🎯 Risk Scores<br/>& Narratives"]
FE5["📈 TradingView<br/>Candlestick Charts"]
FE1 -->|"build request"| FE2 -->|"render components"| FE3 -->|"display scores"| FE4
FE3 -->|"render chart"| FE5
end
subgraph Backend ["🖥️ Backend — Express + Node.js"]
direction LR
BE1["🔀 API Router<br/>+ SQLite Cache"]
BE2["📈 Market Data Fetcher<br/>Yahoo Finance · Finnhub"]
BE3["💬 Social Aggregator<br/>Tavily · Reddit · News"]
BE4["🧮 Feature Vector Builder<br/>Price · Tech · Liquidity · Social · Squeeze"]
BE5["🎯 Scoring Engine<br/>5 Sub-Scores → Composite"]
BE6["🤖 Gemini Post Analyzer<br/>Hype · Sentiment · Narratives"]
BE7["📝 Narrative Generator<br/>Score Explanations"]
BE8["🔗 Similarity Engine<br/>Historical Pump Matching"]
BE1 -->|"fetch market data"| BE2
BE2 -->|"fetch social posts"| BE3
BE3 -->|"compute features"| BE4
BE4 -->|"generate scores"| BE5
BE5 -->|"classify posts"| BE6
BE6 -->|"explain scores"| BE7
BE7 -->|"match history"| BE8
BE8 -->|"assembled analysis"| BE1
end
subgraph External ["🌍 External APIs"]
direction TB
EX1["Yahoo Finance<br/>Price · Volume · Stats"]
EX2["Tavily Search<br/>Social Media Posts"]
EX3["Reddit<br/>r/wallstreetbets"]
EX4["Google Gemini<br/>AI Analysis"]
EX5["Finnhub<br/>Quotes · News"]
EX1 --- EX2 --- EX3 --- EX4 --- EX5
end
%% User → Frontend
User -->|"enters ticker<br/>e.g. GME"| FE1
FE3 -.->|"views dashboard"| User
%% Frontend ↔ Backend
FE2 -->|"GET /api/analysis/:symbol"| BE1
BE1 -->|"JSON scores + narratives"| FE3
%% Backend → External
BE2 -.->|"price, volume, stats"| EX1
BE3 -.->|"social media posts"| EX2
BE3 -.->|"reddit discussions"| EX3
BE2 -.->|"quotes, news"| EX5
BE6 -.->|"classify posts, sentiment"| EX4
BE7 -.->|"generate narratives"| EX4
%% Styling
style Frontend fill:#dbeafe,color:#1e3a5f,stroke:#7aa2f7
style Backend fill:#dcfce7,color:#14532d,stroke:#4ade80
style External fill:#fee2e2,color:#7f1d1d,stroke:#f87171
The composite manipulation risk score is a weighted average of five independent sub-scores, each ranging from 0–100:
┌──────────────────────┬────────┬───────────────────────────────────────────┐
│ Sub-Score │ Weight │ Key Features │
├──────────────────────┼────────┼───────────────────────────────────────────┤
│ 🔴 Pump Risk │ 30% │ Volume z-scores, price gaps, ROC accel. │
│ 🟠 Social Hype │ 25% │ Mention velocity, hype score, spam ratio │
│ 🔵 Liquidity Stress │ 20% │ Float, ADV, market cap, inst. ownership │
│ 🟡 Technical Fragility│ 15% │ RSI, SMA distance, Bollinger breaches │
│ 🟣 Squeeze Pressure │ 10% │ Short % float, days-to-cover, P/C ratio │
└──────────────────────┴────────┴───────────────────────────────────────────┘
| Band | Score Range | Color |
|---|---|---|
| 🟢 LOW | 0–25 | Green |
| 🟡 MEDIUM | 25–50 | Yellow |
| 🟠 HIGH | 50–75 | Orange |
| 🔴 CRITICAL | 75–100 | Red |
The composite applies a stacking floor (when 2+ sub-scores are HIGH, the composite can't fall below their average) and a correlation cap (no single outlier can push the composite more than 15 points above the max sub-score) to prevent dilution or exaggeration.
sussy-scanner/
├── 📂 client/ # React + Vite frontend
│ ├── src/
│ │ ├── components/
│ │ │ ├── AnalysisHeader.jsx # Symbol, date, score badge
│ │ │ ├── DashboardGrid.jsx # Main analysis layout
│ │ │ ├── TradingViewChart.jsx # Candlestick / line chart
│ │ │ ├── SignalsPanel.jsx # Expandable risk scores
│ │ │ ├── NarrativeMixChart.jsx # Social narrative donut
│ │ │ ├── SocialPanel.jsx # Social media posts feed
│ │ │ ├── NewsPanel.jsx # News articles panel
│ │ │ ├── KeyStatsPanel.jsx # Feature value table
│ │ │ ├── ScoreCard.jsx # Individual score display
│ │ │ ├── SimilarityCallout.jsx # Historical match display
│ │ │ └── ...
│ │ ├── routes/
│ │ │ ├── Landing.jsx # Home page with search
│ │ │ └── Analysis.jsx # Analysis dashboard
│ │ ├── services/
│ │ │ └── api.js # Axios API client
│ │ └── styles/
│ │ └── tokens.css # Design tokens
│ └── package.json
│
├── 📂 server/ # Express backend
│ ├── index.js # App entry + route definitions
│ ├── db.js # SQLite connection
│ │
│ ├── 📂 ingestion/ # Data source adapters
│ │ ├── marketData.js # Unified market data facade
│ │ ├── yahooFinance.js # Yahoo Finance quote/stats
│ │ ├── yahooChart.js # Yahoo Finance OHLCV history
│ │ ├── finnhub.js # Finnhub quote/news adapter
│ │ ├── newsService.js # News aggregation
│ │ ├── tavilySearch.js # Tavily social media search
│ │ ├── redditSearch.js # Reddit post search
│ │ └── timestampEnricher.js # Post timestamp normalization
│ │
│ ├── 📂 features/ # Feature engineering modules
│ │ ├── featureVector.js # Feature assembly + ordering
│ │ ├── priceVolumeFeatures.js # Volume z-scores, returns
│ │ ├── technicalFeatures.js # RSI, SMA, Bollinger Bands
│ │ ├── liquidityFeatures.js # Float, ADV, market cap
│ │ ├── squeezeFeatures.js # Short interest, options
│ │ ├── socialFeatures.js # Mentions, hype, sentiment
│ │ └── stats.js # Statistical helpers
│ │
│ ├── 📂 services/ # Business logic
│ │ ├── explainability.js # Main analysis orchestrator
│ │ ├── compositeScore.js # Weighted score aggregation
│ │ ├── pumpRiskScore.js # Pump & dump detection
│ │ ├── socialHypeScore.js # Social media hype scoring
│ │ ├── liquidityScore.js # Liquidity stress scoring
│ │ ├── techFragilityScore.js # Technical fragility scoring
│ │ ├── squeezeScore.js # Short squeeze scoring
│ │ ├── scoringHelpers.js # Severity + band utilities
│ │ ├── geminiClient.js # Gemini API client
│ │ ├── geminiAnalyzer.js # AI post classification
│ │ ├── geminiNarrator.js # AI narrative generation
│ │ ├── similarityEngine.js # Historical event matching
│ │ └── cache.js # SQLite TTL cache
│ │
│ ├── 📂 data/ # Reference datasets
│ │ ├── pump_anchors.json # Known pump event features
│ │ └── preset_squeeze.json # Preset analysis events
│ │
│ └── package.json
│
├── .env.example # Environment template
└── package.json # Root workspace config
- Node.js ≥ 18
- npm ≥ 9
- API keys for:
- Tavily (required — social media search)
- Google AI Studio (required — Gemini API)
- Finnhub (optional — enhanced market data)
# 1. Clone the repository
git clone <repo-url>
cd "Hack Brooklyn"
# 2. Install all dependencies (root + server + client)
npm run install:all
# 3. Configure environment variables
cp .env.example .env
# Edit .env with your API keys
# 4. Start development servers (both client + server)
npm run devThe app will be available at:
- 🖥️ Frontend:
http://localhost:5173(Vite dev server) - ⚙️ Backend:
http://localhost:3001(Express API)
| Variable | Required | Description |
|---|---|---|
TAVILY_API_KEY |
✅ | Tavily search API key for social media ingestion |
GEMINI_API_KEY |
✅ | Google AI Studio API key for Gemini/Gemma model |
GEMINI_MODEL |
❌ | Model ID (default: gemma-3-27b-it) |
FINNHUB_API_KEY |
❌ | Finnhub API key for enhanced market data |
PORT |
❌ | Server port (default: 3001) |
CACHE_DB_PATH |
❌ | SQLite cache path (default: ./cache.sqlite) |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Health check + model info |
GET |
/api/analysis/:symbol |
🔥 Full analysis — scores, features, AI narratives, similarity |
GET |
/api/similarity/:symbol |
Historical pump event similarity match |
GET |
/api/timeline/:symbol |
Price + volume + social velocity time series |
GET |
/api/presets |
List of preset historical events |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/stock/quote/:symbol |
Real-time quote |
GET |
/api/stock/history/:symbol |
OHLCV history (?period1=&period2=&interval=1d) |
GET |
/api/stock/stats/:symbol |
Key statistics (market cap, float, etc.) |
GET |
/api/stock/search?q= |
Symbol search / autocomplete |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/social/:symbol |
Social media posts (?date=&window=7) |
GET |
/api/news/:symbol |
News articles (?date=&window=7) |
All endpoints support an optional date query parameter for historical analysis (e.g., ?date=2021-01-27).
The app ships with pre-configured famous market events for instant analysis:
| Ticker | Date | Event |
|---|---|---|
| 🎮 GME | 2021-01-27 | GameStop short squeeze |
| 🎬 AMC | 2021-06-02 | AMC ape rally |
| 🏛️ DWAC | 2021-10-22 | Trump SPAC pump |
| 🛏️ BBBY | 2022-08-16 | Bed Bath & Beyond meme revival |
| 💻 SMCI | 2024-03-08 | Super Micro AI spike |
- Social Post Collection — Tavily and Reddit APIs gather recent social media posts mentioning the stock
- Pre-filtering — Posts are pre-screened using regex patterns for clearly benign (earnings, SEC filings) or clearly suspicious ("to the moon", "diamond hands") language
- Gemini Batch Analysis — Remaining posts are sent to Google Gemini in batches of 5, classified for:
- Promotional language detection
- Hype score (0–1)
- Urgency signals
- Sentiment (bullish/bearish/neutral)
- Narrative categorization (meme_hype, short_squeeze, coordination_signal, etc.)
- Narrative Generation — Gemini generates one-line explanations for each risk sub-score
- Similarity Matching — The assembled feature vector is compared against known historical pump events using cosine similarity
This project was built for Hack Brooklyn and is intended for educational and research purposes. Market data is sourced from public APIs; this tool does not constitute financial advice.
Built with 🔍 by the Sussy Scanner team @ Hack Brooklyn