# Using Grid Bot

### Overview

The Grid Bot is a systematic trading strategy that places a series of buy and sell orders at predetermined price intervals — forming a "grid" across a price range. As the market oscillates, the bot captures profit from each completed buy-sell cycle within the grid. Grid bots excel in ranging, sideways markets where price repeatedly bounces between support and resistance levels.

**Key advantages of grid trading:**

* Profits from natural market volatility without requiring price direction prediction
* Automatically buys lower and sells higher within the defined range
* Runs autonomously once configured, reducing the need for constant monitoring

***

### Grid Configuration

The Grid Configuration panel is where you define every parameter for your grid bot. The panel is divided into core settings (account, pair, margin, leverage) and strategy settings (spread, soft reset, stop loss).

***

#### Enter Bot Name

A unique identifier for this grid bot instance.

| Detail          | Value            |
| --------------- | ---------------- |
| **Field Type**  | Text input       |
| **Required**    | Yes              |
| **Placeholder** | `Enter Bot Name` |

**What it does:** Names your bot so you can distinguish it from other running bots in the Positions table and in your history. Choose something descriptive — for example, `BTC-Grid-Conservative` or `ETH-5x-Tight` — so you can quickly identify the strategy at a glance.

***

#### Select Account

The trading account whose funds and margin will be used to execute grid orders.

| Detail         | Value             |
| -------------- | ----------------- |
| **Field Type** | Dropdown selector |
| **Example**    | `adev30`          |

**What it does:** Each account has its own balance, margin allocation, and exchange connection. The account you select determines which pool of funds the bot draws from. Your available balance is displayed alongside the Margin field so you can see exactly how much capital is accessible.

> 💡 **Tip:** If you plan to run multiple bots simultaneously, ensure the combined margin across all bots does not exceed your account's available balance.

***

#### Select Trading Pair

The perpetual contract or spot pair on which the grid bot will operate.

| Detail         | Value                                |
| -------------- | ------------------------------------ |
| **Field Type** | Dropdown selector                    |
| **Example**    | `BTC:PERP-USDC`                      |
| **Info Icon**  | ℹ️ Hover for additional pair details |

**What it does:** Defines the market where the grid bot places orders. The pair you choose affects available leverage limits, fee structures, and the chart displayed on the right side of the screen. Perpetual contracts (indicated by `:PERP`) have no expiration date and use funding rate mechanisms.

**Market data displayed in the header bar:**

| Metric            | Description                                                   | Example        |
| ----------------- | ------------------------------------------------------------- | -------------- |
| **24H Change**    | Price change over the last 24 hours (absolute and percentage) | -2,485 / -2.47 |
| **24H Volume**    | Total trading volume in the last 24 hours                     | $134.11k       |
| **Open Interest** | Total value of outstanding positions                          | $288.28k       |

***

#### Margin

The amount of USDC collateral you allocate to this grid bot.

| Detail                | Value                                            |
| --------------------- | ------------------------------------------------ |
| **Field Type**        | Numeric input with stepper arrows                |
| **Minimum**           | $50                                              |
| **Maximum**           | $100,000                                         |
| **Example**           | $100                                             |
| **Available Balance** | Shown to the right of the label (e.g., `$17.84`) |

**What it does:** Margin is the capital that backs your grid positions. It determines how large your grid orders can be and how much loss the bot can absorb before hitting risk limits. Your available balance is displayed beside the field so you always know how much you can allocate.

**How it impacts your bot:**

* Combined with leverage, margin determines your maximum notional exposure. For example, $100 margin at 10x leverage gives you $1,000 in total position capacity spread across the grid.
* Higher margin allows for more grid levels or larger orders at each level.
* The margin you allocate is locked while the bot is active and cannot be used by other bots.

> ⚠️ **Important:** You cannot allocate more than your Available Balance. The field enforces a hard minimum of $50 and maximum of $100,000.

***

#### Leverage

