futures-position-sizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Shapiro流程步骤4：在给定账户风险预算和经过验证的合约规格（multiplier、tick size、tick value）的情况下，将方向、入场价和止损价转换为合约数量。这是一个与

position-sizer

分离的全新技能——期货合约是基于multiplier的杠杆工具，每点美元价值差异极大（ES合约波动0.25美元对应12.50美元，NQ对应5.00美元，ZB对应31.25美元）；若将股票头寸计算器复用在期货上，会悄无声息地产生错误的头寸规模。

两种头寸计算方式：

模式A（显式参数）：直接传入
```
--symbol --direction --entry --stop
```
参数。
模式B（网关传递）：传入
```
--gate-json <contrarian-setup-gate报告文件> --entry
```
参数。方向和止损价（即网关的
```
invalidation_level
```
）来自网关的
```
READY_FOR_PLAN
```
报告——只有网关确认标记为READY的交易设置，计算器才会进行头寸计算；同时传入
```
--gate-json
```
和显式的
```
--direction
```
/
```
--stop
```
参数会被拒绝（网关参数具有权威性）。

两种模式下

--entry

参数都是必填项——本工具和网关都不会推导入场价，需由操作者自行提供。

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
```
)

当
```
contrarian-setup-gate
```
返回
```
READY_FOR_PLAN
```
状态后，需要根据确认的方向和止损价计算合约数量时
用户询问“我应该交易多少份ES/NQ/GC/CL/...合约？”
用户有明确入场价和止损价的期货交易想法，想要基于风险进行头寸规划时
用户在计算头寸前想要查看某一标的经过验证的合约规格（multiplier/tick size/tick value）时（使用
```
--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)

Python 3.9+，仅依赖标准库——无需API密钥，完全离线运行
模式A：需提供方向、入场价和止损价；模式B：需提供包含
```
setup_status: READY_FOR_PLAN
```
状态的
```
contrarian-setup-gate
```
JSON报告
对于核心23个市场以外的标的：需提供其multiplier、tick size和报价货币（三者缺一不可）

Workflow

操作流程

Step 1: Size the Position

步骤1：计算头寸规模

Mode A -- explicit:

bash

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ES --direction LONG --entry 5000.25 --stop 4980.00 \
  --account-size 100000 --risk-pct 1.0 \
  --output-dir reports/ --format both

Mode B -- gate handoff:

bash

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --gate-json reports/contrarian_setup_gate_B6_2026-07-15.json \
  --entry 1.3400 \
  --account-size 100000 --risk-pct 1.0 \
  --output-dir reports/ --format both

--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.

模式A——显式参数：

bash

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ES --direction LONG --entry 5000.25 --stop 4980.00 \
  --account-size 100000 --risk-pct 1.0 \
  --output-dir reports/ --format both

模式B——网关传递：

bash

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --gate-json reports/contrarian_setup_gate_B6_2026-07-15.json \
  --entry 1.3400 \
  --account-size 100000 --risk-pct 1.0 \
  --output-dir reports/ --format both

模式B中可省略

--symbol

参数——该值会从网关报告中提取。若同时传入

--symbol

和网关报告，二者必须一致，否则会触发

gate_symbol_mismatch

错误。

--direction

--stop

参数与

--gate-json

不可同时使用（会触发使用错误，退出码为2）——两种模式二选一，不可混用。

Step 2: Read the Result

步骤2：查看计算结果

`sizing_status`	Meaning
`SIZED`	`contracts` >= 1; `total_risk_usd` / `risk_pct_of_account` are the actual risk taken
`NO_TRADE`	Never a crash -- always carries `no_trade_reason` . See the reason glossary below

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.

`sizing_status`	含义
`SIZED`	`contracts` >= 1； `total_risk_usd` / `risk_pct_of_account` 为实际承担的风险
`NO_TRADE`	程序不会崩溃——该状态始终附带 `no_trade_reason` 字段。详见下方原因说明

