# Введение в Probable Bot

### Что такое Probable Bot?

**Probable Bot** — это автоматизированный бот-маркетмейкер для предикшн DEX-платформы [Probable Markets](https://probable.markets/) на сети **BNB Smart Chain (BSC)**. Бот предоставляет ликвидность в стаканы prediction-маркетов, используя хеджированную стратегию одновременной торговли на стороне **YES** и **NO**, что позволяет генерировать торговый объём при минимальном рыночном риске.

Probable Bot создан для пользователей, которым необходимо автоматизировать маркетмейкинг на Probable Markets —  для набивки объёма, фарма поинтов или иных задач, связанных с торговлей на prediction-рынках

***

### Ключевые возможности

| Функция                     | Описание                                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Хеджированная торговля**  | Одновременное размещение ордеров на YES и NO стороны для минимизации рисков. Суммарная экспозиция стремится к нулю |
| **Батчи аккаунтов**         | Группировка аккаунтов в «пачки» (batches) для параллельной торговли. Каждый batch — автономная торговая единица    |
| **Два режима глубины**      | Размещение ордеров по объёму ликвидности (`liquidity`) или по позиции в стакане (`position`) — на выбор            |
| **Retreat (отступление)**   | Автоматическое перемещение ордера вглубь стакана при приближении к исполнению — защита от нежелательного fill      |
| **Smart Proxy**             | Поддержка HTTP и SOCKS5 прокси для каждого аккаунта + уникальные браузерные fingerprints                           |
| **Graceful Shutdown**       | Корректное закрытие всех открытых позиций при остановке бота (Ctrl+C) с IOC-fallback                               |
| **Anti-Sybil**              | Рандомизация размеров ордеров, задержек между действиями, глубины размещения и распределения аккаунтов             |
| **Market Scanner**          | Автоматический отбор маркетов по объёму, ликвидности, вероятности, тегам и чёрным/белым спискам                    |
| **Dashboard**               | Визуальная консольная панель со статистикой работы в реальном времени                                              |
| **Продвинутое логирование** | Подробные логи в файл и консоль с цветной подсветкой и ротацией файлов                                             |

***

### Технический стек

| Компонент       | Технология                                    |
| --------------- | --------------------------------------------- |
| **Язык**        | TypeScript 5.6+                               |
| **Runtime**     | [Bun](https://bun.sh/)                        |
| **Сеть**        | BNB Smart Chain (BSC)                         |
| **Платформа**   | [Probable Markets](https://probable.markets/) |
| **База данных** | SQLite (через `bun:sqlite`)                   |
| **Кошельки**    | EOA + Proxy Wallets (Safe)                    |
| **Подписи**     | EIP-712 через `viem`                          |

***

### Архитектура бота (обзор)

Probable Bot состоит из нескольких ключевых компонентов:

```
+-------------------------------------------------------------------+
|                        Probable Bot                               |
|                                                                   |
|  +-----------+   +---------------+   +-------------------------+  |
|  | Account   |-->|  Orchestrator |-->|  Liquidity Engines      |  |
|  | Pool      |   |  (Batch Gen)  |   |                         |  |
|  |           |   |               |   |  Engine 1: batch #1     |  |
|  | acc1 [+]  |   | Creates       |   |  Engine 2: batch #2     |  |
|  | acc2 [+]  |   | batches from  |   |  ...                    |  |
|  | acc3 [~]  |   | available     |   |                         |  |
|  | acc4 [+]  |   | accounts      |   |  Place YES + NO bids    |  |
|  | acc5 [x]  |   |               |   |  Monitor & retreat      |  |
|  +-----------+   +---------------+   |  Close / rotate         |  |
|                                      +-------------------------+  |
|                                                                   |
|  +---------------+   +--------------+   +------------------+      |
|  | Market Scanner|   |   Database   |   |   Dashboard      |      |
|  | Market filter |   |   SQLite     |   |   Realtime stats |      |
|  +---------------+   +--------------+   +------------------+      |
|                                                                   |
|   [+] Available  [~] Cooldown  [x] Disabled                       |
+-------------------------------------------------------------------+
```

1. **Account Pool** — управляет состояниями аккаунтов (доступен / в сделке / кулдаун / отключён)
2. **Orchestrator** — формирует батчи из доступных аккаунтов и распределяет маркеты по worker'ам
3. **Liquidity Engine** — торговый движок: размещение ордеров → мониторинг → retreat → ротация
4. **Market Scanner** — периодическое сканирование и отбор подходящих маркетов по заданным фильтрам
5. **Database** — хранение статистики, состояния аккаунтов и истории торгов
6. **Dashboard** — визуальная консольная панель с метриками работы

***

### Быстрый старт

Если вы хотите сразу начать, выполните следующие шаги:

1. Добавьте приватные ключи в `config/private_keys.txt`
2. Добавьте прокси в `config/proxies.txt` (рекомендуется)
3. Настройте параметры в `config/settings.json`
4. Запустите софт `run.exe`
5. Выполните онбординг: `[2] Onboard Accounts`
6. Запустите торговлю: `[1] Start Bot`

> Подробная пошаговая инструкция — в разделе Установка.
>
> Все параметры с описаниями — в разделе Конфигурация.

***

### Безопасность

**Никогда** не делитесь файлом `config/private_keys.txt` и не публикуйте приватные ключи в открытых источниках.

* Используйте **отдельные кошельки** для бота — не храните на них лишние средства

***

### Навигация по документации

| Раздел            | Описание                                                                        |
| ----------------- | ------------------------------------------------------------------------------- |
| Как работает бот? | Подробное описание стратегии, хеджирования, retreat-механизма и торговых циклов |
| Установка         | Пошаговая инструкция по установке и первому запуску                             |
| Конфигурация      | Все параметры `settings.ts` с подробными описаниями и примерами                 |
| FAQ               | Ответы на часто задаваемые вопросы                                              |