The multiplier applied to your margin to increase the notional value of your grid positions.

| Detail             | Value                                   |
| ------------------ | --------------------------------------- |
| **Field Type**     | Slider + preset buttons                 |
| **Range**          | 1x to 40x                               |
| **Preset Buttons** | 1x, 5x, 10x, 20x, 40x                   |
| **Slider**         | Fine-tune to any value within the range |
| **Example**        | `10x`                                   |

**What it does:** Leverage amplifies your buying power. At 10x leverage, your $100 margin controls $1,000 worth of grid positions.

**How it impacts your bot:**

| Leverage | Margin | Total Position Capacity | Liquidation Sensitivity |
| -------- | ------ | ----------------------- | ----------------------- |
| 1x       | $100   | $100                    | Very low                |
| 5x       | $100   | $500                    | Low                     |
| 10x      | $100   | $1,000                  | Moderate                |
| 20x      | $100   | $2,000                  | High                    |
| 40x      | $100   | $4,000                  | Very high               |

> ⚠️ **Warning:** Higher leverage increases both potential returns and liquidation risk. At 40x leverage, even a small adverse price move can result in significant losses or liquidation. Choose leverage that matches your risk tolerance.

***

### Strategy Settings

These settings control the core trading logic of your grid bot — how it prices orders, when it rebalances, and when it stops.

***

#### Spread (bps)

The distance in basis points between your bid and ask orders relative to the reference price.

| Detail              | Value                                   |
| ------------------- | --------------------------------------- |
| **Field Type**      | Slider + preset buttons                 |
| **Range**           | -50 to +50 bps                          |
| **Preset Buttons**  | -10, -5, 0, +5, +10                     |
| **Slider**          | Fine-tune to any value within the range |
| **Default/Example** | +5 bps                                  |
| **Unit**            | Basis points (1 bps = 0.01%)            |

**What it does:** Spread controls the gap between the price at which the bot is willing to buy and sell. A positive spread means you're quoting wider than the market mid-price, while a negative spread means you're quoting tighter (more aggressively).

**How it impacts your bot:**

| Spread Value       | Behavior                                      | Fill Rate | Profit Per Trade                   |
| ------------------ | --------------------------------------------- | --------- | ---------------------------------- |
| **-10 to -1 bps**  | Aggressive — quotes inside the market spread  | Very high | Lower (may be negative after fees) |
| **0 bps**          | Neutral — quotes at the exact mid-price       | High      | Minimal                            |
| **+1 to +5 bps**   | Conservative — quotes slightly wider than mid | Moderate  | Moderate                           |
| **+6 to +10 bps**  | Wide — quotes meaningfully wider              | Lower     | Higher per fill                    |
| **+11 to +50 bps** | Very wide — large distance from mid           | Low       | Highest per fill                   |

**Practical guidance:**

* In **tight, liquid markets** (e.g., BTC:PERP-USDC), a spread of +2 to +5 bps balances fill rate with profitability.
* In **volatile or illiquid markets**, a wider spread of +5 to +10 bps protects against adverse selection.
* **Negative spreads** can be used intentionally to prioritize fills and accumulate or exit positions quickly, but will likely result in a net cost per trade.

> 💡 **Tip:** Start with the default +5 bps and adjust based on observed fill rates in your History. If you're getting filled too rarely, tighten the spread. If you're taking losses on most fills, widen it.

***

#### Soft Reset

A risk management mechanism that triggers a partial position rebalance when unrealized losses reach the configured threshold.

| Detail              | Value                          |
| ------------------- | ------------------------------ |
| **Field Type**      | Preset buttons + toggle switch |
| **Options**         | 0.5%, 1%, 2%, 3%, 5%           |
| **Default/Example** | 0.5%                           |
| **Toggle**          | Enabled (green) / Disabled     |

