feat(backtest): Alpaca historical data source for equities (Stage C)

Adds BacktestAlpacaSource so saved trade plans for US equities can be
backtested without manual CSV upload. Mirrors the existing Kraken
loader pattern.

Backend:
  + backend/src/backtest/data/alpacaLoader.ts
      loadDatasetFromAlpaca({ symbols, fromTs, toTs, feed, adjustment })
      - Uses the existing @alpacahq/alpaca-trade-api SDK
      - Fetches 15Min bars; normalize.ts aggregates 1h/4h
      - 50-day warm-up lookback so ProEngine has enough EMA/RSI history
      - Throws cleanly with config guidance if ALPACA_API_KEY missing
      - In-memory cache keyed by (symbol, window, feed, adjustment)
  ~ backend/src/backtest/types.ts
      + BacktestAlpacaSource interface
      + 'alpaca' added to BacktestDataSource and BacktestDataSourceType
  ~ backend/src/backtest/data/loadHistoricalData.ts
      Wires 'alpaca' source into the dispatcher

Frontend:
  ~ web/src/backtest/types.ts — adds 'alpaca' to BacktestDataSourceType
  ~ web/src/backtest/components/BacktestConfigurator.tsx
      + 'alpaca' as a SourceType option
      + AUTO_FETCH_SOURCES list — kraken AND alpaca skip the upload-required
        validation
      + 'Alpaca (US equities)' option in the source-picker dropdown
      + Source-picker change handler seeds default IEX/raw Alpaca payload

Tests:
  + testBacktestEngine.ts: new "alpaca data source dispatcher" assertion
    Verifies the type discriminator + error message without hitting
    the network. 11/11 regression checks pass.

Caveats (documented in alpacaLoader inline + ENGINE_READINESS.md §3.4):
  - Free IEX feed has limited symbol coverage (~2016+)
  - SIP feed (paid) needed for full pre-2017 + full-market historical
  - The loader graceful-fails when credentials aren't configured
  - Existing Alpaca live-trading connector unchanged — backtest uses
    its own SDK instance with a different fetch path

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

backend/src/backtest/data/alpacaLoader.ts

