# PitBridge, full context for agents and developers

> PitBridge is a local-first Model Context Protocol (MCP) bridge that lets an AI agent trade a NinjaTrader 8 futures account behind a deterministic guardrail engine. Every order the agent proposes passes through hard risk limits that live in code, not in prompts, before it can reach the platform. Orders, keys, and positions never route through a PitBridge server. The core is open source under Apache-2.0. A fresh install runs in paper mode only; unlocking live execution is an operator step at the command line, and the paid tier gates the live provider and advanced rule packs.

This file is the long-form companion to /llms.txt. It exists so an agent can answer questions about PitBridge, install it, and configure it without guessing. Every claim here is meant to match the source repository and the site. Where a fact is a plan rather than shipped behaviour, it is labeled.

## One-line positioning

PitBridge is the local-first, guardrailed MCP bridge that lets your AI agent trade on NinjaTrader 8, on your own machine, behind hard limits it cannot prompt its way past, and for free until you go live.

## The wedge (how PitBridge differs from the field)

1. Local-first, no cloud in the order path. CrossTrade's MCP, TradersPost, and PickMyTrade all place their cloud between the agent and the order. PitBridge keeps the whole order route on machines you own. Open-source alternatives exist but are hobby-grade (0 to a few dozen GitHub stars, no guardrails).
2. Guardrails as a deterministic engine, not a prompt. On the agent path, CrossTrade's MCP safety is largely OAuth scopes plus instructions to the model ("check your daily loss"), which the model can talk around. PitBridge's guardrails run in code outside the model. The kill-line: their MCP safety is prompt instructions, ours is a deterministic engine outside the model.
3. Pricing wedge. CrossTrade gates its MCP behind a $99 per month cloud plan (crosstrade.io/pricing, verified 2026-07-09). PitBridge's MCP is free and local. You pay when you go live.

## Audience

Primary: vibecoders and agent-builders using OpenClaw, Hermes, Claude Code, or Cursor who want to let an agent trade safely. Secondary: prop-firm and futures traders who already automate. The trader is the payer; the agent-builder is the reach.

## What PitBridge is NOT

- Not a broker or exchange. It 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. It ships no trading logic. It will not tell you what, when, or how much to trade.
- 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. You remain responsible for staying within your firm's terms.
- Not a cloud order relay. Orders, keys, and positions never touch a PitBridge server.
- Not autonomous. Enabling live execution is an operator-only ritual at the command line. The agent cannot arm live trading and cannot lift a kill switch.

## Architecture

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

Components:
- A local-first daemon (Python 3.12) that speaks MCP over stdio, a REST API, and a WebSocket event feed. MCP over streamable HTTP is on the roadmap, not in the current build. Runs on macOS, Linux, or Windows.
- A deterministic guardrail engine: pure, synchronous checks that every order must pass before it can reach the broker. The engine is import-pure (no I/O) and returns Allow, Block, or RequireConfirm with a stable set of reason codes.
- 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. The NT8 box never listens; the AddOn dials out.
- An append-only, hash-chained audit log (JSONL) that records every request, decision, and outcome and can prove the chain is intact.

Order pipeline (fixed, not bypassable): schema validation, permission check (read-only / paper / live), guardrail check, optional human confirmation, submit, ack and reconcile, append-only audit. Only the pipeline may submit an order; this is enforced structurally, checked by an AST test that fails if any module outside the pipeline calls the order-submit path.

Paired mode: the daemon can run on your Mac while NinjaTrader runs on your Windows box, connected over your own local network. One machine or two, orders move only between machines you own. The AddOn connects outbound to the daemon at ws://<daemon-host>:8873/v1/addon using a pairing token.

## Install

PitBridge is a Python package distributed for uv and pipx. Run any command straight from PyPI with uvx, or put the CLI on your PATH:

    uvx pitbridge doctor

or

    uv tool install pitbridge

A fresh install starts in paper mode with all guardrails on and live execution locked. There is no agent tool to unlock live.

