# Futures

Source: https://docs.tradefloor.dev/futures.html

> Index, rate and oil futures on pt-v22: symbols, quotes and curves, trading, variation margin and settlement, and the measured rows against real bands.

pt-v22 lists four kinds of futures beside the stocks. Each contract has its own order book, is marked to a settlement price at every close, and settles in cash at expiry. A future costs nothing to open. The account posts [margin](https://docs.tradefloor.dev/margin.html), and each close pays the day's move in cash.

| Root | What it is | Multiplier | Settles on | Listed |
| --- | --- | --- | --- | --- |
| IDX | the price index of the roster's companies | 250 dollars a point | the index of the expiry session's opening prints | two quarterly contracts |
| FF | the policy rate, as 100 less the rate | 4,167 dollars a point | the average policy rate over its 21-session month | thirteen monthly contracts |
| TR3 | the policy rate compounded over a quarter | 2,500 dollars a point | the compounded policy rate over its 63 sessions | eight quarterly contracts |
| OIL | the oil price | 1,000 barrels | the oil price at the expiry session's open | twelve monthly contracts |

Each family has its own switch: `futures_index_listed`, `futures_rates_listed` (`FF` and `TR3`) and `futures_oil_listed`. pt-v22 turns all three on. Index futures list from the first session, and the others list at the first close.

## Symbols

A symbol names the root and the session the contract expires at, so `IDX.F0056` is the index future that settles on the opening prints of session 56. The number is at least four digits, zero-padded. In the library it is the engine's session, counted from 0 like `engine.day_count`. The hosted app, its API, MCP and tfrun count days from 1, so they show the same contract as `IDX.F0057`. `tf.contracts.parse` and `tf.contracts.format` read and write symbols in the library's numbering.

An index future rolls six sessions before it expires, and from then on the next contract is the front one. An oil future rolls six sessions before as well. Rate futures roll on their expiry session.

## Reading the market

```
import tradefloor as tf

engine = tf.Engine(seed=7, universe=tf.Universe.random(20, seed=11), model="pt-v22")
engine.run_days(1)                     # rate and oil futures list at the first close

for c in engine.contracts():
    if c["kind"] == "future" and c["front"]:
        q = engine.quote(c["symbol"])
        print(c["symbol"], q["price"], q["fair"], q["basis_bp"], q["initial_margin"])

print(engine.curve)                    # policy rate, 2- and 10-year yields, corporate
print(engine.index_level)              # the index IDX settles on
```

`contracts()` lists every contract listed now with its `symbol`, `root`, `expiry`, `roll`, `front`, `multiplier`, `tick` and `settlement`. `quote(symbol)` gives the book's `bid` and `ask`, the `price`, the carry `fair` value it is quoted around and the `basis_bp` to it, the last settlement `mark`, the underlying (`index`), the financing `rate` and `dividends` the fair value holds, `sessions_to_expiry`, the `daily_volume` its book is sized to, and the `initial_margin` and `maintenance_margin` one contract asks, as the last close set them. A rate future's quote adds `expected`, the average policy rate the model forecasts over the contract's period, and `premium`, the term premium its price carries on top, both in percent. A symbol that is not listed raises `ValidationError`.

`futures_bars(day)` and `settlements_table(day)` give the same as Arrow tables, one row per contract per recorded day, and `settlements(day)` lists each final settlement with its `value` and the `reference` it was read from.

## Trading

```
from tradefloor.portfolio import Portfolio

pf = Portfolio(cash=1_000_000, max_leverage=4.0)
front = next(c["symbol"] for c in engine.contracts()
             if c["root"] == "IDX" and c["front"])

engine.open_market()
pf.collect_dividends(engine)
pf.settle_open(engine)                 # expiries, then the last close's margin call
pf.execute(engine, front, 2)           # buy 2 contracts in the future's book
engine.run_session(9, 30, 3, 390)
pf.sync(engine)
engine.close_market()
pf.settle_close(engine)                # variation margin to the new settlement mark

print(pf.futures[front], pf.margin(engine))
```

A future always trades in its own book, whatever the preset's book settings for stocks, so a market order walks the book's depth and a limit order waits in it. `Portfolio.futures` holds each position as signed contracts at its settlement mark. A fill pays its distance from the mark in cash at once, and each close moves the mark to the new settlement price and pays the difference. At expiry the last payment is to the settlement price, the position closes, and `Portfolio.settled` records it.

`tf.evaluate`, the gym environment and the library's MCP sessions call `settle_open` and `settle_close` at every open and close. A loop that drives the engine itself calls them as above.

The index future also trades through the night, in `night_session_steps` steps (10 on pt-v22). `engine.run_night(steps)` walks some of them, and `engine.run_night()` the rest.

## The hosted app

On a session whose preset lists futures, `GET /v1/sessions/{id}/contracts` lists them, `GET /v1/sessions/{id}/contracts/quotes?symbols=IDX.F0057` quotes them, and `GET /v1/sessions/{id}/contracts/curves` gives the yield curve and each root's term structure. A contract trades with the ordinary order calls by its symbol, in whole contracts, as a market or a limit order. `observe` shows the contracts held under `contracts` and the account's margin under `account.margin`. Settlements and margin calls appear in the market log as events of kind `account`. tfrun's `market.listed()`, `market.contract_quotes()` and `market.curves()` read the same.

## Measured rows

Each row below was read over 270 simulated histories of 21 years and is graded against a band read from real market data and fixed before the futures were built. Every row falls inside its band.

| Row | What it measures | pt-v22 | Real band | Real value |
| --- | --- | --- | --- | --- |
| IF1 | sd of the front index future's basis to its carry fair value, bp | 3.72 | 1.21 to 6.27 | 3.74 |
| IF2 | lag-1 autocorrelation of that basis | 0.415 | 0.127 to 0.716 | 0.421 |
| IF4 | cost of a day's TWAP at 10% of the front future's volume, daily sigma | 0.164 | 0.100 to 0.210 |  |
| NS1 | the night's share of the front index future's daily variance | 0.470 | 0.300 to 0.600 | 0.461 |
| RF1, 1 month | policy-rate future's rate less the month's realized average, bp | 1.42 | -0.07 to 2.62 | 1.28 |
| RF1, 3 months | the same, 3 months ahead | 11.21 | 3.50 to 17.50 | 10.50 |
| RF1, 6 months | the same, 6 months ahead | 31.22 | 7.96 to 53.44 | 30.70 |
| RF2 | RMS daily change of the front policy-rate future on meeting days over other days | 1.39 | 1.06 to 3.32 | 2.19 |
| RF4 | the eight-quarter term-rate strip less the 2-year yield, bp | 18.3 | -160.3 to 70.6 | -44.8 |
| OF1 | share of sessions with oil contract 1 above contract 4 | 0.440 | 0.396 to 0.638 | 0.517 |
| OF2 | correlation of the oil curve's slope with inventory's deviation from its 5-year mean | 0.588 | 0.443 to 0.665 | 0.554 |
| OF3 | elasticity of oil contract 4's daily change to contract 1's | 0.848 | 0.485 to 1.063 | 0.774 |

The real figures come from E-mini S&P 500 futures against the S&P 500 index (2020 to 2026, with Treasury bill financing and dividends from the total-return index), 30-day fed funds futures and the Federal Reserve's meeting calendar (2000 to 2026), Piazzesi and Swanson (2008) for the 3- and 6-month premia, the Adrian, Crump and Moench term premium (1961 to 2026), and NYMEX WTI contracts 1 to 4 with EIA crude inventories (1985 to 2024). IF4 uses the cost band the stocks are graded on, since the square-root law of trading cost holds on futures too. RF4 reads above the real value because the strip carries the premium RF1 asks for, which the proxy leaves out.

Some rows hold by construction, and each was checked:
- The index future settles on the index of the expiry session's opening prints (IF3, error 0), and a rate future on the realized average policy rate (RF3, error 0).
- After the night session, the index future at 09:29 sits 3.65 bp (sd) from fair value on the opening index, inside IF1's ceiling of 6.27 bp (NS2).
- The model's forecast of the policy rate, which the rate futures are priced from, is unbiased at every horizon graded: its largest mean error is 0.69 standard errors (RF5, limit 2).
- The forecast of oil, which the oil futures are priced from, runs a little high at the longest horizon. At 126 sessions its mean error is 0.36 dollars a barrel, about 0.5% of the price, and its largest is 2.003 standard errors, just past the limit of 2 (OF4). OF4 is shown for comparison and isn't counted toward the grade.
- No rule that trades the basis, calendar spreads, the oil curve or meeting days on published data earns a reliable excess over buy and hold (XD1).
- Buying the stock basket at the open after the night's futures move does no better (XD2).
- Pushing the expiry's opening prints against a position at the limit loses money after cost (XD3).
