MarketHelm

A stock market monitoring and analysis tool (CLI + web dashboard) that screens indices, fetches data, and projects short-term moves—aimed at growing toward suggestions, alerts, and (later) execution. Perfect for traders and analysts building a daily workflow.

Direction: MarketHelm already supports local and hosted multi-user monitoring, projections, and alerts. Broker execution remains a longer-term idea and is not implemented. Read the evidence-based capability matrix in docs/PROJECT_STATUS.md.

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.

Web dashboard

Visual, interactive UI — same pip install market-helm as the CLI. The package includes the FastAPI server and a built React UI (no Node.js needed to use it).

market-helm-web

Open http://localhost:8000 — API docs at /docs.

Develop the React UI (Vite on port 3000): dashboard/README.md.
Hosting and persistence: docs/DEPLOYMENT.md.

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: Install

Create a virtual environment (recommended), then activate it:

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

Install the package—pick one:

• From PyPI (recommended — includes CLI and dashboard):

  pip install market-helm
  

  • Package page: pypi.org/project/market-helm
  • Optional OpenAI summaries: pip install 'market-helm[ai]'

• From source (clone for development or to rebuild the dashboard UI):

  git clone https://github.com/lawaloy/market-helm.git
  cd market-helm
  pip install -e .
  

Step 2: Add Your API Key

Create a .env file where you will run the tool:

FINNHUB_API_KEY=your-api-key-here

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

Step 3: Run It

market-helm          # daily tracker → CSV/JSON under data/
market-helm-web      # web UI + API → http://localhost:8000

If you cloned the repo, you can also run python main.py from the project root.

Each tracker run screens ~201 stocks, selects the top movers, fetches detailed data, and saves data/daily_data_YYYY-MM-DD.csv.

What You Get

More entry points, console examples, and programmatic use: docs/USAGE.md.

Documentation

Full index: docs/README.md

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Next priorities: projection validation/backtesting, external staging sign-off, deeper alert rules, and dashboard quality — details in docs/PROJECT_STATUS.md.

License

MIT License — free to use, modify, and distribute. See LICENSE.

Author

lawaloy — GitHub