xingwudao/open-xquant/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.

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.