FastAPI Endpoint Reference

The Signal.Engine API acts as the bridge between the Hybrid Brain (AI/RL models) and the Observatory Dashboard. It provides endpoints for triggering market scans, retrieving real-time trading signals, and managing the simulation environment.

Base Configuration

Default Base URL: http://localhost:8000
Rate Limiting: 120 requests per minute per IP.
CORS: Enabled for all origins (*) to facilitate local development with React/Vite.

🟢 System Health

`GET /`

Check if the API and the internal reasoning engines are online.

Response

{
  "status": "Online",
  "message": "Sniper Agent is Ready."
}

🧠 Market Intelligence

`GET /api/scan`

Triggers the Hybrid Brain to perform a multi-factor analysis on the configured ticker universe (Nifty 500). This process runs as a Background Task to prevent blocking the API.

Responses

200 OK: Scan started successfully.
200 OK: Returns "status": "busy" if a scan is already in progress.

Example Response

{
  "status": "started",
  "message": "Scan triggered in background."
}

`GET /api/results`

Retrieves the most recent signals, simulation portfolio metrics, and system logs. Use this to poll for updates if not using WebSockets.

Decision Object Schema

{
  "Ticker": "RELIANCE.NS",
  "Action": "BUY",
  "Confidence": 0.89,
  "Rational": [
    "LSTM Sequence: Bullish Trend Detected",
    "RSI Oversold Recovery",
    "PPO Agent: High Reward/Risk Ratio"
  ],
  "QuantRisk": {
    "WinRate": 0.68,
    "EV": 1.25,
    "VaR95": -0.02
  }
}

🎮 Simulation Control

`GET /api/simulation/state`

Returns the current state of the Reinforcement Learning simulation environment, including the virtual portfolio.

Example Response

{
  "balance": 102450.50,
  "equity": 105000.00,
  "pnl_pct": 2.45,
  "status": "ACTIVE",
  "open_positions": 3
}

`POST /api/simulation/reset`

Wipes the current simulation state and re-initializes the virtual portfolio to its default starting balance.

Response

{
  "status": "reset",
  "state": { "balance": 100000.00, "status": "ACTIVE", ... }
}

🔌 Real-Time Updates (WebSocket)

The API supports WebSocket connections for low-latency updates. Clients should connect to ws://localhost:8000/ws.

Broadcast Events The server broadcasts a message whenever a background scan completes:

{
  "type": "scan_complete",
  "data": [...],
  "simulation": {...},
  "logs": [...]
}

🛠 Legacy / MVP Endpoints

Note: These are maintained for backwards compatibility with Version 1.0 components.

`GET /prediction`

Returns a single LSTM-based prediction for the hardcoded AAPL ticker.

Returns: PredictionResponse (Ticker, Prediction: UP/DOWN/NEUTRAL, Confidence).

`GET /backtest`

Triggers the src/backtest.py script and returns a success status once the performance chart has been generated in the static directory.