Claxton-Quant Python Backend

Claxton is an automated, deterministic options trading engine built in Python (FastAPI).

It’s designed around a 9-stage pipeline (evaluate → gate → price → execute → monitor → exit) with desk-style guardrails (no market orders by default, kill switch modes, reconciliation, risk caps, etc.).

Architecture

┌───────────────────────────────┐
│  Dashboard UI (Next.js)        │
│  claxton-dashboard             │
└───────────────┬───────────────┘
                │ REST
                ▼
┌───────────────────────────────┐
│  Claxton-Quant API (FastAPI)   │
│  - Bot loop (entry scan/monitor)
│  - Strategy pipeline (A–I)     │
│  - Risk snapshots + caps       │
│  - Reconciliation              │
│  - Backtest endpoints          │
└───────────────┬───────────────┘
                │
     ┌──────────┴──────────┐
     │                     │
     ▼                     ▼
┌──────────────┐     ┌──────────────┐
│ Broker API   │     │ Supabase DB   │
│ Tradier (live)│     │ Postgres      │
│ + Provider    │     │ (settings,    │
│ abstraction   │     │ trades, audit)
└──────────────┘     └──────────────┘

Related repo (UI): https://github.com/nickgag626/claxton-dashboard

Quick Start

cd claxton-quant-python
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt

cp .env.example .env
# Edit .env with your credentials

python -m api.main
# or: uvicorn api.main:app --reload --port 8000

Server runs at: http://localhost:8000

Configuration (.env)

See phased-approach.md for the full list. Common variables:

• TRADIER_API_TOKEN, TRADIER_ACCOUNT_ID, TRADIER_BASE_URL
• SUPABASE_URL, SUPABASE_SERVICE_KEY
• USE_STREAMING (WebSocket vs polling)
• LIVE_TRADING (safety gate)
• DISALLOW_MARKET_ORDERS
• TASKS_TOKEN (cron task auth)
• PORTFOLIO_MAX_ABS_DELTA_SHARES, PORTFOLIO_MAX_ABS_VEGA, PORTFOLIO_MAX_ABS_GAMMA

API Endpoints (high-level)

Source of truth is api/main.py and the routers in api/*.py.

Health / Ops

• GET /health
• GET /api/health/deep
• GET /api/calendar/status

Bot control (entry + monitoring)

• GET /api/bot/status
• POST /api/bot/start
• POST /api/bot/stop
• POST /api/bot/scan-entries
• GET /api/bot/entry-status
• POST /api/bot/refresh-positions

Market data

• GET /api/quote/{symbol}
• GET /api/chain/{symbol}/{expiration}
• GET /api/expirations/{symbol}

Account

• GET /api/account/balance
• GET /api/account/positions
• GET /api/account/orders

Strategy engine

• POST /api/engine/evaluate
• POST /api/engine/execute
• POST /api/engine/check-exits
• GET /api/cron/check-exits

Reconciliation

• GET /api/reconcile
• GET /api/reconcile/status
• POST /api/reconcile/trigger

Risk (portfolio snapshots + caps)

• GET /api/risk/snapshot
• GET /api/risk/history
• GET /api/risk/scenarios
• POST /api/risk/caps
• GET /api/risk/triggers

Backtesting

• GET /api/backtest/strategies
• POST /api/backtest/run
• POST /api/backtest/sweep

Strategy intelligence

• GET /api/iv-surface/{symbol}
• GET /api/smart-dte/{symbol}

Optional: MCP / parity tooling

• GET /api/mcp/status
• POST /api/mcp/configure
• GET /api/mcp/scan
• GET /api/mcp/analyze/{symbol}
• GET /api/parity/report
• POST /api/parity/run

Project Structure

claxton-quant-python/
├── api/                  # FastAPI app + routers
├── services/             # pipeline, broker/provider adapters, execution, monitoring
├── strategies/           # strategy implementations
├── models/               # pydantic/dataclasses models
├── migrations/           # DB migrations/sql
├── tests/
└── phased-approach.md    # detailed roadmap + pipeline spec

Strategy Engine Features

Phase 2: Risk Scoring (EV_net + POT)

Phase 2 adds a market-implied probability engine used during scanning to compute:

• EV_net (USD): probability-weighted return minus friction.

  • EV_net = (P_win * MaxProfit) - (P_loss * MaxLoss) - TotalFriction
  • Friction = commissions + slippage/spread penalty (per contract per leg).
  • Trades must satisfy EV_net > 0 to pass Stage G.

• POT (Probability of Touch): trade “stress” indicator.

  • Approximation: POT ≈ 2 × Prob(ITM) (clamped to [0, 1]).
  • For iron condors: POT_total = POT_put + POT_call (clamped to 1.0).
  • A soft warning is emitted when POT > 0.70 to flag high-stress setups.

Entry Scanning

• Delta-based strike selection
• Credit/width percentage filters
• Bid/ask spread validation
• DTE range filtering

Exit Monitoring

• Profit target (% of credit)
• Stop loss (% of credit)
• Time stop (DTE threshold)

Risk Management

• Max positions per strategy
• Max risk per trade
• Daily loss limits
• Entry cooldowns

Configuration

Strategies + global settings are stored in Supabase and read by the bot loop.

• Strategy model definitions: models/trading.py
• Settings + strategy tables: see phased-approach.md and migrations/

Example strategy fields (simplified):

{
  "name": "SPY Iron Condor",
  "underlying": "SPY",
  "min_dte": 30,
  "max_dte": 60,
  "target_delta": 0.16,
  "min_credit": 0.50,
  "profit_target_percent": 50.0,
  "stop_loss_percent": 200.0,
  "time_stop_dte": 7,
  "max_positions": 3,
  "max_risk_per_trade": 500.0
}

Dashboard integration

The primary UI lives in claxton-dashboard (Next.js). It calls this API over REST.

Example (entry scan):

const res = await fetch(`${API_URL}/api/engine/evaluate`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ strategies: [...] }),
});
const data = await res.json();

Deployment

On AWS/VPS

# Install dependencies
pip install -r requirements.txt

# Run with systemd or supervisor
uvicorn api.main:app --host 0.0.0.0 --port 8000

# Or use gunicorn for production
pip install gunicorn
gunicorn api.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

With Docker

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Why Python?

• pandas/numpy - Much easier data manipulation
• Better quant libraries - ta-lib, backtrader, scipy
• Options pricing - py_vollib, mibian for greeks
• ML capabilities - scikit-learn, tensorflow if needed
• Industry standard - Most quant shops use Python

License

MIT