Complete Guide: Using AlpacaTradingAgent Web UI for Automated Trading

AaronTrng — Fri, 04 Jul 2025 23:41:26 +0000

⚠️ Important: This system is designed for research and educational purposes. Always start with paper trading mode before risking real money.

🆕 What’s New — AlpacaTradingAgent
🔑 Getting Started: API Keys Setup
⚙️ Environment Setup
🌐 Launching the Web UI
📈 Picking Symbols to Analyze
🧠 Select Analysts
🔍 Research Depth
📈 Understanding Investment vs Trading Modes
⏰ Scheduling Analysis and Trading
⚙️ Automated Trading
🧠 Choosing Your LLMs — Quick vs Deep Thinker
👀 Monitoring Your Operations
💼 Managing Positions and Orders
📊 Reading Reports and Results
🧩 How the Multi-Agent Brain Works
🆘 Troubleshooting Common Issues
🎉 Wrap-Up

🆕 What’s New — AlpacaTradingAgent

Use huygiatrng/AlpacaTradingAgent which was inspired by TauricResearch/TradingAgents and re-engineered **specifically for Alpaca* with an End-of-Day (EOD) focus and a five-agent architecture.*

🚀 Upgrade	Why it matters
Dash-powered Web UI	Modern, reactive dashboard built with Plotly Dash – live charts, tabbed agent reports, manual order buttons, no CLI needed.
Five-agent brain (was four)	• Market (technicals) • News (headline sentiment) • Social (Reddit/Twitter pulse) • Fundamentals (financials & comps) • Macro (FRED data: Fed speeches, CPI, GDP, rates)
EOD-tuned prompts	LLM prompts rewritten around End-of-Day decision-making – less noise from intraday whipsaws, tighter alignment with closing prices.
Debate & 3-layer Risk Gate	Bull vs Bear researchers debate, then three independent Risk-Manager agents vet position size, stop, and exposure before any order routes to Alpaca.
*Stocks and* Crypto**	Analyse and trade `NVDA`, `AAPL`, plus `BTC/USD`, `ETH/USD`, etc. in one batch (crypto data via CoinDesk & DeFi Llama).
Multi-symbol parallel runs	Just type `NVDA, TSLA, ETH/USD` – the stack spins up all agents for each symbol concurrently.
Smart Scheduler	• Continuous loop every N hours (ideal for 24/7 crypto) • Market-hour triggers for equities (e.g. run at 10 AM & 3 PM ET).
Alpaca auto-trade	Full support for paper or live accounts, fractional shares, and margin long/short.
Account dashboard	Real-time buying power, cash, open P/L, and one-click LIQUIDATE for any position.

🔑 Getting Started: API Keys Setup

Before you can use AlpacaTradingAgent's web UI for automated trading, you'll need to obtain API keys from several financial data providers. This section will guide you through each provider step-by-step.

1. 🏦 Alpaca API Keys (Required for Trading and fetching stock chart)

Alpaca is your primary trading broker and the most critical API for this system.

Steps to get Alpaca API Keys:

Visit Alpaca Markets and create an account
Complete the account verification process (this may take 1-3 business days)
Once verified, log into your Alpaca dashboard
Navigate to "API Keys" section in your account settings
Click "Create New Key" and give it a descriptive name like TradingAgent
Copy both the API Key and Secret Key - you'll need both
If you want the agent to be able to perform shorting. You should turn on "Shorting Enabled" in the Alpaca Account's Configuration.

💡 Pro Tip: Keep your API keys secure and never share them publicly!

Important Configuration Notes:

Setting	ALPACA_USE_PAPER	Recommendation	ALPACA_ENDPOINT
Paper Trading	`ALPACA_USE_PAPER=True`	✅ Start here for risk-free testing	`https://paper-api.alpaca.markets/v2`
Live Trading	`ALPACA_USE_PAPER=False`	⚠️ Only when ready to trade real money	`https://api.alpaca.markets`

