Last Updated: 2026-05-03 Owner: API-Dev Summary: API contract reference for the QuantMatrix backend endpoints, payloads, and error conventions.

QuantMatrix API Reference Document¶

This document defines the primary API contracts for QuantMatrix.

Its purpose is to: - make backend interfaces explicit - give frontend and backend a shared contract - reduce ambiguity around request and response formats - support implementation, testing, and operations

This is a product-oriented reference, not a generated OpenAPI export. Use it together with the Implementation Specification and Data Dictionary.

1. API Principles¶

QuantMatrix APIs should follow these principles: - all endpoints must be environment-aware - live trading actions must be clearly distinguishable from paper or demo actions - responses should be stable and explicit - error responses should be structured - read APIs should prefer normalized internal models over raw broker payloads - dangerous write operations should be guarded and auditable

2. Base Conventions¶

Base Path¶

Suggested base path: /api

Content Type¶

application/json

Time Format¶

ISO 8601 UTC timestamps

Example: - 2026-05-03T09:31:00Z

Standard Response Envelope¶

Recommended shape for most endpoints:

{
  "ok": true,
  "data": {},
  "meta": {
    "mode": "PAPER",
    "timestamp": "2026-05-03T09:31:00Z"
  }
}

Standard Error Envelope¶

{
  "ok": false,
  "error": {
    "code": "RISK_BLOCKED",
    "message": "Max daily loss threshold exceeded",
    "detail": {
      "rule": "MAX_DAILY_LOSS"
    }
  },
  "meta": {
    "mode": "PAPER",
    "timestamp": "2026-05-03T10:45:00Z"
  }
}

3. Health and System Endpoints¶

`GET /api/health`¶

Purpose: - quick health status for the whole platform

Response fields: - status - mode - components

Example response:

{
  "ok": true,
  "data": {
    "status": "HEALTHY",
    "mode": "PAPER",
    "components": {
      "api": "HEALTHY",
      "redis": "HEALTHY",
      "postgres": "HEALTHY",
      "data_broker": "HEALTHY",
      "execution_broker": "HEALTHY",
      "risk_manager": "HEALTHY"
    }
  }
}

`GET /api/health/components`¶

Purpose: - detailed per-component health for the Risk & Health screen

Response fields per component: - name - status - latency_ms - last_ok_at - detail

4. Dashboard and Account Endpoints¶

`GET /api/dashboard/summary`¶

Purpose: - aggregate summary for the Command Center top widgets

Response fields: - buying_power - equity - realized_pnl - unrealized_pnl - system_health

Example response:

{
  "ok": true,
  "data": {
    "buying_power": 25000.0,
    "equity": 50250.25,
    "realized_pnl": 450.1,
    "unrealized_pnl": -32.4,
    "system_health": "HEALTHY"
  }
}

`GET /api/account/summary`¶

Purpose: - full account summary from execution broker

Response fields: - buying_power - equity - cash - margin_available - day_pnl - realized_pnl - unrealized_pnl - broker_name - account_status

`GET /api/account/performance`¶

Purpose: - symbol-level performance summary for the Account screen

Query params: - session_id optional - date optional

Response: - array of rows

Row fields: - symbol - realized_pnl - unrealized_pnl - trades

5. Momentum Radar Endpoints¶

`GET /api/radar/momentum`¶

Purpose: - fetch current Momentum Radar rows

Query params: - top_n optional

Response row fields: - symbol - price - percentage_gain - change_1m - change_5m - sector - float - volume - average_volume - captured_at

`POST /api/radar/watch`¶

Purpose: - add a radar symbol to the Active Strategy Watchlist

Request body:

{
  "symbol": "AAPL",
  "source": "MANUAL"
}

Response fields: - symbol - watchlist_status - time_added

`POST /api/radar/block`¶

Purpose: - block a symbol from trading

Request body:

{
  "symbol": "AAPL",
  "block_scope": "TODAY",
  "reason": "Manual operator block"
}

Response fields: - symbol - block_scope - effective_from - expires_at

6. Watchlist Endpoints¶

`GET /api/watchlist`¶

Purpose: - fetch Active Strategy Watchlist rows

Query params: - status optional - sort optional, default time_added_desc

