Skip to the page

Futures

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, and each close pays the day's move in cash.

RootWhat it isMultiplierSettles onListed
IDXthe price index of the roster's companies250 dollars a pointthe index of the expiry session's opening printstwo quarterly contracts
FFthe policy rate, as 100 less the rate4,167 dollars a pointthe average policy rate over its 21-session monththirteen monthly contracts
TR3the policy rate compounded over a quarter2,500 dollars a pointthe compounded policy rate over its 63 sessionseight quarterly contracts
OILthe oil price1,000 barrelsthe oil price at the expiry session's opentwelve 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.

RowWhat it measurespt-v22Real bandReal value
IF1sd of the front index future's basis to its carry fair value, bp3.721.21 to 6.273.74
IF2lag-1 autocorrelation of that basis0.4150.127 to 0.7160.421
IF4cost of a day's TWAP at 10% of the front future's volume, daily sigma0.1640.100 to 0.210
NS1the night's share of the front index future's daily variance0.4700.300 to 0.6000.461
RF1, 1 monthpolicy-rate future's rate less the month's realized average, bp1.42-0.07 to 2.621.28
RF1, 3 monthsthe same, 3 months ahead11.213.50 to 17.5010.50
RF1, 6 monthsthe same, 6 months ahead31.227.96 to 53.4430.70
RF2RMS daily change of the front policy-rate future on meeting days over other days1.391.06 to 3.322.19
RF4the eight-quarter term-rate strip less the 2-year yield, bp18.3-160.3 to 70.6-44.8
OF1share of sessions with oil contract 1 above contract 40.4400.396 to 0.6380.517
OF2correlation of the oil curve's slope with inventory's deviation from its 5-year mean0.5880.443 to 0.6650.554
OF3elasticity of oil contract 4's daily change to contract 1's0.8480.485 to 1.0630.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).