**What it does:** When your grid bot's unrealized loss reaches the Soft Reset percentage of your margin, the bot will partially rebalance its positions — closing some exposure and re-centering the grid around the current price. Unlike Stop Loss, this does **not** shut down the bot. It allows the bot to recover and continue trading.

**How it impacts your bot:**

| Soft Reset Value | Trigger Point ($100 margin) | Behavior                                   |
| ---------------- | --------------------------- | ------------------------------------------ |
| 0.5%             | $0.50 unrealized loss       | Very frequent resets, tighter risk control |
| 1%               | $1.00 unrealized loss       | Frequent resets                            |
| 2%               | $2.00 unrealized loss       | Moderate resets                            |
| 3%               | $3.00 unrealized loss       | Infrequent resets                          |
| 5%               | $5.00 unrealized loss       | Rare resets, allows wider drawdowns        |

**Practical guidance:**

* A **lower Soft Reset** (0.5%–1%) keeps the grid tightly centered around current price, minimizing inventory risk but potentially locking in small losses more often.
* A **higher Soft Reset** (3%–5%) gives the grid more room to breathe, which can be beneficial in volatile markets where price tends to revert.
* You can **disable** Soft Reset entirely using the toggle switch if you prefer the bot to hold positions without periodic rebalancing.

***

#### Stop Loss

The maximum loss threshold, as a percentage of margin, at which the bot will close all positions and shut down entirely.

| Detail              | Value                          |
| ------------------- | ------------------------------ |
| **Field Type**      | Preset buttons + toggle switch |
| **Options**         | 5%, 10%, 25%, 50%, 100%        |
| **Default/Example** | 10%                            |
| **Toggle**          | Enabled (green) / Disabled     |

**What it does:** Stop Loss is your hard safety net. When total losses (realized + unrealized) reach the configured percentage of your margin, the bot immediately closes all open positions and stops trading. This prevents catastrophic losses during sharp, unexpected market moves.

**How it impacts your bot:**

| Stop Loss Value | Trigger Point ($100 margin) | Risk Profile                             |
| --------------- | --------------------------- | ---------------------------------------- |
| 5%              | $5.00 total loss            | Very conservative — bot stops quickly    |
| 10%             | $10.00 total loss           | Conservative — standard protection       |
| 25%             | $25.00 total loss           | Moderate — allows for larger drawdowns   |
| 50%             | $50.00 total loss           | Aggressive — significant loss tolerance  |
| 100%            | $100.00 total loss          | Maximum risk — entire margin can be lost |

**Practical guidance:**

* For most users, **10%–25%** provides a reasonable balance between giving the strategy room to work and protecting capital.
* A **5% stop loss** is appropriate when testing new configurations or trading in highly uncertain conditions.
* Setting stop loss to **100%** effectively means you're willing to lose your entire margin. Use this only with small, expendable allocations.
* You can **disable** Stop Loss using the toggle switch, but this is **strongly discouraged** as it removes your last line of defense against runaway losses.

> ⚠️ **Warning:** Disabling Stop Loss means the bot will continue running even if losses exceed your margin. Always keep Stop Loss enabled unless you have a specific, well-understood reason to disable it.

***

### Actions

At the bottom of the configuration panel, two buttons control your bot's lifecycle.

#### Save Bot

Saves the current configuration without starting the bot.

**Use this when:**

* You want to prepare a configuration for later activation
* You're building multiple bot templates to compare strategies
* You want to preserve settings before making experimental changes

#### Create Bot

Creates and immediately activates the bot with the current configuration.

**Use this when:**

* You've reviewed all settings and are ready to go live
* Your margin and strategy parameters are finalized

> 📝 **Note:** Once created, the bot begins placing grid orders immediately. Ensure all parameters are correct before clicking Create Bot.

***

### Positions

The Positions panel displays all grid bot activity in two views.

#### Active Tab

Shows all currently running grid bots with real-time performance data.

#### Stopped Tab

Shows historical bots that have been manually stopped or hit their Stop Loss.

#### Filters

