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

# Grid Bot

> 了解 Owly Grid Bot 的工作方式，以及如何更稳妥地完成参数配置

Owly Grid Bot 用来在你设定的价格区间内自动执行网格交易。它适合希望用规则化方式持续挂单、补单和调整订单，而不是手动维护每一个价格档位的用户。

## 当前支持范围

<Check>当前已经上线的是永续合约 `perp` 网格</Check>
<Check>支持 `neutral`、`long`、`short` 三种运行模式</Check>
<Check>支持 `arithmetic` 和 `geometric` 两种价格算法</Check>
<Check>支持触发价、区间追踪、止盈和止损</Check>
<Check>支持 `cross` 和 `isolated` 杠杆模式</Check>
<Check>当前面向用户展示的默认账户模式是 `unifiedAccount`</Check>

<Note>
  `spot` 网格已经在规划中，但目前还没有正式开放执行。
</Note>

## Grid Bot 是怎么工作的

从用户视角看，Grid Bot 的运行逻辑可以概括为 5 步：

1. 读取当前市场价格。
2. 如果设置了触发价，就先等待价格满足触发条件。
3. 在设定区间内生成目标网格挂单。
4. 对比当前挂单和目标挂单，只调整真正需要变化的部分。
5. 如果命中止盈或止损，就进入风险退出流程。

实际使用时，下面这几条规则最重要：

* Bot 主要使用 `mark price` 作为判断依据。
* 如果 `trigger_price <= 0`，启动后会直接进入激活状态。
* 如果 `trailing_up_limit` 或 `trailing_down_limit` 为 `0`，表示对应追踪能力关闭。
* 命中止盈或止损后，Bot 会退出正常补网格流程，转入风险退出流程。

## 三种运行模式

### Neutral

适合区间震荡思路。

* 价格下方挂买单。
* 价格上方挂卖单。
* 不会自动建立方向底仓。
* `bootstrap_position` 在 neutral 模式下会自动关闭。

### Long

适合偏多思路。

* 在价格下方用买单补仓。
* 在价格上方使用 `reduce-only` 卖单做止盈。
* 可以开启 `bootstrap_position`，在 Bot 激活时先建立一个方向底仓。

### Short

适合偏空思路。

* 在价格上方用卖单补仓。
* 在价格下方使用 `reduce-only` 买单做止盈。
* 可以开启 `bootstrap_position`，在 Bot 激活时先建立一个方向底仓。

## 核心参数说明

| 参数                            | 控制内容                       | 用户建议                              |
| ----------------------------- | -------------------------- | --------------------------------- |
| `coin`                        | 交易标的，例如 `BTC`              | 先确认自己当前做的是 perp，还是在为未来的 spot 场景准备 |
| `grid_type`                   | 网格市场类型                     | 当前请使用 `perp`；`spot` 仍在规划中         |
| `perp_mode`                   | `neutral`、`long`、`short`   | 让模式和你的行情判断保持一致                    |
| `account_mode`                | 账户模式                       | 当前用户侧默认按 `unifiedAccount` 理解和配置   |
| `margin_mode`                 | `cross` 或 `isolated`       | 不确定时优先从 `cross` 开始                |
| `leverage`                    | 杠杆倍数                       | 建议先从低杠杆开始                         |
| `price_lower` / `price_upper` | 网格运行区间                     | 必须大于 `0`，且上限必须高于下限                |
| `grid_number`                 | 区间内价格档位数量                  | 档位越多，网格越密                         |
| `order_size`                  | 每档订单大小                     | 需要满足交易所最小下单要求                     |
| `price_algorithm`             | `arithmetic` 或 `geometric` | 不确定时优先选择 `arithmetic`             |
| `sync_interval`               | 同步周期，单位秒                   | 当前最小值是 `10`，默认值是 `15`             |
| `rebalance_tolerance_bps`     | 调整订单的容忍带宽                  | 适当放宽可以减少频繁撤挂                      |
| `trigger_price`               | 触发价                        | `0` 表示启动后立即运行                     |
| `trigger_direction`           | `above` 或 `below`          | 控制价格满足什么条件后才开始挂网格                 |
| `trailing_up_limit`           | 区间向上追踪的上限                  | `0` 表示关闭                          |
| `trailing_down_limit`         | 区间向下追踪的下限                  | `0` 表示关闭                          |
| `bootstrap_position`          | 是否先建立方向底仓                  | 只在 `long` 和 `short` 模式下有意义        |
| `bootstrap_size`              | 初始底仓大小                     | 如果不单独设置，会回退到 `order_size`         |
| `take_profit_price`           | 全局止盈价                      | 命中后会进入风险退出                        |
| `stop_loss_price`             | 全局止损价                      | 命中后会进入风险退出                        |

## 如何理解触发、追踪和风控

### 触发价

如果你不希望 Bot 一启动就开始挂单，可以设置触发价。

