Class SpreadExecutionAlgo

java.lang.Object

com.quantfinlib.execution.SpreadExecutionAlgo

public final class SpreadExecutionAlgo
extends Object

Two-legged spread execution with LEGGING-RISK control — pairs trades, cash-vs-futures basis, stub-vs-hedge: the trade is the SPREAD, and the risk is the moment you own one leg without the other. The discipline every spread desk runs:

• the LEAD leg (the illiquid one — single name, off-the-run, basis leg) is worked patiently, because it is the constraint;
• the HEDGE leg (the liquid one — future, ETF, benchmark) CHASES the lead leg's fills at the spread ratio, because liquidity is cheap there;
• the legging imbalance |executedLead·ratio − executedHedge| is capped: at the cap the algo stops adding lead risk entirely and the hedge child becomes the full imbalance — cross it, pay the spread, get flat. An imbalance cap that yields is not a cap.

Quantities are positive per leg (the buy/sell directions are the caller's order tickets); the ratio is hedge units per lead unit. Deterministic, single-threaded, research/warm lane — feed the children to your routers (AdaptiveSor, CrbRouter).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	SpreadExecutionAlgo.Children	This interval's child quantities, per leg.

Constructor Summary

Constructors

Constructor	Description
SpreadExecutionAlgo(long leadParentQty, double hedgePerLeadUnit, long leggingLimitHedgeUnits, long leadChildMax)

Method Summary

Modifier and Type	Method	Description
SpreadExecutionAlgo.Children	decide()	The next children.
boolean	done()	Done when the lead is complete AND the hedge has caught up.
long	hedgeExecuted()
long	imbalanceHedgeUnits()	Current legging imbalance in hedge units (positive = hedge behind).
long	leadExecuted()
void	onHedgeFill(long qty)	Hedge-leg fill.
void	onLeadFill(long qty)	Lead-leg fill.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SpreadExecutionAlgo

public SpreadExecutionAlgo(long leadParentQty,
 double hedgePerLeadUnit,
 long leggingLimitHedgeUnits,
 long leadChildMax)

Parameters:

leadParentQty - total lead-leg quantity to execute, > 0

hedgePerLeadUnit - spread ratio: hedge units per lead unit, > 0

leggingLimitHedgeUnits - max |lead·ratio − hedge| imbalance tolerated, ≥ 1 hedge unit

leadChildMax - largest lead child per decision, > 0 (the patience knob — small children, passive fills)

Method Details

decide

public SpreadExecutionAlgo.Children decide()

The next children. The hedge chases the CURRENT imbalance; the lead child is sized so even a full fill cannot push the projected imbalance past the cap (assuming the hedge child also fills — the cap protects against the hedge NOT filling, which is why the lead stops entirely at the cap).

onLeadFill

public void onLeadFill(long qty)

Lead-leg fill.

onHedgeFill

public void onHedgeFill(long qty)

Hedge-leg fill. Bounded by the full spread's hedge target — a fill beyond it is a duplicate report, the same upstream bug the lead-leg guard exists to catch.

imbalanceHedgeUnits

public long imbalanceHedgeUnits()

Current legging imbalance in hedge units (positive = hedge behind).

leadExecuted

public long leadExecuted()

hedgeExecuted

public long hedgeExecuted()

done

public boolean done()

Done when the lead is complete AND the hedge has caught up.