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.