Zero-config demo sandbox: run the MCP server with no config at all and it boots a safe paper demo sandbox (a fake account, all guardrails on, live locked). It has no broker link and cannot place a real order, so it never crashes for lack of setup, and an agent can immediately call get_accounts and get_guardrail_status before anything is configured:

    uvx pitbridge mcp

Scaffold a real config, then edit it (set your NinjaTrader account name and guardrail values under ~/.pitbridge/config.toml):

    uvx pitbridge init            # writes ~/.pitbridge/config.toml; --force to overwrite

Start the MCP server over stdio (this is what an MCP client attaches to; it reads ~/.pitbridge/config.toml):

    pitbridge mcp

Run the daemon's REST and WebSocket surface against a config file:

    pitbridge run --config ./config.toml

Verify the setup with the read-only self-check. pitbridge doctor prints a PASS, WARN, or FAIL line per section (config, accounts, guardrails, deny-list, kill switch, live gate, and version) and is the go-to troubleshooting command:

    pitbridge doctor

Other CLI commands: pitbridge status (config, kill file, link and halt state), pitbridge confirm <order_id> (approve a held order; the daemon re-runs the full guardrail chain at confirm time), pitbridge audit why <id> (explain any decision), pitbridge audit verify (prove the audit chain is intact and catch edits), pitbridge arm-live (refuses cleanly with a non-zero exit in the open-source core; there is no live provider without the paid plugin).

## Connecting each agent runtime

PitBridge is an MCP server, so any MCP client can attach. Common setups:

