Add prediction-market venue fee models (Kalshi, ForecastEx, Polymarket US)

[stefan-jansen]

What

New module ml4t.backtest.prediction_market_fees with the published trading-fee schedules of three prediction-market venues, as vectorized functions for research and as CommissionModel implementations for the engine.

Venue	Vectorized	Engine model
Kalshi	kalshi_fee, kalshi_order_fees	KalshiCommission
ForecastEx (via IBKR)	forecastex_fee	ForecastExCommission
Polymarket US	polymarket_us_fee	PolymarketUSCommission

Prices are dollars per contract in [0, 1]; buying NO at q is a purchase at q (the quadratic fees are symmetric). Functions accept scalars, NumPy arrays and Polars Series, including per-row liquidity, side, fee_type, fee_multiplier and fee_coefficient, and return a float64 array.

Fee rules

• Kalshi: taker round_up(M * 0.07 * C * P * (1 - P)); maker 0 for quadratic, 0.25x for quadratic_with_maker_fees, 0.5x for quadratic_with_combo_maker_fees; flat raises (formula not published in machine-readable form). rounding="exact" is the trade fee rounded up to 0.000001; "cent" adds the non-direct-member balance alignment to 0.01 (1 contract at 0.50 pays 0.02, 100 contracts pay 1.75); "direct" aligns to 0.0001. kalshi_order_fees applies the per-order accumulator that rebates overpayment in whole precision steps.
• ForecastEx: 0.01 per contract per side, no IBKR commission. Docstring flags the pre-2026-03-31 embedded-fee era and the block-trade waiver.
• Polymarket US: taker theta * C * p * (1 - p) (default 0.0695; pass ml4t-data's per-market fee_coefficient), maker rebate -0.0125 * C * p * (1 - p) as a negative fee, optional per-fill cent rounding half to even. The engine model charges makers 0 because commissions must be non-negative; documented. Combo curve and volume rebates are not modeled.

Values that are exact in decimal (for example 0.07 * 100 * 0.25) are snapped before ceiling or rounding, so float noise cannot add a micro-dollar (1.750001) or move a half-cent (14.595 -> 14.59).

Sources (read 2026-10-08) are cited in each docstring: Kalshi fee schedule PDF, Kalshi OpenAPI FeeType, Kalshi fee-rounding page, ForecastEx CFTC filings, IBKR event-contract commissions, Polymarket US fee schedule.

Tests

tests/test_prediction_market_fees.py (49 tests): schedule values and published worked examples, decimal-arithmetic reference over the full cent price grid for Kalshi (all rounding modes, both sides) and Polymarket US, the per-order accumulator, input validation, protocol/deepcopy compliance, and an engine run that charges 0.02 and 1.75 on two fills.

Each of these planted defects makes at least one test fail: wrong taker rate, dropped series multiplier, maker charged on quadratic, wrong combo maker factor, trade fee rounded down, ceiling without float-noise snap, cent rounding per contract, no per-order rebate, naive round(x, 2), round-half-up, maker rebate sign dropped, ForecastEx half-penny fee.

Docs

User Guide section "Prediction-Market Venue Fees" in market-impact.md, API reference entry, regenerated compatibility snapshot for the two documented imports. CHANGELOG.md is generated and has not been updated by recent PRs, so it is untouched.

Retained validation evidence

The new module moves the engine tree digest that the retained parity evidence is pinned to, so the evidence is refreshed in this PR:

• CORRECTNESS_RESULTS.json: re-derived with run_all_correctness.py; 66 pass, 2 unsupported, unchanged. Of 231,740 values, the 201 that differ are all digests, commits, durations or the timestamp.
• REAL_STRATEGY_RESULTS.json: rebuilt from runs of all 17 required pairs; 17/17 pass. The 72 changed values are timings, output-manifest digests, platform, commit, engine digest and timestamp.
• REAL_STRATEGY_PERFORMANCE.json: certified, not re-timed (the cycle ran twice: once more after switching the public return annotations to plain numpy.ndarray, because NDArray[np.float64] renders differently on the minimum and nightly NumPy and broke the compatibility snapshot). Nothing in the engine or the runners imports the fee module, so it cannot run inside the timed engine.run() call.

Checks run locally

ruff check, ruff format --check, ty check, full pytest (2261 passed, 14 skipped), pre-commit run --all-files, compatibility snapshot, changelog and parity-claim checks, documentation API audit, mkdocs build --strict, rendered link check, coverage gate.

Known failing check, not caused by this PR

Compatibility / Prerelease (Python 3.15) (3 OS) and the Compatibility Gate that aggregates it fail on tests/contracts/test_correctness_evidence.py: pandas 3.1.0rc0 emits Pandas4Warning: Series.values returning an ndarray that drops timezone information from inside exchange_calendars, and filterwarnings = error turns it into a failure. Dependabot PR #130 fails the same jobs. Reproduced locally with pandas 3.1.0rc0; a message-scoped ignore filter makes those tests pass, but test_warning_policy_fails_new_warnings_and_has_no_global_suppression caps the filter list at 5 and it already has 5, so the fix needs an owner decision and is left out of this PR.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.