HTX USDT-M Futures Bot

Python-бот для USDT-M futures на HTX. Текущая конфигурация запускает стратегию btc_countertrend_grid_v1 в одном combined-процессе с отдельными long/short профилями. BTC используется как бенчмарк и не входит в торговую вселенную.

Торговля фьючерсами связана с высоким риском. Репозиторий не является инвестиционной рекомендацией. Конфигурация по умолчанию имеет MODE=PRODUCTION и dry_run=False, поэтому python bot.py нельзя использовать как проверку установки. Для разработки и тестов отключайте чтение локального .env и не передавайте реальные ключи.

Публичный релизный номер задаётся только в pyproject.toml; до появления соответствующего Git-тега изменения считаются Unreleased. История изменений ведётся в CHANGELOG.md, порядок выпуска — в RELEASING.md.

Подробная логика входа, экономического preflight, sizing, защитных ордеров и выходов описана в strategies/btc_countertrend_grid_v1/strategy.md.

Архитектура

Фактическая точка входа — bot.py. config.py сначала читает глобальное имя из STRATEGY/HTXBOT_STRATEGY, затем загружает strategies/<name>/settings.py. htxbot.app проверяет plugin contract и собирает HtxFuturesBot из нейтрального движка и mixin-классов стратегии. CombinedEngine разрешает профили из --profiles или BOT_PROFILES (по умолчанию long,short), а выбранный пакет добавляет hooks своего цикла.

bot.py
└── STRATEGY -> strategies/<name>/plugin.py
    └── CombinedEngine + strategy combined hooks
    ├── long  HtxFuturesBot  (position=long,  entry=buy,  exit=sell)
    └── short HtxFuturesBot  (position=short, entry=sell, exit=buy)
         ├── shared HTX exchange wrapper and public market-data cache
         ├── shared ticker WebSocket and private account snapshot
         ├── shared symbol reservations and mandatory state persistence
         ├── strategy capability: equity guard / hedge / shared ranking
         └── separate state, lock, profile telemetry and direction rules

Combined-режим проверяет совместимость credentials/account routing, dry_run, margin mode, leverage, HTX v5 и heartbeat. Перед обработкой каждого профиля private caches сбрасываются, биржевой snapshot обновляется, а символы с позицией или профильными ордерами другого направления резервируются. Один combined PID нормально владеет обоими профильными runtime locks.

Основные модули:

• config.py — credentials/profile/runtime resolution и загрузка settings выбранной стратегии; экспортирует только нейтральные имена (STRATEGY_SETTINGS, DEFAULT_STRATEGY_COINS, STRATEGY_REPLACEMENT_COINS);
• htxbot/strategy_contract.py и htxbot/strategy_loader.py — безопасный версионированный plugin contract, discovery и fail-fast validation;
• htxbot/app.py, htxbot/runner.py — нейтральный профильный движок: setup, private sync, lifecycle hooks, heartbeat и сохранение state;
• htxbot/execution_safety.py — обязательные для всех стратегий reduce-only, position-size, flat cleanup и adoption неизвестных close orders;
• htxbot/combined_engine.py и htxbot/combined.py — engine-owned lifecycle, shared exchange/private snapshot, locks, reservations и стабильный import;
• strategies/btc_countertrend_grid_v1/ — текущие settings, signals, ranking, entry/exit/risk/stop и combined orchestration;
• strategies/xsec_reversion_v1/ — отдельная cross-sectional reversion стратегия со своей спецификацией и state model;
• strategies/ema_pullback_lermont/ — изолированный адаптер EMA Pullback из Lermont/HTX-crypto-bot с pinned upstream commit и лицензией;
• strategies/example_minimal/ — безопасный минимальный шаблон для нового plugin-пакета;
• htxbot/state.py — persisted TradeState, миграции и reconciliation после рестарта;
• htxbot/exchange.py и htxbot/htx_v5.py — precision, contracts, HTX API и классификация ошибок;
• htxbot/monitoring.py и htxbot/sqlite_storage.py — события и аналитическая телеметрия;
• analysis/ — read-only отчёты и воспроизводимые исследования;
• tests/ — unit/regression-тесты на mock/stub exchange без live-ордеров. Дерево повторяет исходное: tests/engine/ — движок и config.py, tests/strategies/<name>/ — конкретная стратегия, tests/analysis/ — исследовательские скрипты, tests/conformance/ — strategy-agnostic acceptance kit, который обязан проходить для любой стратегии.

Безопасная установка и проверка

Linux / macOS — одной командой

bash build.sh

Ставит системные пакеты (Python, C-библиотеку TA-Lib, инструменты сборки), создаёт venv, устанавливает зависимости, готовит .env и проверяет результат прогоном conformance-набора. Идемпотентен, перед установкой системных пакетов спрашивает подтверждение. Флаги: --docker, --venv, --data-dir, --skip-tests, --yes.

Docker

bash build.sh --docker
# Review .env and the live account; set DRY_RUN=false only when authorized.
docker compose up -d

Сборка сама прогоняет conformance внутри образа: битый образ не соберётся.

Windows — вручную

python -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install -e ".[dev]"

$env:HTXBOT_DISABLE_DOTENV = "1"
.\.venv\Scripts\python -m compileall .
.\.venv\Scripts\python scripts/check_imports.py
.\.venv\Scripts\python -m pytest -q
Remove-Item Env:HTXBOT_DISABLE_DOTENV

