Skip to content

Commit 59bf1c4

Browse files
committed
feat: add prediction-market venue fee models (Kalshi, ForecastEx, Polymarket US)
Prediction-market research needs fee-adjusted returns at executable prices, and backtests need the same fees inside the engine. Adds ml4t.backtest.prediction_market_fees with: - vectorized fee functions over NumPy arrays or Polars Series: kalshi_fee, kalshi_order_fees, forecastex_fee, polymarket_us_fee - CommissionModel adapters: KalshiCommission, ForecastExCommission, PolymarketUSCommission Kalshi: taker round_up(M * 0.07 * C * P * (1 - P)), maker factor 0 / 0.25 / 0.5 by series fee_type, trade fee rounded up to 0.000001, optional balance alignment to 0.01 (non-direct) or 0.0001 (direct) and the per-order rebate of accumulated overpayment. ForecastEx: 0.01 per contract per side. Polymarket US: taker theta (per-market fee_coefficient, default 0.0695) and maker rebate 0.0125, per-fill cent rounding half to even. Exact decimal inputs are snapped before ceiling/rounding so float noise cannot move a fee by a micro-dollar or a cent. Docstrings cite the venue documents read on 2026-10-08.
1 parent 672804b commit 59bf1c4

5 files changed

Lines changed: 927 additions & 0 deletions

File tree

‎docs/api/index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,20 @@ Auto-generated from source docstrings.
161161
options:
162162
show_root_heading: true
163163

164+
## Prediction-Market Fees
165+
166+
::: ml4t.backtest.prediction_market_fees
167+
options:
168+
show_root_heading: true
169+
members:
170+
- kalshi_fee
171+
- kalshi_order_fees
172+
- forecastex_fee
173+
- polymarket_us_fee
174+
- KalshiCommission
175+
- ForecastExCommission
176+
- PolymarketUSCommission
177+
164178
## Results
165179

166180
::: ml4t.backtest.result.BacktestResult

‎docs/user-guide/market-impact.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,66 @@ its opposite is charged once for its full quantity. The fee is allocated between
8484
and opening trade records in proportion to their quantities. Partial fills are
8585
charged separately when they execute.
8686

87+
### Prediction-Market Venue Fees
88+
89+
`ml4t.backtest.prediction_market_fees` implements the published fee schedules
90+
of Kalshi, ForecastEx (via IBKR) and Polymarket US. Prices are dollars per
91+
contract in `[0, 1]`; buying NO at `q` is a purchase at `q`.
92+
93+
| Venue | Fee per fill | Model |
94+
|-------|--------------|-------|
95+
| Kalshi | taker `round_up(M * 0.07 * C * P * (1 - P))`; maker 0, 0.25x or 0.5x taker by series `fee_type` | `KalshiCommission` |
96+
| ForecastEx | 0.01 per contract per side; no IBKR commission | `ForecastExCommission` |
97+
| Polymarket US | taker `0.0695 * C * p * (1 - p)`; maker rebate `0.0125 * C * p * (1 - p)` | `PolymarketUSCommission` |
98+
99+
Kalshi rounds the trade fee up to 0.000001. A non-direct member's balance is
100+
then aligned to whole cents, so one contract at 0.50 costs 0.02 instead of
101+
0.0175 while 100 contracts cost exactly 1.75; `rounding="cent"` reproduces
102+
this, and `kalshi_order_fees` adds the per-order rebate of accumulated
103+
overpayment. Polymarket US rounds each fill to the cent, half to even. The
104+
engine charges only non-negative fees, so `PolymarketUSCommission` charges a
105+
maker fill 0 and leaves out the rebate.
106+
107+
Assign a model to the broker before running:
108+
109+
```python
110+
from ml4t.backtest.prediction_market_fees import KalshiCommission
111+
112+
engine.broker.commission_model = KalshiCommission(
113+
liquidity="taker", fee_type="quadratic", fee_multiplier=1.0, rounding="cent"
114+
)
115+
```
116+
117+
For research over many fills, the vectorized functions take NumPy arrays or
118+
Polars Series and return an array of fees in dollars:
119+
120+
```python
121+
import polars as pl
122+
123+
from ml4t.backtest.prediction_market_fees import kalshi_fee, polymarket_us_fee
124+
125+
fills = pl.DataFrame(
126+
{
127+
"price": [0.50, 0.50, 0.90],
128+
"contracts": [1, 100, 10],
129+
"liquidity": ["taker", "taker", "maker"],
130+
}
131+
)
132+
kalshi = kalshi_fee(
133+
fills["price"],
134+
fills["contracts"],
135+
liquidity=fills["liquidity"],
136+
fee_type="quadratic_with_maker_fees",
137+
rounding="cent",
138+
)
139+
# array([0.02, 1.75, 0.02])
140+
polymarket = polymarket_us_fee(fills["price"], fills["contracts"], liquidity=fills["liquidity"])
141+
# array([ 0.017375, 1.7375 , -0.01125 ])
142+
```
143+
144+
Each function's docstring names the venue documents it follows and the date
145+
they were read; schedules change, so check them before relying on a result.
146+
87147
## Slippage Models
88148

89149
Slippage adjusts the configured execution price in the adverse direction. Use the spread model for a bar-only estimate of bid-ask crossing, or a percentage or fixed amount for other execution drag.

0 commit comments

Comments
 (0)