add paper trading: mark a setup as taken, track open P&L, sell

New paper_trades table (migration 007) + service/router. "Mark as taken" on each
setup card (shares prefilled from position sizing, entry from current price, both
editable) records a simulated trade. Overview gains an Open Trades table that
marks each position to the latest close — P&L in $, %, and R-multiples — with a
total unrealized P&L footer and a Sell button to close at the current price.
Closed trades are retained for future realized-P&L reporting.

Deploy: alembic upgrade (new paper_trades table).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app/main.py

@@ -84,6 +84,7 @@ from app.routers.sr_levels import router as sr_levels_router
 from app.routers.tickers import router as tickers_router
 from app.routers.jobs import router as jobs_router
 from app.routers.market import router as market_router
+from app.routers.paper_trades import router as paper_trades_router
 
 
 def _configure_logging() -> None:
@@ -162,3 +163,4 @@ app.include_router(trades_router, prefix="/api/v1")
 app.include_router(watchlist_router, prefix="/api/v1")
 app.include_router(jobs_router, prefix="/api/v1")
 app.include_router(market_router, prefix="/api/v1")
+app.include_router(paper_trades_router, prefix="/api/v1")

app/models/__init__.py

@@ -9,6 +9,7 @@ from app.models.trade_setup import TradeSetup
 from app.models.watchlist import WatchlistEntry
 from app.models.settings import SystemSetting, IngestionProgress
 from app.models.alert import AlertLog
+from app.models.paper_trade import PaperTrade
 
 __all__ = [
     "Ticker",
@@ -24,4 +25,5 @@ __all__ = [
     "SystemSetting",
     "IngestionProgress",
     "AlertLog",
+    "PaperTrade",
 ]

app/models/paper_trade.py

@@ -0,0 +1,36 @@
+from datetime import datetime
+
+from sqlalchemy import DateTime, Float, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.database import Base
+
+
+class PaperTrade(Base):
+    """A simulated ('taken') trade for paper trading.
+
+    Captured from a setup at the moment the user marks it taken: direction,
+    entry, size, stop and target. Open trades are marked-to-market against the
+    latest close; closing records the exit price and time.
+    """
+
+    __tablename__ = "paper_trades"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    ticker_id: Mapped[int] = mapped_column(
+        ForeignKey("tickers.id", ondelete="CASCADE"), nullable=False
+    )
+    direction: Mapped[str] = mapped_column(String(10), nullable=False)
+    entry_price: Mapped[float] = mapped_column(Float, nullable=False)
+    shares: Mapped[float] = mapped_column(Float, nullable=False)
+    stop_loss: Mapped[float] = mapped_column(Float, nullable=False)
+    target: Mapped[float] = mapped_column(Float, nullable=False)
+    status: Mapped[str] = mapped_column(String(10), nullable=False, default="open")
+    opened_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=datetime.utcnow, nullable=False
+    )
+    close_price: Mapped[float | None] = mapped_column(Float, nullable=True)
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

app/routers/paper_trades.py

@@ -0,0 +1,69 @@
+"""Paper trades router — take, list, and close simulated trades."""
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db, require_access
+from app.models.user import User
+from app.schemas.common import APIEnvelope
+from app.schemas.paper_trade import PaperTradeClose, PaperTradeCreate, PaperTradeResponse
+from app.services import paper_trade_service
+
+router = APIRouter(tags=["paper-trades"])
+
+
+def _resp(trade, symbol: str, current_price=None) -> dict:
+    return PaperTradeResponse(
+        id=trade.id,
+        symbol=symbol,
+        direction=trade.direction,
+        entry_price=trade.entry_price,
+        shares=trade.shares,
+        stop_loss=trade.stop_loss,
+        target=trade.target,
+        status=trade.status,
+        opened_at=trade.opened_at,
+        close_price=trade.close_price,
+        closed_at=trade.closed_at,
+        current_price=current_price,
+    ).model_dump(mode="json")
+
+
+@router.get("/paper-trades", response_model=APIEnvelope)
+async def list_paper_trades(
+    status: str | None = Query(default=None, pattern=r"^(open|closed)$"),
+    user: User = Depends(require_access),
+    db: AsyncSession = Depends(get_db),
+) -> APIEnvelope:
+    rows = await paper_trade_service.list_trades(db, user.id, status=status)
+    data = [PaperTradeResponse(**r).model_dump(mode="json") for r in rows]
+    return APIEnvelope(status="success", data=data)
+
+
+@router.post("/paper-trades", response_model=APIEnvelope, status_code=201)
+async def create_paper_trade(
+    body: PaperTradeCreate,
+    user: User = Depends(require_access),
+    db: AsyncSession = Depends(get_db),
+) -> APIEnvelope:
+    trade = await paper_trade_service.create_trade(
+        db, user.id,
+        symbol=body.symbol,
+        direction=body.direction,
+        entry_price=body.entry_price,
+        shares=body.shares,
+        stop_loss=body.stop_loss,
+        target=body.target,
+    )
+    return APIEnvelope(status="success", data=_resp(trade, body.symbol.strip().upper()))
+
+
+@router.post("/paper-trades/{trade_id}/close", response_model=APIEnvelope)
+async def close_paper_trade(
+    trade_id: int,
+    body: PaperTradeClose,
+    user: User = Depends(require_access),
+    db: AsyncSession = Depends(get_db),
+) -> APIEnvelope:
+    trade = await paper_trade_service.close_trade(db, user.id, trade_id, body.close_price)
+    return APIEnvelope(status="success", data={"id": trade.id, "status": trade.status})

app/schemas/paper_trade.py

