Skip to main content
Alpaca is used for (1) trading (place/cancel orders, portfolio, positions, market data in the Trading Dashboard) and (2) historical OHLCV for stock prediction and backtesting when ALPACA_DATA_ENABLED=true. The same API key and secret are used for both; the base URL selects paper vs live.

​
1. Overview

UseService / componentWhen
TradingTradingAPIService → AlpacaTradingAPIServiceALPACA_API_KEY and ALPACA_API_SECRET set. Order placement, cancel, portfolio, positions, market data for Order Form, Portfolio, Market Data tab.
Historical dataMarketDataService → Alpaca StockHistoricalDataClientALPACA_DATA_ENABLED=true and keys set. OHLCV for StockPredictionService and run_backtest_from_data_source.
If Alpaca keys are not set, trading uses MockTradingAPIService. If ALPACA_DATA_ENABLED is false or Alpaca returns no data, market data falls back to yahooquery (see Stock Prediction Setup).

​
1.1 Broker API (Multiuser Brokerage)

For multiuser brokerage (one Alpaca customer account per user), use the Alpaca Broker API:
UseService / componentWhen
Account openingPOST /api/brokerage/account/applyKYC sufficient; creates Alpaca customer account (SUBMITTED → ACTIVE).
Account statusGET /api/brokerage/account/statusReturns user’s Alpaca account status.
DocumentsPOST /api/brokerage/account/documentsWhen status is ACTION_REQUIRED.
TradingAlpacaBrokerTradingAPIServiceWhen user has ACTIVE Alpaca account; orders per account.
Set ALPACA_BROKER_* env vars. See Account Opening and Broker API.

​
2. Configuration

VariableDescriptionDefault
ALPACA_API_KEYAlpaca API key—
ALPACA_API_SECRETAlpaca API secret—
ALPACA_BASE_URLTrading API base. Paper: https://paper-api.alpaca.markets; live: https://api.alpaca.marketshttps://paper-api.alpaca.markets
ALPACA_DATA_ENABLEDUse Alpaca for historical bars in stock prediction and backtesting. When false, MarketDataService uses yahooquery only.false
Broker API (multiuser): ALPACA_BROKER_API_KEY, ALPACA_BROKER_API_SECRET, ALPACA_BROKER_BASE_URL (sandbox: https://broker-api.sandbox.alpaca.markets), ALPACA_BROKER_PAPER.

​
3. Getting Alpaca Credentials

  1. Sign up at Alpaca.
  2. Paper: Paper Dashboard → API Keys.
  3. Live: Live Dashboard → API Keys. Use with care.
Use paper for development. Set ALPACA_BASE_URL=https://paper-api.alpaca.markets for paper and https://api.alpaca.markets for live.

​
4. Trading (Place Order, Portfolio, Market Data Tab)

  • Place order: POST /api/trades/orders — uses AlpacaTradingAPIService when keys are set.
  • Portfolio: GET /api/trades/portfolio — positions and account info from Alpaca.
  • Market data: GET /api/trades/market-data, GET /api/trades/market-data/{symbol} — bid/ask etc. from Alpaca.
Without Alpaca keys, MockTradingAPIService is used: orders are simulated, no real broker calls.

​
5. Historical Data (Stock Prediction and Backtesting)

When ALPACA_DATA_ENABLED=true and keys are set, MarketDataService.get_historical_data uses alpaca.data.StockHistoricalDataClient for 1D, 1H, 15Min. If Alpaca returns nothing, it falls back to yahooquery.
  • Data client: Separate from trading; uses the same ALPACA_API_KEY and ALPACA_API_SECRET.
  • Timeframes: 1D, 1H, 15Min.
  • Used by: StockPredictionService (daily/hourly/15min) and run_backtest_from_data_source.
See Stock Prediction Setup for backtest and prediction config.

​
6. Dependencies

alpaca-py is required for both trading and historical data: 
pip install alpaca-py
The modal image used for Chronos already includes alpaca-py; the FastAPI app needs it when ALPACA_DATA_ENABLED=true or when Alpaca is used for trading.

​
7. Example .env (Paper + Data for Backtest)

# Paper trading
ALPACA_BASE_URL=https://paper-api.alpaca.markets
ALPACA_API_KEY=PK...
ALPACA_API_SECRET=...

# Use Alpaca for stock prediction and backtest OHLCV
ALPACA_DATA_ENABLED=true

​
8. Troubleshooting

IssueCheck
Orders not reaching AlpacaALPACA_API_KEY, ALPACA_API_SECRET, ALPACA_BASE_URL (paper vs live).
”Using mock trading API”Keys missing or invalid; AlpacaTradingAPIService init failed.
No historical bars / backtest “Insufficient data”ALPACA_DATA_ENABLED=true; valid keys; alpaca-py installed. Symbol and date range must have data on Alpaca.
502 Trading API errorAlpaca outage or rate limits; check status.