OPEN SOURCE · BUILT FOR CODING AGENTS

Build a Hyperliquid Trading Bot With Claude Code or Codex

Four free Python bots you can run on testnet in five minutes, plus the prompts and reference docs your coding agent needs to turn one into your own strategy. Written by a trader who has built trading bots since 2016 and traded on Hyperliquid since February 2024.

4
Starter bots, MIT licensed
5 min
From clone to a testnet run
0
Main-wallet keys saved to disk
$10
Smallest order Hyperliquid accepts
No returns are promised. These bots are teaching code with no proven edge. Real money can be lost quickly. Start on testnet. Nothing here is financial advice.

Run One in Five Minutes

You need Python 3.10 or newer and testnet USDC from Hyperliquid's faucet (it only pays wallets that have made a mainnet deposit). The setup script asks for your main wallet key once, approves an API wallet that can trade but can't withdraw, and saves only that key to a gitignored .env.

Terminal
git clone https://github.com/Hyperliquidguide/hyperliquid-starter-bots
cd hyperliquid-starter-bots
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m scripts.setup_wallet
python -m bots.market_maker --coin BTC --dry-run
Terminal output: setting up an API wallet and running the market maker on testnet

Pick a Starting Bot

Each bot is one readable file with a dry-run mode, a time limit for test runs, and the same risk guard: max order size, max position and a daily loss stop. They all handle HIP-3 markets such as xyz:XYZ100.

Market maker bots/market_maker.py

Quotes a post-only bid and ask around the mid and shifts both quotes against your inventory, so a long position gets sold down first.

Market maker strategy diagram
python -m bots.market_maker --coin BTC --spread-bps 10

Scalper bots/scalper.py

Enters on a fast/slow EMA crossover and puts the stop-loss and take-profit on Hyperliquid as trigger orders, so they fire even if your machine goes down.

Scalper strategy diagram
python -m bots.scalper --coin ETH --interval 1m

Grid bots/grid.py

Places post-only orders at fixed levels. A filled buy is replaced with a sell one level up, and a filled sell with a buy one level down.

Grid strategy diagram
python -m bots.grid --coin BTC --range-pct 2 --levels 8

Funding arb bots/funding_arb.py

When a perp pays shorts enough, it buys the spot token and shorts the perp at the same size, then exits both legs when funding drops.

Funding arb strategy diagram
python -m bots.funding_arb --coin HYPE --min-apr 20

Prompts to Give Your Coding Agent

Open the repo in Claude Code, Codex or Cursor. The repo's AGENTS.md tells the agent the layout and the rules, so new strategies keep the rounding, risk checks and testnet default. Ask for one change at a time and have it write tests.

Start from zero
Clone https://github.com/Hyperliquidguide/hyperliquid-starter-bots and read AGENTS.md. Set it up on Hyperliquid testnet, run the market maker in --dry-run on BTC for 60 seconds with --run-seconds 60, and explain each order it would place.
Add your own strategy
Read AGENTS.md. Add bots/breakout.py: buy when the 5m close breaks the 20-candle high, exit with a 1.5 ATR stop-loss and 3 ATR take-profit as trigger orders. Reuse HLClient and RiskGuard, support --dry-run, and add tests for the signal function.
Improve a bundled bot
In bots/market_maker.py, widen the spread when 5-minute realized volatility rises and narrow it when the market is quiet. Keep compute_quotes a pure function and add tests for it. Then dry-run it on xyz:XYZ100.
Ground the agent in Hyperliquid facts
Before writing any Hyperliquid order code, read https://hyperliquidguide.com/agents/quickstart.md and follow its rounding rules, error table and rate limits.

Plug It Into Your Agent

The repo also ships a read-only MCP server and an Agent Skill. With them installed, your agent can look up live market specs, round an order correctly, rank markets by funding, explain a rejected order and pull any starter bot's source, instead of guessing. The server holds no keys and places no orders. It runs through uv.

Claude Code: skill + MCP plugin
/plugin install hyperliquid-guide --marketplace Hyperliquidguide/hyperliquid-starter-bots
Claude Code: MCP only
claude mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcp
Codex
codex mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcp
Any agent that supports skills
npx skills add Hyperliquidguide/hyperliquid-starter-bots

Cursor and Claude Desktop take the same command in their MCP config file. The README has the JSON.

What Your Agent Should Read

Most broken Hyperliquid bots fail on the same few things: price rounding, the $10 minimum, querying the API wallet address instead of the main account, and rejected orders that still return HTTP 200. These pages give an agent the facts in plain Markdown:

Keep It Safe

  • Testnet first, then mainnet with the smallest size that clears $10.
  • API wallet only. Never give a bot, or a chat window, your main wallet key.
  • Exits on the exchange. Trigger orders fire even when your bot or laptop doesn't.
  • Limits in code. Cap order size, position and daily loss where an agent edit can't silently drop them.
  • Know your liquidation price. Read how liquidation works before you raise leverage.

The Referral, Disclosed

If your account has no referrer, the setup script and the bots apply our code CONCEPT211 and print that they did. Hyperliquid then takes 4% off your fees on your first $25M of volume and pays this site a share of the fees you pay. You pay less, never more. It won't replace an existing referrer, and HL_REFERRAL=off turns it off.

Already trading? In our testnet tests in November 2026, Hyperliquid still accepted a code on accounts that had traded up to about $10,000. If you've only made a few small trades and never used one, it may not be too late.

Related Guides

Frequently Asked Questions

Nobody can promise that, and we do not. The bots are starting points that show how to talk to Hyperliquid safely. They have no proven edge, and running them with real money can lose that money. Test on testnet, keep sizes small, and treat any strategy as unproven until you have your own results.

Yes. Coding agents are good at the plumbing once they have accurate facts: market names, price and size rounding, the $10 minimum, API wallets and error messages. Give the agent the starter repo and our agent quickstart, and ask for one change at a time with tests.

No. The setup script asks for the main key once to approve an API wallet, then saves only the API wallet key. An API wallet can place and cancel orders but cannot withdraw funds.

In our testnet tests in November 2026, Hyperliquid accepted a referral code on accounts that had already traded, up to about $10,000 of lifetime volume. Past that it was refused. The code gives 4% off fees on the first $25M of volume.

No. It is MIT licensed. If your account has no referrer, the setup script and bots apply the Hyperliquid Guide code, which lowers your fees by 4% and pays the site a share from Hyperliquid. Set HL_REFERRAL=off to skip it.

Opening an Account for Your Bot?

Sign up through our link for 4% off fees on your first $25M of volume. It applies to every order your bot places.

Join Hyperliquid