> For the complete documentation index, see [llms.txt](https://qi-blockchain.gitbook.io/qbots/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qi-blockchain.gitbook.io/qbots/futures-grid-bot-logic/futures-grid-trading-bot-how-it-works-complete-guide.md). # 📘 Futures Grid Trading Bot — How It Works (Complete Guide) This document explains how the **Futures Grid Trading Bot** works, from configuration to trading, risk management, and stopping. The Futures Grid Bot trades **perpetual futures contracts** using an automated **grid trading strategy**. It supports: • Automated buy/sell grid execution\ • Futures leverage\ • Smart indicator protection\ • Dual stop-loss protection\ • Continuous automated trading *** ## 1 What Is a Futures Grid Trading Bot? A **Futures Grid Trading Bot** is an automated strategy that: • Places multiple buy and sell orders across a price range\ • Profits from market volatility\ • Works continuously without manual intervention Unlike Spot Grid bots, the Futures Grid Bot: • Uses **futures contracts** instead of spot assets\ • Supports **leverage trading**\ • Can manage larger positions using smaller capital The bot **does not predict market direction**. Instead, it profits from **price movement inside a defined range**. *** ## 2 Important Requirement — Hedge Mode {% hint style="danger" %} ❗ **Enable Hedge Mode Before Starting** The Futures Grid Bot requires **Hedge Mode (Dual Position Mode)** to be enabled on your exchange futures account. If Hedge Mode is not enabled: • Orders may fail\ • Positions may not open correctly\ • The bot may not function properly Please enable **Hedge Mode in your exchange futures settings before creating or starting this bot.** {% endhint %} *** ## 3 Bot Creation (Configuration Parameters) When creating a Futures Grid Bot, you configure the following parameters. *** ### Exchange Defines where the bot will execute trades. Example: ``` Bybit Mexc ``` **NOTE -** The exchange must already have **API keys connected to the platform**. *** ### Trading Pair The futures trading pair used by the bot. Example: ``` BTC/USDT ETH/USDT XRP/USDT ``` Internally the system converts the pair to futures format: ``` BTC/USDT:USDT ``` This ensures compatibility with **perpetual futures markets**. *** ## 4 Grid Configuration These parameters define the **grid trading structure**. *** ### Grid Lower The **lowest price level** where the bot will place buy orders. Example: ``` Grid Lower = 20000 ``` Validation rule: ``` Grid Lower must be below Grid Upper ``` *** ### Grid Upper The **highest price level** of the grid. Example: ``` Grid Upper = 24000 ``` Validation rule: ``` Grid Upper must be greater than Grid Lower ``` *** ### Grid Count Defines how many grid levels exist between the lower and upper price. Example: ``` Grid Count = 6 ``` Limits: ``` Minimum = 2 Maximum = 100 ``` Example grid result: ``` 20000 20666 21333 22000 22666 23333 24000 ``` Each grid level represents a **potential trading opportunity**. *** ## 5 Capital Configuration These parameters define how much capital the bot uses. *** ### Investment Total capital allocated for the bot. Example: ``` Investment = 100 USDT ``` Minimum investment: ``` 10 USDT ``` Important: Currently this value is **informational only**. Actual order execution depends on: • Order size\ • Available exchange balance\ • Number of open orders *** ### Order Size Defines the **size of each individual order** placed by the bot. Example: ``` Order Size = 6 ``` Meaning each grid order uses **6 units of position size**. Smaller order sizes: • More frequent trades\ • Smaller risk per trade Larger order sizes: • Higher exposure\ • Larger profits or losses *** ### Leverage Leverage multiplier used for futures trading. Example: ``` Leverage = 3x ``` Allowed range: ``` Minimum = 1x Maximum = 5x ``` Example: ``` Investment = 100 USDT Leverage = 5x Effective position size = 500 USDT ``` Higher leverage increases: • Profit potential\ • Liquidation risk *** ## 6 Stop Loss Protection The Futures Grid Bot supports **dual stop-loss protection**. *** ### Lower Stop Loss If price drops to this level: • All open orders are canceled\ • All positions are closed at market price\ • Bot stops trading Validation rule: ``` Lower Stop Loss < Grid Lower ``` Example: ``` Grid Lower = 20000 Lower Stop Loss = 19000 ``` *** ### Upper Stop Loss If price rises to this level: • All open orders are canceled\ • Positions are closed\ • Bot stops trading Validation rule: ``` Upper Stop Loss > Grid Upper ``` Example: ``` Grid Upper = 24000 Upper Stop Loss = 25000 ``` This protects the bot from **extreme market movements**. *** ## 7 Smart Indicator Protection The bot includes optional **Smart Indicator Protection**. When enabled, the bot checks market conditions before starting. Indicators may include: • EMA 200 trend analysis\ • RSI momentum conditions\ • BTC market direction *** ### If Indicators Are Disabled The bot starts immediately. • Grid orders are placed\ • Trading begins instantly *** ### If Indicators Are Enabled The bot checks indicators once before starting. If conditions are not favorable: ``` Bot status = WAITING ``` During WAITING: • No orders are placed\ • No capital is used\ • Indicators are rechecked every **5 minutes** When conditions become favorable: ``` Bot automatically starts trading ``` *** ## 8 Cooldown Protection System (Volatility Safety) The Futures Grid Bot includes an advanced **Cooldown Protection System** designed to protect users from trading during **high volatility or market breakouts**. This system continuously monitors market conditions while the bot is running. *** ### How the Cooldown System Works The bot evaluates **three market indicators** during trading. These indicators help detect situations such as: • Strong trending markets\ • Sudden volatility spikes\ • Breakout conditions outside normal grid behavior If **2 out of the 3 indicators fail**, the bot assumes that the market is no longer suitable for grid trading. *** ### When Cooldown Is Triggered If the bot detects that **2 out of 3 indicators are false** during trading: The bot immediately performs the following safety actions: 1. Cancels **all open grid orders** 2. Closes **all open positions at market price** 3. Stops the bot completely This prevents the grid strategy from continuing in a **dangerous market environment**. *** ### 24 Hour Cooldown Period After the bot stops, it enters a **24 hour cooldown period**. During cooldown: • The bot does not place any orders\ • The bot does not hold any open positions\ • The system waits before attempting to trade again This waiting period allows the market to stabilize. *** ### Automatic Restart After Cooldown After **24 hours**, the bot automatically wakes up and rechecks the indicators. The system evaluates the same **3 indicators again**. #### If Indicators Still Fail If **2 out of 3 indicators remain false**: • The bot does **not start trading**\ • A **new 24 hour cooldown period begins** This cycle continues until market conditions become favorable. *** ### When Market Conditions Improve Once the indicators show **at least 2 out of 3 conditions passing**: The bot automatically restarts. At this stage the bot will: 1. Recalculate grid spacing using the user's original **Grid Lower and Grid Upper** values 2. Generate a new grid structure 3. Place new orders 4. Resume automated trading The user **does not need to manually restart the bot**. *** ### Why Cooldown Exists Grid trading strategies perform best in **sideways or ranging markets**. When the market enters strong trends or extreme volatility, grid strategies can become risky. The cooldown system protects users by: • Preventing grid trading during breakouts\ • Automatically pausing during unstable markets\ • Restarting the strategy when conditions stabilize This makes the bot **safer and more adaptive to changing market conditions**. *** ### Lifecycle with indicators enable Bot Running\ ↓\ Indicators evaluated continuously\ ↓\ If 2/3 indicators fail\ ↓\ Cancel all orders\ Close positions\ Stop bot\ ↓\ Cooldown 24h\ ↓\ Recheck indicators\ ↓\ If still bad → another 24h cooldown\ ↓\ If good → restart bot + recalc grids *** ### Indicators * Trend Filter (EMA 200) * Volatility Filter (ATR / Bollinger) * Market Momentum (RSI) ## 9 Grid Order Execution Once the bot starts: 1️⃣ The price range is divided into grids\ 2️⃣ Orders are placed across the grid\ 3️⃣ Trades occur as price moves between levels Example: ``` Grid Lower = 20000 Grid Upper = 24000 Grid Count = 6 ``` Possible grid levels: ``` 20000 20666 21333 22000 22666 23333 24000 ``` The bot continuously executes trades as the market moves within this range. *** ## 10 Continuous Trading Cycle Once running, the bot automatically: • Monitors market price\ • Tracks filled orders\ • Places new orders according to the grid\ • Records profit and trade history This process runs **24/7 automatically**. *** ## 11 Bot Statuses The bot operates using several system states. | Status | Meaning | | ------- | -------------------------------- | | WAITING | Waiting for indicator conditions | | RUNNING | Actively trading | | PAUSED | Temporarily paused | | STOPPED | Fully stopped | | ERROR | Stopped due to safety issue | | DELETED | Soft-deleted from system | *** ## 12 Stopping the Bot Users can stop the bot in two ways. *** ### Stop Bot • Cancels open orders\ • Stops trading\ • Bot can be resumed later *** ### Delete Bot • Cancels all open orders\ • Closes all positions\ • Calculates final PnL\ • Bot is permanently removed *** ## 13 Profit Tracking Every completed grid trade is recorded. The system tracks: • Realized profit and loss (PnL)\ • Trade history\ • Grid performance Trade history remains available **even after the bot is deleted**. *** ## 14 Example Bot Creation Request When the bot is created, the system sends the following payload: ``` { exchange: "bybit", symbol: "BTC/USDT:USDT", gridLower: 20000, gridUpper: 24000, gridCount: 6, investment: 100, orderSize: 6, leverage: 3, lowerStopLossPrice: 19000, upperStopLossPrice: 25000, enableIndicators: true } ``` *** ## 15 Validation Rules | Parameter | Rule | | --------------- | ------------------------------- | | Grid Upper | must be greater than Grid Lower | | Grid Count | 2 to 100 | | Investment | minimum 10 USDT | | Leverage | 1x to 5x | | Lower Stop Loss | must be below Grid Lower | | Upper Stop Loss | must be above Grid Upper | | Hedge Mode | must be enabled | *** ## 16 Default Values The bot initializes with these default values: ``` Investment = 10 Grid Count = 6 Order Size = 6 Leverage = 1 Indicators = Disabled ``` These values are designed as **safe starting parameters**. *** ## 17 Key Things to Understand Important principles of Futures Grid trading: • The bot does not predict market direction\ • It profits from volatility within the grid range\ • Hedge Mode must be enabled\ • Indicators are checked \ • Stop loss protects against extreme market moves\ • Leverage increases both risk and reward The system is **fully automated, state-driven, and designed for controlled futures trading**. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://qi-blockchain.gitbook.io/qbots/futures-grid-bot-logic/futures-grid-trading-bot-how-it-works-complete-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.