- Claude Code: add the local MCP server with one command (the stdio transport, running `pitbridge mcp`).
- Claude Desktop: install the .mcpb bundle; guardrail settings surface in the native settings UI.
- OpenClaw: use the pitbridge-trading skill, a thin wrapper over the MCP tools with the security story up front.
- Hermes and other generic MCP-over-HTTP clients: MCP over streamable HTTP is on the roadmap and not in the current build; use the localhost REST API meanwhile, or any client that can launch a stdio MCP server.
- Cursor: add pitbridge to mcp.json (stdio).
- Your own script: use the localhost REST API (/v1/*) and the WebSocket event feed.

Full copy-paste config blocks per framework live at https://pitbridge.com/docs/quickstart/ (plain markdown: https://pitbridge.com/docs/quickstart.md).

## The nine v0 MCP tools

Reads: get_accounts, get_positions, get_orders, get_account_state, get_guardrail_status.
Writes: place_order, cancel_order, close_position, flatten_account.

Every mutating tool is routed through the pipeline. A guardrail Block returns a structured result (blocked=true plus a reason code and detail), never a raised exception, so the agent session survives a refusal. There is deliberately no tool to mutate config or thresholds, un-kill, or arm live. This is proven by a no-bypass and prompt-injection acceptance test: a guardrail-hitting place_order is blocked and never sent, no tool can weaken a limit, no tool can un-kill or arm live across a whole session, and a flatten then place sequence cannot slip past an engaged kill or a sticky day-halt.

## The twelve deterministic guardrails (v0)

All are default-on and enforced in the daemon, outside the model. Example config values below are illustrative, not defaults.

1. kill_switch. One command halts all order flow. Un-kill is CLI-only; there is no REST route and no agent tool. Example: BLOCK sell 1 RTY. kill_switch is armed.
2. daily_loss_halt. When the configured daily loss is reached (realized plus unrealized, ET day rollover), new orders are refused for the rest of the day. Example: BLOCK buy 1 ES. daily loss 512 >= limit 500.
3. profit_lock. Locks in the day once a configured profit target is reached.
4. max_contracts_per_order. Caps contracts per single order. Example: BLOCK buy 5 MNQ. limit is 2.
5. max_position. Caps net position per instrument and account. An over-cap long cannot flip to an equally over-cap short in one order.
6. instruments (allowlist). The agent trades only the instruments you list. Example: BLOCK buy 1 6E. not in allowlist.
7. trading_window. Orders are accepted only inside the window you define, with a holiday and early-close calendar. Example: BLOCK buy 1 CL at 03:12. window is 09:30-16:00.
8. cooldown_after_order_s. Enforces a cooldown after a loss or an order.
9. max_orders (rate limit). Caps orders per minute, hour, and day so a looping agent cannot spray the book. Example: BLOCK order 7 in 60s. limit is 6.
10. duplicate_order_protection. Refuses the same account, instrument, side, and quantity within a short window.
11. human_confirm. Live accounts can require explicit confirmation (off, first_order, every_live_order, or size_increase). Example: WARN live order held. confirm to send.
12. link_down_block. If the AddOn link is not fresh, orders are blocked with LINK_DOWN until the first post-connect account_state arrives.

Representative reason codes: KILL_SWITCH, DAILY_LOSS_HALT, MAX_CONTRACTS_PER_ORDER, MAX_POSITION, INSTRUMENT_NOT_ALLOWED, OUTSIDE_TRADING_WINDOW, ORDER_RATE_LIMIT, LINK_DOWN, PERMISSION_READ_ONLY, INVALID_QTY, UNKNOWN_ACCOUNT.

## Safety model, short form

- Default-deny live. A fresh install is paper only. arm-live refuses in the open-source core.
- Guardrails outside the model. Limits live in a config file the agent cannot edit; there is no tool to weaken them.
- Fail closed. If the daemon is down or the AddOn link is stale, no orders pass.
- Tamper-evident. The audit log is append-only and hash-chained; pitbridge audit verify catches edits or gaps.
- Reduce-only de-risking. Close and flatten are strictly reduce-only in the AddOn's C# order router.

Full write-up: https://pitbridge.com/docs/security-model/

## Pricing

- Free (open core): $0. Paper and read-only, one account, the full guardrail set, hash-chained audit. This is the top of the funnel.
- Pro: $49 per month list. Founder price $39 per month, locked for life, first 100 accounts. Adds live-execution unlock, prop-firm rule packs, fan-out to about five accounts, and audit export.
- Desk: planned, for 10+ accounts, multi-seat, and priority support. Not available yet.

Live-unlock is the gate: you pay when real money is at stake. The live provider and rule packs are closed components, not just a license flag.

## Honest status (as of 2026-07-09)

The daemon and AddOn are built and tested against a fake AddOn and harness. The first real NinjaTrader 8 session and live migration are gated behind an operator-run parity check. No live account has traded through PitBridge yet, and that is stated plainly until it is no longer true. Test counts, guardrail counts, and tool counts above are drawn from the repository. The package is published on PyPI (uvx pitbridge resolves and runs). The public GitHub repository and MCP registry listing are being finalized; verify availability before relying on them.

## Links

- Home: https://pitbridge.com/
- Quickstart: https://pitbridge.com/docs/quickstart/ (markdown: /docs/quickstart.md)
- Pricing: https://pitbridge.com/pricing/ (markdown: /pricing.md)
- NinjaTrader 8 MCP bridge: https://pitbridge.com/product/ninjatrader-8-ai-agent-bridge/
- Guardrails: https://pitbridge.com/product/guardrails/ (markdown: /product/guardrails.md)
- Local-first bridge: https://pitbridge.com/product/local-first-trading-bridge/
- Security model: https://pitbridge.com/docs/security-model/ (markdown: /docs/security-model.md)
- Trading AI guardrails: https://pitbridge.com/safety/trading-ai-guardrails/
- Prop firm compliance: https://pitbridge.com/safety/prop-firm-compliance/
- MCP for futures trading: https://pitbridge.com/learn/mcp-for-futures-trading/
- Compare vs CrossTrade: https://pitbridge.com/compare/pitbridge-vs-crosstrade/ (markdown: /compare/pitbridge-vs-crosstrade.md)
- Open source: https://pitbridge.com/open-source/
- Changelog: https://pitbridge.com/changelog/
- Waitlist: https://pitbridge.com/waitlist/
- Source: https://github.com/ToolstackVault/pitbridge

## Legal

PitBridge is trading infrastructure, not financial advice. Futures trading involves substantial risk of loss and is not suitable for every investor. Order examples on the site are hypothetical and use example configuration values. NinjaTrader is a registered trademark of NinjaTrader, LLC; PitBridge is an independent project and is not affiliated with, endorsed by, or sponsored by NinjaTrader, LLC.