BlogDeveloper

How to Build a Grid Trading Bot on Hyperliquid

Build a grid trading bot on Hyperliquid: place a ladder of orders in one request, refill filled levels, and know the minimums and request limits. Tested.

HydromancerTeam
How to Build a Grid Trading Bot on Hyperliquid

A grid bot places a ladder of buy orders below the price and sell orders above it. When the price drops and a buy fills, the bot places a sell one step higher; when that sells, it buys again one step lower. In a market that goes sideways, each round trip captures the gap between two levels, minus trading fees.

Why traders run one:

• To profit from sideways markets, when there's no trend to ride.
• To take emotion out of it. Buy low and sell high by rule, not by feel.
• To trade around the clock without watching the screen.
• To build or trim a position gradually across a price range.

Why should you choose to build a grid bot on Hyperliquid?

• Grids earn from movement, and there's plenty. Over two weeks of one-minute prices, BTC's close moved across a level of a 0.5% grid 1,193 times. Every crossing is a chance for an order to fill.
• Orders cost no gas. Placing and canceling hundreds of small orders costs nothing in network fees.
• Resting orders are cheap. The base fee on perps for orders that rest on the book is 0.015%.
• Refills land fast. When a level fills, the bot can rest the next order almost at once: Hyperliquid's docs put the median at 0.2 seconds from sending to on-chain, for a bot hosted close to Hyperliquid's servers.
• The app doesn't refill a grid. Hyperliquid's Scale order places a ladder in one go, but doesn't refill a level once it fills. That loop is what your bot adds.
• Running it for others pays. Attach your builder code to the orders your bot places for its users.

This one is honest about the data side: a grid bot runs entirely on Hyperliquid's free API. It needs prices, its own orders and its own fills, all of which the official API covers. We wrote this guide because the order details are where grid bots break.

The orders below ran on Hyperliquid's testnet on 31 October 2026, priced far from the market and canceled afterwards; the price history came from mainnet. Our trading bot guide covers API wallets and signing, so this one sticks to what's specific to grids. Hydromancer only comes in at one point, choosing the step size from price history, and that part we built on both APIs.

Choose the range and the spacing

A grid needs three numbers: the lowest price, the highest price, and how many levels between them.

• Even spacing (arithmetic) puts the same dollar gap between levels, say every $500 on BTC. Simple, and fine for a narrow range.
• Percentage spacing (geometric) puts the same percentage gap, say every 1%. Better for a wide range, because each round trip earns about the same share wherever the price is.
• Each step must beat fees. A buy and a sell are two trades, so the gap between levels has to be larger than two fees plus any builder fee, or the grid trades for nothing. At the base resting-order fee of 0.015%, a round trip costs 0.03% plus any builder fee, so a 0.5% grid clears it easily.
• Keep leverage low on perps. A grid adds to the position as price falls, so the liquidation price creeps closer with every level filled.

Grids earn in a sideways market and lose in a trend, which is what Step 4 is for.

Step 1: Place the ladder in one request

A grid is many orders at once. Hyperliquid accepts a list of orders in one signed request, so you don't send them one by one. Set HL_TESTNET_AGENT_KEY (your API wallet's key) and HL_MAIN_ADDRESS (the account it trades for):

code
import os, eth_account
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants

URL = constants.TESTNET_API_URL
key = os.environ["HL_TESTNET_AGENT_KEY"]
ex = Exchange(eth_account.Account.from_key(key), URL,
              account_address=os.environ["HL_MAIN_ADDRESS"])
mid = float(ex.info.all_mids()["BTC"])
gtc = {"limit": {"tif": "Gtc"}}
grid = [{"coin": "BTC", "is_buy": True, "sz": 0.0005,
         "limit_px": round(mid * (1 - 0.2 * k)), "order_type": gtc,
         "reduce_only": False} for k in (1, 2, 3)]   # 20%, 40%, 60% below
print(ex.bulk_orders(grid)["response"]["data"]["statuses"])
json
[{'resting': {'oid': 64176647435}}, {'resting': {'oid': 64176647436}}, {'resting': {'oid': 64176647437}}]

All three buys rested, 20%, 40% and 60% below the price. Two details from our first attempt:

• Every order needs at least $10 of value. Our first ladder used 0.0002 BTC per level, about $12 at the top level and less further down. The two lower levels came back with Order must have minimum value of $10, while the top one rested. One bad level doesn't fail the whole request; read every status.
• Prices must follow Hyperliquid's tick rules. Round each level to the market's allowed price steps before sending; see tick size and lot size.

Step 2: Refill levels as they fill

Subscribe to userFills for your account (or orderUpdates). When a buy at level N fills, place a sell at level N+1; when a sell fills, place a buy below. Keep your own map of level → order ID, and rebuild it from openOrders when the bot restarts.