若

NO_TRADE

的原因是

risk_below_one_contract

，报告仍会展示完整的风险计算过程（每份合约风险、风险预算、止损距离）——说明在当前风险比例和止损距离下，账户资金不足以承担1份合约的风险；此时可放宽止损、提高风险比例或放弃该交易。

Step 3: Check Warnings

步骤3：查看警告信息

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).

warnings

（顶层列表）不会中断头寸计算——仅标记需要审核的情况：

risk_pct_above_2

（风险比例超过2%的指导线）、

off_tick_grid_entry

off_tick_grid_stop

（非债券类标的价格未落在tick网格上——若为中间报价则属合理情况，但需再次确认）。

Step 4: Inspect the Verified Contract Spec Table

步骤4：查看经过验证的合约规格表

bash

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py --list-specs

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.

bash

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py --list-specs

该命令会打印完整的23个核心市场合约规格表（包含multiplier、tick size、tick value、货币、交易所），数据来源于官方交易所的合约规格页面——详见

references/futures-contract-specs.md

中的每行数据来源URL和验证日期。

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

示例：债券类标的网格校验（32进制转十进制）

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.

bash

undefined

债券/票据期货（ZT、ZF、ZN、ZB）采用点数分数（32分之一或64分之一）报价，通常用撇号表示：

110'16

代表

110 + 16/32 = 110.50

。若误输入

110.16

——将撇号后的数字当作十进制小数——是典型的隐性计算错误：

110.16

完全不在ZB的tick网格（

0.03125

= 1/32）上。

bash

undefined

WRONG -- 110.16 is not on the 1/32 grid; this is almost certainly a

错误示例——110.16不在1/32网格上；这几乎可以肯定是将"110'16"（代表110.50）输错了。程序将以状态码2退出，不会生成报告：

mistyped "110'16" (which means 110.50). Exits 2, no report written:

—

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py
--symbol ZB --direction LONG --entry 110.16 --stop 108.00
--account-size 100000 --risk-pct 1.0

CORRECT -- decimal points, not the raw 32nds digits:

正确示例——使用十进制格式，而非原始32进制数字：

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py
--symbol ZB --direction LONG --entry 110.50 --stop 108.00
--account-size 100000 --risk-pct 1.0


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.

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py
--symbol ZB --direction LONG --entry 110.50 --stop 108.00
--account-size 100000 --risk-pct 1.0


表格中其他所有标的均采用纯十进制报价——若价格不在网格上（比如中间报价），只会触发`off_tick_grid_*`软警告，不会被拒绝。

Output Contract

输出合约

Writes

futures_position_size_<SYMBOL>_<as-of>.json

--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).

yaml

schema_version: "1.0"
symbol: ES
direction: LONG
sizing_status: SIZED | NO_TRADE
no_trade_reason: null | risk_below_one_contract | gate_not_ready | gate_symbol_mismatch | ...
entry: 5000.25
stop: 4980.00
stop_distance_points: 20.25
stop_distance_ticks: 81
contract_spec: {multiplier: 50, tick_size: 0.25, tick_value: 12.5, currency: USD, source: cme, verified: "2026-07-17"}
risk_per_contract_usd: 1012.50
risk_budget_usd: 2000.00
contracts: 1
total_risk_usd: 1012.50
risk_pct_of_account: 1.01
max_contracts_cap_applied: false
fx_rate_used: 1.0
margin_note: "Exchange margin requirements are broker/time-dependent and NOT computed here; verify initial/maintenance margin with your broker."
gate: {report_path, setup_status, gate_confidence, warnings}   # mode B only
warnings: []
run_context: {symbol, as_of, schema_version, skill}

当使用

--format json|both

参数时，程序会在

--output-dir

目录下生成

futures_position_size_<SYMBOL>_<as-of>.json

文件；使用

--format text|both

参数时，会在标准输出打印格式化的摘要信息。

--as-of

