The Portfolio Engine
The portfolio engine is the component that maintains the authoritative internal record of positions, cash and P&L, updating on every fill and continuously reconciling that record against the broker's.
Quick Answer
The portfolio engine keeps the system's own book of positions, cash and profit, updating on every fill and reconciling continuously against the broker's record. Buying back one of two short Nifty call lots at 90 against an average of 120 books (120 minus 90) times 65, or Rs 1,950, net of STT and charges.
Definition: The Portfolio Engine
The Portfolio Engine is the component that maintains the internal record of positions, cash and P&L, updating on every fill and reconciling continuously against the broker's record.
Key takeaways: The Portfolio Engine
- The portfolio engine is the single reconciled source of truth for positions, cash and P&L
- The broker is authoritative; reconcile against it at startup, periodically and after reconnects
- Apply fills idempotently and include all costs so P&L is realisable, not gross
- Halt on unexplained divergence: acting on a wrong position is a dangerous state
The Portfolio Engine at a glance
| Component | Portfolio engine (the book) |
|---|---|
| Responsibility | Track positions, cash, realised/unrealised P&L |
| Updates | On every fill event |
| Reconciles | Continuously against broker record |
| Cost handling | Deducts STT, charges, brokerage |
| Failure mode | Drift from broker; gross-of-cost P&L |
| Outputs | Authoritative state for risk and reporting |
The Portfolio Engine in simple words
The portfolio engine is the system's accountant. It knows exactly what you hold, how much cash you have, and whether you are up or down, updating every time an order fills. Just as importantly, it keeps checking its books against the broker's, because if the two disagree, every decision above it is built on a wrong number.
What The Portfolio Engine is for
Position sizing, risk checks and signals all need to know the current state. Centralising that state in one reconciled record means the whole system agrees on what it holds, rather than each part guessing from its own fills.
The Portfolio Engine — professional explanation
Single responsibility
The portfolio engine owns the answer to what do we currently hold, at what cost, with how much cash, and what is the P&L. It is the single source of truth for position state that the risk engine, sizing engine and signals all read. It does not decide trades or place orders; it records their consequences. Its correctness is foundational: if the recorded position is wrong, sizing over- or under-bets, the risk engine mis-measures exposure, and the signal may think it is flat when it is long. This is why reconciliation, not just bookkeeping, is central to its design.
State it maintains
Core state is a set of positions (per instrument: quantity, average entry price, and for options the strike, expiry and side), available and blocked cash or margin, and P&L split into realised (from closed trades) and unrealised (mark-to-market on open positions). It also derives exposures the risk engine needs: gross and net exposure, per-instrument concentration, and margin utilisation. Positions update on fills; unrealised P&L updates on every price tick via the data layer's marks. The engine must handle the full lifecycle of a position including averaging into it, partially closing, and flipping direction, each of which changes average price and realised P&L in specific ways.
Inputs and outputs
Inputs are fill events (from execution/OMS), price marks (from the data layer), and periodic broker snapshots of positions and funds. Outputs are read queries the rest of the system depends on: current position for an instrument, available capital for sizing, current P&L and exposure for risk. The engine should expose a consistent snapshot rather than piecemeal fields that can be read mid-update, because a reader that sees an updated position but stale cash will compute nonsense. A clean interface returns an immutable snapshot of the whole state as of a point in time.
Reconciliation with the broker
The broker is the authoritative record of truth; the internal book is a fast local mirror that can drift. Reconciliation compares the two, positions, quantities, and where possible average prices and cash, and flags any mismatch. Drift happens for real reasons: a fill event missed during a disconnect, a manual trade placed outside the system, an exchange-side adjustment, or a bug. Reconciliation should run at startup (before trading, so the system begins from truth), periodically during the session, and after any reconnect. The policy on a mismatch matters: small, explainable differences may auto-correct to the broker's number and log; a large unexplained divergence should halt trading, because acting on a wrong position is dangerous.
P&L accounting subtleties
P&L looks simple and is full of traps. Realised P&L on a partial close must use the correct cost basis (average or FIFO, chosen and applied consistently). Fees, brokerage, STT, exchange charges and GST must be included or reported P&L will be optimistic; in Indian F&O these frictions are non-trivial and STT on option selling and futures is a real drag. Marking open positions needs a sensible price (last trade, or mid) and must handle illiquid strikes where the last trade is stale. Flipping a position from long to short in one fill realises the long P&L and opens a new short at the fill price, which the accounting must split correctly.
How it fails
The engine fails by missing a fill (so its position is wrong), double-counting a fill (same problem, opposite sign), using a stale mark (so unrealised P&L and thus risk are wrong), applying an inconsistent cost basis, or omitting costs. The most dangerous failure is silent position drift: the system believes it is flat and happily opens a new position while actually already holding one, doubling exposure. Defences: idempotent fill application keyed on order/fill ids so a replayed event does not double-count, frequent reconciliation against the broker, halting on unexplained divergence, and marking against a validated price with a staleness check.
Observability
Expose the book so it can be watched and trusted. Emit metrics for each position, current P&L (realised, unrealised, net of costs), exposure and margin used, and, critically, the reconciliation status and the size of any position or cash discrepancy. A reconciliation-difference alert should be prominent, because a growing gap between system and broker means the source of truth is being lost. Log every fill applied with the resulting position and average price so the book's evolution can be replayed, and snapshot the full state periodically so a restart can begin from a recent known-good point and then reconcile forward.
How The Portfolio Engine looks visually
Worked example: The Portfolio Engine
Illustrative example (Indian market)
A bot holds short 2 lots of a Nifty call at an average of 120. A fill event reports buying back 1 lot at 90, so the portfolio engine reduces the position to short 1 lot, books realised P&L of (120 minus 90) times 65 equals 1,950 rupees on the closed lot, and leaves the remaining lot marked at the latest price for unrealised P&L. It nets brokerage, STT and charges into the realised figure, so the reported profit is what actually reaches the account, not the gross. At the next reconciliation the broker also shows short 1 lot, so the books agree. Had the broker instead shown flat, meaning the other lot had been closed by an order the system missed, the engine would flag a divergence, halt new trading, and require the mismatch to be resolved before continuing.
Indian F&O charges STT, exchange transaction charges, SEBI turnover fees, stamp duty and GST on brokerage, and STT on option sell-side and on futures is a meaningful cost; a portfolio engine that reports P&L gross of these will consistently overstate performance, so the accurate approach is to deduct the full charge stack on every fill so the book reflects realisable P&L.
Advantages of The Portfolio Engine
- One reconciled source of truth for positions, cash and P&L across the system
- Reconciliation catches missed fills, manual trades and drift before they compound
- Cost-inclusive P&L reflects what is actually realisable, not an optimistic gross
- A consistent state snapshot prevents readers from acting on half-updated data
Limitations of The Portfolio Engine
- Only as accurate as its fill feed and marks; a missed fill silently corrupts state
- Reconciliation depends on the broker's snapshot being timely and correct
- Marking illiquid options is imprecise when the last trade is stale
- Cost and tax accounting is fiddly and jurisdiction-specific, easy to get subtly wrong
Why The Portfolio Engine matters in practice
- Every sizing and risk decision is only as trustworthy as the portfolio state
- Silent position drift can double exposure without any component noticing
How professionals treat The Portfolio Engine
Professional shops separate a fast internal position keeper from an end-of-day book reconciled against the prime broker or clearer, and they reconcile intraday too. They apply a consistent, documented cost-basis convention, mark to validated prices, fold every fee and tax into P&L, and treat any unexplained break as an incident to resolve before trading continues. The internal book is understood to be a mirror that can drift, so reconciliation against the authoritative record is a scheduled, monitored process rather than an afterthought.
Common mistakes with The Portfolio Engine
- Trusting the internal book without reconciling, so a missed fill leaves the position permanently wrong
- Double-counting a fill on a replay because fill application is not idempotent
- Reporting P&L gross of brokerage, STT and charges, overstating performance
- Marking open positions with a stale last-trade price on an illiquid strike
- Continuing to trade after an unexplained reconciliation divergence instead of halting
- Applying an inconsistent cost basis when partially closing, corrupting realised P&L
The Portfolio Engine: frequently asked questions
What is a portfolio engine in a trading system?
It is the component that maintains the authoritative internal record of positions, cash and P&L, updating on every fill and reconciling continuously against the broker's record so the whole system shares one correct view of state.
Why does the portfolio engine reconcile with the broker?
Because the internal book is a fast local mirror that can drift from reality when a fill is missed, a manual trade is placed, or a bug occurs. The broker is the source of truth, so reconciliation catches and corrects divergence.
How does the portfolio engine handle costs and taxes?
It deducts brokerage, STT, exchange charges, stamp duty and GST from realised P&L on each fill, so reported P&L reflects what is actually realisable. Ignoring these overstates performance, and in Indian F&O the costs are non-trivial.
How does the engine handle a position flipping from long to short?
A fill large enough to flip realises the P&L on the closed long quantity at the fill price and opens a new short at that price. The accounting must split the fill into a close and an open rather than net it into one wrong average.
What state does the portfolio engine provide to other components?
Current positions, available capital or margin for sizing, and P&L and exposure for risk, ideally as a consistent point-in-time snapshot so readers never see a half-updated mix of new position and stale cash.
Does the portfolio engine place orders?
No. It records the consequences of trades, positions, cash and P&L, but it does not decide or place them. That separation keeps it a clean, trustworthy source of state for the components that do act.
Voice search: how people ask about The Portfolio Engine
Natural-language questions people ask about The Portfolio Engine.
What does the portfolio engine do?
It is the system's accountant. It tracks what you hold, your cash, and your profit or loss, updating every time an order fills.
Why check my positions against the broker?
Because your own records can drift if a fill is missed or a trade is placed outside the system. The broker is the real truth, so you keep comparing to it.
What is the difference between realised and unrealised profit?
Realised profit is locked in from trades you have closed. Unrealised profit is the paper gain or loss on positions you still hold, and it moves with the price.
Sources & references
- Robert Kissell, “The Science of Algorithmic Trading and Portfolio Management”, Academic Press (Elsevier), 2013
- Ernest P. Chan, “Quantitative Trading: How to Build Your Own Algorithmic Trading Business”, 2nd ed., Wiley, 2021
Published 10 July 2026. Educational content only — not investment advice. Markets and rules change; verify current conventions with SEBI, NSE/BSE and your broker.