> ## Documentation Index
> Fetch the complete documentation index at: https://condor.hummingbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Grid Executor

> Like Position Executor but with multiple order levels across a price range

The **Grid Executor** is like a Position Executor with multiple levels. It places orders at evenly spaced price intervals between a start and end price, managing each level independently with take profit targets.

## Overview

| Property | Value |
| - | - |
| Position Type | Spot or Perp |
| keep\_position | Configurable |
| Use Cases | Range-bound markets, accumulation, market making |

## How It Works

```mermaid theme={null}
flowchart TB
    subgraph Grid["Grid Levels"]
        L1[Level 1: $3000]
        L2[Level 2: $3100]
        L3[Level 3: $3200]
        L4[Level 4: $3300]
        L5[Level 5: $3400]
    end

    L1 --> F1{Filled?}
    L2 --> F2{Filled?}
    L3 --> F3{Filled?}

    F1 -->|Yes| TP1[Take Profit Order]
    F2 -->|Yes| TP2[Take Profit Order]

    TP1 --> C1[Level Complete]
    TP2 --> C2[Level Complete]
```

1. **Grid Creation**: Divides price range into evenly spaced levels
2. **Order Placement**: Places entry orders at each level
3. **Fill Management**: When a level fills, places take profit order
4. **Level Completion**: Each level manages its own entry/exit cycle
5. **Risk Management**: Overall position managed by triple barrier

## Configuration

```python theme={null}
from hummingbot.strategy_v2.executors.grid_executor.data_types import GridExecutorConfig
from hummingbot.strategy_v2.executors.position_executor.data_types import TripleBarrierConfig

config = GridExecutorConfig(
    controller_id="my-agent",
    connector_name="binance",
    trading_pair="ETH-USDT",
    side=TradeType.BUY,

    # Grid boundaries
    start_price=Decimal("3000"),      # Lower bound
    end_price=Decimal("3500"),        # Upper bound
    limit_price=Decimal("2900"),      # Stop loss price

    # Sizing
    total_amount_quote=Decimal("1000"),  # Total capital to deploy
    min_spread_between_orders=Decimal("0.01"),  # 1% between levels
    min_order_amount_quote=Decimal("5"),  # Min order size

    # Execution
    max_open_orders=5,                # Max simultaneous orders
    activation_bounds=Decimal("0.02"), # Only active within 2% of price

    # Risk management
    triple_barrier_config=TripleBarrierConfig(
        stop_loss=Decimal("0.05"),    # 5% total stop loss
        time_limit=86400,              # 24 hour limit
    ),

    leverage=1,
    keep_position=False,
)
```

## Parameters

### Grid Boundaries

| Parameter | Description |
| - | - |
| `start_price` | Lower price bound of the grid |
| `end_price` | Upper price bound of the grid |
| `limit_price` | Stop loss price - exits all positions if breached |
| `side` | `BUY` for accumulation grid, `SELL` for distribution |

### Sizing

| Parameter | Default | Description |
| - | - | - |
| `total_amount_quote` | - | Total capital to deploy across all levels |
| `min_spread_between_orders` | 0.05% | Minimum % spread between grid levels |
| `min_order_amount_quote` | 5 | Minimum order size in quote |

### Execution

| Parameter | Default | Description |
| - | - | - |
| `max_open_orders` | 5 | Maximum simultaneous open orders |
| `max_orders_per_batch` | None | Orders to place per batch |
| `order_frequency` | 0 | Seconds between order batches |
| `activation_bounds` | None | Only keep orders within this % of current price |
| `safe_extra_spread` | 0.01% | Extra spread for safety |

### Risk Management

| Parameter | Description |
| - | - |
| `triple_barrier_config` | Stop loss, take profit, time limit for overall position |
| `leverage` | Leverage for perpetual markets |
| `keep_position` | Whether to keep net position on termination |

## Grid Level States

Each level tracks its own state independently:

| State | Description |
| - | - |
| `NOT_ACTIVE` | No orders placed at this level |
| `OPEN_ORDER_PLACED` | Entry order active, waiting for fill |
| `OPEN_ORDER_FILLED` | Entry filled, take profit order being placed |
| `CLOSE_ORDER_PLACED` | Take profit order active |
| `COMPLETE` | Both entry and take profit filled |

## Example: Accumulation Grid

Buy ETH between $3000-$3500, taking profit at each level:

```python theme={null}
accumulation = GridExecutorConfig(
    controller_id="eth-accumulator",
    connector_name="binance",
    trading_pair="ETH-USDT",
    side=TradeType.BUY,
    start_price=Decimal("3000"),
    end_price=Decimal("3500"),
    limit_price=Decimal("2800"),      # Stop if price crashes
    total_amount_quote=Decimal("5000"),
    min_spread_between_orders=Decimal("0.02"),  # 2% between levels
    max_open_orders=10,
    triple_barrier_config=TripleBarrierConfig(
        stop_loss=Decimal("0.10"),    # 10% overall stop
        time_limit=604800,             # 1 week
    ),
    keep_position=True,  # Keep accumulated ETH
)
```

## Example: Range Trading Grid

Trade BTC in a range, closing each level for profit:

```python theme={null}
range_trade = GridExecutorConfig(
    controller_id="btc-range",
    connector_name="binance_perpetual",
    trading_pair="BTC-USDT",
    side=TradeType.BUY,
    start_price=Decimal("60000"),
    end_price=Decimal("65000"),
    limit_price=Decimal("58000"),
    total_amount_quote=Decimal("10000"),
    min_spread_between_orders=Decimal("0.01"),
    max_open_orders=5,
    activation_bounds=Decimal("0.03"),  # Orders within 3% of price
    triple_barrier_config=TripleBarrierConfig(
        stop_loss=Decimal("0.05"),
        time_limit=86400,
    ),
    leverage=3,
    keep_position=False,  # Close positions, take P&L
)
```

## Grid vs Position Executor

| Feature | Position Executor | Grid Executor |
| - | - | - |
| Order Levels | Single | Multiple (auto-calculated) |
| Entry | One price | Range of prices |
| Take Profit | Single target | Per-level targets |
| Use Case | Directional bet | Range trading |
| Complexity | Simple | More complex |

Think of Grid Executor as running multiple Position Executors simultaneously across a price range, with coordinated risk management.

## Activation Bounds

The `activation_bounds` parameter keeps orders active only near the current price:

```python theme={null}
activation_bounds=Decimal("0.02")  # 2%
```

* Orders more than 2% from current price are cancelled
* As price moves, new orders are placed within bounds
* Reduces open order count and exchange rate limits

## Position Handover

When `keep_position=True`:

* Net inventory from all levels stays in account
* Added to Position Hold for agent management
* Useful for accumulation strategies

When `keep_position=False`:

* All positions closed on termination
* Realized P\&L from each level reported
* Clean exit with no leftover inventory


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.