2. 🤖 OpenAI API Key (Required for AI Analysis)

OpenAI powers the multi-agent analysis system that makes trading decisions.

Steps to get OpenAI API Key:

Go to OpenAI Platform
Create an account or log in to your existing account
Create a project and name it
Navigate to "API Keys" section in "Setting"
Click "Create new secret key"
Give it a name like AlpacaTradingAgent
Copy the generated key immediately (it won't be shown again)

💰 Cost Considerations:

We recommend using gpt-4.1-nano for both quick and deep thinking models during testing, it has the websearch feature and still minimizes costs

The system makes numerous API calls across 5 different agents

Monitor your OpenAI usage dashboard regularly

3. 📰 Finnhub API Key (Required for Stock News)

Finnhub provides real-time financial news and market data.

Steps to get Finnhub API Key:

Visit Finnhub
Create a free account
Verify your email address
Log in and navigate to your dashboard
Your API key will be displayed on the main dashboard page
Copy the key for later use

4. 🏛️ FRED API Key (Required for Macro Analysis)

FRED (Federal Reserve Economic Data) provides macroeconomic indicators.

Steps to get FRED API Key:

Visit FRED API Registration
Click "Request API Key"
Fill out the registration form (it's completely free)
Check your "API Keys" section for the "API Key"
Save the key for configuration

5. ₿ CoinDesk API Key (Required for Crypto Analysis)

For cryptocurrency news and data analysis.

Steps to get CoinDesk API Key:

Visit CryptoCompare
Create an account
Navigate to API Keys section
Generate a new API key
Copy the key for your configuration

⚙️ Environment Setup

1️⃣ Clone the Repository

# Pick a folder and grab the code
git clone https://github.com/huygiatrng/AlpacaTradingAgent.git
cd AlpacaTradingAgent

Tip: Keep the project inside its own folder so the relative paths in the web UI (logs, checkpoints, screenshots) work out-of-the-box.

2️⃣ Create & Activate a Python Environment

# Create a fresh Conda env (recommended)
conda create -n alpacatradingagent python=3.13
conda activate alpacatradingagent

If you prefer venv/virtualenv, that works too—just make sure it’s isolated.

3️⃣ Install Dependencies

# Inside the repo root
pip install -r requirements.txt

# Optional: keep pip itself current
pip install --upgrade pip

You should see all packages install without errors; the heavy ones are dash, plotly, ta, and the OpenAI client.

4️⃣ Configure Your Secrets

Copy the template:

   cp env.sample .env

Edit .env and drop in your keys:

Keep this file private—never commit it to GitHub.

🔒 Security Note: Never commit your .env file to version control or share it publicly!

🌐 Launching the Web UI

🚀 Starting the Application

Launch the web interface using:

python run_webui_dash.py

🖥️ Accessing the Interface

Open your browser
Navigate to http://localhost:7860
You'll see the top with 2 panels which show your current positions and recent orders, which are fetched from your Alpaca account

Below are the config, chart, status, and decision panels, which are set at their default settings.

And the bottom is the reports panel, where we can navigate analysts' reports, debates, and managers' reports of our agent on multiple symbols.

📈 Picking Symbols to Analyze

In AlpacaTradingAgent, you can analyze both stocks and cryptocurrencies using a simple input format. The system will run a full AI-driven analysis on each symbol you specify.

🔤 Symbol Input Format

✅ For stocks: just use the ticker (e.g., NVDA, AAPL, TSLA)
✅ For cryptocurrencies: use the format COIN/USD (e.g., BTC/USD, ETH/USD)

🧠 Tip: Always include /USD for crypto symbols so the agent recognizes them correctly.

💬 Examples:

Input	What It Analyzes
`NVDA, AMD`	Nvidia and AMD (stocks)
`BTC/USD, TSLA`	Bitcoin (crypto) and Tesla (stock)
`ETH/USD, AAPL, SOL/USD`	Ethereum (crypto), Apple (stock), and Solana (crypto)

⚠️ Reminder: Stick to supported formats. Don't use $TSLA or BTCUSD – always enter TSLA, BTC/USD, etc.

🧩 Multi-Asset Support

The system can handle mixed symbol types in a single run:

NVDA, ETH/USD, GOOGL, BTC/USD

Will analyze:

Nvidia (stock)
Ethereum (crypto)
Google (stock)
Bitcoin (crypto)

Once entered, the agents will begin processing each symbol in parallel and deliver tabbed reports with deep insights per asset.

🧠 Select Analysts

Before starting the analysis, you can choose which AI analysts you want to include in the decision-making process. This allows you to tailor the depth and focus of each run based on your strategy.

✅ Analyst Options:

Analyst	Description
Market Analyst	Performs technical analysis on charts, price patterns, and volume indicators
News Analyst	Extracts and evaluates sentiment and impact of recent financial news
Macro Analyst	Analyzes economic indicators (GDP, interest rates, inflation, etc.) from FRED
Social Media Analyst	Tracks sentiment trends on Reddit, Twitter, and other platforms
Fundamentals Analyst	Reviews company financials, balance sheets, P/E ratio, and earnings reports

💡 Customization Tips:

Turn all analysts ON for full-spectrum analysis
Use Market + Fundamentals for traditional investing
Use News + Social Media for short-term sentiment-based trades
Use Macro Analyst for positions affected by economic cycles

🧪 Experiment Freely: You can rerun the analysis with different combinations to compare perspectives.

Once selected, these analysts will generate their individual reports, and the system will automatically synthesize their insights into a final recommendation.

🔍 Research Depth

You can customize how deeply the AI agents debate, analyze, and deliberate before making a recommendation. This affects how long the analysis takes and how thorough the results are.

🧠 Depth Levels:

Mode	Description	Settings	Best For
Shallow	Quick research with minimal discussion	`max_debate_rounds = 1` `max_risk_discuss_rounds = 1`	Fast results without deep debate
Medium	Balanced analysis and agent debate	`max_debate_rounds = 3` `max_risk_discuss_rounds = 3`	General use cases and regular trading
Deep	Full in-depth research with extensive deliberation	`max_debate_rounds = 5` `max_risk_discuss_rounds = 5`	High-stakes decisions and deep dives

⏱️ Trade-off: More depth = more time + more OpenAI usage. Use Shallow for quick checks and Deep when precision matters.

✅ How to Use

Select the Research Depth in the sidebar before clicking Start Analysis
The number of debate and risk discussion rounds will follow your selected depth
Each agent will use the depth to determine how much reasoning to perform before making conclusions

📈 Understanding Investment vs Trading Modes

The AlpacaTradingAgent supports two distinct approaches to market participation:

💎 Investment Mode (Buy/Hold/Sell)

Characteristics:

⏰ Time Horizon: Long-term focus (days to months)
📊 Strategy: Buy and hold approach
🏦 Account Type: Suitable for retirement accounts and cash accounts
🎯 Decisions: BUY, HOLD, or SELL existing positions

💡 Use Cases:

Building long-term wealth
Retirement portfolio management
Low-frequency trading
Risk-averse investors

⚡ Trading Mode (Short/Neutral/Long)

Characteristics:

⏰ Time Horizon: Short-term focus (minutes to days)
📊 Strategy: Active position management
🏦 Account Type: Requires margin account for short selling
🎯 Decisions: SHORT (sell/bet against), NEUTRAL (no position), LONG (buy/bet for)

💡 Use Cases:

Day trading and swing trading
Market timing strategies
Hedging existing positions
Active portfolio management

⚠️ Important: Trading mode requires a margin account and involves higher risk

🏦Turn on margin for Alpaca Paper account:

You can adjust the Max Margin Multiplier inside the Alpaca Paper account Configuration.

⏰ Scheduling Analysis and Trading

The web UI provides two powerful scheduling options for automated analysis and trading that you can turn on if you want:

🔄 Loop Scheduling (Continuous Analysis)

🛠️ Configuration Steps:

Input your symbols (e.g., "NVDA, ETH/USD, AAPL")
Navigate to the "Scheduling Configuration " section in the web UI
Select "Enable Loop Mode"
Set the "Loop Interval" (e.g., 60 for 60 minutes after finished previous analysis)
Enable/disable auto-execution of trades (switch "Trade After Analyze" in "Automated Trading " section)
Click "Start Analaysis"

✨ Features:

✅ Runs continuously (suited best for cryptocurrency trading)

📝 Best Practices:

Start with longer intervals (4-6 hours) for testing
Use paper trading mode initially
Monitor API usage costs with frequent analysis

🕐 Scheduled Analysis (Specific Time during Market hours)

Absolutely! Here's the completed section for ⚙️ Automated Trading, incorporating the two image states you provided:

⚙️ Automated Trading

You can decide whether to manually review analysis results or let the AI automatically place trades based on the final decision.

🖐️ Manual Trading Mode (Default)

When "Trade After Analyze" is turned OFF, the system enters Manual Trading Mode.

📝 Description:

Analysis results will be shown for your review. No trades will be executed automatically.

⚙️ Behavior:

❌ No automatic orders will be placed
👁️ Review analysis results manually
🧑‍💻 Execute trades manually through your broker (e.g., Alpaca dashboard)

💡 Use This Mode If you're testing, learning, or want full control over execution.

🤖 Automated Trading Mode

Turn ON the "Trade After Analyze" toggle to let the agent auto-execute trades based on its final decision.

📝 Description:

The system will execute trades using the specified Order Amount (\$) per symbol.

⚙️ Behavior:

✅ Automatically places trades after analysis finishes
📏 Uses fractional or integer shares (depending on your Alpaca settings)
📈 Executes trades based on strategy and risk assessment
💸 Each symbol will be allocated the full amount you set (e.g., \$4500 per symbol)

📊 Example:

If Order Amount = 200 and NVDA is trading at $150, the system will purchase 1 share (not fractional unless enabled in Alpaca).

💵 Order Amount (\$)

Specify the amount of capital to use per trade. This is applied individually to each symbol being analyzed.

Setting	Example Input	Outcome
`Order Amount = 500`	Symbol = `TSLA ($250)`	Buys 2 shares
`Order Amount = 200`	Symbol = `NVDA ($150)`	Buys 1 share
`Order Amount = 80`	Symbol = `AAPL ($190)`	No trade (unless fractional trading is on)

🧠 Choosing Your LLMs — Quick vs Deep Thinker

Slot	Purpose	What to look for	Recommended Models
Quick Thinker	Fast, surface-level reasoning, headline scraping, fact-gathering. Runs dozens of short calls per analysis.	⚡ Low latency • 🕸️ Built-in web-search	`gpt-4.1-nano` ⭐ (cheapest) `gpt-4.1-mini` `gpt-4.1`
Deep Thinker	Long-form synthesis, weighing evidence, writing structured reports. Runs only a handful of heavier calls.	🧠 High reasoning depth • 🕸️ Web-search optional	`OpenAI o3` 🏆 (best accuracy) `gpt-4.1` family if cost-sensitive

Web-search support: Only the 4.1 family (4.1-nano, 4.1-mini, 4.1) can call the built-in browser tool. That makes them ideal for the Quick Thinker, which needs fresh headlines, Reddit threads, etc.

Practical tips

Budget testing: Set both slots to gpt-4.1-nano. You keep web-search capability at the lowest token price while you shake down the pipeline.
Production blend: Use gpt-4.1-nano (Quick) + o3 (Deep). You’ll pay a bit more per run but gain noticeably tighter reasoning in Researcher debates and Risk reviews.
You can switch models any time in the dropdowns shown above—changes take effect on the very next analysis cycle.

Keep an eye on your OpenAI usage dashboard; the Quick Thinker makes many more calls, so its model choice has the biggest impact on cost.

👀 Monitoring Your Operations

📊 Real-Time Progress Tracking

The web UI provides comprehensive monitoring capabilities:

🎛️ Analysis Report Panel Overview

📺 Simulate Debate of Researchers and Risk Managers

🔄 Real-Time Updates Include:

🤖 Agent decisions and reasoning
📊 Market data updates
📰 News events affecting analyzed symbols
⚠️ Risk management alerts
✅ Trade execution confirmations

💡 Pro Tip: Keep the live feed open to monitor agent decision-making in real-time

💼 Managing Positions and Orders

📈 Current Positions Dashboard

Panel	What you see	What you can do
Open Positions	Symbol, quantity, market value, unrealised P/L	Click LIQUIDATE to close immediately, or open the symbol to adjust protective stops
Recent Orders	Every submission, fill and cancel (status-coloured)	Cancel or duplicate pending orders; click an order row to view the full JSON sent to Alpaca
Buying Power & Cash	Real-time equity, cash and margin headroom	—

The panels refresh automatically every few seconds; no manual reload needed.

📊 Reading Reports and Results

The web UI organizes analysis results into digestible, tabbed reports:

Executive Summary – one-glance recommendation (BUY / HOLD / SELL or LONG / SHORT / NEUTRAL), conviction score and risk rating.
Market Analysis – annotated 1-year candlestick chart with volume, key moving averages and break-out levels.
News & Social – latest headlines with sentiment scores plus Reddit/Twitter mention heat-maps.
Fundamentals – valuation multiples, growth metrics and peer comparison for equities; on-chain and macro drivers for crypto.
Risk Assessment – suggested position size, stop distance and scenario analysis.

🧩 How the Multi-Agent Brain Works

Below is a step-by-step walk-through of the five-layer “think → debate → trade → vet → commit” pipeline illustrated in your schema. Use it as the “how it works” section in your docs.

Stage	Role(s)	What happens
1. Analysts (5 specialists)	• Market Analyst – price/volume via Alpaca + Stockstats • News Analyst – headlines & sentiment (Google News, Finnhub, CoinDesk) • Social-Media Analyst – Reddit pulse + WebSearch • Fundamentals Analyst – earnings, comps (Finnhub, SimFin, DeFi Llama) • Macro Analyst – FRED macro series	Each analyst ingests its data silo, extracts features, and produces a JSON “evidence packet” (metrics, charts, sentiment scores, etc.).
2. Researcher Team	• Bullish Researcher • Bearish Researcher	Both researchers read every evidence packet and argue in an internal Discussion loop (⁠_N_ rounds set by “Research Depth”⁠). - Bull builds the pro case (why to buy/long) - Bear builds the con case (why to sell/short) All arguments cite the analyst evidence, so nothing is “hand-waved.”
3. Research Manager	Single agent	Acts as the referee/critic. Scores each argument for quality, flags missing data, and produces an Executive Research Report summarising: • strongest buy points • strongest sell points • open questions / confidence level
4. Trader (Plan Builder)	Single agent	Converts the Research Report into a Transaction Proposal: • direction (BUY / SELL / LONG / SHORT / NEUTRAL) • tentative size (shares or USD) • stop-loss & take-profit levels • time horizon
5. Risk-Management Team	• Aggressive • Neutral • Conservative	Three independent risk profiles stress-test the proposal (position sizing, VaR, liquidity, correlation). They debate and may scale size up/down or veto trades that breach their limits.
6. Portfolio Manager	Single agent	Reviews the three risk opinions, the trader’s rationale, and current portfolio exposures. Chooses the Final Decision: approve, modify, or cancel.
7. Execution Engine	—	If approved, submits orders to Alpaca, watches fills, and feeds real-time status back to the dashboard.

🆘 Troubleshooting Common Issues

Symptom	Likely cause	Fix
Agents stuck at “PENDING”	OpenAI quota exhausted	Downgrade research depth or raise quota
Orders “REJECTED” by broker	Trade After Analyze on but insufficient buying power	Reduce Order Amount (\$) or deposit funds
Loop never stops	Both Loop Mode and Trade at Market Hour unticked	Click Stop or refresh browser – default is infinite loop when neither scheduler is active

🎉 Wrap-Up

The AlpacaTradingAgent UI gives you an end-to-end command centre for research-grade analysis and one-click execution. After working through this guide you can:

✅ What you can do	Why it matters
Wire up every required API key (Alpaca, OpenAI, Finnhub, FRED, CoinDesk)	Live data, AI brains and broker access all in one place
Lock down the environment with a clean `.env` and an isolated Conda env	Keeps secrets safe and dependencies conflict-free
Flip between Investment ↔ Trading modes	Match the agent’s tactics to your time-horizon and risk profile
Schedule runs — continuous loops, clock-based slots or both	Automate everything from hourly crypto scans to 10 AM & 2 PM equity check-ins
Track progress in real time with colour-coded status, live fills and P/L	No need to refresh — the dashboard streams updates as they happen
Manage positions and orders directly from the UI	Liquidate, scale in/out or tweak stops without leaving the page
Drill into multi-agent reports to see exactly how each specialist reached the call	Transparency beats black-box signals every time

🚀 First flight: start in paper-trading mode with small order sizes. Prove the loop, study the reports, then graduate to live capital when you’re satisfied.

The agent stack is powerful, but it’s still a tool — final responsibility rests with your risk limits and investment plan.

⚠️ Research & Education only. Markets carry risk and past results are not predictive. Do your own due diligence or consult a licensed professional before committing real funds.

Happy trading & clear skies! 🚀📈

Forem: AaronTrng

Complete Guide: Using AlpacaTradingAgent Web UI for Automated Trading

Table of Contents

🆕 What’s New — AlpacaTradingAgent

🔑 Getting Started: API Keys Setup

1. 🏦 Alpaca API Keys (Required for Trading and fetching stock chart)

2. 🤖 OpenAI API Key (Required for AI Analysis)

3. 📰 Finnhub API Key (Required for Stock News)

4. 🏛️ FRED API Key (Required for Macro Analysis)

5. ₿ CoinDesk API Key (Required for Crypto Analysis)

⚙️ Environment Setup

1️⃣ Clone the Repository

2️⃣ Create & Activate a Python Environment

3️⃣ Install Dependencies

4️⃣ Configure Your Secrets

🌐 Launching the Web UI

🚀 Starting the Application

🖥️ Accessing the Interface

📈 Picking Symbols to Analyze

🔤 Symbol Input Format

💬 Examples:

🧩 Multi-Asset Support

🧠 Select Analysts

✅ Analyst Options:

💡 Customization Tips:

🔍 Research Depth

🧠 Depth Levels:

✅ How to Use

📈 Understanding Investment vs Trading Modes

💎 Investment Mode (Buy/Hold/Sell)

⚡ Trading Mode (Short/Neutral/Long)

⏰ Scheduling Analysis and Trading

🔄 Loop Scheduling (Continuous Analysis)

🕐 Scheduled Analysis (Specific Time during Market hours)

⚙️ Automated Trading

🖐️ Manual Trading Mode (Default)

📝 Description:

⚙️ Behavior:

🤖 Automated Trading Mode

📝 Description:

⚙️ Behavior:

📊 Example:

💵 Order Amount (\$)

🧠 Choosing Your LLMs — Quick vs Deep Thinker

Practical tips

👀 Monitoring Your Operations

📊 Real-Time Progress Tracking

🎛️ Analysis Report Panel Overview

📺 Simulate Debate of Researchers and Risk Managers

💼 Managing Positions and Orders

📈 Current Positions Dashboard

📊 Reading Reports and Results

🧩 How the Multi-Agent Brain Works

🆘 Troubleshooting Common Issues

🎉 Wrap-Up