> For the complete documentation index, see [llms.txt](https://0xcherrydocs.gitbook.io/0xcherry/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://0xcherrydocs.gitbook.io/0xcherry/softs/perpetuals-bot.md).

# Perpetuals Bot

#### 📚 Описание проекта <a href="#user-content-opisanie-proekta" id="user-content-opisanie-proekta"></a>

**Perpetuals Bot** - это специализированный софт для мульти-аккаунтной дельта-нейтральной торговли и отработки топовых перп-дексов (**Variational, OneXyz, Bullet, Perpl, Lighter, Popdex**).

Бот позволяет переливать объемы между биржами без риска направленной торговли (cross-dex), крутить корзины активов (dual-delta) или скрытно набивать объемы внутри одного DEX между своими же аккаунтами (single-dex).

Идеально подходит для накрутки торговых объемов под будущие дропы от топовых дексов с минимизацией рыночных рисков, комиссий и контролем спреда.

> ⚠️ **ДИСКЛЕЙМЕР:** Это фьючерсная дельта торговля, а значит несет все те же риски. Не запускайте софт, если чувствуете, что Трамп хочет что-то высказать, держите на аккаунтах часть депа, не завышайте плечи в погоне за быстрой отработкой. Берегите себя и своих близких!

***

#### 🚀 Доступные активности <a href="#user-content-dostupnye-aktivnosti" id="user-content-dostupnye-aktivnosti"></a>

**Основной функционал:**

* **Поддержка 6 перп-дексов**: Variational, OneXyz, Bullet, Perpl, Lighter, Popdex (работает как с EVM, так и с Solana-кошельками);
* **\[NEW] Интерактивный мастер настройки**: Пункт 5 в меню софта позволяет настроить параметры и стратегию пошагово через удобный опросник прямо в консоли;
* **\[NEW] Режим 3: Dual-Delta Fork (Корзина из двух дельт)**: Одновременная торговля парой активов (например, BTC + ETH) на двух биржах. Баланс ходит не за ценой одного актива, а за спредом между ними, что отдаляет ликвидацию и снижает необходимость перелива средств;
* **\[NEW] Парный вход и закрытие (Paired Limit)**: Ваши же аккаунты исполняют лимитки мастера внутри группы, сводя затраты на спред к абсолютному нулю;
* **\[NEW] Торговля индексами и металлами**: Поддержка свопов на US100S (Nasdaq-100), US500S (S\&P 500), XAUS (золото), XAGS (серебро) на Variational с автоматическим учетом расписания торговых сессий;
* **\[NEW] Автоматический вывод средств**: Модули вывода USDC с 01xyz и Variational (`WITHDRAW_FROM_ONEXYZ`, `WITHDRAW_FROM_VARIATIONAL`);
* **\[NEW] Участие в турнирах**: Автоматическая регистрация в трейдинг-соревнованиях OneXyz и Variational Competition;
* **Cross-Dex Режим (Вилки)**: Хеджированные вилки на разных перп-дексах (один аккаунт держит лонг на одной бирже и шорт на другой);
* **Single-Dex Режим**: Скрытая дельта-нейтраль на одном DEX с распределением объемов и плечей между группой из 3+ кошельков;
* **Регистрация и Whitelist**: Регистрация Solana-кошельков на 01xyz (по реф-коду) и привязка к Terminal Trade;
* **Депозит USDC**: Пополнение баланса на OneXyz и Lighter;
* **Автоматическое закрытие всех позиций**: Быстрое закрытие открытых позиций через отдельный пункт меню или флаги.

**Особенности:**

* **Умное лимитное закрытие (`limit_preclose`)**: При перезапуске софта уже открытые противоположные позиции закрываются лимитками, а не маркет-ордерами;
* **Режим зависшей мастер-лимитки (`enable_solo_hang`)**: Если лимитка набралась частично, софт ждет выхода хвоста в плюс и закрывает его с прибылью;
* **TWAP-набор раундами (`enable_twap_rounds`)**: Постепенный набор крупной позиции частями, чтобы не двигать цену в стакане;
* **Обход Cloudflare**: Поддержка CapSolver API для бесшовной авторизации на Variational;
* **Продвинутый TP/SL**: Расчет стопов и тейков от расстояния до ликвидации с динамическим буфером безопасности;
* **Контроль спреда**: Интеллектуальное ожидание сужения спреда и адаптивный контроль (`spread_config`);
* **Имитация ручной торговли**: Настраиваемые случайные задержки между действиями каждого аккаунта (`delay_between_actions`);
* **Многопоточность и прокси**: Полная изоляция аккаунтов и поддержка отдельных прокси для OneXyz;
* **Встроенные уведомления о статусе работы в Telegram**.

***

#### ⚙️ Установка <a href="#user-content-ustanovka" id="user-content-ustanovka"></a>

**Требования:**

* Установленный **Python 3.12.10** (ВАЖНО! Софт работает строго на версии 3.12.10). Скачать можно с [официального сайта](https://www.python.org/downloads/release/python-31210/).
* Валидные EVM кошельки и HTTP прокси.
* Валидные Solana кошельки (если используете OneXyz или Bullet).
* Ключ от [CapSolver](https://dashboard.capsolver.com/) (если используете Variational).

**Установка и запуск:**

1. Разархивируйте софт в удобное для вас место на вашем ПК.
2. Откройте терминал (или командную строку) в папке с софтом.
3. Установите зависимости командой:

   ```
   pip install -r requirements.txt
   ```
4. Выполните настройку конфигурации в `config.py` (или через пункт 5 меню) и заполните файлы в папке `data/`.

***

#### ✅ Настройка и начало работы <a href="#user-content-nastroika-i-nachalo-raboty" id="user-content-nastroika-i-nachalo-raboty"></a>

**📁 config.py**

Основные настройки софта осуществляются в файле `config.py`. *(Совет: вы можете настроить параметры вручную, либо запустить софт и выбрать **пункт 5** меню для пошаговой настройки через интерактивный мастер).*

**🔑 Базовые настройки**

* `LICENSE_KEY` - Ваш лицензионный ключ (берется в боте).
* `LICENSE_USE_PROXY` - (`True`/`False`) Использовать ли прокси для проверки лицензии.
* `TG_BOT_TOKEN`, `TG_USER_ID` - Данные вашего Telegram-бота для получения отчетов и логов.
* `MAX_PARALLEL_ACCOUNTS` - Максимальное количество аккаунтов, работающих одновременно.
* `RETRIES` - Сколько раз повторять неуспешное/зафейленное действие.
* `CAPSOLVER_API_KEY` - API-ключ CapSolver для автоматического прохождения Cloudflare на Variational.
* `CHECK_STATS_DEX` - Чекер статистики (доступны `'Variational'`, `'OneXyz'`, `'Bullet'`, `'Perpl'`, `'Lighter'`, `'Popdex'`).

**⚙️ Выбор режима торговли (Включать ТОЛЬКО ОДИН!)**

* `CROSS_DEX_FORK` - (`True`/`False`) Включить режим 1: Вилки на разных перп дексах (один аккаунт, лонг там, шорт тут).
* `SINGLE_DEX_FORK` - (`True`/`False`) Включить режим 2: Скрытая дельта-нейтраль на одном DEX (группа от 3 аккаунтов).
* `DUAL_DELTA_FORK` - (`True`/`False`) Включить режим 3: Корзина из двух дельт на паре площадок (например, BTC и ETH).

**🔧 Вспомогательные модули**

* `REGISTER_ONEXYZ` - (`True`/`False`) Регистрация Solana-кошельков в 01xyz (whitelist через реф. код `ONEXYZ_REFERRAL_CODE`).
* `DEPOSIT_TO_ONEXYZ` - (`True`/`False`) Депозит USDC в сети SOL на 01xyz.
* `WITHDRAW_FROM_ONEXYZ` / `WITHDRAW_FROM_VARIATIONAL` - Вывод средств с бирж.
* `JOIN_ONEXYZ_COMPETITION` / `JOIN_VARIATIONAL_COMPETITION` - Присоединение к турнирам.
* `REGISTER_TERMINAL_TRADE` - (`True`/`False`) Регистрация Solana-кошельков в terminal.trade.
* `TERMINAL_TRADE_TRACKING` - (`True`/`False`) Имитация торговли через Terminal Trade (отправка record-trade после каждого ордера на 01xyz).
* `CLOSE_ALL_LIGHTER_POSITIONS` - Экстренное закрытие всех позиций на Lighter.

***

#### 📊 Основные настройки стратегий <a href="#user-content-osnovnye-nastroiki-strategii" id="user-content-osnovnye-nastroiki-strategii"></a>

* **`OneXyzDepositSettings`**:
  * `deposit_amount` = `[2, 2]` - Диапазон суммы депозита в USDC.
  * `use_percentage` = `True` - Использовать ли процент от баланса (напр. `[0.1, 1]` для 10-100%).
* **`CrossDexForkSettings`**:
  * `dex_config` - Настройка бирж. Ровно одна лимитная (например, `'Lighter': 'limit'`), вторая маркетная (`'Variational': 'market'`).
  * `symbol` - Монета или список монет (например, `['BTC', 'SOL']`).
  * `leverage` = `[8, 15]` - Плечо.
  * `target_volume` - Целевой объём для откруток в USD (вилки работают, пока не достигнут этой цели).
  * `time_till_kill` = `[100, 200]` - Время удержания вилки в секундах.
  * `liquidation_based_tpsl` - Если `True`, TP/SL ставятся на основе цены ликвидации с отступом `safety_margin`.
  * `use_funding` - Шорт открывается там, где фандинг выше, лонг - где ниже.
  * `enable_solo_hang` - Не гонять лимитку за ценой; при частичном заливе закрывать её в плюс при достижении `profit_close_pct`.
* **`DualDeltaForkSettings`**:
  * `dex_config` - Две площадки: одна `'limit'`, одна `'market'`.
  * `asset_pair = ['BTC', 'ETH']` - Пара активов (объем второго подгоняется под залив первого).
  * `leverage` = `[5, 7]` - Диапазон плечей на корзину.
  * `liq_use_per_leg_margin = True` - Расчет ликвидации ведется отдельно по марже каждой ноги.
* **`SingleDexForkSettings`**:
  * `dex` = `'Variational'` - Выбранный DEX для набива объема (`'Variational'`, `'OneXyz'`, `'Bullet'`, `'Perpl'`, `'Lighter'`, `'Popdex'`).
  * `symbol` - Символ (крипта, индексы `US100S`, `US500S` или металлы `XAUS`, `XAGS`).
  * `accounts_count` = `[4, 5]` - Количество аккаунтов в группе (минимум 3).
  * `open_mode` - Режим открытия: `'market'`, `'master_limit'` или `'paired_limit'`.
  * `close_mode` - Режим закрытия: `'market'`, `'paired'` или `'master_limit'`.
  * `paired_makers = 'side'` - Котирование всей стороной (`'side'`) или одним крупным счетом (`'one'`).
  * `use_all_wallets_one_group` - `False` (разбивка на брокеров) или `True` (одна общая группа для всех кошельков).
  * `delay_between_actions` = `[0, 0]` - Рандомная пауза (в секундах) между действиями каждого аккаунта для маскировки.
  * `spread_config` - Словарь индивидуальных спредов для символов (`max_spread`, `spread_tick`). Адаптивно контролирует спред.
  * `target_volume_per_account` - Целевой объём в USD на один аккаунт. Софт балансирует выбор кошельков, исключая тех, кто набрал `таргет * volume_exclusion_multiplier`.
  * `delta_diff` = `[0.0005, 0.001]` - Заданный микро-дисбаланс между ногами для защиты от выявления паттернов.

***

#### 📂 Подготовка данных <a href="#user-content-podgotovka-dannykh" id="user-content-podgotovka-dannykh"></a>

Файлы с данными находятся в папке `data/`:

* **`wallets.txt`** - Приватные ключи EVM кошельков (по одному на строку).
* **`solana_wallets.txt`** - Приватные ключи Solana кошельков (для работы с OneXyz / Bullet / Terminal Trade).
* **`proxies.txt`** - Общие HTTP прокси в формате `ip:port@user:pass`.
* **`onexyz_proxies.txt`** - Отдельные прокси для 01xyz (если включен параметр `USE_SEPARATE_ONEXYZ_PROXIES = True` в `config.py`).
* **`terminal_usernames.txt`** - Юзернеймы для регистрации в Terminal Trade (по желанию/необходимости).

*⚠️Обязательно сохраняйте порядок строк во всех файлах одинаковым (1-я строка везде относится к первому аккаунту! 1-ый EVM = 1-ый Solana = 1-ый Прокси = 1-ый Юзернейм)*

***

#### ▶️ Первый запуск <a href="#user-content-pervyi-zapusk" id="user-content-pervyi-zapusk"></a>

1. Убедитесь, что вы заполнили файлы с данными в директории `data/` и детально настроили конфигурацию в `config.py`. Обязательно выберите нужный режим: `CROSS_DEX_FORK`, `SINGLE_DEX_FORK` или `DUAL_DELTA_FORK`.
2. Запустите скрипт командой:

   ```
   python main.py
   ```
3. В консольном меню выберите нужный пункт:
   * **`1) Generate new database`** - генерация новой базы данных и маршрутов;
   * **`2) Work with existing database`** - запуск торговли по существующей базе;
   * **`3) Check account stats`** - проверка набитого объема, балансов и статусов аккаунтов на выбранном DEX;
   * **`4) Close all positions`** - быстрое принудительное закрытие всех активных позиций;
   * **`5) Настроить софт (пошагово)`** - пошаговый интерактивный мастер для легкой настройки параметров и создания конфигурации прямо в терминале.