# KlawTrade

Free, open-source algorithmic trading platform for Python. MIT-licensed.
Website: https://klawtrade.com
Source: https://github.com/klawtrade/klawtrade

## What it is

KlawTrade is a deterministic trading system that runs rule-based and/or
AI-powered strategies against live markets or simulation. It ships with:

- Two rule-based strategies: momentum and mean reversion.
- An optional AI strategy (`KlawTrade AI`) — bring your own Anthropic
  or OpenAI API key.
- A 14-check risk management gate that every signal must pass before
  any order reaches a broker.
- A 7-trigger circuit breaker that halts all trading when defensive
  conditions fire.
- Historical backtesting with full performance metrics.
- A real-time WebSocket dashboard at http://localhost:8080.
- Integrations with six brokers: Alpaca, Interactive Brokers, Coinbase,
  Binance, Kraken, and Tradier.

## Quick start

```bash
pip install klawtrade
klawtrade init
klawtrade start
```

Without any API keys the system runs against a built-in simulation
broker. To use a real broker, set that broker's API keys in your `.env`
and update `config/settings.yaml`.

## Enabling the AI strategy

```bash
pip install "klawtrade[ai]"
export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY
```

Then in `config/settings.yaml`:

```yaml
strategy:
  ai:
    enabled: true
    provider: "anthropic"      # or "openai"
    model: "claude-sonnet-4-20250514"
    temperature: 0.0           # deterministic
    min_confidence: 0.75
    require_rule_confirmation: true
    max_daily_cost_usd: 10.00
```

## How AI accuracy is preserved

Six stacked guardrails keep LLM-generated signals trustworthy:

1. **Strict JSON schema**. Claude uses `tool_use`, OpenAI uses
   `response_format=json_schema`. The model cannot emit malformed
   output.
2. **Temperature zero by default** — deterministic across identical
   prompts.
3. **Confidence threshold**. Signals below `min_confidence` (default
   0.75) are discarded.
4. **Rule cross-validation**. Every AI BUY/SELL must be seconded by at
   least one classic indicator (RSI, MACD, SMA crossover, or Bollinger
   bands). Hallucinated trades are filtered out.
5. **Stop/take sanity checks**. A stop above a BUY entry or below a
   SELL entry is nulled, so the risk manager picks a safe default.
6. **14-check risk gate**. The same deterministic gate used by
   rule-based signals — AI cannot override position sizing, drawdown
   limits, daily loss caps, or any other check.

## The 14-check risk gate

Every signal runs through all fourteen checks (no short-circuit):

1. Symbol blacklist
2. Max position size (percent of equity)
3. Max daily loss
4. Max weekly loss
5. Max drawdown
6. Max single-trade loss
7. Max open positions
8. Max daily trades
9. Minimum cash reserve
10. Minimum volume
11. Maximum spread
12. Sector allocation
13. Correlated exposure
14. Signal confidence

## The 7-trigger circuit breaker

A second layer that halts ALL trading when any of these fires:

1. Consecutive losses
2. Daily loss limit
3. Weekly loss limit
4. Max drawdown
5. VIX spike
6. System error rate
7. Manual kill switch

## Backtesting

```bash
klawtrade backtest --start-date 2024-01-01 --end-date 2024-12-31 \
    --symbols AAPL,MSFT,NVDA --capital 100000
```

Output includes total return, annualised return, Sharpe and Sortino
ratios, max drawdown, drawdown duration, win rate, profit factor, best
and worst trade, average holding period, and the full equity curve.

## Supported brokers

| Broker | Asset classes |
|--------|---------------|
| Alpaca | Stocks, crypto |
| Interactive Brokers | Stocks, futures, options |
| Coinbase | Crypto |
| Binance | Crypto |
| Kraken | Crypto |
| Tradier | Stocks |

If a broker's API keys are missing or the optional dependency is not
installed, KlawTrade automatically falls back to the built-in
simulation broker.

## CLI reference

- `klawtrade start [-c CONFIG] [-p PORT] [--sim]` — start the system.
- `klawtrade init [DIRECTORY] [-q]` — interactive project wizard.
- `klawtrade backtest --start-date YYYY-MM-DD --end-date YYYY-MM-DD` — run backtest.
- `klawtrade status [-p PORT]` — check if a running system is alive.

## Dashboard

Real-time monitoring at http://localhost:8080. Shows live equity,
positions, open orders, trade log, and risk-check history, and
provides a manual kill switch. Streams via WebSocket at 1-second
intervals by default.

## Docker

```bash
docker build -t klawtrade .
docker run -p 8080:8080 -v "$(pwd)/logs:/app/logs" klawtrade
```

Uses Python 3.13-slim and `uv` for fast reproducible builds.

## Pricing

Zero. The software is MIT-licensed. The only cost is your broker fees
(which are broker-side, not KlawTrade-side) and, if you enable the AI
strategy, your direct spend at Anthropic or OpenAI.

## Privacy

KlawTrade has no cloud component and no telemetry. API keys live on
your machine. Market data is fetched directly from your broker or
yfinance. The project can be audited in full at
https://github.com/klawtrade/klawtrade.

## Disclaimer

KlawTrade is software infrastructure for your own trading strategies.
Nothing in the project constitutes investment advice. Algorithmic
trading carries significant risk of loss. Paper-trade extensively and
consult a licensed professional before deploying real capital.