Hyperliquid Copy Trading Bot — Perpetual DEX Trading Bot for Hyperliquid Perps

English · Русский · 中文

https://github.com/user-attachments/assets/d30201f1-546b-4a11-ae88-5a87a6b2a316

The most complete open-source Hyperliquid copy trading bot built with TypeScript & Node.js. Mirror any trader's perpetual futures positions on Hyperliquid in real-time via WebSocket.

---

What Is This? (Hyperliquid Copy Trading Bot)

This is a Hyperliquid copy trading bot — a fully automated perp trading bot that watches a target trader's wallet on the Hyperliquid perpetual DEX and instantly mirrors every trade into your own account.

Whether you're looking for a Hyperliquid perp trading bot, a perpetual DEX copy trading bot, or a crypto copy trading bot for on-chain futures — this project covers it all.

Built on the official @nktkas/hyperliquid TypeScript SDK, this Hyperliquid trading bot connects via WebSocket for near-zero-latency trade replication on the Hyperliquid perp DEX.

---

Why Use This Hyperliquid Copy Trading Bot?

• Real-time perp copy trading — WebSocket userFills subscription fires within milliseconds of the target's fill
• Accurate proportional close logic — if the target closes 40% of their perpetual position, the bot closes exactly 40% of yours
• Leverage sync — the perp trading bot matches (and caps) the target trader's leverage before opening any position
• Periodic reconciliation — the Hyperliquid bot compares your positions against the target every N seconds and auto-closes any that drifted
• Full risk management — max position size, max total exposure, max leverage, and daily loss circuit breaker
• Market IOC orders — uses aggressive IOC (Immediate-Or-Cancel) orders with slippage tolerance so every copy trade fills instantly
• Graceful shutdown — optionally closes all copied perpetual positions on Ctrl+C
• Structured logging — console + rotating file logs via Winston

---

Keywords: What This Bot Covers

This Hyperliquid copy trading bot targets traders interested in any of the following:

• Hyperliquid copy trading bot
• Hyperliquid perp trading bot
• Hyperliquid perpetual DEX trading bot
• Perpetual DEX copy trading bot
• Perp trading bot open source
• Crypto copy trading bot TypeScript
• On-chain copy trading bot
• Hyperliquid automated trading bot
• Hyperliquid mirror trading bot
• Hyperliquid follow trader bot
• DEX perp bot Node.js
• Hyperliquid bot TypeScript

---

Project Structure

hyperliquid-copy-trading-bot/
├── src/
│   ├── index.ts              # Entry point — startup & graceful shutdown
│   ├── bot.ts                # CopyTradingBot — main orchestration
│   ├── config.ts             # .env loading & validation
│   ├── types.ts              # TypeScript interfaces & types
│   ├── services/
│   │   ├── hlClient.ts        # Hyperliquid SDK wrapper (Info + Exchange + Subscription)
│   │   ├── riskManager.ts     # Risk checks, daily loss tracking
│   │   ├── kellySizer.ts       # Kelly-criterion position sizing (@zscdao/kelly)
│   │   ├── orderExecutor.ts   # Order placement with retry logic
│   │   ├── fillProcessor.ts   # Target fills → copied orders (open/close/leverage)
│   │   ├── reconciler.ts      # Periodic position re-sync safety net
│   │   ├── stopLossMonitor.ts # Per-position stop-loss enforcement
│   │   ├── positionRegistry.ts# Set of coins the bot actively manages
│   │   └── statsTracker.ts    # Lifetime run counters
│   └── utils/
│       ├── logger.ts         # Winston logger (console + file)
│       ├── math.ts           # Price/size formatting helpers
│       ├── keyedQueue.ts     # Per-coin serial task queue (concurrency safety)
│       └── sleep.ts          # sleep() + withRetry() utilities
├── logs/                     # Auto-created log files
├── .env.example              # Config template
├── package.json
├── tsconfig.json
└── README.md

---

Quick Start — Run the Hyperliquid Copy Trading Bot

Prerequisites

• Node.js 18+
• A Hyperliquid account with USDC deposited on mainnet (or testnet)
• A dedicated API wallet — a sub-wallet that can trade but cannot withdraw funds (strongly recommended for any Hyperliquid trading bot)

1. Clone and Install

npm install

2. Configure the Perp Trading Bot

cp .env.example .env

Open .env and fill in your values:

# ── Required ───────────────────────────────────────────────────
# Private key of your dedicated trading wallet
PRIVATE_KEY=0xYourTradingWalletPrivateKey

# The wallet address whose perp trades you want to copy
TARGET_TRADER=0xTargetTraderAddressHere

# ── Sizing ──────────────────────────────────────────────────────
SIZE_MULTIPLIER=1.0          # 1.0 = same size as target
MAX_POSITION_SIZE_USD=1000   # max notional per position
MAX_TOTAL_EXPOSURE_USD=5000  # max sum of all open notional
MAX_LEVERAGE=10              # never exceed 10x

