configure-trade-execution

Trade Executor

You configure execution assumptions in strategy_spec.yaml or SDK brokers.

Stable Spec Configuration

Use this for audited CLI backtests:

signal:
  signal_time: close_t

execution:
  trade_time: next_open
  fill_price_mode: next_open
  order_timing: next_session_open
  price_bar: next_session
  price_type: open
  initial_cash: 100000
  lot_size: 1
  lot_size_config:
    default: 1
    by_symbol: {}
  cash_annual_return: 0.0
  insufficient_cash_policy: scale_down
  rebalance:
    frequency: daily
    interval_days: 1
    schedule: ""

cost:
  fee_rate: 0.001
  fee_min: 0.0
  slippage_rate: 0.001

Use side-specific costs only when confirmed:

cost:
  fee_rate: 0.0003
  fee_min: 0.0
  buy_fee_rate: 0.0003
  sell_fee_rate: 0.0003
  sell_tax_rate: 0.001
  slippage_rate: 0.001

Validator constraints:

• signal_time=close_t with trade_time=close_t is fatal.
• fill_price_mode=close or mid with signal_time=close_t is fatal.
• Legacy trade_time / fill_price_mode must agree with explicit order_timing / price_bar / price_type when both are present.
• fee_rate and slippage_rate must each be positive.
• buy_fee_rate and sell_fee_rate may override fee_rate when the user explicitly confirms side-specific fees.
• sell_tax_rate and stamp_tax model sell-side tax. If both are set, they must match; otherwise use one confirmed field and leave the other empty or zero.
• The only zero-cost exception is when both values are exactly 0.0 and the spec declares explicit execution semantics for a replay-style validation run; preserve the warning.
• lot_size must be a positive integer.
• lot_size_config.default must be a positive integer.
• lot_size_config.by_symbol is parsed but not executable yet; leave it empty until by-symbol sizing is supported.
• initial_cash must be positive and finite.
• cash_annual_return must be non-negative and finite.
• insufficient_cash_policy is scale_down (default) or reject. Orders are sized from the signal bar's close but fill at a later price, so a fully invested rebalance can be a few units short of cash at fill time. scale_down fills the largest whole-lot quantity the cash affords (the fill is marked scaled_to_available_cash); reject drops the whole BUY and leaves that target position empty until the next rebalance.
• execution.rebalance.frequency=daily uses interval_days.
• frequency=weekly requires schedule: week_start.
• frequency=monthly requires schedule: month_start.
• Do not use month-end or week-end calendar schedules in audited specs; those depend on future-row knowledge unless the runtime has explicit support.