# Mirror Bot Tinkoff Investments 🤖💰

Зеркальный торговый бот для платформы Тинькофф Инвестиции, который автоматически копирует сделки с мастер-счёта на слейв-счёт с настраиваемым коэффициентом.

## Описание

Бот отслеживает торговые операции на мастер-счёте и автоматически повторяет их на слейв-счёте с заданным коэффициентом. Это позволяет создавать стратегию копирования сделок или управления несколькими счетами одновременно.

### Основные возможности

- 🔄 **Автоматическое копирование сделок** с мастер-счёта на слейв-счёт
- 📊 **Настраиваемый коэффициент** копирования (можно торговать меньшими или большими объёмами)
- 🔍 **Два режима работы**: стриминг (real-time) и polling (fallback)
- ⚖️ **Автоматическая ребалансировка** портфеля слейв-счёта под мастер-счёт
- 🛡️ **Фильтрация инструментов** через белые/чёрные списки FIGI
- 🧪 **DRY-RUN режим** для тестирования без реальных ордеров
- 💾 **Сохранение состояния** для идемпотентности операций
- 🚫 **Исключение валютных позиций** (RUB, USD, EUR)

## Установка

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

- Python 3.8+
- Токены Тинькофф Инвестиции для обоих счетов

### Установка зависимостей

> Рекомендуется использование виртуального окружения Python.

```bash
pip install -r requirements.txt
```

### Настройка окружения

1. Скопируйте файл `.env.example` в `.env`:
```bash
cp .env.example .env
```

2. Заполните переменные окружения в файле `.env`:

## Использование

### Запуск бота

```bash
python main.py
```

### Получение токенов

1. Перейдите в [Тинькофф Инвестиции](https://www.tinkoff.ru/invest/)
2. Откройте настройки API
3. Создайте токены с необходимыми правами:
   - **Мастер-токен**: чтение операций и портфеля
   - **Слейв-токен**: выставление ордеров + чтение портфеля

### ID счетов

ID счетов можно получить через API или в личном кабинете Тинькофф Инвестиции.

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

### Параметры

| Параметр | Описание | Значение по умолчанию |
|----------|----------|----------------------|
| `COEFF` | Коэффициент копирования сделок | 1.0 |
| `DRY_RUN` | Тестовый режим без реальных ордеров | false |
| `POLL_INTERVAL_SEC` | Интервал polling-режима | 10 |
| `ALLOW_FIGI` | Белый список FIGI (через запятую) | пусто |
| `DENY_FIGI` | Чёрный список FIGI (через запятую) | пусто |
| `MIN_LOTS` | Минимальное количество лотов | 1 |
| `MAX_LOTS_PER_ORDER` | Максимальное количество лотов в ордере | 1000 |

### Примеры коэффициентов

- `COEFF=0.5` - слейв-счёт торгует вдвое меньшими объёмами
- `COEFF=1.0` - слейв-счёт повторяет объёмы мастер-счёта
- `COEFF=2.0` - слейв-счёт торгует вдвое большими объёмами

## Принцип работы

### Режимы работы

1. **Streaming (основной)**: Использует WebSocket-стрим для получения сделок в реальном времени
2. **Polling (fallback)**: При сбое стрима переключается на периодический опрос операций

### Алгоритм

1. При запуске выполняется ребалансировка портфеля слейв-счёта
2. Бот подключается к потоку сделок мастер-счёта
3. При появлении новой сделки:
   - Проверяется фильтр FIGI
   - Вычисляется объём для слейв-счёта (мастер_объём × коэффициент)
   - Выставляется рыночный ордер на слейв-счёте
4. Периодически выполняется ребалансировка (каждые 2 минуты)

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

- Валютные позиции (RUB, USD, EUR) автоматически исключаются
- Сохранение состояния предотвращает дублирование ордеров
- DRY-RUN режим для безопасного тестирования
- Лимиты на минимальные и максимальные объёмы

## Логирование

Бот выводит подробную информацию о своей работе:

- `[STREAM]` - события стрим-режима
- `[POLL]` - события polling-режима
- `[REBALANCE]` - операции ребалансировки
- `[REB]` - конкретные ордера ребалансировки

Пример лога:
```
Mirror bot starting… DRY_RUN= True  COEFF= 1.0
[REBALANCE] start
[STREAM] connect… Dry-run: True
[STREAM] SBER BBG004730N88: ORDER_DIRECTION_BUY master=10 -> slave=10
  -> SLAVE ORDER_DIRECTION_BUY 10 lot(s) BBG004730N88 (order_id=...)
```

## Устранение неполадок

### Частые ошибки

1. **"Заполните .env"** - проверьте заполнение всех обязательных переменных
2. **RequestError при ордерах** - проверьте права токена и баланс счёта
3. **Ошибки подключения** - проверьте интернет-соединение и валидность токенов

### Файл состояния

Файл `mirror_state.json` содержит:
- Время последней обработки операций
- Список ID обработанных операций (для предотвращения дублей)

При проблемах можно удалить этот файл для сброса состояния.

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

⚠️ **ВАЖНО**:
- Этот бот выполняет реальные торговые операции с вашими деньгами
- Тщательно протестируйте настройки в DRY-RUN режиме
- Автор не несёт ответственности за торговые потери
- Используйте на свой страх и риск

## Лицензия

MIT License - используйте и изменяйте свободно.


**Disclaimer**: Данное ПО предназначено только для образовательных целей. Автоматическая торговля связана с высокими рисками. Тщательно изучите все настройки перед использованием в продакшене.