❓ Help & Documentation
How the strategy works and how to use the dashboard.
On This Page
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.
- Find it - scan the market for stocks down significantly from yesterday's close.
- Watch it - track price, volume, and how much of the drop has been recovered.
- Score it - combine recovery %, volume strength, VWAP position, and RSI into one weighted Reversal Score.
- Buy it - only when every configured buy condition passes at once (recovery, RSI, volume, score, VWAP, consecutive positive samples, tradeable price range, and price below its own 5-sample moving average).
- 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
- Log in with the admin token.
- Go to 📈 Alpaca Setup and enter your Alpaca API key/secret (see Connecting Alpaca below). Until you do, the app runs in mock mode with simulated data.
- Click 📡 Update Watchlist on the dashboard to run a real scan.
- 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), a 5-minute buy-justification chart, and a Sample Moving Average chart (see below).
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 8 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.
Sample Moving Average (5-sample)
Further down the same detail view, the Sample Moving Average chart plots the last 10 five-minute scan cycles for that stock: its raw price alongside a rolling 5-sample moving average, sample count on the x-axis. The "Price below 5-sample moving average" buy condition reads the latest point on this chart - it only passes once the current price dips below its own short-term average, confirming a pullback relative to the last 25 minutes of scans rather than chasing a stock that's still climbing. This condition has no per-stock override yet (it's a plain above/below check, not a numeric threshold) and fails closed - it won't pass - until the stock has been through at least one 5-minute cycle.
Connecting Alpaca
Alpaca is the only broker this app supports - there's no code path for Robinhood, Schwab, TD Ameritrade, Interactive Brokers, or anything else. Go to 📈 Alpaca Setup from the dashboard. You'll need a free Alpaca account and an API key/secret pair from it.
- Paste your API Key and Secret, then click Save Credentials.
- Click Test Alpaca API Connection to confirm they authenticate.
Credentials are saved to the database, not the browser - they persist across sessions and devices. Alpaca issues a separate key pair for paper vs. live trading - which one these credentials need to be depends entirely on the Live Trading switch on the same page (see below); pasting a paper key while live trading is on (or vice versa) simply fails to authenticate rather than trading on the wrong account.
Live Trading (Real Money)
By default this app only ever places paper (simulated) trades - no real money is ever at risk unless an admin deliberately turns Live Trading on. This section explains exactly what that switch does.
What flipping it on actually does
It does not add a new, separate "live mode" of the app - it's the exact same automated scanner and buy/sell cycle that already runs every 5 minutes, now submitting real orders to Alpaca's live endpoint instead of the paper one. There is no extra per-trade confirmation once it's on: the very next scheduled cycle can open or close a real position with real money, following whatever Trading Settings (position size, thresholds, stop-loss, etc.) are currently configured.
How to enable it
On the 📈 Alpaca Setup page, under ⚠️ Live Trading: save real, verified live-trading Alpaca credentials first (paper keys won't authenticate against the live endpoint), then type the exact confirmation phrase shown on the page and click Enable Live Trading. This typed-phrase requirement exists specifically because a single checkbox click isn't enough friction for something this consequential.
How to turn it back off
Click Disable Live Trading on the same page - no confirmation phrase needed, since returning to paper trading is always the safe direction. You can also pause all trading entirely (paper or live) at any time via Strategy Enabled in Trading Settings, which also stops the app from polling Alpaca's account/position endpoints in the background.
Every trade tells you which mode it was
If email notifications are set up, every buy/sell email carries a clear 🔴 LIVE - REAL MONEY banner or a 📝 Paper trade note - never ambiguous about which one just happened. The dashboard's top nav also shows a persistent 🔴 LIVE / 📝 PAPER badge whenever real credentials are connected.
⚠️ Only enable live trading once you've reviewed every risk setting on the Trading Settings page (Position Size, Max Positions, Max Daily Trades, Stop Loss %) and are comfortable with what this strategy would do unsupervised with real money. Start small.
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.