A testnet surprise worth repeating: on our first run, three sell orders placed 35–45% above the price filled within seconds, because a liquidation on the thin testnet book swept up through them. Testnet books can be empty on one side. Check the book before you trust a testnet run, and on mainnet, never assume a far-away order is safe from a sudden move.

Step 3: Watch your request budget

Each order in a bulk request counts as one request against the account's budget: our ladder of 6 orders raised nRequestsUsed by 6. Hyperliquid gives each address a buffer of 10,000 requests, then about 1 more per $1 traded. A grid that cancels and re-places its whole ladder every few seconds burns through that fast. Refill only the levels that filled, and check userRateLimit while the bot runs.

Step 4: Have a stop

Grids lose in trends. If the price falls through the bottom of your ladder, the bot holds everything it bought on the way down. Set a price below which the bot cancels all orders and stops, and a maximum position size.

Hyperliquid has a "dead man's switch" (scheduleCancel) that cancels all orders at a set time if your bot stops checking in. On testnet, Hyperliquid refused it for an account that hadn't traded $1M yet (Cannot set scheduled cancel time until enough volume traded. Required: $1000000.). Its docs don't list this requirement, so check it on mainnet, and run your own watchdog either way.

Where Hydromancer fits

Mostly it doesn't, and that's fine. A grid bot reads its own orders and the price; Hyperliquid's free API covers both. The one place it helps is before you start: choosing the step size from history. A simple test is to count how often the price crossed a grid level in the past two weeks, since every crossing is a chance to fill. We built that check on both APIs:

Hyperliquid API

One candleSnapshot request:

code
import time, requests

now, day = int(time.time() * 1000), 86400000
req = {"coin": "BTC", "interval": "1m",
       "startTime": now - 14 * day, "endTime": now}
c = requests.post("https://api.hyperliquid.xyz/info",
                  json={"type": "candleSnapshot", "req": req}).json()
step, crossings, last = 0.005, 0, None       # grid levels 0.5% apart
for k in c:
    level = int(float(k["c"]) / (float(c[0]["c"]) * step))
    crossings, last = crossings + (last not in (None, level)), level
print(round((now - c[0]["t"]) / day, 1), "days;", crossings, "level crossings")
code
3.6 days; 391 level crossings

Hydromancer API

The same count, paging back the full two weeks:

code
import os, time, requests

H = {"Authorization": "Bearer " + os.environ["HYDROMANCER_API_KEY"]}
now, day = int(time.time() * 1000), 86400000
c, start = [], now - 14 * day
while start < now:
    req = {"coin": "BTC", "interval": "1m", "startTime": start, "endTime": now}
    page = requests.post("https://api.hydromancer.xyz/info", headers=H,
                         json={"type": "candleSnapshot", "req": req}).json()
    c, start = c + page, (page[-1]["t"] + 60000 if len(page) == 5000 else now)
step, crossings, last = 0.005, 0, None       # grid levels 0.5% apart
for k in c:
    level = int(float(k["c"]) / (float(c[0]["c"]) * step))
    crossings, last = crossings + (last not in (None, level)), level
print(round((now - c[0]["t"]) / day, 1), "days;", crossings, "level crossings")
code
14.0 days; 1193 level crossings

Side by side

Hyperliquid API Hydromancer API
History covered3.6 of 14 days14 of 14 days
Worked3 of 3 runs3 of 3 runs
Time to finish (median)0.5 s2.1 s
Requests15
Rate-limit cost105 weight (limit: 1,200 a minute per IP)100 points (limit: 20,000 a minute on the Growth plan)
Data received over REST (uncompressed)0.7 MB3.4 MB

Both run, but they count different weeks. Hyperliquid's 1-minute candles reach back only three and a half days (why), so a quiet or wild few days decides your step size. Two weeks gives a fairer picture. If you run grids for many users, the Telegram bot guide measures how to follow all their fills at once.

If you host grids for other people, your builder code is charged on both the buy and the sell of every round trip, so set it well below the grid step.

FAQ

Can I run a grid bot on Hyperliquid?

Yes. Place the ladder with one bulk order request, refill levels from your fills, and keep each order above $10 of value.

Does Hyperliquid have a built-in grid bot?

Not as a bot. Hyperliquid's Scale order places a ladder of limit orders in one go, but it doesn't refill a level once it fills; that loop is your bot.

What's the minimum order size on Hyperliquid?

$10 of value per order. Smaller orders are rejected with "Order must have minimum value of $10."

• How to build a Hyperliquid trading bot
• Hyperliquid tick size and lot size
• Hyperliquid testnet guide
• Hyperliquid rate limits explained

Sources

- Hyperliquid docs: Exchange endpoint, Rate limits, Builder codes

All posts
Continue

Read next