* `trigger_direction = "above"`：价格高于等于触发价后启动
* `trigger_direction = "below"`：价格低于等于触发价后启动

常见用法包括：

* 等价格突破后再启动
* 等价格回到目标区间后再启动

### 区间追踪

当市场价格离开原始区间时，你可以让整个网格区间跟着移动。

* `trailing_up_limit` 控制区间最多向上移动到哪里
* `trailing_down_limit` 控制区间最多向下移动到哪里

这通常适合：

* 趋势行情里，避免价格离开原区间后长时间不再挂单
* 想让区间策略具备有限跟随机制的场景

### 止盈止损

止盈止损是全局策略级风控，不是单一挂单的局部设置。

一旦命中，Grid Bot 会进入风险退出流程：

* 尝试平掉当前持仓
* 撤掉相关网格挂单
* 停止正常的网格维护

## Directional 模式下的 Bootstrap 规则

`bootstrap_position` 只适用于 `long` 和 `short` 模式，但有几个关键限制：

* `neutral` 模式不会执行 bootstrap。
* 账户当前要么是空仓，要么已经持有同方向仓位。
* 如果已经有同方向仓位，但仓位仍小于 `bootstrap_size`，Bot 不会半自动补齐后继续执行，而是会直接报错退出。
* 如果开启了 `bootstrap_position` 但没有设置 `bootstrap_size`，系统会默认使用 `order_size`。

因此，directional 网格更适合以下两种起点：

* 从空仓开始运行
* 你已经手动准备好了与策略方向一致的底仓

## 使用前一定要知道的限制

### 最小下单金额

网格挂单需要满足交易所最小下单要求。按当前实现，每一档订单通常至少需要接近 `10.5 USDC` 的名义价值。

如果 `order_size` 太小，或者你设置的区间导致单档名义价值过低，Bot 可能会直接拒绝启动。

### 实际下单仍受交易所规则约束

最终下单价格和数量会按交易所可接受的规则处理，实际执行结果以交易所当时接受的参数为准。

### Spot Grid 还没有正式上线

`spot` 网格已经在规划中，范围包含 HIP3 场景。如果未来某个 HIP3 DEX 使用的 quote coin 不是 `USDC`，你需要提前在账户里准备好对应的 quote 资产。

### 账户模式需要匹配

当前官网面向用户的配置说明以 `unifiedAccount` 为主，这也与 Hyperliquid 的默认账户模型保持一致。

## 建议的起步方式

如果你是第一次使用 Grid Bot，建议先保持配置简单：

* 使用 `neutral + perp + cross + 低杠杆`
* 先关闭 `bootstrap_position`
* 先关闭 trailing
* 先不要设置过于激进的止盈止损

这样更容易先确认网格密度、单档金额和区间是否合理，再逐步增加复杂度。

## 一个适合入门的配置示例

| 配置项    | 示例值              | 含义                     |
| ------ | ---------------- | ---------------------- |
| 标的     | `BTC`            | 做 `BTC` 永续网格           |
| 网格类型   | `perp`           | 当前正式支持的是永续网格           |
| 运行模式   | `neutral`        | 区间下方买、区间上方卖            |
| 账户模式   | `unifiedAccount` | 与 Hyperliquid 默认账户模式一致 |
| 杠杆模式   | `cross`          | 使用全仓模式                 |
| 杠杆倍数   | `1`              | 以低杠杆启动                 |
| 区间下限   | `95,000`         | 网格下边界                  |
| 区间上限   | `105,000`        | 网格上边界                  |
| 网格档位   | `10`             | 在区间内划分 10 个价格档位        |
| 单档数量   | `0.001`          | 每一档使用相同的下单数量           |
| 价格算法   | `arithmetic`     | 使用等差网格                 |
| 同步周期   | `15 秒`           | 每 15 秒检查并同步一次网格        |
| 容忍带宽   | `8 bps`          | 小幅偏差内不频繁重建订单           |
| 触发价    | `0`              | 启动后立即运行                |
| 触发方向   | `above`          | 当触发价大于 `0` 时按上破逻辑激活    |
| 上移追踪上限 | `0`              | 关闭                     |
| 下移追踪下限 | `0`              | 关闭                     |
| 全局止盈价  | `0`              | 关闭                     |
| 全局止损价  | `0`              | 关闭                     |

这是一套偏基础、适合首次理解产品的配置：

* 做 `BTC` 永续 neutral 网格
* 账户模式按 `unifiedAccount` 理解
* 运行区间为 `95,000` 到 `105,000`
* 不开启 trailing
* 不开启全局止盈止损

## 给用户的关键提醒

<Warning>
  `long` 和 `short` 模式不是自动纠偏工具。请先确认你的初始仓位状态和底仓计划本身就是合理的。
</Warning>

<Tip>
  如果你不希望 Bot 频繁改挂单，可以适当增大 `rebalance_tolerance_bps`，避免把区间设得过窄，也不要把网格档位设得过密。
</Tip>