Skip to main content
The Grid Executor splits a price range into evenly spaced levels. Each level places an entry order and, when that fills, a take-profit order on the other side. When both fill, the level resets and trades again. The grid as a whole stops when the price leaves the range, crosses a safety price, or runs out of time.

Overview

Create one from Condor

Agents and the Condor chat use the create_grid_executor tool:
This runs a $500 long grid on SOL-USDT between 140 and 150. Each filled buy places a post-only sell 0.2% higher. The grid stops if SOL falls to 138, or after 12 hours. In an agent session, controller_id must be the session ID (see Session IDs).

Direction rules

side sets the direction. start_price is always the bottom of the range and end_price the top, for both sides. Condor rejects a grid whose prices are in the wrong order before anything is sent: The Hummingbot API accepts limit_price: 0, which turns the safety stop off. Through Condor that is only possible for a long grid, because 0 can’t be above the range.

Parameters

Check your saved grid defaults. Condor merges your saved executor defaults under every create call. The defaults file Condor writes on first use already contains grid values, including keep_position: true, take_profit: 0.0002, max_open_orders: 15, activation_bounds: 0.001, order_frequency: 5, max_orders_per_batch: 1, coerce_tp_to_step: true, min_spread_between_orders: 0.0001, min_order_amount_quote: 6 and LIMIT_MAKER for both open_order_type and take_profit_order_type. Anything you don’t pass in the call comes from there, not from the backend defaults in the table above. Read it with executor_defaults(action="get") and change it with action="save"; reset keeps the values that are already there. See Saved defaults.

How the levels are built

The executor fits as many levels as both limits allow, and the tighter limit wins:
  • Capital: total_amount_quote divided by the per-level minimum. The minimum is the larger of min_order_amount_quote and the exchange’s minimum order value, plus a 5% margin.
  • Spacing: the range (end_price − start_price) / start_price divided by min_spread_between_orders.
Levels are spread evenly from start_price to end_price, with the same capital at each. If only one level fits, it sits at the middle of the range. Entry orders go to the levels closest to the current price first, in batches of max_orders_per_batch every order_frequency seconds, while fewer than max_open_orders are open. When a level’s entry fills, the executor places that level’s take-profit order at level price × (1 + take_profit) for a long grid, or level price × (1 − take_profit) for a short grid. When the take profit fills too, the level is free to trade again. take_profit is per level. It is not a target for the grid as a whole.

How the grid stops

keep_position in the config changes only the limit_price case. Leaving the range on the winning side and reaching the time limit always close the position.

Stop loss and trailing stop

The Hummingbot API also accepts a grid stop_loss and trailing_stop inside triple_barrier_config. Both are measured on the open position’s P&L and always close the position at market (STOP_LOSS or TRAILING_STOP), even when keep_position is true. create_grid_executor has no parameters for them, so a grid created from Condor has neither. Its losses are bounded only by limit_price and, if you set one, time_limit.

Stopping a grid

Stop the executor with stop_executor or POST /executors/{executor_id}/stop. The keep_position you pass with the stop decides what happens; the config value is not used:
  • keep_position=false (the default) cancels open orders and closes the accumulated position at market. Close type EARLY_STOP.
  • keep_position=true cancels open orders and keeps the position. Close type POSITION_HOLD, or EARLY_STOP if nothing was held.
A held position goes to the Position Hold for this executor’s controller_id. See Position Handover.

Grid level states

Each level reports its own state:

Via the API

Create the executor with POST /executors/. triple_barrier_config is required and must contain take_profit. Order types are numbers and side is 1 or 2.
The API doesn’t apply Condor’s saved defaults, so every field you leave out takes the backend default in the parameter table.

Grid vs position executor

Learn more