Skip to content
Back to search

hyperliquid-guide

Hyperliquid trading-bot tooling from Hyperliquid Guide: a bot-builder skill and an MCP server that is read-only by default.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hyperliquidguide--hyperliquid-starter-bots/badge.svg)](/listings/hyperliquidguide--hyperliquid-starter-bots)

HTML

<a href="/listings/hyperliquidguide--hyperliquid-starter-bots"><img src="/api/listings/hyperliquidguide--hyperliquid-starter-bots/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 BTC

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "hyperliquid-guide",
  3. "owner": {
  4. "name": "Hyperliquid Guide",
  5. "url": "https://hyperliquidguide.com"
  6. },
  7. "plugins": [
  8. {
  9. "name": "hyperliquid-guide",
  10. "source": "./",
  11. "description": "Hyperliquid bot-builder skill and MCP server (read-only by default) from Hyperliquid Guide (independent, not affiliated with Hyperliquid)."
  12. }
  13. ],
  14. "description": "Hyperliquid trading-bot tooling from Hyperliquid Guide: a bot-builder skill and an MCP server that is read-only by default."
  15. }
README.md · README · 223 lines
  1. <p align="center">
  2. <img src="assets/banner.png" alt="Hyperliquid Starter Bots: readable Python trading bots you can extend with Claude Code, Codex or Cursor" width="100%">
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/Hyperliquidguide/hyperliquid-starter-bots/actions/workflows/tests.yml"><img src="https://github.com/Hyperliquidguide/hyperliquid-starter-bots/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
  6. <a href="https://pypi.org/project/hyperliquid-starter-bots/"><img src="https://img.shields.io/pypi/v/hyperliquid-starter-bots?color=97FCE4" alt="PyPI"></a>
  7. <a href="https://glama.ai/mcp/servers/Hyperliquidguide/hyperliquid-starter-bots"><img src="https://glama.ai/mcp/servers/Hyperliquidguide/hyperliquid-starter-bots/badges/score.svg" alt="Glama MCP server score" height="20"></a>
  8. <img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+">
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-97FCE4" alt="MIT license"></a>
  10. <img src="https://img.shields.io/badge/default-testnet-F5C76B" alt="Testnet by default">
  11. <img src="https://img.shields.io/badge/Claude%20Code-ready-D97757" alt="Claude Code ready">
  12. <img src="https://img.shields.io/badge/Codex-ready-10A37F" alt="Codex ready">
  13. <a href="https://hyperliquidguide.com/build"><img src="https://img.shields.io/badge/docs-hyperliquidguide.com-0a9b7a" alt="Docs"></a>
  14. </p>
  15. <p align="center">
  16. <b>Four small, readable trading bots and a TWAP executor for <a href="https://app.hyperliquid.xyz/join/CONCEPT211">Hyperliquid</a>.</b><br>
  17. Run one on testnet in five minutes, then have your coding agent turn it into your own strategy.
  18. </p>
  19. <!-- mcp-name: io.github.Hyperliquidguide/hyperliquid-guide -->
  20. > [!WARNING]
  21. > **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](DISCLAIMER.md).
  22. <p align="center">
  23. <img src="assets/terminal-demo.svg" alt="Terminal: setting up an API wallet and running the market maker on testnet" width="760">
  24. </p>
  25. ## Why this repo
  26. - **Short enough to read.** Each bot is one file of a couple hundred lines, built on the official [hyperliquid-python-sdk](https://github.com/hyperliquid-dex/hyperliquid-python-sdk).
  27. - **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.
  28. - **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.
  29. - **Coding agents can extend it.** [AGENTS.md](AGENTS.md) gives Claude Code, Codex or Cursor the layout and the rules, so it can add a strategy without breaking the safety rails.
  30. ## The bots
  31. ### Market maker · `bots/market_maker.py`
  32. 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.
  33. ```bash
  34. python -m bots.market_maker --coin BTC --spread-bps 10 --order-usd 15
  35. ```
  36. <img src="assets/diagram-market-maker.svg" alt="Market maker quotes shifting with inventory" width="100%">
  37. ### Scalper · `bots/scalper.py`
  38. 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.
  39. ```bash
  40. python -m bots.scalper --coin ETH --interval 1m --stop-atr 1.5 --tp-atr 2
  41. ```
  42. <img src="assets/diagram-scalper.svg" alt="Scalper EMA crossover with stop-loss and take-profit" width="100%">
  43. ### Grid · `bots/grid.py`
  44. 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.
  45. ```bash
  46. python -m bots.grid --coin BTC --range-pct 2 --levels 8 --order-usd 12
  47. ```
  48. <img src="assets/diagram-grid.svg" alt="Grid bot price levels" width="100%">
  49. ### Funding arb · `bots/funding_arb.py`
  50. 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. It sends the perp short only after the spot buy fills, and skips entry when spot and perp prices differ by more than `--max-basis-pct` (0.5% by default).
  51. ```bash
  52. python -m bots.funding_arb --coin HYPE --min-apr 20 --exit-apr 5
  53. ```
  54. <img src="assets/diagram-funding-arb.svg" alt="Funding arbitrage: spot long plus perp short" width="100%">
  55. ### TWAP · `bots/twap.py`
  56. Execution tooling rather than a strategy: it works an order you already chose in equal slices over time. Each slice rests post-only at the touch first (maker fee), and whatever is left crosses with an IOC capped by `--max-slippage-bps` and `--limit-px`. `--reduce-only` unwinds a position. Hyperliquid also has a [native TWAP order](https://hyperliquidguide.com/guides/trading/twap-orders); use this one when you want your own rules.
  57. ```bash
  58. python -m bots.twap --coin ETH --side buy --total-usd 300 --minutes 30 --limit-px 3200
  59. ```
  60. <img src="assets/diagram-twap.svg" alt="TWAP slices: post-only first, then a capped IOC catch-up" width="100%">
  61. Every bot takes `--help` and `--dry-run`, and the strategy bots take `--run-seconds` (TWAP uses `--minutes`). HIP-3 markets use their dex prefix, for example `--coin xyz:XYZ100`.
  62. ### TypeScript · `ts/`
  63. A TypeScript market maker on [`@nktkas/hyperliquid`](https://github.com/nktkas/hyperliquid) with the same defaults: testnet, post-only quotes, inventory skew, risk caps, dry-run and the disclosed referral step. It reads the same `.env`. See [ts/README.md](ts/README.md).
  64. ```bash
  65. cd ts && npm install && npm run mm -- --coin BTC --dry-run
  66. ```
  67. ## Quick start (testnet)
  68. You need Python 3.10+ and a wallet that has made a deposit on Hyperliquid mainnet (the testnet faucet requires one).
  69. ```bash
  70. git clone https://github.com/Hyperliquidguide/hyperliquid-starter-bots
  71. cd hyperliquid-starter-bots
  72. python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
  73. pip install -r requirements.txt
  74. # 1. Get testnet USDC: https://app.hyperliquid-testnet.xyz/drip
  75. # 2. Create an API wallet for the bots (asks for your main key, never saves it)
  76. python -m scripts.setup_wallet
  77. # 3. See what the bot sees
  78. python -m scripts.check_account --coin BTC
  79. # 4. Watch a bot think without sending orders, then run it for real on testnet
  80. python -m bots.market_maker --coin BTC --dry-run
  81. python -m bots.market_maker --coin BTC
  82. ```
  83. ## How it fits together
  84. ```mermaid
  85. flowchart LR
  86. A["scripts/setup_wallet.py<br/>API wallet + .env"] --> B["hlbots/config.py<br/>settings"]
  87. B --> C["hlbots/client.py<br/>HLClient"]
  88. C --> D["hlbots/specs.py<br/>tick + lot rounding"]
  89. C --> E["Hyperliquid API<br/>testnet or mainnet"]
  90. F["bots/*.py<br/>your strategy"] --> G["hlbots/risk.py<br/>RiskGuard"]
  91. G --> C
  92. ```
  93. ## Build your own strategy with a coding agent
  94. Open the repo in Claude Code, Codex or Cursor and ask for what you want. The agent reads [AGENTS.md](AGENTS.md) (Claude Code loads it through `CLAUDE.md`) and follows the same rules as the bundled bots. Prompts that work:
  95. - *"Add a bot in `bots/breakout.py` that buys a 20-candle high on the 5m chart, with an ATR stop and tests."*
  96. - *"Make the market maker widen its spread when 5-minute volatility rises, and test the spread function."*
  97. - *"Give the scalper a funding filter: only go long when funding is negative."*
  98. - *"Run the grid bot in dry-run on `xyz:XYZ100` and explain every order it would place."*
  99. For Hyperliquid details (fees, rate limits, error messages, HIP-3 markets) point the agent at the [agent quickstart](https://hyperliquidguide.com/agents/quickstart.md) or [llms.txt](https://hyperliquidguide.com/llms.txt).
  100. ## Use it from your coding agent
  101. This repo also ships an **MCP server** (read-only by default, with [opt-in testnet order tools](hlmcp/README.md#opt-in-order-tools)) 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](hlmcp/README.md)). It's on [PyPI](https://pypi.org/project/hyperliquid-starter-bots/) and runs through [uv](https://docs.astral.sh/uv/), or `pip install hyperliquid-starter-bots` and then run `hl-guide-mcp`.
  102. **Claude Code** (plugin: skill + MCP in one step)
  103. ```text
  104. /plugin install hyperliquid-guide --marketplace Hyperliquidguide/hyperliquid-starter-bots
  105. ```
  106. **Claude Code** (MCP only)
  107. ```bash
  108. claude mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcp
  109. ```
  110. **Codex**
  111. ```bash
  112. codex mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcp
  113. ```
  114. **Cursor, Claude Desktop and other MCP clients** (add to `mcp.json` / `claude_desktop_config.json`)
  115. ```json
  116. {
  117. "mcpServers": {
  118. "hyperliquid-guide": {
  119. "command": "uvx",
  120. "args": ["--from", "hyperliquid-starter-bots", "hl-guide-mcp"]
  121. }
  122. }
  123. }
  124. ```
  125. **Agent Skill only** (Claude Code, Codex, Cursor and [other skills-compatible agents](https://github.com/vercel-labs/skills))
  126. ```bash
  127. npx skills add Hyperliquidguide/hyperliquid-starter-bots
  128. ```
  129. ## Going to mainnet
  130. 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.
  131. ## Safety
  132. - **Use an API wallet.** It can trade but can't withdraw. `setup_wallet` creates one, and the bots warn you if they're given your main key.
  133. - **Keys stay local.** `.env` is gitignored. Never paste a key into a chat, an issue or a commit.
  134. - **The risk limits are a floor.** Tighten them before you size up.
  135. - **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.
  136. ## Referral disclosure
  137. 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.
  138. To opt out, set `HL_REFERRAL=off` in `.env`. To use a different code, set `HL_REFERRAL_CODE`.
  139. ## Tests
  140. ```bash
  141. python -m pytest
  142. ```
  143. They run offline with no keys. CI runs them on Python 3.10 and 3.12.
  144. ## More from Hyperliquid Guide
  145. - [Build a Hyperliquid bot with Claude Code or Codex](https://hyperliquidguide.com/build)
  146. - [Grid bot guide](https://hyperliquidguide.com/guides/trading/hyperliquid-grid-bot)
  147. - [Funding rate arbitrage guide](https://hyperliquidguide.com/guides/trading/hyperliquid-funding-rate-arbitrage)
  148. - [Hyperliquid MCP servers compared](https://hyperliquidguide.com/guides/trading/hyperliquid-mcp-server)
  149. - [Hyperliquid API guide](https://hyperliquidguide.com/guides/trading/hyperliquid-api-guide)
  150. - [Market making on Hyperliquid](https://hyperliquidguide.com/guides/trading/hyperliquid-market-making-guide)
  151. - [Fees and VIP tiers](https://hyperliquidguide.com/guides/fees/fees-explained)
  152. ---
  153. <sub>Maintained by <a href="https://hyperliquidguide.com">Hyperliquid Guide</a>, an independent site. Not affiliated with, endorsed by, or reviewed by Hyperliquid or the Hyper Foundation. MIT licensed. Graphics are regenerated with <code>tools/make-assets.mjs</code>.</sub>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.