@@ -0,0 +1,145 @@
+import Alpaca from '@alpacahq/alpaca-trade-api';
+import { config } from '../../config/index.js';
+import logger from '../../utils/logger.js';
+import type { BacktestRawCandle, HistoricalDataset } from '../types.js';
+import { buildDatasetFromRows, normalizeRawCandles } from './normalize.js';
+
+const FIFTEEN_MINUTES_MS = 15 * 60 * 1000;
+const DEFAULT_PAGE_LIMIT = 10_000;
+
+export interface AlpacaLoaderInput {
+    symbols: string[];
+    fromTs: number;
+    toTs: number;
+    /** Alpaca data feed: 'iex' (default, free) or 'sip' (paid, full market). */
+    feed?: 'iex' | 'sip';
+    /** Adjustment for splits/dividends. 'raw' | 'split' | 'dividend' | 'all'. */
+    adjustment?: 'raw' | 'split' | 'dividend' | 'all';
+    disableCache?: boolean;
+}
+
+const symbolCache = new Map<string, BacktestRawCandle[]>();
+
+const toIso = (timestamp: number): string => new Date(timestamp).toISOString();
+
+/**
+ * Fetch 15m bars for a single symbol over a window using Alpaca's v2 data API.
+ * Throws with a useful message if Alpaca isn't configured. Always emits 15m
+ * raw rows; the normalizer aggregates 1h/4h downstream.
+ *
+ * Free Alpaca tier serves IEX-only historical data, which has limited symbol
+ * coverage and starts ~2016 for major symbols. SIP feed (paid) is required
+ * for full pre-2017 coverage and full-market data. See
+ * docs/backtest/ENGINE_READINESS.md §3.4.
+ */
+const fetchSymbolRows = async (
+    client: any,
+    symbol: string,
+    fromTs: number,
+    toTs: number,
+    feed: 'iex' | 'sip',
+    adjustment: 'raw' | 'split' | 'dividend' | 'all',
+    disableCache: boolean
+): Promise<BacktestRawCandle[]> => {
+    const cacheKey = `${symbol}|15Min|${fromTs}|${toTs}|${feed}|${adjustment}`;
+    if (!disableCache) {
+        const cached = symbolCache.get(cacheKey);
+        if (cached) return [...cached];
+    }
+    const formatted = symbol.replace('/', '');
+    const out: BacktestRawCandle[] = [];
+    const generator = client.getBarsV2(formatted, {
+        timeframe: '15Min',
+        start: toIso(fromTs),
+        end: toIso(toTs),
+        feed,
+        adjustment,
+        limit: DEFAULT_PAGE_LIMIT,
+    });
+    for await (const bar of generator) {
+        const ts = new Date(bar.Timestamp).getTime();
+        if (!Number.isFinite(ts)) continue;
+        if (ts < fromTs || ts > toTs) continue;
+        out.push({
+            symbol,
+            timeframe: '15m',
+            timestamp: ts,
+            open: bar.OpenPrice,
+            high: bar.HighPrice,
+            low: bar.LowPrice,
+            close: bar.ClosePrice,
+            volume: bar.Volume,
+        });
+    }
+    if (out.length === 0) {
+        throw new Error(
+            `Alpaca returned no 15Min bars for ${symbol} in window ${toIso(fromTs)} → ${toIso(toTs)} ` +
+            `(feed=${feed}). Free IEX feed has limited coverage; consider SIP (paid) for full history.`
+        );
+    }
+    out.sort((a, b) => Number(a.timestamp) - Number(b.timestamp));
+    if (!disableCache) symbolCache.set(cacheKey, [...out]);
+    return out;
+};
+
+export const loadDatasetFromAlpaca = async ({
+    symbols,
+    fromTs,
+    toTs,
+    feed = 'iex',
+    adjustment = 'raw',
+    disableCache = false,
+}: AlpacaLoaderInput): Promise<HistoricalDataset> => {
+    const apiKey = config.ALPACA_API_KEY;
+    const apiSecret = config.ALPACA_API_SECRET;
+    if (!apiKey || !apiSecret) {
+        throw new Error(
+            'Alpaca backtest source requires ALPACA_API_KEY and ALPACA_API_SECRET. ' +
+            'Free tier (IEX feed) has limited historical depth; SIP feed (paid) recommended for ' +
+            'pre-2017 coverage and full-market equity data. See docs/backtest/ENGINE_READINESS.md §3.4.'
+        );
+    }
+
+    const uniqueSymbols = Array.from(new Set(
+        (symbols || [])
+            .map((s) => String(s || '').trim().toUpperCase())
+            .filter(Boolean)
+    )).sort((a, b) => a.localeCompare(b));
+    if (!uniqueSymbols.length) {
+        throw new Error('Alpaca loader requires at least one symbol.');
+    }
+    if (!Number.isFinite(fromTs) || !Number.isFinite(toTs) || toTs < fromTs) {
+        throw new Error('Invalid replay window for Alpaca loader.');
+    }
+
+    const client = new (Alpaca as any)({
+        keyId: apiKey,
+        secretKey: apiSecret,
+        paper: config.PAPER_TRADING,
+    });
+
+    // Warm the window with a small look-back so the strategy engine has enough
+    // 4h candles for its EMA/RSI windows. Mirrors krakenLoader's lookbackCandles
+    // pattern but expressed in time (4h × 300 ≈ 50 days).
+    const warmupMs = 50 * 24 * 60 * 60 * 1000;
+    const fetchFromTs = Math.max(0, fromTs - warmupMs);
+
+    const allRows: BacktestRawCandle[] = [];
+    for (const symbol of uniqueSymbols) {
+        try {
+            const rows = await fetchSymbolRows(client, symbol, fetchFromTs, toTs, feed, adjustment, disableCache);
+            allRows.push(...rows);
+        } catch (err) {
+            logger.error(`[AlpacaLoader] ${symbol}: ${(err as Error).message}`);
+            throw err;
+        }
+    }
+
+    const normalized = normalizeRawCandles(allRows);
+    return buildDatasetFromRows(normalized);
+};
+
+/** Test-only: clear in-memory cache. Not exported in production builds. */
+export const __clearAlpacaCacheForTests = (): void => {
+    symbolCache.clear();
+};

backend/src/backtest/data/loadHistoricalData.ts

@@ -3,6 +3,7 @@ import { InlineReplayAdapter } from './exchangeReplayAdapter.js';
 import { loadDatasetFromCsv } from './csvLoader.js';
 import { loadDatasetFromJsonPayload } from './jsonLoader.js';
 import { loadDatasetFromKraken } from './krakenLoader.js';
