Backend API Reference

The Backend API provides a RESTful interface for accessing backtest results, performance metrics, and real-time trade updates. It is built using FastAPI and serves as the bridge between the trading engine's data storage and the React-based dashboard.

Base Configuration

The default development server runs on: http://localhost:8000

All API responses are returned in application/json format.

REST API Endpoints

Backtests

List All Backtests

Returns a summary list of all executed backtests stored in the database, ordered by creation date (newest first).

• URL: /api/backtests
• Method: GET
• Success Response: List[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

Returns comprehensive performance data for a specific backtest, including the equity curve and individual trade logs with agent reasoning.

• URL: /api/backtests/{backtest_id}
• Method: GET
• Parameters: backtest_id (int)
• Success Response: BacktestDetail

{
  "id": 1,
  "start_date": "...",
  "end_date": "...",
  "total_return_pct": 25.0,
  "sharpe_ratio": 1.8,
  "max_drawdown_pct": -5.2,
  "equity_curve": [
    {"timestamp": "2023-01-01", "portfolio_value": 10000.0, "btc_price": 16500.0}
  ],
  "trades": [
    {
      "id": 101,
      "timestamp": "2023-01-05T10:00:00",
      "asset": "BTC",
      "action": "BUY",
      "price": 16800.0,
      "reasoning": "Technical agent detected RSI oversold condition...",
      "confidence": 85.0
    }
  ]
}

WebSocket API

The system provides a WebSocket endpoint for real-time communication during live trading sessions or active backtest runs.

• URL: ws://localhost:8000/ws

Outgoing Messages

The server pushes JSON messages when specific events occur.

Trade Event

Sent whenever a new trade is executed by the orchestrator.

{
  "type": "trade",
  "data": {
    "id": 102,
    "action": "SELL",
    "asset": "BTC",
    "price": 45000.0,
    "timestamp": "2024-03-20T14:30:00"
  }
}

Data Models (Schemas)

The API uses the following Pydantic models for request/response validation.

TradeResponse

Represents an individual trade execution and the LLM agent's justification.

| Field | Type | Description | | :--- | :--- | :--- | | id | int | Unique identifier for the trade. | | timestamp | string | ISO format timestamp of execution. | | asset | string | Trading pair (e.g., BTC/USD). | | action | string | BUY, SELL, or HOLD. | | price | float | Execution price. | | reasoning | string | Detailed explanation from the multi-agent system. | | confidence | float | Confidence score (0-100) assigned by the lead agent. |

BacktestDetail

The full payload for performance analysis.

| Field | Type | Description | | :--- | :--- | :--- | | total_return_pct | float | Cumulative return for the period. | | sharpe_ratio | float | Risk-adjusted return metric. | | max_drawdown_pct| float | Maximum peak-to-trough decline. | | equity_curve | list | List of EquityPoint objects for charting. | | trades | list | List of TradeResponse objects. |

Error Handling

The API uses standard HTTP status codes:

• 200 OK: Request successful.
• 404 Not Found: The requested backtest ID does not exist.
• 500 Internal Server Error: Database connection issues or processing errors.

Errors are returned with a detail message:

{
  "detail": "Backtest not found"
}