# Hyperliquid Grid Bot: How Grid Trading Works and a Free Open-Source Bot

> How a grid bot works on Hyperliquid, the fee math on post-only orders, how to pick a range from live candle data, and a free open-source Python grid bot to run on testnet first.

*Source: https://hyperliquidguide.com/guides/trading/hyperliquid-grid-bot*

A grid bot places a ladder of buy and sell limit orders around the current price and replaces each one as it fills. It earns the spacing between rungs every time price swings across one. On [Hyperliquid](https://app.hyperliquid.xyz/join/Concept211) the orders can be post-only, so the fee on each fill is the low maker rate. This guide covers how that works, the fee math, how to choose a range from real candle data, and a free open-source grid bot you can run on testnet.

> **Key takeaway:** A grid earns the spacing between rungs on every round trip, minus two maker fees. It does well when price chops inside a range and badly when price trends out of it, because you are left holding inventory. Nothing here is a promise of returns. Start on testnet.

## What grid trading is

You pick a lower price, an upper price and a number of levels. The bot spaces the levels evenly, puts buys on the levels below the current price and sells on the levels above it. When a buy fills, it places a sell one level higher. When a sell fills, it places a buy one level lower. Each completed pair, one buy and one sell a rung apart, is a round trip.

![Diagram of a grid: buy orders resting below the price, sell orders above it, each fill re-arming one level over](/images/build/diagram-grid.svg)

The bot doesn't predict direction. It sells into rises, buys into dips, and collects the gap each time.

## When a grid works and when it fails

**It works in a range.** If price oscillates between the bounds, every swing across a rung completes a round trip. More chop means more round trips.

**It fails in a trend.** If price falls through the bottom of the grid, every rung filled on the way down was a buy. You end up long, with the whole ladder filled and nothing left to buy, while the position loses value. A rally through the top does the mirror image on the short side. The grid is not hedged, and the bot is not a stop-loss.

On a perp this matters more than on spot. The inventory you are stuck with is a leveraged position, so a long trend against it can move toward liquidation. Read [how liquidation works on Hyperliquid](/guides/trading/liquidation-explained) and the [leverage guide](/guides/trading/leverage-guide) before you size a grid, and keep the total the grid can accumulate small enough that you would hold it through a bad week.

> **Warning:** A grid has a capped upside (the spacing per round trip) and an open-ended downside (the inventory it accumulates when price leaves the range). Size it for the downside.

## Spacing, levels, order size and fees

Three settings interact. The range and the number of levels set the spacing. The order size sets how much each rung is worth. The fee sets the floor under the spacing.

With evenly spaced levels, spacing is the range divided by the number of gaps, which is levels minus one. A round trip earns the spacing and pays a fee on each of its two fills. So:

**Profit per round trip = spacing minus two maker fees**, both as a percentage of the order's notional value.

Here is a real setup. An 8-level grid across a 4% total range (2% either side of the mid) has 7 gaps, so spacing is 4% / 7 = 0.571%. The fees depend on the market.

| Market | Maker fee | Two fees | Net per round trip on a $100 rung |
|--------|-----------|----------|-----------------------------------|
| Native perp, base tier | 0.015% | 0.030% | 0.571% minus 0.030% = 0.541%, about $0.54 |
| HIP-3 growth-mode market | about 0.003% | 0.006% | 0.571% minus 0.006% = 0.565%, about $0.57 |

Those are the base-tier rates from the [Hyperliquid fee docs](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees), before any [fee tier](/guides/fees/fee-tiers) or staking discount, and not every HIP-3 market runs growth mode, so read the fee line on the market you trade. Our [fees guide](/guides/fees/fees-explained) lists the full schedule, and the [growth mode guide](/guides/trading/hyperliquid-growth-mode-markets) explains why those markets are cheaper and what the trade-off is.

Three things follow from the formula.

- **Spacing has to clear the fees.** If spacing falls below two maker fees (0.030% at the base tier), each round trip loses money even when everything fills perfectly. Packing more levels into a narrow range shrinks spacing, so there is a limit to how dense a grid is worth running.
- **More levels is not more profit.** Doubling the levels over the same range halves the spacing.
- **Order size scales both sides.** A bigger rung earns more per round trip and builds inventory faster when price trends. The fee percentage does not change with size at a given tier.

Hyperliquid has no gas fee, so the fee on each fill is the only per-order cost. Orders have a $10 minimum notional.

## Why post-only matters

A grid placed with ordinary limit orders can cross the book if price has moved between the moment the bot decides and the moment the order arrives, and that fill pays the taker fee (0.045% at the base tier on native perps). A post-only order, which Hyperliquid calls Alo (add liquidity only), is rejected instead of crossing. It can only rest, so any fill it gets is a maker fill. Our [order types guide](/guides/trading/order-types-guide) covers Alo next to the other time-in-force options. The trade-off is that a rejected order leaves a rung unplaced.

## Pick a range from live data

The bounds should come from how the market has actually moved, not from a round number. We pulled hourly candles from the Hyperliquid API (`candleSnapshot`, `1h` interval) covering the seven days to November 21, 2026, 17:35 UTC, and measured them.

| Market | 7-day high | 7-day low | High-to-low range | Average hourly range |
|--------|-----------|-----------|-------------------|----------------------|
| BTC | $66,231 | $55,170 | about 20% | 1.08% of price |
| ETH | $1,866.2 | $1,536.7 | about 21% | 1.30% of price |

The average hourly range is the mean of each candle's high minus low, divided by its close. Those figures are one week's snapshot and they will not hold next week.

What the numbers say about a grid:

- **Spacing versus noise.** BTC's average hourly candle spanned about 1.08%. A grid with 0.57% spacing, like the example above, would typically see price cross more than one rung in an hour. That activity is what a grid feeds on, as long as price stays inside the bounds.
- **A narrow range did not survive the week.** The 2% either side range from the example covers 4% in total, against a 20% high-to-low range. BTC's first hourly candle in the window opened at $65,328 and the last closed at $60,086, a drop of about 8%. A grid centered on the start of that week would have been run over: every buy filled on the way down, and the bot would have ended the week long and below its bottom rung.
- **A wide range dilutes the spacing.** Covering the full 20% with 8 levels gives spacing of about 2.9%, which fills rarely. To keep spacing near 0.5% across 20% you would need around 40 levels, each rung holding a smaller order, and you pay the fee on every fill.

A narrow grid earns often until it breaks. A wide grid is sturdier but fills rarely. Pull the candles yourself before each run, and decide in advance what you will do when price leaves the range. Here is the request:

```bash
curl -s https://api.hyperliquid.xyz/info -H "Content-Type: application/json" \
 -d '{"type":"candleSnapshot","req":{"coin":"BTC","interval":"1h","startTime":1763000000000,"endTime":1763700000000}}'
```

The `startTime` and `endTime` are Unix milliseconds. Each candle returns `o`, `h`, `l`, `c`, `v` and a timestamp. The [API guide](/guides/trading/hyperliquid-api-guide) covers the rest of the endpoints.

**Open a Hyperliquid Account** — Accounts opened through our link get 4% off fees on your first $25M of volume. The bots work on testnet before you fund anything. [Join Hyperliquid](https://app.hyperliquid.xyz/join/Concept211)

## Our free open-source grid bot

We publish a grid bot in our [starter bots repository](https://github.com/Hyperliquidguide/hyperliquid-starter-bots), in `bots/grid.py`. It is a starting point to learn from and modify, not a strategy with an edge. The [build page](/build) lists the other starter bots and a quickstart your coding agent can read. We read the file to write this section, and this is what it does.

1. **Builds the ladder.** `--levels` evenly spaced prices from `--lower` to `--upper`, both included. If you leave the bounds out, it uses the mid price plus and minus `--range-pct` percent.
2. **Starts clean.** It cancels any leftover orders on that market, then places post-only (Alo) buys on every rung below the mid and post-only sells on every rung above it. A rung sitting exactly on the mid is skipped.
3. **Re-arms on fills.** A filled buy at rung `i` becomes a sell at rung `i+1`. A filled sell at rung `i` becomes a buy at rung `i-1`. It confirms a fill against the account's fill history, and an order that vanished without a fill is placed again after a short grace period. At the top or bottom edge of the grid, there is nothing to re-arm.
4. **Skips occupied rungs.** If a rung already has a tracked order, it will not place a second one there.
5. **Caps the position.** Every order passes a risk check. Once the position reaches `--max-position-usd`, the bot stops adding to it, buys when long and sells when short, and only orders that reduce the position go out.
6. **Stops on a loss limit.** If equity drops by `--max-loss-usd`, the loop exits.
7. **Cleans up on exit.** On Ctrl+C, `--run-seconds` expiry or a stop, it cancels all open orders on the market. The position is left as it is, so you still own whatever the grid accumulated.

The main options:

| Option | What it does | Default |
|--------|--------------|---------|
| `--coin` | Market, e.g. `BTC`, `ETH`, `xyz:XYZ100` | BTC |
| `--lower`, `--upper` | Grid bounds (pass both, or neither) | mid -/+ range-pct |
| `--range-pct` | Half-width of the default range, in percent | 1.0 |
| `--levels` | Number of grid prices, bounds included | 6 |
| `--order-usd` | Notional per order (minimum $10) | 12 |
| `--max-position-usd` | Stop adding to a position beyond this | 60 |
| `--max-loss-usd` | Stop when equity drops this much | 15 |
| `--dry-run` | Log orders instead of sending them | off |
| `--run-seconds` | Stop after this many seconds (0 = until Ctrl+C) | 0 |

Spacing is arithmetic (equal dollar steps), not percentage steps, so rungs near the bottom are slightly wider in percentage terms than rungs near the top. The bot polls every few seconds, and it does not move the grid or close the position if price breaks out.

### Run it on testnet first

You need Python 3.10 or newer and the repo cloned. The setup script creates an API wallet, and the dry run shows the orders without sending them.

```bash
python -m scripts.setup_wallet
python -m bots.grid --coin BTC --range-pct 2 --levels 8 --dry-run
```

The bots default to testnet, so a run with the `--dry-run` flag removed uses testnet funds. Go to mainnet only after you have watched the bot through volatile hours with small sizes. The repo's README covers the mainnet switch.

We tested it live on Hyperliquid testnet. A 6-level grid of 1% either side on BTC placed 6 resting orders. A much tighter grid, 0.02% either side, filled sells and re-armed buys, which confirmed the re-arm loop. That tight grid was a mechanics test, not a trading setup: at that spacing, fees would eat the rungs. Testnet fills say nothing about mainnet profits, because the order book, spreads and fill behavior differ.

HIP-3 markets work by adding the dex prefix:

```bash
python -m bots.grid --coin xyz:XYZ100 --range-pct 1 --levels 6 --dry-run
```

Check that market's fee line first, and its hours. Some HIP-3 markets track assets that trade on fixed schedules, and a grid left running over a closed session can sit at stale prices.

### Referral disclosure

The starter kit applies our referral code to accounts that have none. Under Hyperliquid's referral program, that gives your account 4% off trading fees on your first $25M of volume, and Hyperliquid pays Hyperliquid Guide a share of the fees you pay. You pay less, not more. It never replaces an existing referrer, and it is skipped on testnet. Hyperliquid stops accepting a referrer once an account has traded roughly $10,000, based on our testing. To opt out, set `HL_REFERRAL=off` in `.env`.

## What this is not

This is not financial advice, and the bot has no proven edge. A grid turns price oscillation into spacing income, and the price of that is trend risk. For quoting both sides continuously, see the [market making guide](/guides/trading/hyperliquid-market-making-guide). If you are new to bots, read the [trading bot setup guide](/guides/trading/trading-bot-setup-guide) and the [strategies guide](/guides/trading/hyperliquid-trading-strategies) first, and keep the starting amount small enough that a full loss would not matter.

**Test the Grid on Hyperliquid** — Sign up through our link for 4% off fees on your first $25M of volume. Run the bot on testnet first, then decide. [Open a Hyperliquid Account](https://app.hyperliquid.xyz/join/Concept211)