Response row fields: - symbol - current_price - time_added - time_closed - time_completed - strategy_status - strategy_id - strategy_version - polling_status

`POST /api/watchlist/stop`¶

Purpose: - stop a strategy for a symbol or candidate

Request body:

{
  "symbol": "AAPL",
  "reason": "Manual operator stop"
}

Response fields: - symbol - previous_status - new_status

`POST /api/watchlist/restart`¶

Purpose: - restart strategy processing for a symbol

Request body:

{
  "symbol": "AAPL"
}

Response fields: - symbol - strategy_status - polling_status

7. Positions Endpoints¶

`GET /api/positions`¶

Purpose: - fetch open positions

Response row fields: - symbol - market_price - average_entry_price - quantity - unrealized_pnl - realized_pnl - strategy_status - opened_at

`POST /api/positions/close`¶

Purpose: - manually close an open position

Request body:

{
  "symbol": "AAPL",
  "quantity": 100
}

Response fields: - symbol - close_order_client_order_id - status

`POST /api/positions/halt`¶

Purpose: - halt strategy management for a live position

Request body:

{
  "symbol": "AAPL",
  "reason": "Manual position halt"
}

Response fields: - symbol - strategy_status

8. Orders Endpoints¶

`GET /api/orders`¶

Purpose: - fetch order history for current session or provided date

Query params: - date optional - status optional - symbol optional

Response row fields: - submitted_at - status - symbol - side - quantity - broker_name - client_order_id - broker_order_id

`GET /api/orders/{client_order_id}`¶

Purpose: - fetch one order detail record

Response fields: - all core order fields - linked executions

`POST /api/orders/cancel`¶

Purpose: - cancel an existing order

Request body:

{
  "client_order_id": "ord_001"
}

Response fields: - client_order_id - status

9. Risk and Emergency Endpoints¶

`GET /api/risk/state`¶

Purpose: - current risk state for Risk & Health screen

Response fields: - trading_state - max_daily_loss - current_daily_loss - max_position_size - max_trades_per_day - trades_today - active_watchlist_limit - open_position_limit - blocked_symbols

`GET /api/risk/violations`¶

Purpose: - fetch current or recent risk violations

Response row fields: - rule - symbol - client_order_id - detail - timestamp

`POST /api/risk/emergency-halt`¶

Purpose: - trigger Emergency Liquidate & Halt

Request body:

{
  "reason": "Operator initiated emergency halt"
}

Response fields: - halted - liquidation_requested - timestamp

10. Settings Endpoints¶

`GET /api/settings`¶

Purpose: - fetch effective runtime settings

Response groups: - runtime - momentum_radar - strategy_allocator - risk_controls - analytics

`PUT /api/settings`¶

Purpose: - update editable settings

Request body example:

{
  "runtime": {
    "trading_mode": "PAPER",
    "market_data_broker": "ALPACA",
    "execution_broker": "ALPACA_PAPER"
  },
  "risk_controls": {
    "max_daily_loss": 500.0,
    "max_position_size": 2500.0
  }
}

Response fields: - updated - effective_settings

Validation rules: - unsafe live changes may require explicit guard or operator confirmation

11. Backtesting and Data Endpoints¶

`POST /api/data/download`¶

Purpose: - request historical data download

Request body:

{
  "symbol": "AAPL",
  "start": "2026-04-01T09:30:00Z",
  "end": "2026-04-01T16:00:00Z"
}

Response fields: - request_id - status

`GET /api/data/downloads`¶

Purpose: - list download requests and statuses

`POST /api/backtests/run`¶

Purpose: - trigger a backtest using configured strategy and historical data

Request body:

{
  "strategy_id": "opening_breakout_v1",
  "symbol": "AAPL",
  "start": "2026-04-01T09:30:00Z",
  "end": "2026-04-30T16:00:00Z"
}

Response fields: - backtest_id - status

`GET /api/backtests/{backtest_id}`¶

Purpose: - retrieve backtest results

Response fields: - total_return - sharpe_ratio - max_drawdown - win_loss_ratio - trades

12. Trade Analytics Endpoints¶

`GET /api/trades`¶

Purpose: - list normalized completed trades

Query params: - date optional - strategy_id optional - symbol optional

