hyperliquid-guide
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
No returns are promised. These bots are teaching code with no proven edge. Real money can be lost, fast. Start on testnet and read DISCLAIMER.md.
Why this repo
Short enough to read. Each bot is one file of a couple hundred lines, built on the official hyperliquid-python-sdk.
The fiddly parts are already solved. Tick and lot rounding, the $10 minimum, rejected orders that still return HTTP 200, HIP-3 market names, API wallets and unified accounts.
Risk limits come built in. Each bot has a max order size, a max position and a daily loss kill switch, plus dry-run mode and testnet by default.
Coding agents can extend it. AGENTS.md gives Claude Code, Codex or Cursor the layout and the rules, so it can add a strategy without breaking the safety rails.
Related MCP server: market-depth-lab-mcp
The bots
Market maker · bots/market_maker.py
Quotes a post-only bid and ask around the mid and leans both quotes against your inventory, so a long position gets sold down first.
python -m bots.market_maker --coin BTC --spread-bps 10 --order-usd 15Scalper · bots/scalper.py
Enters on a fast/slow EMA crossover and places the stop-loss and take-profit as trigger orders on Hyperliquid itself, so they still fire if your machine goes down.
python -m bots.scalper --coin ETH --interval 1m --stop-atr 1.5 --tp-atr 2Grid · bots/grid.py
Places post-only orders at fixed price levels. Each filled buy is replaced by a sell one level up, and each filled sell by a buy one level down.
python -m bots.grid --coin BTC --range-pct 2 --levels 8 --order-usd 12Funding arb · bots/funding_arb.py
When a perp's funding is positive enough, it buys the spot token and shorts the same size on the perp, then exits both legs when funding falls.
python -m bots.funding_arb --coin HYPE --min-apr 20 --exit-apr 5Every bot takes --help, --dry-run and --run-seconds. HIP-3 markets use their dex prefix, for example --coin xyz:XYZ100.
Quick start (testnet)
You need Python 3.10+ and a wallet that has made a deposit on Hyperliquid mainnet (the testnet faucet requires one).
git clone https://github.com/Hyperliquidguide/hyperliquid-starter-bots
cd hyperliquid-starter-bots
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# 1. Get testnet USDC: https://app.hyperliquid-testnet.xyz/drip
# 2. Create an API wallet for the bots (asks for your main key, never saves it)
python -m scripts.setup_wallet
# 3. See what the bot sees
python -m scripts.check_account --coin BTC
# 4. Watch a bot think without sending orders, then run it for real on testnet
python -m bots.market_maker --coin BTC --dry-run
python -m bots.market_maker --coin BTCHow it fits together
flowchart LR
A["scripts/setup_wallet.py<br/>API wallet + .env"] --> B["hlbots/config.py<br/>settings"]
B --> C["hlbots/client.py<br/>HLClient"]
C --> D["hlbots/specs.py<br/>tick + lot rounding"]
C --> E["Hyperliquid API<br/>testnet or mainnet"]
F["bots/*.py<br/>your strategy"] --> G["hlbots/risk.py<br/>RiskGuard"]
G --> CBuild your own strategy with a coding agent
Open the repo in Claude Code, Codex or Cursor and ask for what you want. The agent reads AGENTS.md (Claude Code loads it through CLAUDE.md) and follows the same rules as the bundled bots. Prompts that work:
"Add a bot in
bots/breakout.pythat buys a 20-candle high on the 5m chart, with an ATR stop and tests.""Make the market maker widen its spread when 5-minute volatility rises, and test the spread function."
"Give the scalper a funding filter: only go long when funding is negative."
"Run the grid bot in dry-run on
xyz:XYZ100and explain every order it would place."
For Hyperliquid details (fees, rate limits, error messages, HIP-3 markets) point the agent at the agent quickstart or llms.txt.
Use it from your coding agent
This repo also ships a read-only MCP server and an Agent Skill, so your agent can look up live Hyperliquid specs instead of guessing. The server holds no keys and places no orders. Its tools: market_specs, round_order, top_funding, explain_error, account_status, quickstart, starter_bot (details). It's on PyPI and runs through uv, or pip install hyperliquid-starter-bots and then run hl-guide-mcp.
Claude Code (plugin: skill + MCP in one step)
/plugin install hyperliquid-guide --marketplace Hyperliquidguide/hyperliquid-starter-botsClaude Code (MCP only)
claude mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcpCodex
codex mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcpCursor, Claude Desktop and other MCP clients (add to mcp.json / claude_desktop_config.json)
{
"mcpServers": {
"hyperliquid-guide": {
"command": "uvx",
"args": ["--from", "hyperliquid-starter-bots", "hl-guide-mcp"]
}
}
}Agent Skill only (Claude Code, Codex, Cursor and other skills-compatible agents)
npx skills add Hyperliquidguide/hyperliquid-starter-botsGoing to mainnet
Run python -m scripts.setup_wallet --mainnet, deposit USDC, and keep the default small sizes until you've watched the bot through a few volatile hours. The bots read HL_NETWORK from .env, so nothing touches mainnet until you set it.
Safety
Use an API wallet. It can trade but can't withdraw.
setup_walletcreates one, and the bots warn you if they're given your main key.Keys stay local.
.envis gitignored. Never paste a key into a chat, an issue or a commit.The risk limits are a floor. Tighten them before you size up.
Exits that live on the exchange keep working. The scalper's stop-loss still fires if your machine dies. The market maker and grid bots cancel their orders when they exit.
Referral disclosure
If your account has no referrer yet and has traded less than about $10K, setup_wallet and the bots apply the Hyperliquid Guide referral code CONCEPT211. Under Hyperliquid's referral program you get 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's skipped on testnet.
To opt out, set HL_REFERRAL=off in .env. To use a different code, set HL_REFERRAL_CODE.
Tests
python -m pytestThey run offline with no keys. CI runs them on Python 3.10 and 3.12.
More from Hyperliquid Guide
Maintained by Hyperliquid Guide, an independent site. Not affiliated with, endorsed by, or reviewed by Hyperliquid or the Hyper Foundation. MIT licensed. Graphics are regenerated with tools/make-assets.mjs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hyperliquid referral code, perp markets, funding rates, HIP-3 dexes and site search. Read-only.
Read-only Hyperliquid analytics: orderflow, liquidation levels, whale positioning, funding.
Read-only crypto market data: Hyperliquid liquidation heatmaps, liquidations, whales, funding, flow.
Hyperliquid MCP — read-only market data from Hyperliquid's public info API.
Related MCP Servers
- AlicenseCqualityDmaintenanceA read-only Model Context Protocol server for Hyperliquid that exposes over 30 tools to query public market data and user state via the Hyperliquid Info API, without requiring a private key.41MIT
- AlicenseAqualityCmaintenanceRead-only Hyperliquid and cross-exchange market research for AI agents, providing structured tools for live market data without requiring authentication.981 npmMIT
- AlicenseAqualityDmaintenanceProvides live market and account data from Hyperliquid, including perp and spot prices, funding rates, open interest, order books, and wallet positions, without requiring an API key.7MIT
- AlicenseAqualityBmaintenanceProvides AI agents read-only, keyless access to Hyperliquid market data, funding rates, account risk, and HyperEVM token transfers through MCP tools, with caching and rate limiting to protect upstream APIs.1285 PyPI1MIT