futures-position-sizer

Futures Position Sizer

Overview

Shapiro pipeline step 4: convert a direction, entry price, and stop-loss into a contract count, given an account risk budget and a verified contract spec (multiplier, tick size, tick value). This is a NEW, separate skill from position-sizer -- futures contracts are leveraged, multiplier-based instruments with wildly different dollar-per-point values (a $0.25 move is $12.50 on ES but $5.00 on NQ and $31.25 on ZB); reusing the equity share-count sizer for futures would silently produce wrong position sizes.

Two ways to size a trade:

• Mode A (explicit): supply --symbol --direction --entry --stop directly.
• Mode B (gate handoff): supply --gate-json <contrarian-setup-gate report> --entry. Direction and stop (the gate's invalidation_level) come from the gate's READY_FOR_PLAN report -- the sizer never sizes a setup the gate has not confirmed as READY, and never accepts an explicit --direction/--stop alongside --gate-json (the gate is authoritative when provided).

--entry is ALWAYS required, in both modes -- neither this skill nor the gate ever derives an entry price; the operator supplies it.

When to Use

• After contrarian-setup-gate reaches READY_FOR_PLAN and you need a contract count for the confirmed direction and stop
• User asks "how many ES/NQ/GC/CL/... contracts should I trade?"
• User has a futures trade idea with a known entry and stop and wants risk-based sizing
• User wants to check the verified contract spec (multiplier/tick size/tick value) for a symbol before sizing (--list-specs)

Prerequisites

• Python 3.9+, standard library only -- no API keys, fully offline
• A direction, entry, and stop (mode A), or a contrarian-setup-gate JSON report with setup_status: READY_FOR_PLAN (mode B)
• For a symbol outside the verified 23-market core table: its multiplier, tick size, and quote currency (all three, together)

Workflow

Step 1: Size the Position

Mode A -- explicit:

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ES --direction LONG --entry 5000.25 --stop 4980.00 \
  --account-size 100000

Mode B -- gate handoff:

--symbol may be omitted in mode B -- it is taken from the gate report. If both are given, they must match (gate_symbol_mismatch otherwise). --direction/--stop are rejected alongside --gate-json (usage error, exit 2) -- pass one mode or the other, never both.

Step 2: Read the Result

A NO_TRADE result from risk_below_one_contract still reports the full risk math (risk per contract, risk budget, stop distance) -- the account simply cannot afford one contract at this risk percentage and stop distance; widen the stop, increase risk %, or skip the trade.

Step 3: Check Warnings

warnings (top-level list) never blocks sizing -- it flags audit-worthy conditions: risk_pct_above_2 (risk above the 2% guideline), off_tick_grid_entry/off_tick_grid_stop (a non-bond symbol's price is not exactly on the tick grid -- legitimate for a mid-quote, but worth a second look).

Step 4: Inspect the Verified Contract Spec Table

Prints the full 23-market core table (multiplier, tick size, tick value, currency, exchange) sourced from official exchange contract-spec pages -- see references/futures-contract-specs.md for the per-row source URLs and verification dates.

Worked Example: Bond Off-Grid Guard (32nds -> Decimal)

Bond/note futures (ZT, ZF, ZN, ZB) quote in fractions of a point (32nds, or 32nds-of-32nds), commonly written with an apostrophe: 110'16 means 110 + 16/32 = 110.50. Typing 110.16 instead -- reading the digits after the apostrophe as if they were decimal cents -- is a classic, silent, wrong-money-math mistake: 110.16 is not on the ZB tick grid (0.03125 = 1/32) at all.

Every other symbol in the table quotes in plain decimal points -- an off-grid price there (a mid-quote, for instance) is only a soft off_tick_grid_* warning, never a rejection.

Output Contract

Writes futures_position_size_<SYMBOL>_<as-of>.json to --output-dir when --format json|both; --format text|both prints a formatted summary to stdout. --as-of defaults to today (this is an operator-time sizing tool, not a backtest tool).

Guardrails

1. Never sizes a position without an explicit stop. --stop is required in mode A; mode B refuses to size (gate_not_ready) until the gate itself reports READY_FOR_PLAN with a valid invalidation_level.
2. Floor, never round up -- exact by construction, no epsilon. contracts = floor(risk_budget / risk_per_contract) is computed with exact rational arithmetic (Python's Fraction, not float division), so contracts * risk_per_contract <= risk_budget holds by construction -- no epsilon nudge, no float-representation edge case, and no risk of ever exceeding the budget. Also rejected outright if the resulting count is economically implausible (an absurd input like a denormal-scale multiplier override). Zero contracts is a legitimate, fail-closed NO_TRADE outcome, not an error.
3. Two fail-closed classes, matched to who supplied the bad value. An operator-caused problem (an explicit --stop on the wrong side of --entry, a stop closer than one tick, a bond price typed off the tick grid) is a usage error: exit 2, no report written. The identical class of problem on a value that came from the untrusted gate-report file (mode B's stop) is instead a fail-closed NO_TRADE result: exit 0, a report IS written, naming the reason -- this never crashes on a bad or not-yet-ready gate file, matching every other skill in this pipeline.
4. Bond-family off-grid prices are a hard rejection, not a warning. ZT/ZF/ZN/ZB quote in 32nds/64ths notation; a price that doesn't land on the tick grid is almost certainly a notation mistype and would silently produce wrong money math if sized. Every other symbol only warns.
5. Margin is never computed. margin_note is a static, never-stale reminder -- margin requirements are broker- and time-dependent; this skill does not estimate them.
6. Currency-aware. Every core-table symbol is USD-quoted (confirmed by a table-wide unit test), including the CME FX futures whose contract SIZE is denominated in a foreign currency (e.g. B6's GBP 62,500) but which trade and settle in USD. A symbol quoted in a non-USD currency (via --contract-currency override) requires an explicit --fx-rate -- there is no silent default.
7. Not investment advice. This skill performs risk-based arithmetic on operator-supplied or gate-confirmed inputs; it does not recommend a trade, a direction, or an entry.

Resources

• scripts/futures_position_sizer.py -- CLI: argument parsing, hardened gate-json loading (unreadable / parse_error incl. RecursionError / non_finite via an iterative whole-file scan), report generation
• scripts/futures_sizing.py -- Pure sizing core: numeric validators, the verified 23-market contract-spec table, risk math, the floor algorithm, tick-grid guards, and gate-report shape normalization
• references/futures-contract-specs.md -- The verified contract-spec table with per-row official source URLs and verification dates
• references/sizing-methodology.md -- Formulas, the exact-rational floor algorithm's rationale, the fail-closed exit-code convention, and worked examples (ES long, B6 short via gate handoff)