README.md

OpenPit (Pre-trade Integrity Toolkit) for Python

openpit is an embeddable pre-trade risk SDK for integrating policy-driven risk checks into trading systems from Python.

For an overview and links to all resources, see the project website openpit.dev. For the Python API guide and reference, see openpit.readthedocs.io. For full project documentation, see the repository README. For conceptual and architectural pages, see the project wiki.

Versioning Policy (Pre‑1.0)

Before the 1.0 release OpenPit follows a relaxed Semantic Versioning:

• PATCH releases carry bug fixes and small internal corrections.
• MINOR releases may introduce new features and may also change the public interface.

Breaking API changes can appear in minor releases before 1.0. Pick version constraints that tolerate API evolution during the pre-stable phase.

Getting Started

Visit the PyPI package.

Examples

Runnable end-to-end examples live in examples/python/:

• spot_funds - simplest SpotFunds policy integration (limit-only).
• spot_table - table-driven test runner for the SpotFunds policy.
• rate_pnl_killswitch - rate-limit + P&L kill-switch supervisor.

Install

For normal end-user installation, use the published PyPI package:

pip install openpit

POSIX (Linux, macOS, etc)

Install Rust and Python 3.10+. Just is optional but recommended.

If you need local development/debugging, clone this repository and build from source with Maturin:

With Just:

just python-develop-debug

Local release build:

just python-develop-release

Manual:

python3 -m venv .venv
.venv/bin/python -m pip install -r ./requirements.txt
.venv/bin/python -m maturin develop --manifest-path bindings/python/Cargo.toml
.venv/bin/python -m maturin develop --release --manifest-path bindings/python/Cargo.toml

Windows

Install rustup, target x86_64-pc-windows-msvc, and Python 3.10+. Just is optional but recommended.

With Just:

rustup target add x86_64-pc-windows-msvc
just python-develop-debug
just python-develop-release

Manual:

rustup target add x86_64-pc-windows-msvc
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r .\requirements.txt
.\.venv\Scripts\python.exe -m maturin develop `
  --manifest-path bindings/python/Cargo.toml `
  --target x86_64-pc-windows-msvc
.\.venv\Scripts\python.exe -m maturin develop `
  --release `
  --manifest-path bindings/python/Cargo.toml `
  --target x86_64-pc-windows-msvc

Quick Start

import openpit
from openpit.param import AccountId, Price, Quantity, Side, TradeAmount, Volume
from openpit.pretrade.policies import (
    OrderSizeBrokerBarrier,
    OrderSizeLimit,
    build_order_size_limit,
)

# Build the engine once, at start-up: one broker-wide fat-finger cap.
engine = (
    openpit.Engine.builder()
    .no_sync()
    .builtin(
        build_order_size_limit().broker_barrier(
            OrderSizeBrokerBarrier(
                limit=OrderSizeLimit(
                    max_quantity=Quantity("500"),
                    max_notional=Volume("1000000"),
                ),
            ),
        ),
    )
    .build()
)

order = openpit.Order(
    operation=openpit.OrderOperation(
        instrument=openpit.Instrument("AAPL", "USD"),
        account_id=AccountId.from_int(99224416),
        side=Side.BUY,
        trade_amount=TradeAmount.quantity("1000"),
        price=Price("185"),
    ),
)

result = engine.execute_pre_trade(order=order)
if result.ok:
    # Send the order to the venue, then commit or roll the reservation back.
    result.reservation.commit()
else:
    for reject in result.rejects:
        # OrderSizeLimitPolicy [OrderQtyExceedsLimit]: order quantity exceeded
        print(f"{reject.policy} [{reject.code}]: {reject.reason}")

The explicit two-stage flow, drop copy, and post-trade reports are described on the Pre-trade Pipeline page.

What Is Inside

• Spot Funds - per-account solvency gate over spendable funds.
• Order Validation - structural integrity checks on every order.
• Rate Limit - throttle order flow per broker, asset, or account.
• Order Size Limit - fat-finger caps on quantity and notional.
• P&L Kill Switch - halt an account when realized P&L breaches bounds.
• Custom Python policies - the primary integration model.
• Account Blocking, Account Groups, Account Adjustments, and Balance Reconciliation.
• Drop Copy - record already executed orders without pre-trade enforcement.
• Market Data.
• Dynamic Reconfiguration of a live policy.
• Threading Contract - the GIL is held across callbacks, so Python policies run on the calling thread.
• Rejects and errors with stable reject codes; the full Python exception guide is on readthedocs.

Local Testing

POSIX (Linux, macOS, etc)

Recommended local flow:

With Just:

just test-python-debug
just test-python-unit-debug
just test-python-integration-debug

Manual:

python3 -m venv .venv
.venv/bin/python -m pip install -r ./requirements.txt
.venv/bin/python -m maturin develop --manifest-path bindings/python/Cargo.toml
.venv/bin/python -m pytest bindings/python/tests

Run only unit tests:

.venv/bin/python -m maturin develop --manifest-path bindings/python/Cargo.toml
.venv/bin/python -m pytest bindings/python/tests/unit

Run only integration test:

.venv/bin/python -m maturin develop --manifest-path bindings/python/Cargo.toml
.venv/bin/python -m pytest bindings/python/tests/integration

Windows

Optional: Just.

With Just:

just test-python-debug
just test-python-unit-debug
just test-python-integration-debug

Manual:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r .\requirements.txt
.\.venv\Scripts\python.exe -m maturin develop `
  --manifest-path bindings/python/Cargo.toml `
  --target x86_64-pc-windows-msvc
.\.venv\Scripts\python.exe -m pytest bindings/python/tests
.\.venv\Scripts\python.exe -m pytest bindings/python/tests/unit
.\.venv\Scripts\python.exe -m pytest bindings/python/tests/integration

For full build/test command matrix (manual and just), see the repository README.