# PitBridge

**A local-first MCP bridge for NinjaTrader 8, with hard risk limits your AI cannot bypass.**

[![CI](https://github.com/ToolstackVault/pitbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/ToolstackVault/pitbridge/actions/workflows/ci.yml)
[![AddOn build](https://github.com/ToolstackVault/pitbridge/actions/workflows/addon-build.yml/badge.svg)](https://github.com/ToolstackVault/pitbridge/actions/workflows/addon-build.yml)

PitBridge connects an AI agent (Claude Code, Claude Desktop, or your own script)
to a NinjaTrader 8 futures account through a daemon that runs on your own
machine. Every order the agent asks for passes through a deterministic guardrail
engine first. The guardrails are default-on, they live in code rather than in
prompts, and the agent has no tool to weaken them, unlock live trading, or
release the kill switch.

We build rails, not alpha. PitBridge does not tell you what to trade.

## What it is

* A **local-first** daemon (Python 3.12) that speaks **MCP** (stdio and
  streamable HTTP), a REST API, and a WebSocket event feed. It runs on macOS,
  Linux, or Windows.
* A **deterministic guardrail engine**: pure, synchronous checks (daily-loss
  halt, position caps, trading windows, rate limits, a kill switch, and more)
  that every order must pass before it can reach the broker.
* A thin **NinjaTrader 8 AddOn** (C#) that connects out to the daemon and places
  orders through the official `NinjaTrader.Cbi` Account API. The AddOn is
  deliberately dumb: all safety lives in the daemon.
* An append-only, **hash-chained audit log** that records every request,
  decision, and outcome, and can tell you exactly why any order was allowed or
  blocked.

## What it is NOT

Read this section before anything else.

* **Not a broker or an exchange.** PitBridge routes orders you (or your agent)
  create to your existing NinjaTrader account. It holds no funds and executes
  nothing itself.
* **Not signals, strategies, or alpha.** PitBridge ships no trading logic. It
  will not tell you what, when, or how much to trade. That is your job, or your
  agent's.
* **Not financial or investment advice.** It is trading infrastructure.
* **Not a guarantee of prop-firm compliance.** You configure the limits that
  match your firm's rules. PitBridge helps you encode and enforce them locally,
  but you remain responsible for staying within your firm's terms. We make no
  compliance guarantee.
* **Not a cloud order relay.** Orders, keys, and positions never touch our
  servers. There is no PitBridge account in the order path.
* **Not autonomous.** Enabling live execution is an operator-only ritual at the
  command line. The agent cannot arm live trading, and it cannot lift a kill.

## Architecture

The entire order path is local. PitBridge's own cloud (the marketing site, the
docs, software updates) is never in it.

```
   AI agent   (Claude Code / Claude Desktop / your own script)
      │
      │   MCP (stdio or HTTP)   REST /v1/*   WS events
      ▼
   PitBridge daemon                         ← runs on YOUR machine
      │
      │   frozen pipeline (no code path skips it):
      │   schema → permission → GUARDRAILS → confirm → submit → audit
      ▼
   Guardrail engine   (deterministic, default-on, not reconfigurable by the agent)
      │
      │   WebSocket on :8873   (the AddOn dials OUT; the NT8 box never listens)
      ▼
   NT8 AddOn   (C#, .NET 4.8, next to NinjaTrader 8 on Windows)
      │
      │   NinjaTrader.Cbi Account API   (close / flatten are strictly reduce-only)
      ▼
   NinjaTrader 8   →   your broker / prop account   (CQG, Rithmic, ...)

   PitBridge's own cloud is NOT on this path.
   Orders, keys, and positions never leave your machine(s).
```

Two run modes:

* **Localhost** (default): the daemon and NinjaTrader run on the same Windows
  machine, bound to `127.0.0.1`.
* **Paired**: the daemon runs on, for example, your Mac, and the NinjaTrader
  AddOn connects out to it over your own private network (Tailscale / LAN). This
  is the "runs on your Mac, your Windows box, or both" setup. Non-localhost binds
  are refused unless paired mode is explicitly enabled and a pairing token is
  configured.

## Safety model in short

* **Deterministic guardrails.** The engine is a set of pure functions with no
  I/O and no LLM in the loop: `check(request, state, now)` returns Allow, Block
  (with a typed reason code), or RequireConfirm. Given the same inputs it always
  returns the same decision, and that decision is testable.
* **A frozen pipeline.** Every order takes exactly one path: schema validation,
  then permission (read-only / paper / live), then the guardrail chain, then an
  optional human-confirm gate, then submit, then an audit append. There is no
  route from the agent surface to the broker that skips it. A structural test in
  CI fails the build if any code tries.
* **The agent cannot reconfigure safety.** Limits live in an on-disk config that
  is checksum-verified. No MCP tool can edit config, raise a limit, un-kill, or
  arm live trading. Those controls exist only at the operator's command line.
* **Local-first.** The daemon runs on your machine(s). Orders, keys, and
  positions never reach a PitBridge server.
* **Kill switch.** A file, the CLI, or a REST call can engage it instantly.
  Only the CLI (a human at the keyboard) can release it. De-risking (cancel,
  close, flatten) is deliberately still allowed under a kill, so you can always
  get flat.
* **Tamper-evident audit log.** Append-only, hash-chained JSONL with an
  out-of-file anchor. `pitbridge audit why <id>` explains any order;
  `pitbridge audit verify` proves the chain is intact and catches edits,
  truncation, or a wiped tail.

## The guardrails

Twelve v0 guardrails, each its own module, all table-tested. The chain runs in a
frozen order: the kill switch is checked first, the human-confirm gate last.

1. **Kill switch**: file, CLI, or REST engages it; release is CLI-only, never
   an agent tool.
2. **Daily-loss halt**: per-account day ledger with New-York rollover; can
   latch sticky for the rest of the day once breached.
3. **Profit lock**: stop trading for the day after a configured profit.
4. **Max contracts per order**: reject any single order above the cap.
5. **Max position per instrument and account**: cap net exposure, and refuse an
   over-cap position flipping to an equally over-cap opposite side.
6. **Instrument allowlist**: only configured contracts may be traded.
7. **Trading windows and holiday calendar**: per-account timezone, holiday and
   early-close aware.
8. **Cooldown**: a minimum spacing after a loss and/or after an order.
9. **Order rate limits**: caps per minute, per hour, and per day.
10. **Duplicate-order protection**: same account, instrument, side, and quantity
    within N seconds is rejected.
11. **Link-down block**: if the heartbeat to the AddOn goes stale, new orders
    hard-reject rather than queue against a dead link.
12. **Human-confirm gate**: parks an order as PENDING_CONFIRM, pings a notifier,
    and waits for `pitbridge confirm <id>` (or a REST approval); auto-rejects
    after 60 seconds.

## Open-core boundary

PitBridge is open-core. The safety kernel is open so it can be read and trusted.
Live execution and the operational suite for running many accounts are the paid
tier.

| Open source (free) | Pro (paid) |
|---|---|
| The daemon and the full guardrail engine | Live-execution unlock (the private `LiveExecutionProvider` plugin) |
| The MCP, REST, and WebSocket agent surface | The advanced guardrail suite and prop-firm rule packs |
| Read-only tools and paper trading (against the fake AddOn / simulation) | Multi-account fan-out (one tool call, N accounts) |
| The CLI and the hash-chained audit log | The human-confirm UI and audit export |

This is licensing-gating, not DRM. The core is fully functional for read-only
and paper use on its own. Live trading requires the Pro plugin plus a deliberate,
operator-only `arm-live` step.

## Quickstart

You can run the **complete** daemon on a Mac today, with no NinjaTrader install,
no Windows box, and no market data. A **fake AddOn** simulator stands in for the
real C# AddOn, so you can watch the guardrails pass good orders, block bad ones
with a typed reason, stop everything with the kill switch, and explain every
decision from the audit log.

```bash
cd daemon
uv sync --extra dev
uv run pitbridge run --config ./config.toml     # terminal A
uv run python ../tools/fake_addon.py \           # terminal B
  --host 127.0.0.1 --port 8873 --token pb_pair_demo --account Sim101
```

Then place a paper order over REST or wire up Claude as the MCP client and ask
it in plain language. The full walkthrough, a ready-to-paste config, the Claude
Desktop / Claude Code MCP setup block, five test scenarios, and a "try to break
it" section are in **[docs/testing-on-mac.md](docs/testing-on-mac.md)**.

Everything in the quickstart is paper / simulation. See that guide's "What this
does and does not prove" for the honest boundary.

## Status and roadmap

PitBridge is early and pre-launch. We are honest about what exists versus what is
planned.

**Built and tested today (paper / simulation only):**

* the daemon core, the full guardrail engine (all twelve guardrails), the day
  ledger, and the hash-chained audit log;
* the MCP server (nine tools), the REST API, the WebSocket event feed, and the
  CLI;
* a scripted fake AddOn for end-to-end and chaos testing;
* a table-driven test suite (300+ tests) that runs on macOS, Linux, and Windows
  in CI, including prompt-injection and no-bypass tests.

**In progress:**

* the real C# NinjaTrader 8 AddOn (order routing on a Sim101 account), with
  close and flatten implemented as strictly reduce-only.

**Planned:**

* shadow-mode validation, running PitBridge in parallel with our own live
  prop-trading operation to prove order-intent parity before it ever routes a
  live order;
* a supervised, operator-gated live migration;
* the open-core public launch, the website, and full docs;
* additional platforms (Tradovate, ProjectX / TopstepX) via thin adapters.

**No live account has been traded through PitBridge yet.** Live routing sits
behind an operator-only ritual and is not part of the current build.

## Documentation

* [docs/architecture.md](docs/architecture.md): the binding architecture and
  safety spec.
* [docs/testing-on-mac.md](docs/testing-on-mac.md): run and test the daemon on a
  Mac against the fake AddOn.
* [SECURITY.md](SECURITY.md): how to report a vulnerability.
* [CONTRIBUTING.md](CONTRIBUTING.md): how to contribute, and the rules for
  safety-critical changes.

## Disclaimers

**Trademarks.** NinjaTrader is a registered trademark of NinjaTrader Group, LLC.
CQG, Rithmic, and any prop-firm names are trademarks of their respective owners.
PitBridge is an independent project and is not affiliated with, endorsed by, or
sponsored by NinjaTrader Group, LLC, any data or clearing provider, or any prop
firm. Platform names are used nominatively, only to describe compatibility.

**Not financial advice.** PitBridge is trading infrastructure, not financial,
investment, or trading advice. It provides no signals, strategies, or
recommendations.

**Risk.** Trading futures involves substantial risk of loss and is not suitable
for every investor. You are solely responsible for your own trading decisions and
for staying within the terms of any broker or prop firm you use.

**CFTC Rule 4.41 (hypothetical and simulated performance).** Any results,
examples, or simulated data shown for PitBridge are hypothetical or
simulation-based. Simulated performance has inherent limitations: unlike a live
record, simulated results do not represent actual trading, and because the trades
were not actually executed, they may under- or over-compensate for factors such
as lack of liquidity. No representation is being made that any account will or is
likely to achieve profits or losses similar to those shown.