+import { loadDatasetFromAlpaca } from './alpacaLoader.js';
 import { selectDatasetForReplayWindow } from './normalize.js';
 
 const parseIsoDate = (value: string, field: string): number => {
@@ -40,6 +41,18 @@ const loadBaseDataset = async (request: BacktestRequest): Promise<HistoricalData
             disableCache: source.payload?.disableCache === true
         });
     }
+    if (source.type === 'alpaca') {
+        const fromTs = parseIsoDate(request.dateRange.from, 'from');
+        const toTs = parseIsoDate(request.dateRange.to, 'to');
+        return loadDatasetFromAlpaca({
+            symbols: request.symbols,
+            fromTs,
+            toTs,
+            feed: source.payload?.feed,
+            adjustment: source.payload?.adjustment,
+            disableCache: source.payload?.disableCache === true,
+        });
+    }
     throw new Error(`Unsupported backtest data source: ${(source as { type?: string })?.type || 'unknown'}`);
 };
 

backend/src/backtest/types.ts

@@ -3,7 +3,7 @@ import type { Candle } from '../connectors/types.js';
 export type BacktestMode = 'backtest';
 export type BacktestTimeframe = '1m' | '15m' | '1h' | '4h';
 export type BacktestOrderType = 'market' | 'limit';
-export type BacktestDataSourceType = 'csv' | 'json' | 'replay' | 'kraken';
+export type BacktestDataSourceType = 'csv' | 'json' | 'replay' | 'kraken' | 'alpaca';
 export type BacktestWindowClosePolicy = 'OPEN_AT_END' | 'FORCE_CLOSE';
 export type BacktestIntraCandlePolicy = 'stop_loss_first' | 'take_profit_first' | 'ohlc_path';
 export type BacktestTriggerTimeframe = 'off' | '1m';
@@ -54,7 +54,16 @@ export interface BacktestKrakenSource {
     };
 }
 
