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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
/plugin install hyperliquid-guide --marketplace Hyperliquidguide/hyperliquid-starter-bots
claude mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcp
codex mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcp
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
- Grid bot guideSpacing, fees and ranges for grid trading on Hyperliquid
- Funding rate arbitrageSpot long + perp short, with break-even math
- Hyperliquid MCP serversConnect Claude, Codex or Cursor to Hyperliquid safely
- Hyperliquid API guideEndpoints, agent-wallet signing and WebSocket feeds
- Trading bot setupStrategy types and the risk controls a bot needs
- Market making on HyperliquidMaker fees, rebates and the limits quoting bots hit
- Hyperliquid for pro tradersFee tiers, rebates and rate limits at volume
- Growth-mode marketsHIP-3 markets with 90% lower fees
- Live funding ratesFind the markets a funding bot would look at
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