Architecture guide · Updated 2026-05-29

How to Build an LLM-Driven Paper Trading Agent

Most "AI trading" tutorials show you a ChatGPT prompt fed to a broker API and call it an agent. That's not an agent — it's a script with extra hallucination risk. A real LLM trading agent has five distinct layers, each with its own failure modes. This guide covers the full architecture AlgoDrill's agentic-AI module teaches — before you risk a single dollar of real capital.

Architecture Overview

The five layers of an LLM paper-trading agent, in dependency order:

Layer 1 — Data Ingestion

The LLM doesn't read raw prices — it reads a representation of prices you construct. Your feature engineering is the most important design decision in the stack. A model that receives raw OHLCV values has no meaningful baseline; a model that receives normalized ratios and regime labels can apply its pattern-recognition training productively.

# Build a normalized feature vector from OHLCV data
def build_feature_vector(ohlcv: pd.DataFrame, window: int = 20) -> dict:
    close = ohlcv["close"]
    returns = close.pct_change().dropna()
    return {
        "symbol": "ESZ4",
        "date": close.index[-1].isoformat(),
        "return_1d":      round(returns.iloc[-1], 4),
        "return_5d":      round(close.iloc[-1] / close.iloc[-5] - 1, 4),
        "return_20d":     round(close.iloc[-1] / close.iloc[-20] - 1, 4),
        "vol_20d":        round(returns.tail(20).std() * (252**0.5), 4),
        "price_vs_20ma":  round(close.iloc[-1] / close.tail(20).mean() - 1, 4),
    }

Key considerations for feature engineering:

• Lookback bias: if today's feature uses today's close, you've already seen the move. Use yesterday's close for everything except the current bar's signal — this is the single most common overfitting mistake in LLM trading systems.
• Normalization: LLMs handle percentages and ratios far better than raw prices. 0.023 is more meaningful to the model than 4,523.00.
• Context window budget: the feature dict above is roughly 150 tokens. Passing 20 days of raw OHLCV is 3,000+ tokens per symbol — expensive and often counterproductive. Start sparse; add features only when you can measure their impact on signal quality from your paper ledger.

Recommended paper data sources: Polygon.io (REST + WebSocket), Alpaca paper trading API, IBKR paper account. All provide free or low-cost access to real tick data without real-money risk.

Layer 2 — LLM Signal Generation

This layer takes the feature vector and returns a typed trading decision. The critical design choice is structured output: force the LLM to return a JSON object with fixed fields, not free prose. Without it you're parsing natural language — and you will get parse errors on exactly the bars where the model is most uncertain.

# Define the typed schema the LLM must output
from pydantic import BaseModel
from enum import Enum

class Direction(str, Enum):
    long  = "long"
    short = "short"
    flat  = "flat"   # "I don't know" is a valid signal

class TradeSignal(BaseModel):
    symbol:          str
    direction:       Direction
    confidence:      float        # 0.0–1.0; calibrate against realized win rate
    rationale:       str          # logged for debugging, never acted on mechanically
    stop_loss_pct:   float        # fraction of entry price to place stop
    take_profit_pct: float        # fraction of entry price to place target

SYSTEM_PROMPT = """
You are a quantitative trading signal generator. Given a feature vector for a futures
instrument, output a structured JSON trading signal matching the TradeSignal schema.
Base your decision only on the provided features — do not speculate about news,
fundamentals, or information not in the feature vector. When uncertain, set direction
to 'flat' rather than forcing a directional view.
"""

def generate_signal(features: dict, model: str = "claude-sonnet-4-6") -> TradeSignal:
    # Use structured output / tool_use to enforce schema — never "return JSON" in prompt
    response = llm_client.chat(
        system=SYSTEM_PROMPT,
        user=json.dumps(features, indent=2),
        response_format=TradeSignal,
    )
    return response

Prompt engineering lessons from the first 100 paper trades:

