# Grid Trader Configuration

This file explains every config parameter used by `strategies/grid_trader.py`.

## Core grid behavior

### `grid_levels`
- **Type:** int
- **Default:** `6`
- **Range:** `1..20`
- **What it does:** Number of grid orders kept per side.
- **When to change it:**
  - Lower it for a smaller, simpler grid.
  - Raise it if you want a wider ladder and more incremental entries/exits.
- **Tradeoff:** More levels means more orders, more clutter, and usually slower capital usage.

### `grid_step_pct`
- **Type:** float
- **Default:** `0.012`
- **Range:** `0.001..0.1`
- **What it does:** Base spacing between grid levels as a percentage of price.
- **When to change it:**
  - Increase it in volatile markets.
  - Decrease it in quiet, tight ranges.
- **Tradeoff:** Too small can make the grid noisy, too large can make it miss moves.

### `volatility_timeframe`
- **Type:** string
- **Default:** `"1h"`
- **What it does:** Timeframe used to measure volatility for adaptive grid sizing.
- **When to change it:**
  - Use a shorter timeframe for faster adaptation.
  - Use a longer one for smoother, slower reactions.
- **Tradeoff:** Shorter = more reactive, longer = more stable.

### `volatility_multiplier`
- **Type:** float
- **Default:** `0.5`
- **Range:** `0.0..10.0`
- **What it does:** Scales ATR-based volatility into the live grid step.
- **When to change it:**
  - Increase it if you want the grid to widen more aggressively in volatility.
  - Decrease it if you want tighter spacing.
- **Tradeoff:** Higher values make the grid less sensitive to the base step.

### `grid_step_min_pct`
- **Type:** float
- **Default:** `0.005`
- **Range:** `0.0001..0.5`
- **What it does:** Lower bound for the live grid step.
- **When to change it:**
  - Raise it if the grid gets too tight.
  - Lower it if you want very fine spacing.

### `grid_step_max_pct`
- **Type:** float
- **Default:** `0.03`
- **Range:** `0.0001..1.0`
- **What it does:** Upper bound for the live grid step.
- **When to change it:**
  - Lower it to prevent the grid from becoming too wide in volatile markets.
  - Raise it if you want the strategy to tolerate bigger swings.

## Position sizing and inventory

### `order_size`
- **Type:** float
- **Default:** `0.0`
- **What it does:** Fixed per-order size when you want manual sizing.
- **When to change it:**
  - Set it when you want a static size instead of wallet-derived sizing.
  - Leave it at `0.0` to let the strategy derive size from balance logic.

### `inventory_cap_pct`
- **Type:** float
- **Default:** `0.7`
- **Range:** `0.0..1.0`
- **What it does:** Caps how much inventory the strategy should commit.
- **When to change it:**
  - Lower it for more conservative inventory usage.
  - Raise it if you want the grid to keep more capital active.

### `max_notional_per_order`
- **Type:** float
- **Default:** `0.0`
- **What it does:** Upper limit for the notional value of a single order.
- **When to change it:**
  - Set it to cap order size risk.
  - Leave it at `0.0` for no explicit per-order cap.
- **Note:** With `dust_collect=true`, the strategy may exceed this cap to clear small leftover balances, but never more than available funds.

### `dust_collect`
- **Type:** bool
- **Default:** `False`
- **What it does:** Allows the sizing logic to exceed `max_notional_per_order` if needed to consume dust.
- **When to change it:**
  - Enable it when you want the strategy to clean up small leftover balances.
  - Leave it off if you want strict order caps.

### `use_all_available`
- **Type:** bool
- **Default:** `True`
- **What it does:** Lets the strategy use the available balance more fully when sizing orders.
- **When to change it:**
  - Disable it for stricter, more conservative capital usage.
  - Keep it enabled if you want the grid to self-fill as much as possible.

## Re-centering

### `recenter_pct`
- **Type:** float
- **Default:** `0.05`
- **Range:** `0.0..0.5`
- **What it does:** Baseline deviation threshold that can trigger a recenter.
- **When to change it:**
  - Lower it for faster recentering.
  - Raise it if you want the grid to stay anchored longer.
- **Tradeoff:** Too low can make the grid chase price.

### `recenter_atr_multiplier`
- **Type:** float
- **Default:** `0.35`
- **Range:** `0.0..10.0`
- **What it does:** Adjusts the recenter threshold using volatility.
- **When to change it:**
  - Increase it if you want recentering to be less eager in volatile markets.
  - Decrease it if you want it to react faster.

### `recenter_min_pct`
- **Type:** float
- **Default:** `0.0025`
- **Range:** `0.0..0.5`
- **What it does:** Minimum allowed recenter threshold.
- **When to change it:**
  - Raise it to prevent over-reactive recentering.
  - Lower it if you want very tight anchor control.

### `recenter_max_pct`
- **Type:** float
- **Default:** `0.03`
- **Range:** `0.0..0.5`
- **What it does:** Maximum allowed recenter threshold.
- **When to change it:**
  - Raise it if you want the strategy to tolerate larger drifts before recentring.
  - Lower it if you want a tighter leash.

### `center_shift_factor`
- **Type:** float
- **Default:** `0.3333333333`
- **Range:** `0.0..1.0`
- **What it does:** Controls where the new center lands between the old center and the new price.
- **Formula:** `new_center = price + (old_center - price) * center_shift_factor`
- **Meaning:**
  - `0.0` = snap center to current price
  - `1.0` = keep old center
  - `0.333...` = move the center one third of the way back from price toward the old center
- **When to change it:**
  - Lower it if you want the grid to follow price more aggressively.
  - Raise it if you want the grid to retain more of its old anchor.

## Fees and execution

### `fee_rate`
- **Type:** float
- **Default:** `0.0025`
- **Range:** `0.0..0.05`
- **What it does:** Fallback fee assumption used when live fee lookup is unavailable.
- **When to change it:**
  - Set it to match your venue if fee lookup is unreliable.
  - Leave it as a fallback safety value if live fees are available.

### `order_call_delay_ms`
- **Type:** int
- **Default:** `250`
- **Range:** `0..10000`
- **What it does:** Delay between order calls.
- **When to change it:**
  - Increase it if the exchange is sensitive to bursts.
  - Set it to `0` for test or fast local runs.

## Trend protection

### `enable_trend_guard`
- **Type:** bool
- **Default:** `True`
- **What it does:** Enables the higher-timeframe trend guard.
- **When to change it:**
  - Disable it if you want the grid to trade regardless of regime.
  - Keep it on if you want the strategy to stand down in strong opposing trends.

### `trend_guard_reversal_max`
- **Type:** float
- **Default:** `0.25`
- **Range:** `0.0..1.0`
- **What it does:** Maximum reversal score allowed before the trend guard stops the grid.
- **When to change it:**
  - Lower it for stricter trend filtering.
  - Raise it if you want the grid to remain active more often.

## Visibility

### `debug_orders`
- **Type:** bool
- **Default:** `True`
- **What it does:** Enables verbose order/debug logging.
- **When to change it:**
  - Keep it on while tuning.
  - Turn it off when you want quieter logs.

## Practical starting points

- **Conservative:** lower `inventory_cap_pct`, higher `recenter_pct`, higher `center_shift_factor`
- **Reactive:** lower `recenter_pct`, lower `center_shift_factor`, smaller `grid_step_pct`
- **Range-friendly:** moderate `grid_levels`, moderate `grid_step_pct`, `enable_trend_guard=true`

## Current recommended interpretation

If you want the grid to feel like it “leans” toward the fill instead of snapping, the key knob is `center_shift_factor`.

For your described behavior, `0.3333333333` is the right default.