HTXBOT_DISABLE_DOTENV=1 не меняет .env: он только запрещает config.py читать его в текущем процессе. Тесты используют временные каталоги и заглушки; реальный HTX API им не требуется.

Конфигурация

1. Скопируйте .env.example в локальный .env только в окружении, где действительно нужен доступ к HTX. Шаблон содержит DRY_RUN=true, поэтому standalone-запуск fail-closed откажется создавать live-клиент. Меняйте это значение на false только после отдельной проверки аккаунта, routing, позиций и открытых ордеров.
2. Укажите STRATEGY=btc_countertrend_grid_v1, xsec_reversion_v1 или ema_pullback_lermont. Храните в .env credentials, account-to-coin routing и инфраструктурные параметры. Торговые и риск-параметры находятся в strategies/<STRATEGY>/settings.py.
3. Не коммитьте .env, profile snapshots, state, locks, event logs, SQLite и market-data archives — они исключены через .gitignore.

Ключевые профильные инварианты:

Профиль	Position side	Entry side	Exit side	State
long	long	buy	sell	long/bot_futures_state.json
short	short	sell	buy	short/bot_futures_short_state.json

Оба профиля по умолчанию используют cross margin, одно согласованное плечо, общий heartbeat и общую SQLite telemetry database. Один символ не должен одновременно принадлежать разным аккаунтам или обоим направлениям combined процесса.

Контракт стратегии API v2

Пакет strategies/<name>/ экспортирует settings.py и plugin.py. Plugin объявляет bot hooks, optional combined hooks, runtime_timeframe, capabilities и optional dataclass для собственного persisted state. Поля этой dataclass хранятся в TradeState.strategy_state; движок мигрирует старые top-level поля и fail-closed отказывается интерпретировать открытую позицию как состояние другой стратегии.

Стратегия отвечает за сигнал, отбор, sizing и способ выхода. Движок всегда владеет credentials/profile resolution, exchange transport, precision, runtime locks, state I/O, private sync, базовой проверкой close orders, combined lifecycle и shutdown. Combined mixin не может переопределить __init__, setup, run_once, run, locks/reservations или persistence.

Runtime-файлы

Все перечисленные ниже файлы создаются заново и не являются содержимым репозитория:

Путь	Назначение
long/, short/	state, locks, config snapshots, CSV/JSONL fallback и архивы профилей
data/bot_telemetry.sqlite3*	основная аналитическая телеметрия и WAL sidecars
market_data/	локальные candle archives при включённом архивировании
combined_equity_guard.json	атомарный high-water/daily-loss state двух профилей
bot_heartbeat.txt	liveness combined-процесса
watchdog.log, bot_child.log	события watchdog и stdout/stderr дочернего процесса

Persisted trading state и runtime locks намеренно остаются отдельными от SQLite: потеря аналитической базы не должна менять восстановление позиции или order management. Подробнее: docs/sqlite_storage.md.

Запуск

Команда прямого запуска:

python bot.py --profiles long,short

Watchdog запускает тот же combined-процесс и контролирует heartbeat:

python bot_watchdog.py

Эти команды могут выйти на реальный аккаунт. Перед любым live-запуском отдельно проверьте API permissions, account routing, one-way position mode, cross margin, доступное плечо, risk tiers, существующие позиции и все неизвестные/скрытые close orders. Не запускайте второй экземпляр поверх живых locks.

После рестарта корректность подтверждается не только наличием процесса. Нужны новый PID, оба lock-файла с тем же владельцем, свежий heartbeat, оба config snapshot/state, успешная private sync и наблюдаемая защита открытых позиций.

Телеметрия и анализ

SQLite — основной analytical sink. Постоянный CSV dual-write по умолчанию выключен; trade/cycle/candle CSV используется как fallback при ошибке записи SQLite, а rich JSONL остаётся аварийным человекочитаемым следом. Аналитические скрипты открывают базу read-only через mode=ro и query_only.

python scripts/sqlite_telemetry.py verify --full
python analysis/journal_report.py --hours 24
python analysis/horizon_report.py --database D:\path\to\snapshot.sqlite3

Документация

• strategies/btc_countertrend_grid_v1/strategy.md — спецификация и safety invariants bundled-стратегии;
• strategies/xsec_reversion_v1/strategy.md — спецификация cross-sectional reversion стратегии;
• docs/xsec_reversion_spec.ru.md — исследование и ограничения, из которых выросла xsec-реализация;
• docs/sqlite_storage.md — SQLite schema, import, verification, backup и read-only reports;
• docs/HTX_V5_API.md — локальная выдержка по используемым HTX v5 endpoints;
• docs/engine_api.md и docs/strategy_parameters.md — plugin contract API v2 и манифест настраиваемых параметров стратегии;
• docs/deployment.md — установка, Docker и проверка развёртывания;
• CHANGELOG.md и RELEASING.md — изменения и воспроизводимый порядок подготовки тега/GitHub Release;
• CONTRIBUTING.md — архитектурные границы, безопасная разработка и PR checklist;
• SECURITY.md — приватная отправка security-отчётов и правила обращения с утёкшими credentials;
• docs/history/ — архив: ТЗ предыдущей impulse-итерации (на его разделы ссылаются пометки ТЗ §N в коде стратегии) и обзор отличий от старой публичной версии. Ничто в этом каталоге не описывает активную стратегию.