❓ Help & Documentation

The Strategy, In Plain English

This app watches for stocks that drop sharply at market open, then tracks whether they start recovering. The idea: a stock that opens down hard, keeps falling briefly, then reverses and climbs back above key levels is often showing genuine buying interest stepping in - not just noise.

1. Find it - scan the market for stocks down significantly from yesterday's close.
2. Watch it - track price, volume, and how much of the drop has been recovered.
3. Score it - combine recovery %, volume strength, VWAP position, and RSI into one weighted Reversal Score.
4. Buy it - only when every configured buy condition passes at once (recovery, RSI, volume, score, VWAP, consecutive positive samples).
5. Exit it - stop-loss, trailing stop, profit-lock, or a time-based exit, whichever triggers first.

Getting Started

Logging in

The dashboard is gated behind a single admin token, entered on the Login page. If you don't have the token, ask whoever set up this instance.

First-time setup

1. Log in with the admin token.
2. Go to 📈 Alpaca Setup and enter your Alpaca paper-trading API key/secret (see Connecting Alpaca below). Until you do, the app runs in mock mode with simulated data.
3. Click 📡 Update Watchlist on the dashboard to run a real scan.
4. Review ⚙️ Trading Settings and adjust thresholds to taste - nothing is hardcoded, every parameter is admin-editable.

Dashboard Overview

Key Metrics

Five live tiles: stocks currently on the watchlist, today's buy signals, open positions, total portfolio value, and current unrealized gain/loss across your real Alpaca holdings.

Click any stock symbol

Clicking a symbol row - in the watchlist or in Open Positions - opens a detail view with the reversal chart, a recovery-progress meter, the full buy-condition checklist, an intraday price chart with VWAP/EMA overlays (switchable between 1m/5m/15m/1h), and a 5-minute buy-justification chart.

Action buttons

• 🔄 Refresh Data - reloads whatever is already stored, no new scan.
• 📡 Update Watchlist - triggers a real scan: refreshes existing entries, looks for new candidates, drops recovered stocks, checks buy conditions.
• ⚙️ Trading Settings / 📈 Alpaca Setup - configuration pages, see below.

Managing the Watchlist

The watchlist normally fills itself - the scanner adds real candidates automatically, and only considers stocks within the tradeable price range (Min/Max Price in Trading Settings) - a stock priced outside that range can never actually be bought, so it's excluded at discovery time rather than sitting on the list looking buy-ready when it structurally isn't. You can also manage the list directly:

• Add a symbol manually - type a ticker in the box above the watchlist table and click ➕ Add. Pulls a live snapshot immediately, works for any real symbol.
• Remove a symbol - click 🗑️ Remove in that row's Action column.

Per-stock buy conditions

Click any symbol to open its detail view and scroll to Buy Readiness. Each of the 7 buy conditions shows there with a checkbox and, for the five numeric ones (recovery %, RSI, relative volume, reversal score, positive samples), an editable threshold - these values are per-stock, not global, since a thin small-cap and a mega-cap don't behave the same way. A blue border on the number means it's a custom value for that stock; clear it to fall back to the global default.

A note above the checklist shows where each stock's current values came from: 🤖 Agent analysis means the periodic historical backtest set them (see Trading Settings below), ✏️ Admin edit means a person changed at least one value by hand since. Unchecking a condition excludes it from that stock's auto-buy requirement entirely.

Connecting Alpaca

Go to 📈 Alpaca Setup from the dashboard. You'll need a free Alpaca account and its paper trading API key/secret (found on your Alpaca dashboard, not the live-trading keys).

1. Paste your API Key and Secret.
2. Leave the environment set to Paper Trading (Live Trading isn't supported by this build).
3. Click Test Alpaca API Connection to confirm it works, then Save Credentials.

Credentials are saved to the database, not the browser - they persist across sessions and devices.

Trading Settings

Every parameter the algorithm reads is editable on the ⚙️ Trading Settings page - screening thresholds, reversal-score weights, position sizing, exit rules, and the historical backtest cadence. Buy condition values (recovery %, RSI, volume, reversal score) are set per stock, not globally - see Managing the Watchlist above. A CUSTOM badge marks any setting you've overridden from its default. Each section has its own Save Section button, or use Save All Settings at the bottom.

Relative Volume Condition (global on/off)

In 🛠️ Admin Controls, alongside the master Strategy Enabled switch: turns the relative-volume buy condition off for every stock at once, regardless of what any individual stock's own setting says. A stock's detail view shows this clearly - the condition row greys out with a 🔒 icon and "(off globally)" when this switch is off, so it's obvious the row is auto-passing rather than genuinely clearing its threshold.

Historical Backtest

A background job that periodically re-derives every watchlist stock's buy-condition thresholds from a real simulation against years of that stock's own historical price data - not a guess, an actual test of which threshold values would have produced better outcomes historically, using the same stop-loss/trailing-stop/time-exit rules the live strategy uses. Re-run Every (days) and Lookback (years) control the cadence and how far back it looks. The Historical Backtest Status panel further down the page shows when it last ran and what it changed, and has a ▶️ Run Backtest Now button to trigger one immediately instead of waiting for the schedule.

Position Monitor Offset

Shifts which minutes the 5-minute buy/sell check fires on - offset 1 with the default 5-minute interval fires at :01, :06, :11... instead of :00, :05, :10.... Mainly useful when running more than one instance of this app against the same Alpaca account: staggering their poll times means they never check prices or attempt a trade at the exact same instant.

Public Watchlist (No Login)

The live demo page - and the "Today's Top 10 Watchlist" section on the home page - show real watchlist data with full chart access, no account needed. It's read-only: no settings, no add/remove, no trading. If the market is closed and there's nothing new to show, these pages automatically fall back to the last available data rather than showing a blank table.

FAQ