Hyperliquid directional bot

A small, readable automated systematic trading bot for Hyperliquid perps. It runs an EMA-crossover signal on one symbol and reconciles your position toward flat / long / short, with hard risk limits and a loss kill-switch.

Read this first (honest expectations)

• This is not HFT and will not out-compete professional HFT/market-making firms. Those win on microsecond latency (co-located servers, custom hardware, direct feeds). A Python bot polling a public API is structurally slower. This bot trades on signal, not speed.
• It is a learning template, not a proven edge. The EMA strategy is a starting point. Most retail algo traders lose money. Backtest and paper-trade before risking a cent, and never risk more than you can lose entirely.
• Claude helped write the code; Claude does not trade for you. The bot is deterministic code running on your machine with your keys. No LLM is in the trading loop (models are too slow/nondeterministic for that).

Safety model — three switches, all must flip for real money

.env	Default	Meaning
DRY_RUN	true	Logs intended orders, sends nothing.
USE_TESTNET	true	Testnet = fake money.
ALLOW_MAINNET	no	Must be yes before USE_TESTNET=false is even allowed.

Real funds are only ever touched with DRY_RUN=false, USE_TESTNET=false, and ALLOW_MAINNET=yes.

Setup

cd hyperliquid-bot
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env         # then edit .env

1) Dry-run right now (no wallet, no money)

python3 bot.py

Uses real live testnet prices, simulates fills, prints what it would do. Stop with Ctrl+C. Tweak SYMBOL, FAST_EMA/SLOW_EMA, NEUTRAL_BAND, POLL_SECONDS in .env and watch how behavior changes.

2) Get an agent wallet + testnet funds (for live testnet)

Use an API/agent wallet, never your main private key. An agent wallet can place orders but cannot withdraw — so a leaked bot key can't drain your funds.

1. Go to https://app.hyperliquid.xyz/API, connect your wallet, and generate an API/agent wallet. Copy its private key.
2. Fund testnet: switch the app to Testnet, use the faucet to get test USDC.
3. In .env:

   HL_SECRET_KEY=<the agent wallet private key>
   HL_ACCOUNT_ADDRESS=<your MAIN account address, 0x...>
   DRY_RUN=false
   USE_TESTNET=true
   

4. Run python3 bot.py. Now it places real testnet orders (fake money). Watch it for a while.

3) Small mainnet (only after testnet looks right)

USE_TESTNET=false
ALLOW_MAINNET=yes
MAX_POSITION_USD=50        # start tiny
DAILY_MAX_LOSS_USD=20      # kill switch

Fund the agent's main account with a small amount you can fully afford to lose. Start with the smallest size that clears the $10 minimum order.

Risk controls (enforced every loop)

• MAX_POSITION_USD — the bot never holds more notional than this.
• DAILY_MAX_LOSS_USD — session loss cap. Hitting it flattens the position and stops the bot (kill switch).
• LEVERAGE — keep at 1 unless you know what you're doing.
• MIN_ORDER_USD — Hyperliquid's ~$10 minimum; smaller top-ups are skipped.
• SLIPPAGE — max slippage for market orders.

How it works

• strategy.py — the signal. Fast/slow EMA crossover with a neutral band to cut chop. Returns -1/0/+1. Swap this file to test other ideas — the bot only needs signal(closes, fast, slow, band).
• hl_client.py — market data + orders (real in live, paper-simulated in dry-run) with size rounding and min-notional handling.
• risk.py — position clamp + loss kill-switch.
• bot.py — the loop: price → signal → reconcile position → risk-checked order.
• config.py — loads .env, validates, resolves testnet/mainnet.

MAX_CYCLES=N runs a bounded number of loops (handy for testing); 0 = run forever.

Go-live checklist

• Dry-run behaves sensibly for a while.
• Live testnet places/closes orders correctly; kill switch works.
• MAX_POSITION_USD and DAILY_MAX_LOSS_USD set to amounts you're fine losing.
• Using an agent wallet key (not your main key); .env is gitignored.
• You understand this can lose money and you accept that.

Disclaimer

Educational software provided as-is, with no warranty. Not financial advice. Trading perpetual futures is high-risk and you can lose your entire balance (and more, with leverage). You are solely responsible for any use and any losses.