trader-mcp/strategies/grid_trader.md

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.