• Explicit schema enforcement beats "return JSON" in the prompt. Use tool use or native structured output — the model cannot accidentally return malformed output if the schema is enforced at the API layer.
• Log the rationale field. It's free information about why your agent is wrong when it's wrong. The rationale is the debugger; never drop it.
• One symbol per call (at first). Batching multiple symbols in one prompt invites attention diffusion. Start with one symbol per LLM call; measure whether batching improves or degrades calibration before adopting it.
• Temperature: start at 0 for determinism. Raise it only after you've established a signal baseline at temperature=0. Ensemble-style randomness requires at least 5× more data to evaluate.
• Model selection: Claude Sonnet and GPT-4o are both strong starting points. Local models (Mistral, Llama-3.1) are cost-free for paper trading but require more prompt engineering to produce reliably structured output.

Layer 3 — Execution State Machine

The execution layer processes signals and maintains a paper position ledger. It is entirely deterministic code — no LLM involvement. This is not an aesthetic choice: deterministic execution is what lets you reason about, backtest, and audit your agent's behavior. Anything that touches positions or capital must be reproducible from a log.

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class Position:
    symbol:     str
    direction:  Direction
    entry_price: float
    size_usd:   float       # Kelly-constrained
    stop_loss:  float
    take_profit: float
    opened_at:  datetime

class PaperLedger:
    def __init__(self, starting_capital: float, kelly_frac: float = 0.25):
        self.capital         = starting_capital
        self.starting_capital = starting_capital
        self.kelly_frac      = kelly_frac   # quarter-Kelly by default — see note below
        self.positions: dict[str, Position] = {}
        self.trades:    list[dict]          = []
        self.equity_curve: list[float]      = [starting_capital]

    def open_position(self, signal: TradeSignal, price: float):
        # Kelly fraction × confidence × capital = position size
        size_usd = self.capital * self.kelly_frac * signal.confidence
        self.positions[signal.symbol] = Position(
            symbol=signal.symbol, direction=signal.direction,
            entry_price=price, size_usd=size_usd,
            stop_loss  = price * (1 - signal.stop_loss_pct),
            take_profit= price * (1 + signal.take_profit_pct),
            opened_at  = datetime.utcnow(),
        )

    def process_bar(self, symbol: str, price: float):
        if symbol not in self.positions: return
        pos = self.positions[symbol]
        is_long   = pos.direction == Direction.long
        hit_stop  = price <= pos.stop_loss   if is_long else price >= pos.stop_loss
        hit_target= price >= pos.take_profit  if is_long else price <= pos.take_profit
        if hit_stop or hit_target:
            self._close(symbol, price)

    def _close(self, symbol: str, exit_price: float):
        pos = self.positions.pop(symbol)
        pnl_pct = (exit_price - pos.entry_price) / pos.entry_price
        if pos.direction == Direction.short: pnl_pct = -pnl_pct
        pnl_usd = pos.size_usd * pnl_pct
        self.capital += pnl_usd
        self.equity_curve.append(self.capital)
        self.trades.append({"symbol": symbol, "pnl": pnl_usd, "exit": exit_price})

Key execution design decisions:

• Quarter-Kelly (0.25× Kelly): full Kelly is theoretically optimal but maximizes variance. A 25% Kelly fraction cuts volatility by ~75% (variance by ~94%) while retaining roughly 44% of the full-Kelly growth rate — a trade worth making when the sizing inputs are uncertain. Start here; raise it only with a live Sharpe above 1.5 and 200+ paper trades.
• Flat on no signal: when the LLM returns direction: flat, close any existing position in that symbol. "I don't know" is a valid signal and should be respected mechanically.
• No partial fills in paper mode: assume fills at the exact trigger price. Before graduating to live trading, add a slippage model — at minimum 0.05% per fill for liquid futures, 0.1–0.3% for less-liquid instruments.

Layer 4 — Performance Feedback Loop

After at least 30 trades, compute performance metrics from the ledger and inject them into the LLM's context as a system prompt addition. This closes the loop: the model sees its own realized performance and can adjust its signal calibration.

def build_feedback_context(ledger: PaperLedger) -> str:
    trades = ledger.trades
    if len(trades) < 30:
        return ""   # too few to measure; don't inject noise
    returns  = [t["pnl"] / ledger.starting_capital for t in trades]
    sharpe   = compute_sharpe(returns)
    mdd      = compute_max_drawdown(ledger.equity_curve)
    exp      = compute_expectancy(trades)
    return f"""
## Your Recent Performance ({len(trades)} paper trades)
- Sharpe ratio:   {sharpe:.2f}  (>1.0 = good; <0.5 = weak signal)
- Max drawdown:   {mdd:.1%}    (<10% = controlled; >20% = review stop logic)
- Expectancy:     ${exp:.2f}/trade  (positive = edge exists; negative = stop and debug)
Recalibrate confidence and stop-loss levels if max drawdown > 15% or expectancy < 0.
"""

