# Hyperliquid Copy Trading Bot — бот копитрейдинга бессрочных контрактов на Hyperliquid

[English](README.md) · **Русский** · [中文](README.zh.md)

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

> **Наиболее полный open-source бот копитрейдинга для Hyperliquid, написанный на TypeScript и Node.js.**
> Зеркалируйте позиции по бессрочным фьючерсам любого трейдера на Hyperliquid в реальном времени через WebSocket.

---

## Что это? (Бот копитрейдинга Hyperliquid)

Это **бот копитрейдинга Hyperliquid** — полностью автоматизированный торговый бот для перпетуалов, который следит за кошельком целевого трейдера на бессрочном DEX Hyperliquid и мгновенно повторяет каждую его сделку на вашем счёте.

Ищете ли вы **бота для торговли перпетуалами на Hyperliquid**, **бота копитрейдинга для бессрочного DEX** или **криптобота копитрейдинга** для ончейн-фьючерсов — этот проект охватывает всё это.

Построенный на официальном TypeScript SDK [`@nktkas/hyperliquid`](https://www.npmjs.com/package/@nktkas/hyperliquid), этот **торговый бот Hyperliquid** подключается через WebSocket для репликации сделок с почти нулевой задержкой на перп-DEX Hyperliquid.

---

## Зачем использовать этого бота копитрейдинга Hyperliquid?

- **Копитрейдинг перпетуалов в реальном времени** — подписка на WebSocket `userFills` срабатывает в течение миллисекунд после исполнения сделки цели
- **Точная пропорциональная логика закрытия** — если цель закрывает 40% своей бессрочной позиции, бот закрывает ровно 40% вашей
- **Синхронизация плеча** — перп-бот повторяет (и ограничивает) плечо целевого трейдера перед открытием любой позиции
- **Периодическая сверка (reconciliation)** — бот Hyperliquid сравнивает ваши позиции с целевыми каждые N секунд и автоматически закрывает те, что рассинхронизировались
- **Полноценный риск-менеджмент** — максимальный размер позиции, максимальная суммарная экспозиция, максимальное плечо и автостоп по дневному убытку
- **Рыночные IOC-ордера** — использует агрессивные IOC-ордера (Immediate-Or-Cancel) с допуском на проскальзывание, чтобы каждая копируемая сделка исполнялась мгновенно
- **Корректное завершение работы** — по желанию закрывает все скопированные бессрочные позиции при Ctrl+C
- **Структурированное логирование** — консоль + ротация файловых логов через Winston

---

## Ключевые слова: что охватывает этот бот

Этот **бот копитрейдинга Hyperliquid** ориентирован на трейдеров, которым интересно любое из следующего:

- Бот копитрейдинга Hyperliquid
- Бот для торговли перпетуалами Hyperliquid
- Торговый бот для бессрочного DEX Hyperliquid
- Бот копитрейдинга для бессрочного DEX
- Open-source бот для торговли перпетуалами
- Криптобот копитрейдинга на TypeScript
- Ончейн-бот копитрейдинга
- Автоматизированный торговый бот Hyperliquid
- Бот зеркалирования сделок Hyperliquid
- Бот «следуй за трейдером» Hyperliquid
- Перп-бот для DEX на Node.js
- Бот Hyperliquid на TypeScript

---

## Структура проекта

```
hyperliquid-copy-trading-bot/
├── src/
│   ├── index.ts              # Точка входа — запуск и корректное завершение
│   ├── bot.ts                # CopyTradingBot — основная оркестрация
│   ├── config.ts             # Загрузка и валидация .env
│   ├── types.ts              # Интерфейсы и типы TypeScript
│   ├── services/
│   │   ├── hlClient.ts        # Обёртка над SDK Hyperliquid (Info + Exchange + Subscription)
│   │   ├── riskManager.ts     # Риск-проверки, учёт дневного убытка
│   │   ├── kellySizer.ts       # Размер позиции по критерию Келли (kelly-stake)
│   │   ├── orderExecutor.ts   # Размещение ордеров с логикой повторов
│   │   ├── fillProcessor.ts   # Сделки цели → скопированные ордера (открытие/закрытие/плечо)
│   │   ├── reconciler.ts      # Периодическая сверка позиций (страховка)
│   │   ├── stopLossMonitor.ts # Контроль стоп-лосса по позициям
│   │   ├── positionRegistry.ts# Набор монет, которыми бот активно управляет
│   │   └── statsTracker.ts    # Счётчики за время работы
│   └── utils/
│       ├── logger.ts         # Логгер Winston (консоль + файл)
│       ├── math.ts           # Помощники форматирования цены/размера
│       ├── keyedQueue.ts     # Последовательная очередь задач по монете (безопасность конкурентности)
│       └── sleep.ts          # Утилиты sleep() + withRetry()
├── logs/                     # Автосоздаваемые файлы логов
├── .env.example              # Шаблон конфигурации
├── package.json
├── tsconfig.json
└── README.md
```

---

## Быстрый старт — запуск бота копитрейдинга Hyperliquid

### Требования

- **Node.js 18+**
- Аккаунт **Hyperliquid** с внесённым USDC на mainnet (или testnet)
- Отдельный **API-кошелёк** — суб-кошелёк, который может торговать, но не может выводить средства (настоятельно рекомендуется для любого торгового бота Hyperliquid)

### 1. Клонирование и установка

```bash
npm install
```

### 2. Настройка перп-бота

```bash
cp .env.example .env
```

Откройте `.env` и заполните значения:

```env
# ── Обязательно ────────────────────────────────────────────────
# Приватный ключ вашего выделенного торгового кошелька
PRIVATE_KEY=0xYourTradingWalletPrivateKey

# Адрес кошелька, чьи перп-сделки вы хотите копировать
TARGET_TRADER=0xTargetTraderAddressHere

# ── Размер позиции ─────────────────────────────────────────────
SIZE_MULTIPLIER=1.0          # 1.0 = тот же размер, что у цели
MAX_POSITION_SIZE_USD=1000   # макс. номинал на одну позицию
MAX_TOTAL_EXPOSURE_USD=5000  # макс. сумма всех открытых номиналов
MAX_LEVERAGE=10              # никогда не превышать 10x

# ── Размер по Келли (опционально) ──────────────────────────────
KELLY_ENABLED=false          # ограничивать копии ставкой дробного Келли
KELLY_FRACTION=0.5           # половинный Келли (рекомендуется)
KELLY_MAX_FRACTION=0.2       # не ставить >20% капитала на одну копию
KELLY_WINDOW=50              # скользящее окно сделок цели
KELLY_MIN_SAMPLES=10         # число закрытий до включения Келли

# ── Риск ───────────────────────────────────────────────────────
MAX_DAILY_LOSS_USD=500       # приостановить бота при дневном убытке $500

# ── Сеть ───────────────────────────────────────────────────────
NETWORK=testnet              # всегда сначала тестируйте на testnet!
```

### 3. Запуск перп-бота Hyperliquid

**Режим разработки (авто-перезапуск при изменении файлов):**
```bash
npm run dev
```

**Продакшн (сборка, затем запуск):**
```bash
npm run build
npm start
```

---

## Справочник конфигурации

| Переменная | По умолчанию | Описание |
|---|---|---|
| `PRIVATE_KEY` | **обязательно** | Приватный ключ вашего торгового кошелька Hyperliquid (0x...) |
| `TARGET_TRADER` | **обязательно** | Адрес кошелька для копирования на перп-DEX |
| `SIZE_MULTIPLIER` | `1.0` | Умножить размер сделки цели на этот коэффициент |
| `MAX_POSITION_SIZE_USD` | `1000` | Макс. номинал (USD) на одну скопированную позицию |
| `MAX_TOTAL_EXPOSURE_USD` | `5000` | Макс. суммарный открытый номинал по всем перп-позициям |
| `MAX_LEVERAGE` | `10` | Потолок плеча — бот никогда его не превышает |
| `KELLY_ENABLED` | `false` | Включить размер по критерию Келли (ограничивает каждую копию ставкой дробного Келли) |
| `KELLY_FRACTION` | `0.5` | Множитель дробного Келли в (0, 1]. `0.5` = половинный Келли (рекомендуется) |
| `KELLY_MAX_FRACTION` | `0.2` | Жёсткий предел доли капитала на одну копию, в (0, 1] |
| `KELLY_WINDOW` | `50` | Скользящее окно недавних сделок цели для оценки преимущества (edge) |
| `KELLY_MIN_SAMPLES` | `10` | Мин. число закрытий цели до включения Келли (иначе используется зеркалирование) |
| `STOP_LOSS_PERCENT` | `0` | Авто стоп-лосс в % от цены входа (0 = отключено) |
| `STOP_LOSS_CHECK_INTERVAL_MS` | `5000` | Как часто (мс) проверять управляемые позиции на срабатывание стоп-лосса |
| `MAX_DAILY_LOSS_USD` | `0` | Приостановить бота, если дневной реализованный убыток превысит значение (0 = отключено) |
| `COPY_EXISTING_POSITIONS` | `false` | При старте также копировать уже открытые перп-позиции цели |
| `CLOSE_ON_EXIT` | `false` | Закрывать все скопированные перп-позиции при остановке бота |
| `RECONCILE_INTERVAL_MS` | `60000` | Как часто (мс) запускать сверку позиций |
| `SLIPPAGE_BPS` | `50` | Проскальзывание IOC-ордера в базисных пунктах (50 = 0.5%) |
| `NETWORK` | `mainnet` | `mainnet` или `testnet` |
| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
| `LOG_TO_FILE` | `true` | Писать логи в `./logs/` |

---

## Как работает бот копитрейдинга Hyperliquid

### Шаг 1 — Подписка на сделки через WebSocket

**Бот копитрейдинга Hyperliquid** подписывается на WebSocket-канал `userFills` для адреса целевого трейдера.
Каждый раз, когда у цели происходит исполнение сделки на перп-DEX Hyperliquid, бот получает событие, содержащее:

| Поле | Значение |
|---|---|
| `coin` | Бессрочный рынок (например, `"BTC"`, `"ETH"`, `"SOL"`) |
| `dir` | `"Open Long"` / `"Close Long"` / `"Open Short"` / `"Close Short"` |
| `sz` | Размер исполнения |
| `px` | Цена исполнения |
| `startPosition` | Размер позиции цели **до** этого исполнения |
| `side` | `"B"` = покупка/лонг, `"A"` = продажа/шорт |

### Шаг 2 — Расчёт размера копии

**Открытие перп-позиции** (`dir` содержит `"Open"`):
```
copySize = fill.sz × SIZE_MULTIPLIER
copySize = min(copySize, kellyStake / currentMidPrice)   ← только при KELLY_ENABLED
copySize = min(copySize, MAX_POSITION_SIZE_USD / currentMidPrice)
```

При `KELLY_ENABLED=true` бот определяет размер по **критерию Келли** с помощью модуля
[`kelly-stake`](https://www.npmjs.com/package/kelly-stake). Он отслеживает реализованный PnL закрытий
целевого трейдера, оценивает его преимущество `{ winProbability, payoffRatio }` на скользящем
окне `KELLY_WINDOW` и переводит текущую стоимость вашего счёта в ставку дробного Келли:

```
f*        = p − (1 − p) / b                        ← сырая доля Келли
stake     = accountValue × f* × KELLY_FRACTION      ← ограничено KELLY_MAX_FRACTION
copySize  = min(mirrorSize, stake / midPrice)       ← Келли только уменьшает копию
```

Келли работает как **ограничитель**: он никогда не устанавливает размер больше зеркальной сделки или
`MAX_POSITION_SIZE_USD` и полностью пропускает открытие, если наблюдаемое преимущество
неположительно (`f* ≤ 0`). Пока не накопится `KELLY_MIN_SAMPLES` закрытий
(инициализируется при старте из недавних сделок цели), размер определяется
обычным зеркалированием по `SIZE_MULTIPLIER`.

**Закрытие перп-позиции** (`dir` содержит `"Close"`):
```
closePercent = fill.sz / |startPosition|    ← % позиции, который цель закрыла
copySize     = |ourPosition.szi| × closePercent  ← тот же % от нашей
```

Эта пропорциональная логика закрытия гарантирует, что **перп-бот копитрейдинга** остаётся синхронным, даже когда цель частично сокращает позицию.

### Шаг 3 — Синхронизация плеча

Перед открытием любой скопированной бессрочной позиции **перп-бот Hyperliquid** получает текущее плечо цели по этой монете и применяет его к нашему счёту — с ограничением `MAX_LEVERAGE`.

### Шаг 4 — Исполнение IOC-ордеров

Все копируемые ордера размещаются как **IOC (Immediate-Or-Cancel)** лимитные ордера с буфером проскальзывания:

- **Покупка / Лонг**: `price = midPrice × (1 + SLIPPAGE_BPS / 10000)` → цена выше рынка для гарантии исполнения
- **Продажа / Шорт**: `price = midPrice × (1 - SLIPPAGE_BPS / 10000)` → цена ниже рынка для гарантии исполнения

Это заставляет каждую копируемую сделку вести себя как рыночный ордер, не платя спред явного рыночного ордера.

### Шаг 5 — Сверка (Reconciliation)

Каждые `RECONCILE_INTERVAL_MS` миллисекунд **бот копитрейдинга Hyperliquid** запускает цикл сверки:

1. Получает актуальные открытые бессрочные позиции цели
2. Получает наши текущие открытые позиции
3. Для любой управляемой монеты, где **цель уже без позиции, а мы всё ещё держим** → закрывает нашу позицию
4. Логирует предупреждение, если наш размер значительно отклонился от ожидаемого масштабированного

---

## Риск-менеджмент

**Перп-бот** включает несколько уровней контроля риска:

| Защита | Переменная конфигурации | Поведение |
|---|---|---|
| Макс. размер позиции | `MAX_POSITION_SIZE_USD` | Отклоняет любой копируемый ордер, где номинал > лимита |
| Макс. суммарная экспозиция | `MAX_TOTAL_EXPOSURE_USD` | Отклоняет, если добавление позиции превысит общий лимит номинала |
| Макс. плечо | `MAX_LEVERAGE` | Ограничивает плечо для всех скопированных бессрочных позиций |
| Размер по Келли | `KELLY_ENABLED` | Ограничивает каждую копию ставкой дробного Келли от капитала; пропускает открытия без преимущества |
| Лимит дневного убытка | `MAX_DAILY_LOSS_USD` | Приостанавливает всего бота до полуночи UTC, если совокупный реализованный убыток достиг лимита |
| Минимальный номинал | Жёстко задано $5 | Пропускает микросделки, которые создали бы пылевые (dust) позиции |
| Логика повторов | Встроено | Все API-вызовы повторяются до 3× с экспоненциальной задержкой |

---

## Лучшие практики безопасности для любого торгового бота Hyperliquid

1. **Используйте выделенный API-кошелёк, а не основной.**
   Hyperliquid позволяет авторизовать отдельный кошелёк, который может торговать, но не может выводить средства. Если API-ключ бота будет скомпрометирован, ваши средства останутся в безопасности.

2. **Никогда не коммитьте `.env` в git.**
   `.gitignore` уже исключает его, но перепроверьте перед push.

3. **Всегда сначала тестируйте на testnet.**
   Установите `NETWORK=testnet` и получите бесплатный testnet-USDC в Discord Hyperliquid. Запустите бота как минимум на 24 часа на testnet перед выходом в mainnet.

4. **Начинайте с малого.**
   Используйте `SIZE_MULTIPLIER=0.1`, чтобы копировать 10% от размера цели. Проверьте поведение бота перед масштабированием.

5. **Задайте `MAX_DAILY_LOSS_USD`.**
   Всегда настраивайте лимит дневного убытка, чтобы перп-бот автоматически приостанавливался, если случится что-то непредвиденное.

---

## Пример вывода логов

Когда **бот копитрейдинга Hyperliquid** запущен, вы увидите вывод вроде такого:

```
[2026-03-31 14:22:01] info: ══════════════════════════════════════════════════════════════
[2026-03-31 14:22:01] info:   Hyperliquid Perpetual Copy Trading Bot
[2026-03-31 14:22:01] info: ══════════════════════════════════════════════════════════════
[2026-03-31 14:22:01] info:   Network          : mainnet
[2026-03-31 14:22:01] info:   Target trader    : 0xabcd...1234
[2026-03-31 14:22:01] info:   Our wallet       : 0xef01...5678
[2026-03-31 14:22:01] info:   Size multiplier  : 1×
[2026-03-31 14:22:01] info:   Max pos size     : $1000
[2026-03-31 14:22:03] info: Loaded metadata for 142 perpetual markets
[2026-03-31 14:22:04] info: Our account value : $2450.00
[2026-03-31 14:22:04] info: Target trader open positions: 2
[2026-03-31 14:22:04] info:   BTC      LONG  0.02 @ entry 85432.0
[2026-03-31 14:22:04] info:   ETH      SHORT 0.5  @ entry 1920.0
[2026-03-31 14:22:04] info: Subscribing to live fills for 0xabcd...1234...
[2026-03-31 14:22:04] info: Bot is live. Press Ctrl+C to stop.

[2026-03-31 14:35:12] info: ◆ TARGET FILL  BTC      [Open Long  ] sz=0.01  px=86100.0  tx=0xaabbcc...
[2026-03-31 14:35:12] info: → BTC       BUY          0.010 @      86543.0 [open    ]  (copy-open-long)
[2026-03-31 14:35:12] info: ✓ BTC BUY  0.010 FILLED @ avg 86510.5 (oid=109234)
```

---

## Часто задаваемые вопросы

**В: Работает ли этот бот копитрейдинга Hyperliquid со спотовыми рынками?**
Нет — бот автоматически отфильтровывает спотовые сделки и копирует только бессрочные (перп) сделки на Hyperliquid.

**В: Что произойдёт, если целевого трейдера ликвидируют?**
Ликвидация приходит как направление `"Liquidated Long"` или `"Liquidated Short"`. Бот не будет пытаться копировать ликвидацию — он пропускает неизвестные значения `dir`, а цикл сверки обнаружит теперь уже нулевую позицию и закроет нашу.

**В: Можно ли копировать нескольких трейдеров сразу?**
Текущая архитектура поддерживает одного целевого трейдера на экземпляр бота. Чтобы копировать нескольких трейдеров, запустите несколько экземпляров бота с разными файлами `.env`.

**В: Какой минимальный баланс нужен для запуска этого перп-бота копитрейдинга?**
Рекомендуется минимум $50 USDC. Бот пропускает любой копируемый ордер с номиналом ниже $5 (чтобы избежать пыли), и вам понадобится маржа для позиций.

**В: Обрабатывает ли перп-бот Hyperliquid разрывы WebSocket?**
Да. `WebSocketTransport` из SDK автоматически переподключается. Цикл сверки (по умолчанию каждые 60 секунд) служит страховкой для повторной синхронизации позиций после любого переподключения.

---

## Технологический стек

| Компонент | Технология |
|---|---|
| Язык | TypeScript 5 |
| Среда выполнения | Node.js 18+ |
| SDK Hyperliquid | `@nktkas/hyperliquid` v0.32+ |
| Подпись кошелька | `viem` (EIP-712) |
| Логирование | Winston |
| Сборка | tsc |

---

## Отказ от ответственности

Данное ПО **бота копитрейдинга Hyperliquid** и **торгового бота для бессрочного DEX** предоставляется исключительно в образовательных и информационных целях. Торговля бессрочными криптофьючерсами несёт существенный риск финансовых потерь. Прошлые результаты любого копируемого трейдера не гарантируют будущих результатов. Всегда проводите собственную проверку (due diligence). Авторы не несут ответственности за любые торговые убытки, понесённые при использовании этого перп-бота.

**Используйте на свой страх и риск. Сначала тестируйте на testnet. Никогда не торгуйте средствами, потерю которых вы не можете себе позволить.**