Narrow down the positions list using the following dropdown filters:

| Filter            | Description                                   |
| ----------------- | --------------------------------------------- |
| **All Markets**   | Filter by market type (perpetual, spot, etc.) |
| **All Exchanges** | Filter by connected exchange account          |
| **All Pairs**     | Filter by specific trading pair               |

#### Position Table Columns

| Column      | Description                                                          |
| ----------- | -------------------------------------------------------------------- |
| **MODE**    | Bot operating mode                                                   |
| **PAIR**    | The trading pair (e.g., BTC:PERP-USDC)                               |
| **Account** | Which account is running the bot (sortable ↑↓)                       |
| **Fees**    | Total fees paid or rebated (sortable ↑↓)                             |
| **RPNL**    | Realized Profit and Loss — closed trade profits/losses (sortable ↑↓) |
| **SPREAD**  | Average spread captured across fills                                 |
| **FILLED**  | Total order volume that has been filled                              |
| **STATUS**  | Current bot status (Active, Stopped, etc.)                           |

***

### Example Trades

#### Example 1: Conservative Range-Bound BTC Grid

**Scenario:** BTC has been trading sideways between $95,000 and $100,000 for the past week. You want to capture small profits from each price oscillation with minimal risk.

**Configuration**

| Parameter        | Value            | Rationale                                   |
| ---------------- | ---------------- | ------------------------------------------- |
| **Bot Name**     | `BTC-Range-Safe` | Descriptive for tracking                    |
| **Account**      | `adev30`         | Primary trading account                     |
| **Trading Pair** | `BTC:PERP-USDC`  | High liquidity perpetual pair               |
| **Margin**       | $200             | Small allocation to limit risk              |
| **Leverage**     | 5x               | Moderate leverage for $1,000 total capacity |
| **Spread**       | +5 bps           | Standard spread for balanced fill rate      |
| **Soft Reset**   | 1%               | Rebalances at $2.00 unrealized loss         |
| **Stop Loss**    | 10%              | Hard stop at $20.00 total loss              |

**How This Bot Operates**

1. The bot allocates $200 in margin and uses 5x leverage, giving it $1,000 in total position capacity.
2. It places a grid of buy orders below the current BTC price and sell orders above it, each spaced according to the +5 bps spread.
3. When BTC dips, buy orders fill. When BTC rises, sell orders fill. Each completed buy-sell cycle earns a small profit (the spread minus fees).
4. If the market moves sharply against the grid and unrealized losses hit $2.00 (1% of margin), Soft Reset triggers — the bot rebalances and re-centers the grid around the new price.
5. If total losses reach $20.00 (10% of margin), Stop Loss activates and the bot shuts down, closing all positions.

**Expected Behavior**

| Metric                      | Estimate                           |
| --------------------------- | ---------------------------------- |
| **Total Position Capacity** | $1,000                             |
| **Soft Reset Trigger**      | $2.00 unrealized loss              |
| **Stop Loss Trigger**       | $20.00 total loss                  |
| **Ideal Market Condition**  | Sideways, range-bound price action |
| **Risk Level**              | Low                                |

***

#### Example 2: Aggressive High-Leverage ETH Grid

**Scenario:** ETH is experiencing elevated volatility after a major protocol upgrade announcement. You want to capitalize on rapid price swings using a larger allocation and tighter spread to maximize fill rate.

**Configuration**

| Parameter        | Value                | Rationale                                |
| ---------------- | -------------------- | ---------------------------------------- |
| **Bot Name**     | `ETH-Volatile-Aggro` | Identifies the aggressive strategy       |
| **Account**      | `adev30`             | Primary trading account                  |
| **Trading Pair** | `ETH:PERP-USDC`      | Volatile perpetual pair                  |
| **Margin**       | $2,000               | Larger allocation for serious exposure   |
| **Leverage**     | 20x                  | High leverage for $40,000 total capacity |
| **Spread**       | 0 bps                | Zero spread for maximum fill rate        |
| **Soft Reset**   | 3%                   | Rebalances at $60.00 unrealized loss     |
| **Stop Loss**    | 25%                  | Hard stop at $500.00 total loss          |

