Backend API (FastAPI)

The Backend API serves as the orchestration layer between the trading system's data (stored in SQLite/PostgreSQL) and the React-based frontend dashboard. Built with FastAPI, it provides high-performance REST endpoints for historical analysis and a WebSocket interface for real-time trade monitoring.

Overview

The API is responsible for:

• Retrieving and summarizing backtest reports.
• Providing detailed equity curve data for visualization.
• Exposing agent reasoning and decision logs for every trade.
• Streaming live updates to the dashboard via WebSockets.

The base URL for the API is typically http://localhost:8000.

REST API Reference

Backtests

List All Backtests

GET /api/backtests

Returns a list of all executed backtests, including summary statistics for the sidebar and selection menus.

Response Schema (BacktestSummary):

[
  {
    "id": 1,
    "start_date": "2023-01-01T00:00:00",
    "end_date": "2023-12-31T23:59:59",
    "initial_capital": 10000.0,
    "final_value": 12500.0,
    "total_return_pct": 25.0,
    "total_trades": 42,
    "backend": "ollama"
  }
]

Get Backtest Details

GET /api/backtests/{backtest_id}

Retrieves comprehensive data for a specific backtest, including the time-series data for equity curves and the full trade log with agent reasoning.

Response Schema (BacktestDetail):

• Metrics: Sharpe ratio, Max Drawdown, Win Rate, Alpha vs. Hold.
• equity_curve: List of timestamp, portfolio_value, and btc_price.
• trades: List of individual trade objects (see below).

Trades

Trade Object Schema

The API provides rich metadata for each trade, capturing not just the execution price but the "Why" behind the trade.

Field Descriptions:

• action: BUY, SELL, or HOLD.
• reasoning: The raw text explanation generated by the agent ensemble.
• confidence: An integer (0-100) representing the agent's certainty.

Real-Time Updates (WebSockets)

For live trading or active backtesting, the dashboard maintains a persistent connection to receive immediate updates without polling.

WebSocket Endpoint

WS /ws

Message Format: When a trade is executed by the orchestrator, the backend broadcasts a JSON message:

{
  "type": "trade",
  "data": {
    "id": 123,
    "asset": "BTC",
    "action": "BUY",
    "price": 45000.0,
    "reasoning": "Technical indicators show oversold conditions..."
  }
}

Usage in Frontend: The dashboard uses these messages to trigger a state refresh, ensuring that the metrics and trade tables are always current.

Data Models & Validation

The API uses Pydantic to enforce strict data typing. This ensures that the frontend receives consistent data structures, even when switching between different LLM backends (e.g., Groq vs. Ollama).

Key Response Schemas

| Model | Purpose | | :--- | :--- | | MetricsResponse | Portfolio performance stats (Profit Factor, Alpha, etc.) | | EquityPoint | Individual data points for the performance chart | | TradeResponse | Executed trade details including agent reasoning |

Running the API

The backend is intended to run alongside the main trading orchestrator. To start the development server:

cd dashboard/backend
uvicorn main:app --reload

The Interactive API documentation (Swagger UI) will be available at http://localhost:8000/docs, providing a sandbox to test endpoints and view complete JSON schemas.