-export type BacktestDataSource = BacktestCsvSource | BacktestJsonSource | BacktestReplaySource | BacktestKrakenSource;
+export interface BacktestAlpacaSource {
+    type: 'alpaca';
+    payload?: {
+        feed?: 'iex' | 'sip';
+        adjustment?: 'raw' | 'split' | 'dividend' | 'all';
+        disableCache?: boolean;
+    };
+}
+
+export type BacktestDataSource = BacktestCsvSource | BacktestJsonSource | BacktestReplaySource | BacktestKrakenSource | BacktestAlpacaSource;
 
 export interface BacktestExecutionConfig {
     initialCapitalUsd: number;

backend/testBacktestEngine.ts

@@ -313,6 +313,48 @@ try {
     pass('empty candle dataset throws explicit error');
 } catch (e) { fail('empty data error', e); }
 
+// ---------------------------------------------------------------------------
+// Test 8 — Alpaca data source plumbing (without hitting the network)
+//
+// Stage C added BacktestAlpacaSource. We can't call the real Alpaca API in a
+// test, but we can verify the type discriminator + dispatcher routing by
+// asserting that a malformed Alpaca request fails with the expected error.
+
+try {
+    const previousKey = config.ALPACA_API_KEY;
+    const previousSecret = config.ALPACA_API_SECRET;
+    config.ALPACA_API_KEY = '';
+    config.ALPACA_API_SECRET = '';
+    let caught: unknown = null;
+    try {
+        await runBacktest({
+            mode: 'backtest',
+            symbols: ['AAPL'],
+            timeframe: '15m',
+            dateRange: { from: '2024-01-01T00:00:00Z', to: '2024-01-31T00:00:00Z' },
+            dataSource: { type: 'alpaca', payload: { feed: 'iex' } },
+            execution: {
+                initialCapitalUsd: 10000, orderType: 'market', slippageBps: 5,
+                feeBps: 10, partialFillPct: 1, fillOnNextBar: true,
+                intraCandlePolicy: 'ohlc_path', triggerTimeframe: '1m',
+                forceCloseAtWindowEnd: false,
+            },
+            strategyConfig: { enabled: true, symbol: 'AAPL', riskPerTrade: 0.02, maxPositions: 1 },
+        } as BacktestRequest);
+    } catch (e) {
+        caught = e;
+    }
+    config.ALPACA_API_KEY = previousKey;
+    config.ALPACA_API_SECRET = previousSecret;
+    assert.ok(caught instanceof Error, 'Alpaca source without credentials throws');
+    assert.match(
+        (caught as Error).message,
+        /ALPACA_API_KEY/i,
+        'error message names the missing env var'
+    );
+    pass('alpaca data source dispatcher routes correctly + errors clearly');
+} catch (e) { fail('alpaca dispatcher', e); }
+
 // ---------------------------------------------------------------------------
 
 config.ENABLE_BACKTEST = originalFlag;

web/src/backtest/components/BacktestConfigurator.tsx

@@ -9,7 +9,8 @@ import { parseSymbolsInput, toDateInputValue } from '../utils';
 import { Button, Input, Select } from '../../components/ui/Primitives';
 import { HistoricalPresetPicker } from './HistoricalPresetPicker';
 
-type SourceType = 'csv' | 'json' | 'replay' | 'kraken';
+type SourceType = 'csv' | 'json' | 'replay' | 'kraken' | 'alpaca';
+const AUTO_FETCH_SOURCES: SourceType[] = ['kraken', 'alpaca'];
 
 interface BacktestConfiguratorProps {
     profileId?: string;
@@ -96,7 +97,7 @@ const defaultTo = toDateInputValue(now);
             setError('To date must be greater than or equal to From date.');
             return;
         }
-        if (sourceType !== 'kraken' && !sourcePayload) {
+        if (!AUTO_FETCH_SOURCES.includes(sourceType) && !sourcePayload) {
             setError('Please upload historical data (CSV/JSON/Replay JSON) before running.');
             return;
         }
@@ -122,7 +123,14 @@ const defaultTo = toDateInputValue(now);
                         exchange: 'kraken',
                         lookbackCandles: Number(krakenLookbackCandles || 2000)
                     }
-                    : (sourceType === 'csv' ? String(sourcePayload || '') : sourcePayload)
+                    : sourceType === 'alpaca'
+                        ? {
+                            // IEX is the free Alpaca feed (limited symbols, ~2016+).
+                            // SIP requires paid subscription but covers full market + earlier history.
+                            feed: 'iex',
+                            adjustment: 'raw',
+                        }
+                        : (sourceType === 'csv' ? String(sourcePayload || '') : sourcePayload)
             },
             execution: {
                 initialCapitalUsd: Number(initialCapital || 0),
@@ -306,10 +314,14 @@ const defaultTo = toDateInputValue(now);
                     <Select
                         value={sourceType}
                         onChange={(event) => {
-                            setSourceType(event.target.value as SourceType);
+                            const next = event.target.value as SourceType;
-                            if (event.target.value === 'kraken') {
+                            setSourceType(next);
+                            if (next === 'kraken') {
                                 setSourcePayload({ exchange: 'kraken' });
                                 setSourceName('Kraken historical API');
+                            } else if (next === 'alpaca') {
+                                setSourcePayload({ feed: 'iex', adjustment: 'raw' });
+                                setSourceName('Alpaca historical API (IEX, free tier)');
                             } else {
                                 setSourcePayload(null);
                                 setSourceName('');
@@ -320,7 +332,8 @@ const defaultTo = toDateInputValue(now);
                             { value: 'csv', label: 'CSV' },
                             { value: 'json', label: 'JSON' },
                             { value: 'replay', label: 'Replay JSON' },
-                            { value: 'kraken', label: 'Kraken Historical API' },
+                            { value: 'kraken', label: 'Kraken (crypto)' },
+                            { value: 'alpaca', label: 'Alpaca (US equities)' },
                         ]}
                     />
                 </label>

web/src/backtest/types.ts

@@ -1,5 +1,5 @@
 export type BacktestTimeframe = '1m' | '15m' | '1h' | '4h';
-export type BacktestDataSourceType = 'csv' | 'json' | 'replay' | 'kraken';
+export type BacktestDataSourceType = 'csv' | 'json' | 'replay' | 'kraken' | 'alpaca';
 export type BacktestWindowClosePolicy = 'OPEN_AT_END' | 'FORCE_CLOSE';
 export type BacktestIntraCandlePolicy = 'stop_loss_first' | 'take_profit_first' | 'ohlc_path';
 export type BacktestTriggerTimeframe = 'off' | '1m';