Skip to content

qlcore

Pure trading math and domain models for Python.

qlcore provides the computational foundation for trading systems: positions, portfolios, PnL calculations, risk metrics, position sizing, margin, and fees — all with financial-grade precision using Python's Decimal.

Why qlcore?

  • :material-calculator: Pure Computation

    No I/O, no network, no database. Just math. Use it anywhere — backtesting, live trading, analytics.

  • :material-decimal: Decimal-Safe

    All calculations use Python's Decimal for financial precision. No floating-point surprises.

  • :material-lock: Immutable Positions

    Positions are frozen dataclasses. Thread-safe, audit-friendly, and easy to reason about.

  • :material-check-decagram: Type-Safe

    PEP 561 compliant with full type annotations. Your IDE and mypy will thank you.

Quick Example

import qlcore as qc

# Create a crypto portfolio
portfolio = qc.crypto_portfolio(initial_balance=10_000)

# Record a trade
fill = qc.Fill.create(
    order_id="order-001",
    instrument_id="BTC-USDT-PERP",
    side=qc.OrderSide.BUY,
    quantity="0.1",
    price="45000",
    fee="4.5",
    timestamp_ms=1701849600000,
)

# Apply to portfolio
portfolio = portfolio.apply_fill(fill)

# Check unrealized PnL
position = portfolio.positions["BTC-USDT-PERP"]
upnl = qc.unrealized_pnl(position, current_price="46000")
print(f"Unrealized PnL: {upnl}")  # +$100

Getting Started

Modules at a Glance

Module Purpose
positions SpotPosition, PerpetualPosition, FuturesPosition
portfolio Portfolio, Account, Ledger
events Fill, FundingEvent, LiquidationEvent, SettlementEvent
risk sharpe_ratio, sortino_ratio, max_drawdown, VaR
sizing fixed_quantity, percent_of_equity, kelly_fraction
margin Initial/maintenance margin, margin utilization
fees FeeSchedule, VIP tiers, funding fees
pnl Realized/unrealized PnL, portfolio PnL
serialization JSON encode/decode, file persistence