GridBTRebalancer
What it does
Detects when your position has drifted from the expected baseline and gradually corrects it by adjusting the size of normal grid orders. No extra orders are placed. Correction blends invisibly into regular grid activity.
The baseline is the position size the bot expects based on normal grid fills. If you manually add to a position, your actual size exceeds the baseline and creates an excess. If the bot misses fills during downtime, your actual size falls short and creates a deficit. The Rebalancer detects the mismatch and corrects it gradually.
How it works
After every order fill, the bot compares your actual position to the baseline. If the difference (the imbalance) exceeds a threshold, rebalancing kicks in:
- Excess (you hold more than baseline): CLOSE orders are slightly oversized so you sell off the surplus over multiple fills.
- Deficit (you hold less than baseline): OPEN orders are slightly oversized so you rebuild the position over multiple fills.
The correction spreads across many fills rather than one large order, so it blends into normal grid activity.
The Rebalancer column on the dashboard shows the current excess or deficit for each side. A positive number means the bot is working to reduce your position. A negative number means it is working to rebuild it.
For all config fields, see Config Reference → Rebalancer.
Resetting the baseline
If you manually add inventory and do not want the Rebalancer to treat it as excess, reset the baseline from the dashboard. The reset button is next to the Rebalancer column heading. Only reset when you have intentionally added inventory and want the bot to treat that new size as normal. Leave it alone during regular operation.
Pressing reset tells the bot to treat your current live position as the new baseline. Any existing excess or deficit is cleared and rebalancing starts fresh from that point.
How price gating works (excess only)
Price gating is a configurable tolerance band that controls when excess correction is active. Price gating exists for one specific purpose: when you manually add to a position, you want the bot to work off that excess profitably. You do not want your amplified CLOSE orders filling while the price is below what you paid.
Price gating never closes the full excess in one order. It only controls whether the amplified CLOSE orders from the distribution formula are active or paused. When the price gate is active, the normal grid continues cycling but the excess portion of each CLOSE order is suppressed. When price moves into a favourable zone, the amplification resumes and each CLOSE order gradually chips away at the excess over many fills.
When the Rebalancer detects excess, it checks the current market price against the average price you added at. If price is above that average, amplified CLOSE orders are active and the excess is worked off gradually. If price is within the buffer zone below your average, the amplification is paused and you wait for recovery.
You can add to a position multiple times at different prices using limit orders, whenever you want. The Rebalancer tracks the imbalance across bot restarts (it persists in the database), and multiple adds at different prices produce a single average imbalance price. The bot always gates against that average.
When price drops far enough below your average add price to exceed the buffer, the amplification resumes even at a loss. This is intentional: holding oversized inventory indefinitely is riskier than accepting a small loss to restore balance. A tight buffer (
priceGatingBufferPct = 1) means amplified CLOSE orders resume almost immediately if price moves against you. A loose buffer (priceGatingBufferPct = 50) gives you a wide margin before resuming.Both examples below use HYPEUSDT with an average excess add price of $30.00.
Example 1: Default buffer:
priceGatingBufferPct = 10 (10% = $3.00)| Zone | Price condition | What happens |
|---|---|---|
| Above average | Price ≥ $30.00 | Amplified CLOSE orders active. Excess worked off gradually at a profit. |
| Buffer zone | $27.00 ≤ price < $30.00 | Amplification paused. Normal grid continues. Bot waits up to $3.00 below average. |
| Below buffer | Price < $27.00 | Amplified CLOSE orders resume. Excess worked off gradually to avoid holding oversized inventory indefinitely. |
Example 2: Tight buffer:
priceGatingBufferPct = 1 (1% = $0.30)| Zone | Price condition | What happens |
|---|---|---|
| Above average | Price ≥ $30.00 | Amplified CLOSE orders active. Excess worked off gradually at a profit. |
| Buffer zone | $29.70 ≤ price < $30.00 | Amplification paused. Normal grid continues. Bot waits for a $0.30 recovery. |
| Below buffer | Price < $29.70 | Amplified CLOSE orders resume. Excess worked off gradually to avoid holding oversized inventory indefinitely. |
Price gating only applies to excess rebalancing. Deficit rebalancing (rebuilding a position) is not applicable.
Worked example
Settings:
orderSizeUsd = $10, minTriggerRatio = 2.0, pivotRatio = 10.0, maxDistributionRate = 20.0.HYPEUSDT is anchored at $30.00. Price trended down and your long accumulated $50 excess over baseline. The current price is above your average add price, so the price gate is open and amplified CLOSE orders are active.
| Step | Calculation | Result |
|---|---|---|
| Imbalance | Long excess = $50 over baseline | |
| Trigger check | $50 ÷ $10 = 5.0, exceeds minTriggerRatio of 2.0 | Rebalancing activates |
| Base rate | 100 ÷ (pivotRatio × 4) = 100 ÷ 40 = 2.5% | |
| Distribution rate | 2.5% × 10.0 ÷ 5.0 = 5.0%, within maxDistributionRate (20%) | 5% applied |
| Extra per fill | $50 × 5% = $2.50 | Each CLOSE order = $12.50 |
| Recovery | ~20 filled CLOSE orders to clear $50 excess | Rebalancing deactivates |
With a smaller imbalance (ratio 1.5), the calculated rate would be 16.7%, capped at 20%. Very small imbalances get higher rates so they resolve quickly. Large imbalances get lower rates so they unwind gradually.
Tuning tips
The defaults work well for most setups. If you need to adjust:
- Excess corrects too slowly: Lower
pivotRatioto concentrate correction into fewer fills - Price gating blocks too often: Reduce
priceGatingBufferPctto narrow the hold zone - Small fluctuations trigger rebalancing: Raise
minTriggerRatio
See Config Reference for all fields, and Formulas for the math behind distribution rate.