User Guide

Complete reference for all AlpaTrade commands. Type any command in the terminal on the home page.

Backtesting

Quick Start

Run a parameterized backtest across multiple strategy configurations:

agent:backtest lookback:1m

This 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.

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

Reading 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:7d

This 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 session

Paper 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:1m

Workflow:

1. Backtest — find the optimal parameters
2. Validate — check backtest trades for anomalies
3. Paper Trade — deploy the winning config live (paper)
4. 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_trade

The 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 days

Reports:

• 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 news

Returns headlines with source and date. By default, the system tries XAI first and falls back to Tavily.

Company Profile

profile:TSLA

Company overview: sector, industry, market cap, description, and key stats.

Financials

financials:AAPL              # annual income & balance sheet
financials:AAPL period:quarterly

Revenue, net income, EPS, debt, and other fundamental data.

Price & Technicals

price:TSLA

Current quote, daily change, volume, 52-week range, and technical indicators.

Market Movers

movers              # top gainers and losers
movers gainers      # only gainers
movers losers       # only losers

Today's biggest price movers in the US market.

Analyst Ratings

analysts:AAPL

Consensus rating (buy/hold/sell), price targets, and recent analyst actions.

Valuation Comparison

valuation:AAPL              # single stock valuation
valuation:AAPL,MSFT,GOOGL   # side-by-side comparison

P/E, P/S, P/B, EV/EBITDA, and other valuation multiples. Compare multiple tickers to spot relative value.

Query & Reporting

Trades & Runs

trades                       # latest run's trades (current account)
trades paper                 # paper trades only
trades backtest              # backtest trades only
trades paper btd             # paper + strategy slug filter
trades backtest btd-3dp      # backtest + specific slug
trades all                   # all accounts (not just active)
runs                         # recent runs
runs paper                   # paper runs only
runs backtest                # backtest runs only

Filter order: type → slug → run-id (all optional). Add all to see across all linked accounts. Default: current user + active account, latest run.

Performance Reports

report                       # summary of recent runs
report paper                 # paper runs summary
report backtest              # backtest runs summary
report <run-id>              # detailed single-run report
report paper btd             # paper + strategy slug filter
report all                   # all accounts

The 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

top                          # rank strategies (backtest)
top paper                    # rank paper trade results
top paper btd               # paper + slug filter
top all                      # all accounts

Aggregates across all runs to rank strategy configurations by average annualized return. Shows Sharpe ratio, return, win rate, drawdown, and how many times each config has been tested.

Strategy Slugs

Each backtest variation gets a human-readable slug that encodes the strategy type, parameters, and lookback period into a compact identifier. Slugs let you compare configurations at a glance and filter results with agent:top or agent:report.

Format

{strategy}-{param1}-{param2}-...-{lookback}

Units use consistent suffixes: d = days, m = months. Percentages drop the decimal point for fractional values (0.5% becomes 05).

Buy the Dip

Prefix: btd

btd-7dp-05sl-1tp-1d-3m

Token	Meaning
btd	Strategy: buy_the_dip
{n}dp	Dip threshold %
{n}sl	Stop loss %
{n}tp	Take profit %
{n}d	Hold (days)
{period}	Lookback (e.g. 1m, 3m)

Example: btd-7dp-05sl-1tp-1d-3m = 7% dip, 0.5% stop loss, 1% take profit, 1 day hold, 3-month lookback

Momentum

Prefix: mom

mom-20lb-5mt-5d-10tp-5sl-1m

Token	Meaning
mom	Strategy: momentum
{n}lb	Lookback period (days)
{n}mt	Momentum threshold %
{n}d	Hold (days)
{n}tp	Take profit %
{n}sl	Stop loss %
{period}	Lookback

VIX Fear Index

Prefix: vix

vix-20t-on

Token	Meaning
vix	Strategy: vix
{n}t	VIX threshold
{type}	Hold type (e.g. on = overnight)

Box-Wedge

Prefix: bwg

bwg-2r-5ct

Token	Meaning
bwg	Strategy: box_wedge
{n}r	Risk %
{n}ct	Contraction threshold %

Options & Flags

These flags can be appended to backtest, paper trade, and full cycle commands.

Extended Hours

agent:backtest lookback:1m hours:extended

Regular 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:true

When 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:false

The 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.