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, andbtc_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, orHOLD.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.