Skip to main content
Transaction costs are modelled as a pluggable, per-pulse calculator. They are strictly opt-in: the default NoFeeCalculator charges zero, so a backtest only sees fees once you inject a real calculator.

How fees are charged

Within a single pulse the portfolio collects every fee-bearing transaction into one batch, then charges the whole batch at once. There are three kinds of event, captured by FeeEventType: Each event is a frozen FeeEvent dataclass carrying the trade, the signed quantity_units (lots already expanded to units, positive for buys and negative for sells), the fill price, and the event_type. At the end of the pulse the portfolio drains the batch in a single call:
The returned per-event fees are summed and netted against equity for that pulse:
Why a batch, not one call per tradePassing the whole pulse’s events together lets a calculator price events relative to each other - for example block-trade pricing where the larger-notional side is charged and the other side is rebated to zero. A per-event call could not see those relationships.

Built-in calculators

All live in pulse.fees. FeeCalculator is the ABC; the contract is calculate(events, datafeed) -> list[float], returning one non-negative fee per event in the same order and length as the input. FixedFeeCalculator and PercentageFeeCalculator reject a negative argument with ValueError.

Injecting a calculator

Three entry points, all interchangeable:

A custom calculator

Subclass FeeCalculator and implement calculate. Use the datafeed for contract metadata or market lookups when a scheme needs it.
Return exactly one fee per event, in order; the portfolio relies on the alignment.

Reading fees back

After a run the totals live on the portfolio and in Stats:
  • portfolio.total_fees - cumulative fees over the whole run.
  • portfolio.pulse_fees_history - fees per pulse, aligned with the equity history.
  • Stats.fee_stats - a FeeStats with total_fees, fee_drag_pct (fees over initial equity), avg_fee_per_trade, fees_pct_of_gross_pnl, max_pulse_fees, and max_pulse_fees_datetime. When fees are all zero (the default), fee_stats is a zero-valued instance.
Three charts visualise the impact: plot_pulse_fees_history, plot_cumulative_fees, and plot_fee_impact_on_equity. The last one synthesises the no-fee counterfactual from pulse_total_pnl_history, so you do not need to run the backtest twice to see the drag.
Gross vs netpulse_total_pnl_history is gross of fees (per-pulse market PnL before fees); equity_history is net (the money in the account after fees). With NoFeeCalculator the two agree. See Portfolio, equity and PnL for the full distinction.
Related: Portfolio, equity and PnL · Metrics and Stats · Architecture and the pulse loop · Fees notebook
Last modified on November 4, 2026