**How This Bot Operates**

1. The bot commits $2,000 in margin at 20x leverage, creating $40,000 in total position capacity — substantial firepower for capturing volatile swings.
2. With 0 bps spread, the bot quotes at the exact mid-price, ensuring nearly every trading opportunity is captured.
3. In a volatile market, orders fill rapidly on both sides. Each micro-swing generates completed grid cycles.
4. Soft Reset at 3% gives the grid breathing room — it won't rebalance until unrealized losses reach $60.00, allowing the bot to ride out moderate swings.
5. Stop Loss at 25% provides a safety net at $500.00 total loss.

**Expected Behavior**

| Metric                      | Estimate                                |
| --------------------------- | --------------------------------------- |
| **Total Position Capacity** | $40,000                                 |
| **Soft Reset Trigger**      | $60.00 unrealized loss                  |
| **Stop Loss Trigger**       | $500.00 total loss                      |
| **Ideal Market Condition**  | High volatility with frequent reversals |
| **Risk Level**              | High                                    |

**Risk Considerations**

> ⚠️ **Warning:** This is an aggressive configuration. Key risks include:
>
> * **20x leverage** means a 5% adverse move consumes 100% of your margin
> * **0 bps spread** means every fill carries execution risk with no built-in cushion
> * **High fill rate** in a trending (non-mean-reverting) market can lead to rapid inventory accumulation on the losing side
> * Only suitable for experienced traders comfortable with significant drawdowns

***

### Best Practices

1. **Name your bots descriptively** — include the pair, leverage, and strategy style so you can identify them instantly in the Positions table.
2. **Start with low leverage** — use 1x–5x until you understand how the grid behaves with your chosen pair and spread settings.
3. **Match spread to market conditions** — tighter spreads for liquid, stable markets; wider spreads for volatile or illiquid ones.
4. **Always keep Stop Loss enabled** — this is your last line of defense against unexpected market events.
5. **Use Soft Reset for longevity** — a well-tuned Soft Reset keeps your bot running through moderate drawdowns instead of accumulating one-sided inventory.
6. **Monitor the Positions table** — review RPNL, Fees, and Filled columns regularly to assess whether your strategy is profitable.
7. **Don't over-allocate margin** — leave a buffer in your account balance for margin calls or new opportunities.

***

### Glossary

| Term                          | Definition                                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Basis Point (bps)**         | One hundredth of a percentage point (0.01%). A +5 bps spread equals 0.05%.                                                                  |
| **Grid**                      | A set of buy and sell orders placed at regular price intervals above and below the current market price.                                    |
| **Leverage**                  | A multiplier that increases your effective position size beyond your deposited margin.                                                      |
| **Margin**                    | The collateral you deposit to open and maintain leveraged positions.                                                                        |
| **Open Interest**             | The total value of all outstanding derivative contracts that have not been settled.                                                         |
| **Perpetual Contract (PERP)** | A derivatives contract with no expiration date, tracking the spot price through a funding rate mechanism.                                   |
| **RPNL**                      | Realized Profit and Loss — the cumulative profit or loss from all closed positions.                                                         |
| **Soft Reset**                | An automatic partial rebalance triggered when unrealized losses reach a configured threshold. The bot continues running after a soft reset. |
| **Spread**                    | The difference in basis points between the bot's bid and ask prices relative to the market mid-price.                                       |
| **Stop Loss**                 | A hard risk limit that shuts down the bot and closes all positions when total losses reach a configured percentage of margin.               |

***

*For additional support, visit our discord to contact our support team.*


---

# Agent Instructions: 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://docs.hyperflash.xyz/using-bots/using-grid-bot.md?ask=<question>
```

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.