Alpaca Trading and Market Data Setup

Configure Alpaca for trading and historical market data in CreditNexus

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

Use	Service / component	When
Trading	TradingAPIService → AlpacaTradingAPIService	ALPACA_API_KEY and ALPACA_API_SECRET set. Order placement, cancel, portfolio, positions, market data for Order Form, Portfolio, Market Data tab.
Historical data	MarketDataService → Alpaca StockHistoricalDataClient	ALPACA_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:

Use	Service / component	When
Account opening	POST /api/brokerage/account/apply	KYC sufficient; creates Alpaca customer account (SUBMITTED → ACTIVE).
Account status	GET /api/brokerage/account/status	Returns user’s Alpaca account status.
Documents	POST /api/brokerage/account/documents	When status is ACTION_REQUIRED.
Trading	AlpacaBrokerTradingAPIService	When user has ACTIVE Alpaca account; orders per account.

Set ALPACA_BROKER_* env vars. See Account Opening and Broker API.

---

2. Configuration

Variable	Description	Default
ALPACA_API_KEY	Alpaca API key	—
ALPACA_API_SECRET	Alpaca API secret	—
ALPACA_BASE_URL	Trading API base. Paper: https://paper-api.alpaca.markets; live: https://api.alpaca.markets	https://paper-api.alpaca.markets
ALPACA_DATA_ENABLED	Use 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

Issue	Check
Orders not reaching Alpaca	ALPACA_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 error	Alpaca outage or rate limits; check status.