🪙 CatalystWatch

Advanced AI-Powered Cryptocurrency Market Intelligence Agent.

📖 Read the full write-up: CatalystWatch: AI Agent That Explains Why Crypto Moves

CatalystWatch is an autonomous monitoring agent that identifies significant "catalysts" (volume spikes and price anomalies) across the crypto market. It combines Concurrent Web Scraping, Stateful AI Reasoning (LangGraph), Real-World News Grounding, and Real-time Alerting to provide deep insights into why markets are moving.

---

🚀 Quick Start

1. Environment Setup

Linux / macOS

cd CatalystWatch
chmod +x setup.sh
./setup.sh

Manual Linux Installation (Alternative)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 -m playwright install chromium

Windows (PowerShell)

python -m venv .venv

.\.venv\Scripts\Activate.ps1

pip install -r requirements.txt

python -m playwright install chromium

2. Configure Environment Variables

Create a .env file in the root directory and add the following:

MONGODB_URI="your_mongodb_connection_string"
DATABASE_NAME="CatalystWatch"
GEMINI_API_KEY="your_google_ai_api_key"
DISCORD_WEBHOOK_URL="your_discord_webhook_url"

3. Run the App

source .venv/bin/activate  

python3 -m app.main

---

🛠 Features

• Concurrent Scraping: Uses Playwright to scrape multiple coins simultaneously, reducing cycle time by 80%.
• Agentic Reasoning: Powered by LangGraph & Gemini 2.5 Flash to analyze market context and explain movements.
• News-Grounded Analysis: Pulls real, free headlines (via Google News RSS, no API key required) so the AI's "likely causes" are grounded in actual news instead of guesswork — and explicitly flags Low confidence when no relevant headline is found.
• Smart Storage: MongoDB implementation with compound indexing and automatic TTL (Time-To-Live) cleanup.
• Self-Healing: Robust Discord notification system with exponential backoff and rate-limit handling, plus a graceful fallback alert if the AI analysis step fails.
• Visual Intelligence: Generates structured reports with market signals, recent headlines, and AI-driven confidence scores.

---

📊 Real-world Alert Example

Below is an example of a real-time alert sent to Discord. The agent identifies the catalyst, performs technical analysis, and provides a confidence score based on the data points.

Example of an AI-generated analysis for INJ (Injective Protocol)

---

🔗 How to Get Discord Webhook

Follow these steps to receive alerts in your Discord server:

1. Create a Server: If you don't have one, create a private Discord server.
2. Channel Settings: Go to the settings of the channel where you want alerts.
3. Integrations: Click on "Integrations" and then "Webhooks".
4. New Webhook: Click "New Webhook", name it (e.g., "CatalystBot"), and click "Copy Webhook URL".

Visual Guide:

Go to Channel Settings

Go to Integrations and Create Webhook

Copy the Webhook URL

---

⚙️ Customization

Changing tracked coins

Modify app/config/coins.py to add or remove coin slugs:

COINS = ["bitcoin", "ethereum", "solana"]

Adjusting Retention

Edit app/storage/cleanup.py to change how many historical snapshots are kept:

MAX_SNAPSHOTS_PER_COIN = 200  

News Source

News headlines are fetched for free from Google News RSS in app/context/news.py — no API key needed. If a coin's slug is too generic to search well (e.g. sui, near-protocol), add a better search term to SEARCH_TERM_OVERRIDES in that file:

SEARCH_TERM_OVERRIDES = {
    "near-protocol": "NEAR Protocol crypto",
}

You can also localize results by changing hl/gl/ceid in the request params (defaults to en-US).

---

📂 Project Structure

app/
├── agents/    # LangGraph & LLM logic
├── config/    # App settings & coin list
├── context/   # Data aggregation logic (market stats + free news headlines)
├── detectors/ # Anomaly detection algorithms
├── scraper/   # Concurrent Playwright scraper
├── storage/   # MongoDB & Cleanup logic
└── main.py    # Entry point

---

Built with ❤️ by Malahim Haseeb

---

⚖️ Legal Disclaimer

This project is for educational and research purposes only.

• Scraping: This tool uses automated scraping to gather data. Please be aware that scraping may violate the Terms of Service of certain websites (like CoinMarketCap). Use this tool responsibly and at your own risk.
• Financial Advice: This software does not provide financial advice. Cryptocurrency markets are highly volatile. Always do your own research (DYOR).
• Data Accuracy: Data is provided "as is" and may be subject to lag or inaccuracies from the source.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Powered by Google Gemini, LangGraph & Playwright.