Long Bias Guard

What it does

Boosts your long OPEN order size when the EXO indicator triggers, but only while your long inventory has fallen below a configurable ratio against your short inventory. Helps steer the pair back toward a user-chosen long bias without creating new triggers of its own.

Why this exists

In hedge mode you run a long grid and a short grid independently. On a strong uptrend, the short grid keeps filling sell orders so your short grows, while price moves away from the long grid's buy levels and long CLOSE sells fill, so your long shrinks. Over time your long can end up much smaller than your short.

Hedge Guard already catches the extreme case of this imbalance, but by the time it fires the gap is wide and the response is a single flat multiplier. On the short side, Hedge Throttle slows short accumulation during the pump itself. Long Bias Guard fills the long-side gap before Hedge Guard is needed.

It does not create new fills. Every time the long grid sizes an OPEN order, if EXO is already amplifying and Long Bias Guard is armed, EXO's multiplier is replaced with a larger one. While both conditions hold, every long OPEN order placed (new grid fills, counter orders, reconstructions) uses the boosted multiplier. When either condition stops holding, sizing reverts to the normal EXO multiplier (or base size) on the next order.

This feature is long-mode only. There is no short-side equivalent in v1.

For all config fields, see Config Reference.

How it works

Long Bias Guard runs every time the long grid sizes an OPEN order, right after EXO has been evaluated. It reads two numbers from your live position state:

longNotionalUsd and shortNotionalUsd for the pair, from the same source Hedge Guard uses
Combined realized plus unrealized PnL across both sides

From those it computes:

Quantity	Formula
Current ratio R	`longNotionalUsd / shortNotionalUsd`
Deficit in USD	`max(0, shortNotionalUsd * targetRatio - longNotionalUsd)`
Severity	`deficitUsd / shortNotionalUsd`

Long Bias Guard is armed when R is below targetRatio, unless:

shortNotionalUsd is 0 (nothing to compare against)
Combined PnL is negative (PnL gate, see below)
Hysteresis is holding it down after a recent disarm

Once armed, it picks a severity tier and reports a boost multiplier. Whenever EXO is also amplifying at the moment a long OPEN order is sized, that boost multiplier replaces EXO's multiplier for that order. This is re-evaluated on every long-OPEN sizing decision, so as long as both conditions hold the boost applies to every such order. EXO and Long Bias Guard never stack.

Tier selection

Tiers are an array of { minSeverity, multiplier } entries, evaluated top-down. The first tier whose minSeverity <= severity wins. The last tier must have minSeverity = 0 so a tier is always selected while armed.

Defaults (three tiers):

Tier	Severity range	Multiplier
Heavy	severity ≥ 0.30	4.0x
Medium	0.15 ≤ severity < 0.30	3.0x
Light	severity < 0.15	2.0x

You can use two or three tiers. Length 1 and length 4 or more are rejected by config validation.

Worked example

Settings: defaults (targetRatio = 1.5, hysteresisFactor = 0.95, three-tier default table).

You hold $4,000 short and $5,000 long on HYPEUSDT.

Step 1: Arming check

	Value	Check
R = $5,000 / $4,000	1.25	R < 1.5 → arming condition passes
Combined PnL	$+120	positive → PnL gate passes

Step 2: Deficit and severity

	Value
Deficit = max(0, $4,000 × 1.5 − $5,000)	$1,000
Severity = $1,000 / $4,000	0.25 (25%)

Step 3: Tier selection

Scanning the default table top-down: 0.25 is below 0.30 (Heavy), at or above 0.15 (Medium). Medium tier wins. Boost multiplier is 3.0x.

Step 4: Effective order size

Later, EXO triggers and stays active for a window. Your base size is $10 and EXO would normally apply 1.5x. Instead, for every long OPEN order sized during that window while Long Bias Guard stays armed:

Order	Base	EXO-only would give	Long Bias Guard gives
Long OPEN (each)	$10	$15 (1.5x)	$30 (3.0x)

EXO's 1.5x is replaced, not stacked. The boost applies to every long OPEN order placed while EXO is amplifying and Long Bias Guard is armed, including grid reconstructions and counter orders. Short OPEN and all CLOSE orders are unaffected.

Hysteresis

When R climbs above targetRatio, the feature disarms. To avoid flapping back on the same tick, re-arming requires R to fall below targetRatio * hysteresisFactor.

With defaults, that floor is 1.5 * 0.95 = 1.425. A sequence of R values [1.3, 1.55, 1.44, 1.42] produces armed states [true, false, false, true]: 1.44 is above the 1.425 floor, so re-arming waits until 1.42.

Set hysteresisFactor = 1.0 to disable hysteresis. Arming and disarming then both use targetRatio.

PnL gate

Long Bias Guard does not boost long-OPEN while the pair is losing money overall. If long.realisedPnl + long.unrealisedPnl + short.realisedPnl + short.unrealisedPnl is negative, the feature reports reason: pnl_gate_blocked and acts as disarmed. The ratio, deficit, and severity are still computed so the UI shows the real numbers.

This prevents the feature from doubling down size while the pair is underwater.

Interaction with other features

Feature	Interaction
EXO indicator	Long Bias Guard only ever replaces the EXO multiplier slot. When EXO does not trigger, Long Bias Guard has zero effect on order size.
Hedge Guard	When Hedge Guard is active, its multiplier wins and the EXO / Long Bias Guard branch is skipped entirely. Long Bias Guard never stacks with Hedge Guard.
Hedge Throttle	Short-mode only. Runs independently on the short grid and does not affect Long Bias Guard on the long grid.
Rebalancer (deficit amplification)	Rebalancer's `amplificationPerFill` still stacks on top of the EXO slot as before. Long Bias Guard changes only what sits in that slot.
Position Balancer (decumulation)	CLOSE-side only. No interaction.

Kill switches

Two layers of opt-out:

Per-user config: longBiasGuard.enabled = false (the default). Toggle to true in the Strategy page to turn the feature on.
Operator global kill switch: environment variable LONG_BIAS_GUARD_DISABLED=1. When set, the evaluator is not invoked and a single long_bias_guard_kill_switched log line is emitted at bot startup. User configs are left untouched.

Tuning tips

If you want...	Adjust this
A more aggressive target bias toward long	Raise `targetRatio` (e.g. `1.75` aims for long 75% larger than short)
Long Bias Guard to wait for larger drift before acting	Lower `targetRatio` or tighten `tiers[].minSeverity` thresholds
Faster re-arming after a disarm	Raise `hysteresisFactor` toward `1.0`
Gentler boosts	Lower each tier's `multiplier` (minimum above 1.0)
Fewer tiers	Use a two-tier config. The last tier must still have `minSeverity: 0`.

Troubleshooting

Symptom	Likely cause
Feature never arms	Short position is 0, or your current ratio is already above target
Armed but never boosts an order	EXO is not triggering on your long OPEN orders. Long Bias Guard only substitutes when EXO does
Armed flashes and then disarms	PnL gate is blocking. Check combined realized + unrealized PnL across both sides
Toggles rapidly near target	Raise `hysteresisFactor` slightly (e.g. `0.92` from `0.95`)
No effect after config change	Verify `enabled: true` at the effective scope, and that the operator kill switch env var is not set