configure-trade-execution

name	configure-trade-execution
description	Configure open-xquant execution timing, fees, slippage, lot size, fill price mode, and broker assumptions; use when users discuss trading costs or order 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
  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.
• 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.

Supported audited calendars are XNYS, ARCX, XSHG, and XSHE. Use lot_size_config.default: 100 for A-share examples.

Cost Defaults Are Not Conclusions

If the user does not specify costs, use conservative placeholders only after stating the assumption:

• US equity demo: fee_rate=0.001, slippage_rate=0.001, lot_size=1
• A-share demo: ask first; lot size is often 100; commission, stamp tax, and slippage must be confirmed instead of inferred
• crypto demo: ask exchange and fee tier first

Do not silently choose zero fees or zero slippage.

SDK Broker Pattern

from decimal import Decimal

from oxq.trade.fees import PercentageFee, SideAwarePercentageFee
from oxq.trade.sim_broker import FillPriceMode, SimBroker
from oxq.trade.slippage import PercentageSlippage

broker = SimBroker(
    fee_model=SideAwarePercentageFee(
        buy_rate=Decimal("0.0003"),
        sell_rate=Decimal("0.0003"),
        sell_tax_rate=Decimal("0.001"),
    ),
    slippage_model=PercentageSlippage(rate=Decimal("0.001")),
    fill_price_mode=FillPriceMode.NEXT_OPEN,
    market_calendar="XNYS",
)

Red Lines

• Do not allow same-bar close signal and close fill in audited research.
• Do not call a result tradable unless execution costs were explicit.
• Do not compare two strategies with different cost assumptions without highlighting the difference.
• Do not compare two strategies with different fill price, calendar, lot size, or cash return assumptions without highlighting the difference.