> ## Documentation Index
> Fetch the complete documentation index at: https://tonic-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](stock-prediction-setup.mdx)).

***

## 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](https://docs.alpaca.markets/docs/account-opening) and [Broker API](https://docs.alpaca.markets/docs/about-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](https://alpaca.markets/).
2. Paper: [Paper Dashboard](https://app.alpaca.markets/paper/dashboard/overview) → API Keys.
3. Live: [Live Dashboard](https://app.alpaca.markets/live/dashboard/overview) → 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](stock-prediction-setup.mdx) for backtest and prediction config.

***

## 6. Dependencies

`alpaca-py` is required for both trading and historical data:

```bash theme={null}
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)

```env theme={null}
# 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](https://status.alpaca.markets/).                                  |