Hyperliquid Copy-Trading Bot

TypeScript scaffold for a low-latency Hyperliquid copy-trading bot. It listens to userFills over WebSocket, mirrors fills onto a follower wallet, and applies basic risk controls before every order.

Important note

This project is a trading automation scaffold, not a profit guarantee. No bot can honestly promise to be "very profitable" in all market conditions. Start on testnet, keep HL_DRY_RUN=true first, and use an API-only wallet with limited permissions.

Features

• WebSocket subscriptions for userFills and allMids
• Hyperliquid SDK-based order entry and leverage setup
• Dry-run mode for safe rehearsal
• Per-trade notional cap
• Per-coin exposure cap
• Coin allowlist and blocklist
• Snapshot handling toggle
• Leader fill deduplication and per-coin cooldown
• Entry sizing by mirrored size or mirrored notional
• Periodic follower state reconciliation without blocking every order path

Quick start

1. Install dependencies:

npm install

2. Copy the environment file and fill in your wallet / leader addresses:

cp .env.example .env

3. Start in dry-run mode:

npm run dev

4. Build production output:

npm run build
npm start

Environment variables

• HL_PRIVATE_KEY: Follower wallet private key. Use a dedicated API wallet.
• HL_FOLLOWER_ADDRESS: Optional explicit follower address. If omitted, it is derived from HL_PRIVATE_KEY.
• HL_LEADER_ADDRESSES: Comma-separated leader addresses to mirror.
• HL_NETWORK: mainnet or testnet. Default is testnet.
• HL_DRY_RUN: When true, logs simulated orders instead of placing real ones.
• HL_COPY_MODE: mirror_size or mirror_notional.
• HL_COPY_SCALE: Scaling factor applied to mirrored size or notional.
• HL_MAX_NOTIONAL_PER_TRADE_USD: Maximum entry size for a single copied leg.
• HL_MAX_POSITION_NOTIONAL_PER_COIN_USD: Maximum non-reduce exposure per coin.
• HL_MIN_LEADER_FILL_USD: Ignore tiny leader fills below this notional.
• HL_MAX_SLIPPAGE_BPS: IOC limit buffer over the current mid price.
• HL_FOLLOWER_LEVERAGE: Requested follower leverage per coin.
• HL_USE_CROSS_MARGIN: true for cross margin, false for isolated.
• HL_ALLOWED_COINS: Optional comma-separated allowlist.
• HL_IGNORED_COINS: Optional comma-separated denylist.
• HL_PROCESS_SNAPSHOTS: Whether to copy the initial historical snapshot on subscription.
• HL_AGGREGATE_FILLS: Aggregate partial fills from Hyperliquid when available.
• HL_REQUEST_TIMEOUT_MS: Info / exchange request timeout.
• HL_ORDER_COOLDOWN_MS: Optional minimum spacing between copied orders per coin.
• HL_STATE_REFRESH_INTERVAL_MS: Periodic follower state reconciliation interval. Set 0 to disable.

How it works

1. Loads perp metadata and follower state.
2. Seeds mid prices, then subscribes to live mid updates.
3. Subscribes to userFills for each leader.
4. Splits a leader reversal fill into a reduce-only leg plus a new-entry leg.
5. Applies sizing and risk caps.
6. Sends IOC limit orders on the follower wallet.
7. Reconciles follower state on a timer so order submission stays fast.

Good next upgrades

• Persist dedupe state across restarts
• Add stop-loss / kill-switch logic from follower equity drawdown
• Add a leader scoring layer before blindly copying every address
• Track fill latency, slippage, and realized copy divergence
• Add alerting for rejected orders and reconnection storms