# Grid Bot Architecture

This note describes the intended grid-bot design.

## Core idea

A survivable grid bot has three layers:

1. **Micro layer** , places trades and captures oscillation.
2. **Meso layer** , adapts the grid structure.
3. **Macro layer** , protects capital in bad regimes.

If one layer is missing:
- micro only, the bot can blow up
- macro only, it barely trades
- meso only, the behavior is unstable

## Operational model

The bot should not be static. It should:
- scale spacing with volatility
- slide with the market
- recenter only occasionally
- stop or reduce activity in strong trends

## Pseudocode outline

```text
INIT:
  center_price = current_price()
  grid_levels = 12
  recenter_threshold = 0.05
  max_inventory_pct = 0.7
  trend_filter_enabled = true

  build_grid(center_price)

LOOP:
  price = current_price()
  volatility = ATR(lookback=50)

  grid_step = clamp(k * volatility, min=0.008, max=0.025)

  handle fills
  slide grid when price leaves the active band
  recenter only when deviation is large
  pause new orders in strong trends
```

## Key mechanisms

### 1. Sliding grid

This is the default adjustment mode.

Effect:
- keeps the bot active
- avoids full reset shock
- behaves more like a market maker

Use this as the main structural adjustment.

### 2. Re-centering

Use only when price drifts too far.

Rule of thumb:
- keep it rare
- use only for larger deviations, e.g. 5 to 8 percent

Too much recentering kills the edge.

### 3. Volatility-based spacing

Fixed spacing is fragile.

Better:
- high volatility, wider grid
- low volatility, tighter grid

This reduces overtrading and avoids getting wrecked in spikes.

### 4. Trend filter

This is the survival layer.

A simple version can use:
- price vs MA200
- slope of MA50

When a strong trend is detected:
- pause new orders
- optionally allow only one-sided behavior

## Tunable parameters

Suggested starting range:
- grid spacing: ~1 to 1.5 percent for XRP
- grid width: ~±10 to 20 percent
- recenter threshold: 4 to 8 percent
- inventory cap: never above ~70 percent of capital
- volatility multiplier `k`: ~0.8 to 1.5

## Failure modes

Common ways grid bots die:
- always-on grid with no trend filter
- over-adjustment and too many recentering events
- ignoring inventory drift
- spacing too tight, so fees eat the edge
- static behavior while market regime changes

## Mental model

Think of the layers like this:
- **Grid** , engine
- **Sliding** , steering
- **Volatility scaling** , suspension
- **Trend filter** , brakes

## Summary

A good grid bot sells local volatility, respects regime shifts, and stays bounded in inventory. The goal is not constant activity, it is controlled adaptation.