Response row fields: - trade_id - symbol - strategy_id - entry_time - exit_time - gross_pnl - net_pnl - winner_loser_label

`GET /api/trades/{trade_id}`¶

Purpose: - fetch one trade deep-dive

Response groups: - trade - events - features - outcomes - explanations

`GET /api/trades/recommendations`¶

Purpose: - fetch current recommendations derived from prior trades

Query params: - scope_type optional - scope_value optional

Response row fields: - recommendation_id - scope_type - scope_value - recommendation_text - confidence_score - sample_size

13. API Error Codes¶

Suggested stable error codes: - VALIDATION_ERROR - NOT_FOUND - BROKER_UNAVAILABLE - RISK_BLOCKED - DUPLICATE_ORDER_BLOCKED - MARKET_CLOSED - POSITION_NOT_FOUND - ORDER_NOT_CANCELLABLE - SETTINGS_UPDATE_BLOCKED - EMERGENCY_HALT_ACTIVE - INTERNAL_ERROR

14. Authentication and Authorization Notes¶

For local development: - lightweight or disabled auth may be acceptable

For paper and live: - operator-level authentication should be enabled - dangerous actions should be restricted - audit logs should capture who triggered manual actions

Sensitive actions include: - emergency halt - manual close position - cancel order - settings updates - block/unblock symbols

15. Recommended Companion Document¶

The next best companion after this one is an Event Contract Reference or an OpenAPI-aligned endpoint spec, if you want implementation teams to wire frontend and backend against machine-checkable contracts.

QuantMatrix API Reference Document¶

1. API Principles¶

2. Base Conventions¶

Base Path¶

Content Type¶

Time Format¶

Standard Response Envelope¶

Standard Error Envelope¶

3. Health and System Endpoints¶

GET /api/health¶

GET /api/health/components¶

4. Dashboard and Account Endpoints¶

GET /api/dashboard/summary¶

GET /api/account/summary¶

GET /api/account/performance¶

5. Momentum Radar Endpoints¶

GET /api/radar/momentum¶

POST /api/radar/watch¶

POST /api/radar/block¶

6. Watchlist Endpoints¶

GET /api/watchlist¶

POST /api/watchlist/stop¶

POST /api/watchlist/restart¶

7. Positions Endpoints¶

GET /api/positions¶

POST /api/positions/close¶

POST /api/positions/halt¶

8. Orders Endpoints¶

GET /api/orders¶

GET /api/orders/{client_order_id}¶

POST /api/orders/cancel¶

9. Risk and Emergency Endpoints¶

GET /api/risk/state¶

GET /api/risk/violations¶

POST /api/risk/emergency-halt¶

10. Settings Endpoints¶

GET /api/settings¶

PUT /api/settings¶

11. Backtesting and Data Endpoints¶

POST /api/data/download¶

GET /api/data/downloads¶

POST /api/backtests/run¶

GET /api/backtests/{backtest_id}¶

12. Trade Analytics Endpoints¶

GET /api/trades¶

GET /api/trades/{trade_id}¶

GET /api/trades/recommendations¶

13. API Error Codes¶

14. Authentication and Authorization Notes¶

15. Recommended Companion Document¶

`GET /api/health`¶

`GET /api/health/components`¶

`GET /api/dashboard/summary`¶

`GET /api/account/summary`¶

`GET /api/account/performance`¶

`GET /api/radar/momentum`¶

`POST /api/radar/watch`¶

`POST /api/radar/block`¶

`GET /api/watchlist`¶

`POST /api/watchlist/stop`¶

`POST /api/watchlist/restart`¶

`GET /api/positions`¶

`POST /api/positions/close`¶

`POST /api/positions/halt`¶

`GET /api/orders`¶

`GET /api/orders/{client_order_id}`¶

`POST /api/orders/cancel`¶

`GET /api/risk/state`¶

`GET /api/risk/violations`¶

`POST /api/risk/emergency-halt`¶

`GET /api/settings`¶

`PUT /api/settings`¶

`POST /api/data/download`¶

`GET /api/data/downloads`¶

`POST /api/backtests/run`¶

`GET /api/backtests/{backtest_id}`¶

`GET /api/trades`¶

`GET /api/trades/{trade_id}`¶

`GET /api/trades/recommendations`¶