stock-exchange-tracker 0.2.6

A comprehensive stock market tracking tool with AI-powered insights and projection capabilities

Stock Exchange Tracker

A daily stock market tracking tool that automatically identifies promising stocks, fetches market data, and generates insights. Perfect for traders, analysts, or anyone interested in tracking market trends.

What Does It Do?

This tool automatically:

1. Screens major stock indices (S&P 500, NASDAQ-100) to find active, high-volume stocks
2. Fetches real-time market data using official APIs (no scraping!)
3. Analyzes daily changes, identifies top gainers/losers
4. Projects 5-day price targets with buy/sell/hold recommendations
5. Saves results to CSV files and generates summary reports
6. Logs everything for troubleshooting and monitoring

Run time: ~4 minutes per day on the free tier

NEW: Web Dashboard (v0.3.0)

Visual, interactive dashboard is now available! Explore stock data, projections, and recommendations in a modern React interface.

Quick Start:

# Start backend
cd dashboard/backend && python main.py

# Start frontend (in another terminal)
cd dashboard/frontend && npm install && npm run dev

Visit http://localhost:3000 to see it in action!

See Dashboard README for full setup instructions.

---

Quick Start (Beginners Welcome!)

Prerequisites

• Python 3.12 or higher (Download here)
• A free Finnhub API key (Sign up here - takes 2 minutes)

Step 1: Get the Code

git clone https://github.com/lawaloy/stock-exchange-tracker.git
cd stock-exchange-tracker

Step 2: Install

# Create a virtual environment
python -m venv .venv

# Activate it
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# Windows CMD:
.venv\Scripts\activate
# Mac/Linux:
source .venv/bin/activate

# Install the tracker
pip install -e .

Step 3: Add Your API Key

Create a file named .env in the project folder:

FINNHUB_API_KEY=your-api-key-here

(Get your free key from finnhub.io/register)

Step 4: Run It

python main.py

That's it! The tool will:

• Screen 201 stocks from major indices
• Select the top 20 most active stocks
• Fetch detailed data and analyze trends
• Save results to data/daily_data_YYYY-MM-DD.csv

---

What You Get

Output Files

• data/daily_data_YYYY-MM-DD.csv: Full stock data (prices, volume, changes)
• data/summary_YYYY-MM-DD.json: Analysis summary (gainers, losers, statistics)
• logs/stock_tracker_YYYY-MM-DD.log: Detailed execution logs

Console Output

Top 5 Gainers:
  1. MU (Micron Technology): +10.51% @ $315.42
  2. WDC (Western Digital): +8.96% @ $187.70
  ...

Top 5 Losers:
  1. PLTR (Palantir): -5.56% @ $167.86
  ...

Index Performance:
  S&P 500: Avg Change +1.82% (23 gainers | 7 losers)
  NASDAQ-100: Avg Change +0.01% (12 gainers | 18 losers)

---

Running the Tracker (Multiple Ways)

Option 1: CLI Interface (Recommended for Daily Use)

# Main entry point - formatted console output
python main.py

This runs the CLI interface which:

• Shows formatted console output
• Displays top gainers/losers
• Shows index performance
• Prints AI summary (if enabled)

Option 2: Direct CLI Module

# Run CLI module directly
python -m src.cli.commands

Same as Option 1, just a different way to invoke it.

Option 3: Direct Workflow (Programmatic)

# Run workflow without CLI formatting
python -m src.workflows.tracker

This runs the core workflow and returns structured JSON data. Useful for:

• Testing the workflow logic
• Integrating into other Python scripts
• CI/CD pipelines
• Debugging

Option 4: Programmatic Import (Python Scripts)

from src.workflows.tracker import StockTrackerWorkflow

# Run the workflow
workflow = StockTrackerWorkflow()
result = workflow.run(use_screener=True)

# Access structured data
if result["success"]:
    analysis = result["analysis"]
    top_gainers = analysis["top_gainers"]
    ai_summary = result.get("ai_summary")
    # ... use the data in your application

This is ideal for:

• Building a web API
• Creating custom dashboards
• Integrating with other systems
• Scheduled tasks with custom notifications

---

Configuration

What Stocks to Track

Edit config/exchanges.json:

{
  "indices_to_track": [
    "S&P 500",
    "NASDAQ-100"
  ]
}

