Skip to content

API Reference

QGTMAI exposes a FastAPI control plane for the paper-first precious-metals stack.

Interactive docs when running locally:

Base URLs

Environment URL
Local dev http://localhost:8000
Production https://api.qgtmai.com

Auth Model

Production uses two auth paths:

  1. Owner API key via X-QGTM-API-Key or Authorization: Bearer ...
  2. Browser session via the qgtm_session httpOnly cookie issued by POST /api/v1/auth/session

Route classes:

  • public read-only: no auth dependency
  • protected read surfaces: accept either owner API key or browser session
  • owner-only control surfaces: require owner API key

Local development bypasses auth only when neither QGTM_API_KEY nor QGTM_JWT_SECRET is configured and the app is not running in production mode.

Health and Auth

Method Path Auth Description
GET /health public overall API health and component status
GET /metrics public Prometheus-style metrics endpoint
GET /api/v1/monitoring/health public forward-monitor / strategy-health summary
POST /api/v1/auth/session public founder login; sets qgtm_session cookie
DELETE /api/v1/auth/session session clears session cookie

Universe, Strategy, and Signals

Method Path Auth Description
GET /api/v1/universe public PM-focused universe by default; pass focus=broad for the broader legacy universe
GET /api/v1/universe/{symbol} public single instrument details
GET /api/v1/universe/sector/{sector} public sector slice from the broad universe
GET /api/v1/strategies public live-known strategy surface; dynamic runtime view
GET /api/v1/signals/latest protected latest computed signals
GET /api/v1/signals/delivery-status protected Discord/Telegram delivery configuration status
GET /api/v1/signals/dashboard public live signal dashboard payload

Market Data, Account, and Orders

Method Path Auth Description
GET /api/v1/market-data/snapshots public real-time snapshots for one or more symbols
GET /api/v1/market-data/bars/{symbol} public historical OHLCV bars
GET /api/v1/account protected Alpaca account summary
GET /api/v1/positions protected live positions plus hygiene summary
GET /api/v1/orders protected recent orders
GET /api/v1/orders/attribution protected strategy-tag turnover plus realized-PnL summary
GET /api/v1/session/readiness protected next/active-session readiness snapshot

Current readiness and attribution fields

/api/v1/orders/attribution now includes:

  • realized_pnl_total
  • realized_pnl_available
  • legacy_unattributed_filled_notional
  • unknown_unattributed_filled_notional
  • attribution_coverage_ex_legacy_ratio

/api/v1/session/readiness now includes:

  • top-level ready
  • market_session_open
  • checks.order_tag_coverage_ok
  • checks.legacy_tag_debt_present
  • checks.position_hygiene_clean
  • order_tag_audit payload from the attribution summary

Forecasts and Options

Method Path Auth Description
GET /api/v1/forecast/gold public GLD trend / volatility / support-resistance forecast
GET /api/v1/forecast/silver public SLV forecast plus ratio context
GET /api/v1/forecast/ratio public gold/silver ratio forecast
GET /api/v1/forecast/signals public daemon-live signals if present, else computed fallback
GET /api/v1/forecast/always-on/{symbol} public always-on frontend forecast contract
GET /api/v1/options/chain/{symbol} public filtered options chain
GET /api/v1/options/iv/{symbol} public IV summary
GET /api/v1/options/greeks public portfolio delta and placeholder Greeks view
GET /api/v1/options/put-call-ratio/{symbol} public put/call ratio
GET /api/v1/options/vol-indices public GVZ / VXSLV / VIX summary
GET /api/v1/options/strategies public supported options strategy list

Risk and Daemon

Method Path Auth Description
GET /api/v1/risk protected portfolio and daemon risk view
GET /api/v1/risk/stress/scenarios public available stress scenarios
POST /api/v1/risk/stress/run public run a stress test
GET /api/v1/risk/decay/summary public strategy decay summary
GET /api/v1/risk/decay/{strategy_id} public per-strategy decay details
GET /api/v1/risk/evt/tail-risk public tail-risk snapshot
GET /api/v1/risk/factors public factor-risk view
GET /api/v1/daemon/status public daemon status plus active/inactive strategies
GET /api/v1/daemon/telemetry protected daemon telemetry, heartbeat, drawdown, recon, risk
POST /api/v1/daemon/toggle-strategy owner-only enable or disable a strategy flag
POST /api/v1/daemon/start owner-only start daemon subprocess for non-systemd contexts
POST /api/v1/daemon/stop owner-only stop daemon subprocess for non-systemd contexts
POST /api/v1/daemon/ingest-state owner-only ingest daemon heartbeat/state payload
GET /api/v1/backtest/results public fetch backtest results
POST /api/v1/backtest/run public trigger a backtest run

NLP and WebSocket

Method Path Auth Description
POST /api/v1/ask public natural-language query endpoint
WS /ws/terminal protected terminal event stream

Example Calls

curl https://api.qgtmai.com/health
curl https://api.qgtmai.com/api/v1/strategies
curl "https://api.qgtmai.com/api/v1/market-data/bars/GLD?limit=5"
curl -H "X-QGTM-API-Key: $QGTM_API_KEY" \
  https://api.qgtmai.com/api/v1/session/readiness

import httpx

client = httpx.Client(base_url="http://localhost:8000")

health = client.get("/health").json()
strategies = client.get("/api/v1/strategies").json()

print(health["status"])
print(strategies["total_count"])