Hyperliquid copy trading bot

Mirror a leader’s perp fills on Hyperliquid with proportional sizing—built for traders who want execution without babysitting a browser.

Pulse Mirror watches your chosen wallet over WebSocket, scales each leg against your equity vs theirs, applies notional caps and minimum ticket checks, then fires HL-compliant limit orders using the official SDK patterns (asset IDs, tick/lot formatting).

Trading perpetuals can wipe an account. Run TESTNET=true and DRY_RUN=true until you trust sizing and symbols.

---

Why traders use this

Benefit	What it means
Fill-tied logic	Reacts to leader executions, not stale snapshots
Equity-aware sizing	Scales size by (your NAV / leader NAV) × SCALE, capped by CAP_PCT_EQUITY
Exchange-realistic formatting	Uses HL size/price rules via @nktkas/hyperliquid helpers
Operational clarity	Logs flow through ts-logger-pack so you can swap to structured sinks later

---

Requirements

• Node.js 20+
• A Hyperliquid API wallet (PRIVATE_KEY) with margin on mainnet or testnet
• The leader address (TARGET_LEADER) you want to follow

---

Setup

npm install
cp .env.example .env
# Edit .env — never commit real keys
npm run dev

Production-style:

npm run build
node dist/main.js

---

Environment

Variable	Required	Description
PRIVATE_KEY	yes	Bot wallet private key (0x-prefixed or plain hex)
TARGET_LEADER	yes	Leader wallet (0x address)
TESTNET	no	true / false — default false
SCALE	no	Extra multiplier on sized qty — default 1
MAX_LEV	no	Hard cap on leverage mirrored — default 20
MIN_USD	no	Skip mirrors below this notional — default 10
BLOCKLIST	no	Comma-separated coins to ignore (e.g. DOGE,PEPE)
DRY_RUN	no	Log only — default false
CAP_PCT_EQUITY	no	Max % of your equity allowed as notional per slice — default 40

---

Architecture (mental model)

1. Tap — WebSocket userFills on the leader.
2. Normalize — Dedupe by fill hash; classify open / reduce / close from HL dir.
3. Size — Equity ratio × SCALE, min-notional guard, per-leg notional cap.
4. Execute — updateLeverage when needed, then nested order with GTC limits.

Logging implements the Logger shape from ts-logger-pack (console backend today).

---

Disclaimer

This software is provided as-is for experimentation. You alone control leverage, margin mode, and capital at risk. No performance or profitability claims are made.