Screening Filters

Edit config/filters.json to adjust what qualifies as a "good" stock:

{
  "volume_threshold": 1000000,     // Minimum daily volume
  "price_min": 5.0,                 // Minimum stock price
  "price_max": 500.0,               // Maximum stock price
  "min_daily_change_pct": 2.0,      // Minimum % move (filters quiet stocks)
  "market_cap_min": 1000000000,     // Minimum market cap ($1B)
  "top_n": 30                       // How many stocks to track
}

Tip: Lower top_n to run even faster (currently optimized at 20 for ~4 min runs)

---

Production Deployment

Docker

docker build -t stock-tracker:latest .
docker run --rm -e FINNHUB_API_KEY=your-key stock-tracker:latest
# Or: docker run --rm --env-file .env stock-tracker:latest

Schedule daily runs: Use cron (Linux/Mac), Task Scheduler (Windows), or systemd. Example cron:

0 9 * * * docker run --rm -e FINNHUB_API_KEY=$(cat /path/to/key) stock-tracker:latest >> /var/log/stock-tracker.log 2>&1

Docker Compose

services:
  stock-tracker:
    build: .
    environment:
      - FINNHUB_API_KEY=${FINNHUB_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

Kubernetes

Use k8s/stock-tracker-cronjob.yaml as a CronJob. Create secrets first:

kubectl create secret generic stock-tracker-secrets \
  --from-literal=FINNHUB_API_KEY=your-key \
  --from-literal=OPENAI_API_KEY=your-key

Cloud

AWS ECS + EventBridge, GCP Cloud Run + Scheduler, Azure Container Instances + Logic Apps — store keys in secret manager, trigger daily.

Security

• Never commit keys; .env is gitignored
• Use secret stores in production (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault)
• Rotate keys periodically; audit Finnhub usage

---

Understanding the Code

Project Structure

stock-exchange-tracker/
├── main.py                     # Entry point (run this!)
├── src/
│   ├── __init__.py             # Package initialization
│   ├── core/                   # Core utilities
│   │   ├── config.py           # Configuration loader
│   │   └── logger.py           # Logging setup
│   ├── services/               # External data services
│   │   ├── api_client.py       # Finnhub API client (rate limiting, retries)
│   │   ├── index_fetcher.py    # Gets stock lists from indices
│   │   ├── stock_screener.py   # Filters stocks by volume/activity
│   │   └── data_fetcher.py     # Fetches detailed stock data
│   ├── analysis/               # Data analysis & AI
│   │   ├── analyzer.py         # Computes gainers/losers/stats
│   │   └── ai_summarizer.py    # AI-powered market summaries
│   ├── storage/                # Data persistence
│   │   └── data_storage.py     # Saves CSV/JSON files
│   ├── workflows/              # Business logic (reusable)
│   │   └── tracker.py          # Core workflow orchestration
│   └── cli/                    # CLI interface (presentation)
│       └── commands.py         # Command-line interface
├── config/
│   ├── exchanges.json          # Which indices to track
│   └── filters.json            # Screening criteria
├── data/                       # Output files (CSV, JSON)
└── logs/                       # Execution logs

How It Works

1. Index Fetching: Gets stock symbols from S&P 500 (first 100), NASDAQ-100
2. Screening (1 API call per stock): Quick check of price/volume to filter candidates
3. Data Fetching (2 API calls per qualified stock): Get detailed data for top 20 stocks
4. Analysis: Calculate changes, identify trends
5. Storage: Save to CSV/JSON

Rate Limiting

• Free tier: 60 API calls per minute
• Current setup: ~241 total calls (~4 minutes)
• How we stay under limit:
  • Screening uses lightweight 1-call method (quote only)
  • Only 20 qualified stocks get full 2-call fetch (quote + profile)
  • S&P 500 capped at 100 stocks for screening
  • 2 parallel workers with staggered starts
  • Automatic pauses every 25-50 requests

---

Troubleshooting

API key required

• Make sure .env file exists with FINNHUB_API_KEY=your-key
• Check the key is correct (40 characters)
• Restart terminal after creating .env

Rate limit exceeded (429)

• The tool has built-in retry logic
• If it happens frequently:
  • Lower top_n in config/filters.json
  • Wait 5-10 minutes between runs
  • Consider upgrading to Finnhub paid tier

No data fetched

• Check internet connection
• Verify Finnhub API key is valid
• Check logs/stock_tracker_errors_*.log for details

Logs not showing?

• Logs are in logs/ folder (created automatically)
• Console shows INFO level, files show DEBUG level

---

Advanced Topics

AI-Powered Market Summaries (Optional)

By default, the tool generates basic market summaries from templates. Want natural language AI summaries instead? Add OpenAI!

What you get with OpenAI:

Market Summary for YYYY-MM-DD:

Today's market showed strong momentum with technology stocks leading the charge. 
The top gainer, Micron Technology (MU), surged 10.51% on strong earnings expectations, 
while semiconductor stocks broadly outperformed. The S&P 500 averaged a +1.82% gain 
with 23 stocks advancing against only 7 declining, indicating broad-based strength. 
However, select technology stocks like Palantir (PLTR) saw profit-taking with a 
-5.56% decline after recent gains...

What you get without OpenAI (demo mode):

Market Summary for YYYY-MM-DD:
Top gainer: MU +10.51%
Top loser: PLTR -5.56%
Overall market: Mixed with 23 gainers and 7 losers

Setup (takes 3 minutes)

1. Get an OpenAI API key (costs ~$0.01-0.05 per summary):

   • Visit: https://platform.openai.com/signup
   • Add payment method (pay-as-you-go, no monthly fees)
   • Generate API key from: https://platform.openai.com/api-keys

2. Add to your .env file:

   FINNHUB_API_KEY=your-finnhub-key
   OPENAI_API_KEY=sk-proj-your-openai-key-here
   

3. Run normally - AI summaries are automatic!

python main.py

Cost estimate: ~$0.02/day for GPT-4 summaries (< $1/month for daily runs)

Custom Providers

Want to use a different data provider? Edit src/api_client.py to add your provider's API calls.

---

Performance Tips

Run Faster

• Lower top_n: Currently at 20.
• Track fewer indices: Remove one from config/exchanges.json
• Upgrade API tier: Paid Finnhub plans allow more calls/minute

Run Cheaper

• Keep free tier (60 calls/min)
• Run once per day (not multiple times) when the scheduler is enabled
• Use Docker for efficiency

---

FAQ

Q: Is this free?
A: Yes! Finnhub's free tier is sufficient for daily tracking.

Q: Can I track other stocks?
A: Yes, edit config/exchanges.json to add symbols or change indices.

Q: What if I miss a day?
A: Just rerun it. Each run is independent; data is saved with the date.

Q: Can I backtest strategies?
A: This tool focuses on daily snapshots. For backtesting, you'd need historical data (not included).

Q: Is my data private?
A: Yes. All data stays on your machine. API keys never leave your environment.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for detailed guidelines.

Next Priority (by impact):

1. Alert & notification system – Price/screening/recommendation alerts, SNS/email/webhook (design ready; see ALERTING_DESIGN.md)
2. Historical trends – Multi-day data aggregation, projection accuracy tracking, trend charts
3. Additional exchanges, screening filters (RSI/MACD), enhanced AI summaries

Quick Start:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

---

License

MIT License - Free to use, modify, and distribute. See LICENSE for details.

Author

lawaloy - GitHub

---

API Architecture Details

Our API client (src/api_client.py) provides:

• Thread-safe rate limiting: Token bucket algorithm ensures we never exceed 60 calls/min
• Automatic retry: Exponential backoff on failures (1s, 2s, 4s)
• 429 handling: Respects Retry-After headers, resets rate limiter after waits
• Session management: Connection pooling for efficiency
• Two modes:
  • get_stock_data_for_screening(): 1 API call (quote only) - used for screening
  • get_stock_data(): 2 API calls (quote + profile) - used for qualified stocks

This architecture minimizes API calls while maximizing data quality.

---

API Resources

• Finnhub Documentation: https://finnhub.io/docs/api
• API Status: https://finnhub.io/status
• Support: [e-mail]
• Dashboard: https://finnhub.io/dashboard (monitor your usage)

---

Do you need any help?

• Check logs/stock_tracker_errors_*.log for error details
• Review the Troubleshooting section above
• Open an issue on GitHub with log excerpts
• Check Finnhub API status if data fetch fails