User Guide
Complete reference for all AlpaTrade commands. Type any command in the terminal on the home page.
Table of Contents
Backtesting
Quick Start
Run a parameterized backtest across multiple strategy configurations:
agent:backtest lookback:1mThis runs the Buy the Dip strategy over the last month using the default 7 symbols (AAPL, MSFT, GOOGL, AMZN, NVDA, TSLA, META) with $10,000 starting capital. The backtester automatically tests multiple parameter combinations and reports the best one.
Parameter Grid
The backtester doesn't run a single configuration — it builds a parameter grid and tests every combination. This is how it finds the optimal strategy parameters for the given time period.
Default grid for Buy the Dip:
| Parameter | Values tested | Count |
|---|---|---|
dip_threshold | 3%, 5%, 7% | 3 |
take_profit | 1%, 1.5% | 2 |
hold_days | 1, 2, 3 days | 3 |
stop_loss | 0.5% | 1 |
position_size | 10% | 1 |
Total combinations: 3 x 2 x 3 x 1 x 1 = 18 variations
Each variation runs a full backtest — fetching price data, simulating entries and exits, calculating P&L, fees, and risk metrics. The best configuration is selected by Sharpe ratio (risk-adjusted return).
Parameters Reference
| Parameter | Default | Description |
|---|---|---|
lookback:1m | 3m | Data period — 1m, 3m, 6m, 1y |
symbols:AAPL,TSLA | 7 large caps | Comma-separated ticker list |
capital:50000 | 10000 | Starting capital ($) |
strategy:buy_the_dip | buy_the_dip | Strategy name |
hours:extended | regular | Include pre/after-market (4AM-8PM ET) |
intraday_exit:true | false | Use 5-min bars for precise TP/SL timing |
pdt:false | auto | Disable Pattern Day Trader rule (for >$25k accounts) |
Examples:
# 1-month backtest, custom symbols
agent:backtest lookback:1m symbols:AAPL,TSLA,NVDA
# 6-month backtest with extended hours
agent:backtest lookback:6m hours:extended
# Large account, no PDT rule, intraday exits
agent:backtest lookback:3m capital:50000 pdt:false intraday_exit:trueReading Results
After a backtest completes, you'll see a results table:
| Metric | What it means |
|---|---|
| Sharpe Ratio | Risk-adjusted return. Higher is better. >1 is good, >2 is excellent |
| Total Return | Percentage gain/loss on initial capital |
| Annualized Return | Return projected to a 1-year basis |
| Total P&L | Dollar profit or loss |
| Win Rate | Percentage of trades that were profitable |
| Total Trades | Number of trades executed across all symbols |
| Max Drawdown | Largest peak-to-trough decline. Lower is better |
The Params line shows which parameter combination won: dip threshold, take profit target, and hold days.
Equity Curve Chart
An interactive Plotly chart renders below the results showing:
- Strategy (blue solid) — your portfolio value over time
- Buy & Hold SPY (orange dashed) — S&P 500 benchmark
- Buy & Hold Portfolio (green dotted) — holding your symbols passively
- Initial Capital (gray dashed) — starting value reference
Hover over the chart to compare values at any date. If the blue line is above the others, the strategy outperformed passive investing.
Paper Trading
Starting a Session
Paper trading runs continuously in the background, placing real orders on Alpaca's paper trading API:
agent:paper duration:7dThis monitors your symbols every 5 minutes for 7 days, executing the Buy the Dip strategy with real market data — but no real money is at risk.
| Parameter | Default | Description |
|---|---|---|
duration:7d | 7d | How long to run — 1h, 1d, 7d, 1m |
symbols:AAPL,MSFT | 7 large caps | Tickers to trade |
poll:60 | 300 | Seconds between strategy checks |
hours:extended | regular | Trade pre/after-market |
email:false | true | Disable daily P&L email reports |
pdt:false | auto | Disable PDT rule |
Monitoring & Stopping
agent:status # check paper trading state
agent:stop # cancel the background sessionPaper trading logs appear in the console. When the session ends, a summary with total trades and P&L is shown.
Email Reports
When enabled (default), a daily P&L summary is emailed via Postmark. Requires POSTMARK_API_KEY, TO_EMAIL, and FROM_EMAIL in your .env file.
Full Cycle
The full cycle chains all phases automatically:
agent:full lookback:1m duration:1mWorkflow:
- Backtest — find the optimal parameters
- Validate — check backtest trades for anomalies
- Paper Trade — deploy the winning config live (paper)
- Validate — verify paper trades against market data
Each phase passes its results to the next. If validation finds issues, it attempts up to 10 self-correction iterations before stopping.
| Parameter | Description |
|---|---|
lookback:3m | Backtest data period |
duration:1m | Paper trading duration |
symbols:AAPL,TSLA | Tickers to trade |
hours:extended | Extended trading hours |
Validation
Validate backtest or paper trade results against real market data:
agent:validate run-id:abc12345
agent:validate run-id:abc12345 source:paper_tradeThe validator checks:
- Price accuracy — do entry/exit prices match actual market data?
- P&L math — is profit/loss calculated correctly?
- Market hours — were trades placed during valid trading hours?
- Weekend trades — no trades should occur on weekends
- TP/SL logic — did take-profit and stop-loss triggers fire correctly?
If anomalies are found, the validator attempts up to 10 self-correction iterations to fix them. After 10 failures, it stops and reports the issues with suggestions.
Reconciliation
Compare your database records against your actual Alpaca account:
agent:reconcile # last 7 days
agent:reconcile window:14d # last 14 daysReports:
- Position mismatches — DB says you hold X shares but Alpaca disagrees
- Missing trades — orders in Alpaca not recorded in DB
- Extra trades — DB trades not found in Alpaca
- P&L comparison — DB total P&L vs Alpaca equity/cash
Research Commands
Market research commands use the command:TICKER syntax. Data is sourced from XAI Grok and Tavily APIs.
News
news:TSLA # company news (default 10 articles)
news:TSLA limit:20 # more articles
news:TSLA provider:xai # force XAI Grok provider
news:TSLA provider:tavily # force Tavily search
news # general market newsReturns headlines with source and date. By default, the system tries XAI first and falls back to Tavily.
Company Profile
profile:TSLACompany overview: sector, industry, market cap, description, and key stats.
Financials
financials:AAPL # annual income & balance sheet
financials:AAPL period:quarterlyRevenue, net income, EPS, debt, and other fundamental data.
Price & Technicals
price:TSLACurrent quote, daily change, volume, 52-week range, and technical indicators.
Market Movers
movers # top gainers and losers
movers gainers # only gainers
movers losers # only losersToday's biggest price movers in the US market.
Analyst Ratings
analysts:AAPLConsensus rating (buy/hold/sell), price targets, and recent analyst actions.
Valuation Comparison
valuation:AAPL # single stock valuation
valuation:AAPL,MSFT,GOOGL # side-by-side comparisonP/E, P/S, P/B, EV/EBITDA, and other valuation multiples. Compare multiple tickers to spot relative value.
Query & Reporting
Trades & Runs
trades # recent trades from DB
runs # recent backtest/paper runsShows tables from the PostgreSQL database with your trade history and run summaries.
Performance Reports
agent:report # summary of recent runs
agent:report run-id:abc12345 # detailed single-run report
agent:report type:backtest # filter by trade type
agent:report strategy:btd # filter by strategy slug prefixThe summary view shows a compact table with return, Sharpe ratio, P&L, and trade count for each run. The detail view shows full metrics for a specific run.
Top Strategies
agent:top # rank all strategy slugs by avg Sharpe
agent:top strategy:btd # filter by slug prefixAggregates across all runs to rank strategy configurations. Shows average Sharpe ratio, return, win rate, drawdown, and how many times each config has been tested.
Options & Flags
These flags can be appended to backtest, paper trade, and full cycle commands.
Extended Hours
agent:backtest lookback:1m hours:extendedRegular hours: 9:30 AM - 4:00 PM ET. Extended hours: 4:00 AM - 8:00 PM ET (pre-market + after-hours). Extended hours backtests include more trading opportunities but may have lower liquidity and wider spreads.
Intraday Exits
agent:backtest lookback:1m intraday_exit:trueWhen enabled, the backtester uses 5-minute intraday bars to determine exactly when take-profit or stop-loss would trigger within each trading day. This is more accurate than daily bars (which only check open/high/low/close) but takes longer to run.
Key behavior: determines which of TP/SL is hit first. No same-day re-entry after exit.
PDT Rule
agent:backtest lookback:1m pdt:falseThe Pattern Day Trader (PDT) rule is a FINRA regulation: accounts under $25,000 are limited to 3 day trades per rolling 5-business-day window. AlpaTrade enforces this by default.
Set pdt:false if your account has $25k+ equity. This removes the day-trade limit and allows the strategy to trade more aggressively.
Need quick help? Type help in the terminal for a compact command reference.