参数默认值为当前日期（本工具为实时头寸计算工具，而非回测工具）。

yaml

schema_version: "1.0"
symbol: ES
direction: LONG
sizing_status: SIZED | NO_TRADE
no_trade_reason: null | risk_below_one_contract | gate_not_ready | gate_symbol_mismatch | ...
entry: 5000.25
stop: 4980.00
stop_distance_points: 20.25
stop_distance_ticks: 81
contract_spec: {multiplier: 50, tick_size: 0.25, tick_value: 12.5, currency: USD, source: cme, verified: "2026-07-17"}
risk_per_contract_usd: 1012.50
risk_budget_usd: 2000.00
contracts: 1
total_risk_usd: 1012.50
risk_pct_of_account: 1.01
max_contracts_cap_applied: false
fx_rate_used: 1.0
margin_note: "Exchange margin requirements are broker/time-dependent and NOT computed here; verify initial/maintenance margin with your broker."
gate: {report_path, setup_status, gate_confidence, warnings}   # mode B only
warnings: []
run_context: {symbol, as_of, schema_version, skill}

Guardrails

防护机制

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
```
.
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.
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.
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.
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.
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.
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.

无明确止损价则绝不计算头寸：模式A中
```
--stop
```
为必填项；模式B中，只有当网关报告
```
READY_FOR_PLAN
```
状态并提供有效的
```
invalidation_level
```
时，才会进行计算，否则会返回
```
gate_not_ready
```
状态。
向下取整，绝不向上舍入——计算精确无误差：
```
contracts = floor(risk_budget / risk_per_contract)
```
采用精确的有理数运算（Python的
```
Fraction
```
，而非浮点数除法），因此
```
contracts * risk_per_contract <= risk_budget
```
始终成立——无误差调整、无浮点数表示边缘情况，绝不会超出风险预算。若计算结果为0份合约，属于合法的
```
NO_TRADE
```
结果，而非错误。
两类故障闭环处理，匹配错误来源：操作者导致的问题（比如
```
--stop
```
与
```
--entry
```
方向错误、止损距离小于1个tick、债券类标的价格输错网格）属于使用错误：程序以状态码2退出，不生成报告。若相同问题来自不可信的网关报告（模式B的止损价），则返回
```
NO_TRADE
```
结果：程序以状态码0退出，生成报告并说明原因——绝不会因网关文件错误或未就绪而崩溃，与本流程中其他技能保持一致。
债券类标的价格不在网格上会被强制拒绝，而非警告：ZT/ZF/ZN/ZB采用32/64进制报价，价格不在网格上几乎可以肯定是输入错误，若进行计算会产生隐性资金计算错误。其他标的仅会触发警告。
绝不计算保证金：
```
margin_note
```
为静态提示——保证金要求取决于经纪商和时间；本工具不估算保证金。
支持多货币：核心表格中所有标的均以美元报价（已通过表级单元测试确认），包括合约规模以外币计价但以美元交易结算的CME外汇期货（如B6的62,500英镑）。若标的采用非美元报价（通过
```
--contract-currency
```
参数覆盖），需显式传入
```
--fx-rate
```
参数——无默认值。
不提供投资建议：本工具仅对操作者提供或网关确认的输入进行基于风险的算术计算；不推荐交易、方向或入场价。

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)

```
scripts/futures_position_sizer.py
```
——CLI工具：参数解析、增强型网关JSON加载（处理不可读/解析错误包括RecursionError/非有限值等情况）、报告生成
```
scripts/futures_sizing.py
```
——纯计算核心：数值验证器、经过验证的23个市场合约规格表、风险计算、向下取整算法、tick网格校验、网关报告格式标准化
```
references/futures-contract-specs.md
```
——经过验证的合约规格表，包含每行数据的官方来源URL和验证日期
```
references/sizing-methodology.md
```
——计算公式、精确有理数向下取整算法的原理、故障闭环退出码约定、示例（ES多头、通过网关传递的B6空头）