# ── Kelly sizing (optional) ─────────────────────────────────────
KELLY_ENABLED=false          # cap copies at the fractional-Kelly stake
KELLY_FRACTION=0.5           # half-Kelly (recommended)
KELLY_MAX_FRACTION=0.2       # never stake >20% of equity per copy
KELLY_WINDOW=50              # rolling window of target trades
KELLY_MIN_SAMPLES=10         # closes needed before Kelly engages

# ── Risk ────────────────────────────────────────────────────────
MAX_DAILY_LOSS_USD=500       # pause the perp bot if daily loss hits $500

# ── Network ─────────────────────────────────────────────────────
NETWORK=testnet              # always test on testnet first!

3. Run the Hyperliquid Perp Bot

Development mode (auto-reloads on file changes):

npm run dev

Production (compile then run):

npm run build
npm start

---

Configuration Reference

| Variable | Default | Description | |---|---|---| | PRIVATE_KEY | required | Private key of your Hyperliquid trading wallet (0x...) | | TARGET_TRADER | required | Wallet address to copy-trade on the perp DEX | | SIZE_MULTIPLIER | 1.0 | Multiply the target's trade size by this factor | | MAX_POSITION_SIZE_USD | 1000 | Max notional (USD) per single copied position | | MAX_TOTAL_EXPOSURE_USD | 5000 | Max total open notional across all perp positions | | MAX_LEVERAGE | 10 | Leverage ceiling — the copy trading bot never exceeds this | | KELLY_ENABLED | false | Enable Kelly-criterion sizing (caps each copy at the fractional-Kelly stake) | | KELLY_FRACTION | 0.5 | Fractional-Kelly multiplier in (0, 1]. 0.5 = half-Kelly (recommended) | | KELLY_MAX_FRACTION | 0.2 | Hard cap on the equity fraction staked per copy, in (0, 1] | | KELLY_WINDOW | 50 | Rolling window of the target's recent trades used to estimate edge | | KELLY_MIN_SAMPLES | 10 | Minimum target closes before Kelly engages (else it uses the mirror) | | STOP_LOSS_PERCENT | 0 | Auto stop-loss % from entry price (0 = disabled) | | STOP_LOSS_CHECK_INTERVAL_MS | 5000 | How often (ms) to check managed positions for stop-loss breach | | MAX_DAILY_LOSS_USD | 0 | Pause the bot if daily realized loss exceeds this (0 = disabled) | | COPY_EXISTING_POSITIONS | false | On start, also copy the target's currently open perp positions | | CLOSE_ON_EXIT | false | Close all copied perp positions when the bot shuts down | | RECONCILE_INTERVAL_MS | 60000 | How often (ms) to run position reconciliation | | SLIPPAGE_BPS | 50 | IOC order slippage in basis points (50 = 0.5%) | | NETWORK | mainnet | mainnet or testnet | | LOG_LEVEL | info | debug / info / warn / error | | LOG_TO_FILE | true | Write logs to ./logs/ |

---

How the Hyperliquid Copy Trading Bot Works

Step 1 — WebSocket Fill Subscription

The Hyperliquid copy trading bot subscribes to the userFills WebSocket channel for the target trader's address. Every time the target gets a trade fill on the Hyperliquid perp DEX, the bot receives an event containing:

| Field | Meaning | |---|---| | coin | Perpetual market (e.g., "BTC", "ETH", "SOL") | | dir | "Open Long" / "Close Long" / "Open Short" / "Close Short" | | sz | Size of the fill | | px | Fill price | | startPosition | The target's position size before this fill | | side | "B" = buy/long, "A" = ask/sell/short |

Step 2 — Copy Size Calculation

Opening a perp position (dir contains "Open"):

copySize = fill.sz × SIZE_MULTIPLIER
copySize = min(copySize, kellyStake / currentMidPrice)   ← only when KELLY_ENABLED
copySize = min(copySize, MAX_POSITION_SIZE_USD / currentMidPrice)

When KELLY_ENABLED=true, the bot sizes with the Kelly criterion via the kelly-stake module. It watches the target trader's realised close PnL, estimates their edge { winProbability, payoffRatio } over a rolling KELLY_WINDOW, and converts your live account value into the fractional-Kelly stake:

f*        = p − (1 − p) / b                        ← raw Kelly fraction
stake     = accountValue × f* × KELLY_FRACTION      ← capped at KELLY_MAX_FRACTION
copySize  = min(mirrorSize, stake / midPrice)       ← Kelly only ever shrinks a copy

Kelly acts as a cap: it never sizes above the mirrored trade or MAX_POSITION_SIZE_USD, and it skips the open entirely when the observed edge is non-positive (f* ≤ 0). Until KELLY_MIN_SAMPLES closes have accumulated (seeded at startup from the target's recent fills), sizing falls back to the plain SIZE_MULTIPLIER mirror.

Closing a perp position (dir contains "Close"):

closePercent = fill.sz / |startPosition|    ← % of their position they exited
copySize     = |ourPosition.szi| × closePercent  ← same % of ours

This proportional close logic ensures the perp copy trading bot stays in sync eve