Layer 5 — Guardrails

Guardrails are hard constraints enforced at the code level, inside the execution state machine. They run after the LLM generates a signal and before any order is submitted. The LLM cannot override them — this is the design invariant that prevents a rogue prompt from blowing up a paper account (and, eventually, a live one).

class RiskGuardrails:
    MAX_POSITION_PCT  = 0.10   # never risk >10% of capital on one position
    DAILY_LOSS_LIMIT  = 0.05   # halt today if P&L drops below -5%
    MAX_OPEN          = 5      # never hold more than 5 positions simultaneously
    MIN_CONFIDENCE    = 0.55   # reject signals with confidence < 55%

    def check(self, signal: TradeSignal, ledger: PaperLedger) -> bool:
        if signal.confidence < self.MIN_CONFIDENCE:
            return False              # below threshold — skip, don't trade
        if len(ledger.positions) >= self.MAX_OPEN:
            return False              # too many open positions
        today_pnl_pct = ledger.today_pnl / ledger.capital
        if today_pnl_pct <= -self.DAILY_LOSS_LIMIT:
            return False              # daily circuit breaker — stop for today
        return True

The daily circuit breaker is the most important guardrail. If the LLM enters a bad regime — hallucinating structure where there is none, or reacting to prompt-injected "instructions" in market data — the circuit breaker caps the maximum single-day paper loss at 5%. Never deploy to a live account without every guardrail from your paper session intact. Add new guardrails before going live; never remove them.

What LLMs Are Actually Good At in Trading

Where they add value

• Multi-factor reasoning: a good LLM can integrate momentum + volatility regime + macro factor in one prompt in ways that rule-based systems require separate code for each combination. The advantage is breadth, not depth.
• Diverse data types: structured features, news text, fundamental ratios, and sentiment signals can all coexist in one prompt. For an LLM, the cost of adding a new data modality is one new key in the feature dict.
• Rationale as debugging: the rationale field is a free audit trail. When your agent is wrong, the rationale tells you whether it misread momentum, misjudged vol regime, or produced a response that suggests prompt injection.

Where they underperform

• Precise arithmetic: always compute metrics (Sharpe, Kelly, expectancy) in deterministic code and pass the result to the LLM. Never ask the model to calculate numerical values — it will hallucinate plausible-looking numbers.
• Long-term memory: the context window is not persistent. The model doesn't remember yesterday's decision unless you include it explicitly. Your ledger and feedback context are the model's only memory.
• Calibrated confidence: LLM-reported confidence scores tend to be overconfident. Calibrate the model's confidence against its realized win rate from the paper ledger before using confidence for position sizing. A model that says 0.85 confidence but wins 55% of the time should be treated as 0.55.
• Consistency: the same prompt with temperature > 0 produces different signals. This is a feature for ensemble approaches and a bug for single-signal systems. Build your evaluation around the distribution of signals, not individual outputs.

Common Failure Modes

Getting Started

The fastest path to your first paper-trade loop:

1. Open an Alpaca paper trading account — free, instant approval, REST + WebSocket API.
2. Build the feature vector for one symbol (S&P 500 futures or SPY is a good baseline — liquid, well-understood, easy to find educational backtests against).
3. Write the structured-output LLM call with a minimal system prompt. Iterate the prompt until you get directional signals, not just flat.
4. Build the paper ledger and guardrails first, before writing the signal loop. Guardrails must exist before the agent runs — not as an afterthought.
5. Run 30+ paper trades. Compute Sharpe, expectancy, and max drawdown. Only then should you adjust any layer.

AlgoDrill's flashcard drills cover the concepts behind each layer: Kelly Criterion for sizing, Sharpe and Sortino for signal evaluation, drawdown math for guardrail calibration, and backtesting health for detecting overfitting. Use the live calculators on the homepage to validate each layer's metrics as you build.

All code examples are for educational paper-trading purposes; past paper performance does not predict live results.