Skip to main content

Hyperliquid Starter Bots: readable Python trading bots you can extend with Claude Code, Codex or Cursor

tests PyPI Python 3.10+ MIT license Testnet by default Claude Code ready Codex ready Docs

Four small, readable trading bots for Hyperliquid.
Run one on testnet in five minutes, then have your coding agent turn it into your own strategy.

Terminal: setting up an API wallet and running the market maker on testnet

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.

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 15
Market maker quotes shifting with inventory

Scalper · 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 2
Scalper EMA crossover with stop-loss and take-profit

Grid · 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 12
Grid bot price levels

Funding 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 5
Funding arbitrage: spot long plus perp short

Every 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 BTC

How 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 --> C

Build 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.py that 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:XYZ100 and 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-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

Cursor, 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-bots

Going 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_wallet creates one, and the bots warn you if they're given your main key.
  • Keys stay local. .env is 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 pytest

They 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.

Metadata

Release files for hyperliquid-starter-bots 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hyperliquid-starter-bots 0.2.1
File Size Uploaded Provenance Actions
hyperliquid_starter_bots-0.2.1.tar.gz 37.7 kB With provenance Details for hyperliquid_starter_bots-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hyperliquid-starter-bots 0.2.1
File Interpreter ABI Platform Actions
hyperliquid_starter_bots-0.2.1-py3-none-any.whl Python 3 none any Details for hyperliquid_starter_bots-0.2.1-py3-none-any.whl

Total release size: 77.9 kB

Release files / hyperliquid_starter_bots-0.2.1.tar.gz

Download URL hyperliquid_starter_bots-0.2.1.tar.gz
Size 37.7 kB
Tags Source
SHA-256 checksum
How to use checksums
164c3adff79639fc7d3d517122d84a0241477fc2a21f40943709b949929c7d67
BLAKE2b-256 checksum
How to use checksums
f48240b4d5c7dcfdb418b04dbfd94099aae20fd04c9613fe7ce1cc35bd5c2d36
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / hyperliquid_starter_bots-0.2.1-py3-none-any.whl

Download URL hyperliquid_starter_bots-0.2.1-py3-none-any.whl
Size 40.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
813d12a3b0f5b74fb00161095e34aeed94e0d70be2289700070faf305be919d8
BLAKE2b-256 checksum
How to use checksums
f53d980336ad8d04d03c763e67171b45706e3fb75f1af1382d7a553d52dec1b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for hyperliquid-starter-bots 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hyperliquid_starter_bots-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page