@@ -0,0 +1,35 @@
+"""Schemas for paper trades."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class PaperTradeCreate(BaseModel):
+    symbol: str = Field(..., min_length=1, max_length=10)
+    direction: str = Field(..., pattern=r"^(long|short)$")
+    entry_price: float = Field(..., gt=0)
+    shares: float = Field(..., gt=0)
+    stop_loss: float = Field(..., gt=0)
+    target: float = Field(..., gt=0)
+
+
+class PaperTradeClose(BaseModel):
+    close_price: float | None = Field(default=None, gt=0)
+
+
+class PaperTradeResponse(BaseModel):
+    id: int
+    symbol: str
+    direction: str
+    entry_price: float
+    shares: float
+    stop_loss: float
+    target: float
+    status: str
+    opened_at: datetime
+    close_price: float | None = None
+    closed_at: datetime | None = None
+    current_price: float | None = None

app/services/paper_trade_service.py

@@ -0,0 +1,148 @@
+"""Paper-trading service: take, mark-to-market, and close simulated trades."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import and_, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.exceptions import NotFoundError, ValidationError
+from app.models.ohlcv import OHLCVRecord
+from app.models.paper_trade import PaperTrade
+from app.models.ticker import Ticker
+
+
+async def _get_ticker(db: AsyncSession, symbol: str) -> Ticker:
+    normalised = symbol.strip().upper()
+    result = await db.execute(select(Ticker).where(Ticker.symbol == normalised))
+    ticker = result.scalar_one_or_none()
+    if ticker is None:
+        raise NotFoundError(f"Ticker not found: {normalised}")
+    return ticker
+
+
+async def _latest_closes(db: AsyncSession, ticker_ids: set[int]) -> dict[int, float]:
+    """Latest stored close per ticker."""
+    if not ticker_ids:
+        return {}
+    latest = (
+        select(OHLCVRecord.ticker_id, func.max(OHLCVRecord.date).label("md"))
+        .where(OHLCVRecord.ticker_id.in_(ticker_ids))
+        .group_by(OHLCVRecord.ticker_id)
+        .subquery()
+    )
+    stmt = select(OHLCVRecord.ticker_id, OHLCVRecord.close).join(
+        latest,
+        and_(
+            OHLCVRecord.ticker_id == latest.c.ticker_id,
+            OHLCVRecord.date == latest.c.md,
+        ),
+    )
+    result = await db.execute(stmt)
+    return {tid: float(close) for tid, close in result.all()}
+
+
+async def create_trade(
+    db: AsyncSession,
+    user_id: int,
+    *,
+    symbol: str,
+    direction: str,
+    entry_price: float,
+    shares: float,
+    stop_loss: float,
+    target: float,
+) -> PaperTrade:
+    direction = direction.strip().lower()
+    if direction not in ("long", "short"):
+        raise ValidationError("direction must be 'long' or 'short'")
+    if shares <= 0 or entry_price <= 0:
+        raise ValidationError("shares and entry_price must be positive")
+
+    ticker = await _get_ticker(db, symbol)
+    trade = PaperTrade(
+        user_id=user_id,
+        ticker_id=ticker.id,
+        direction=direction,
+        entry_price=entry_price,
+        shares=shares,
+        stop_loss=stop_loss,
+        target=target,
+        status="open",
+        opened_at=datetime.now(timezone.utc),
+    )
+    db.add(trade)
+    await db.commit()
+    await db.refresh(trade)
+    return trade
+
+
+def _to_dict(trade: PaperTrade, symbol: str, current_price: float | None) -> dict:
+    return {
+        "id": trade.id,
+        "symbol": symbol,
+        "direction": trade.direction,
+        "entry_price": trade.entry_price,
+        "shares": trade.shares,
+        "stop_loss": trade.stop_loss,
+        "target": trade.target,
+        "status": trade.status,
+        "opened_at": trade.opened_at,
+        "close_price": trade.close_price,
+        "closed_at": trade.closed_at,
+        # For open trades, mark to market; for closed, the realized exit price.
+        "current_price": current_price if trade.status == "open" else trade.close_price,
+    }
+
+
+async def list_trades(
+    db: AsyncSession,
+    user_id: int,
+    status: str | None = None,
+) -> list[dict]:
+    stmt = (
+        select(PaperTrade, Ticker.symbol)
+        .join(Ticker, PaperTrade.ticker_id == Ticker.id)
+        .where(PaperTrade.user_id == user_id)
+    )
+    if status is not None:
+        stmt = stmt.where(PaperTrade.status == status)
+    stmt = stmt.order_by(PaperTrade.opened_at.desc())
+
+    rows = (await db.execute(stmt)).all()
+    open_ids = {t.ticker_id for t, _ in rows if t.status == "open"}
+    prices = await _latest_closes(db, open_ids)
+    return [_to_dict(t, sym, prices.get(t.ticker_id)) for t, sym in rows]
+
+
+async def close_trade(
+    db: AsyncSession,
+    user_id: int,
+    trade_id: int,
+    close_price: float | None = None,
+) -> PaperTrade:
+    result = await db.execute(
+        select(PaperTrade).where(
+            PaperTrade.id == trade_id,
+            PaperTrade.user_id == user_id,
+        )
+    )
+    trade = result.scalar_one_or_none()
+    if trade is None:
+        raise NotFoundError(f"Paper trade not found: {trade_id}")
+    if trade.status == "closed":
+        raise ValidationError("Trade is already closed")
+
+    if close_price is None:
+        prices = await _latest_closes(db, {trade.ticker_id})
+        close_price = prices.get(trade.ticker_id)
+        if close_price is None:
+            raise ValidationError("No current price available to close at; supply close_price")
+
+    trade.status = "closed"
+    trade.close_price = float(close_price)
+    trade.closed_at = datetime.now(timezone.utc)
+    await db.commit()
+    await db.refresh(trade)
+    return trade