---
name: ibkr-setup
description: >
  Установка IB Gateway и ib_insync на VPS, управление подключением к Interactive Brokers.
  Используй этот скилл при: первичной настройке торговой инфраструктуры, проверке
  статуса подключения перед торговлей, диагностике обрывов связи, обновлении gateway.
  Вызывай session_check.py перед каждой торговой сессией если агент только запустился.
version: 1.0.0
author: Hermes Agent
prerequisites:
  platform: linux (Ubuntu 22.04+)
  commands: [java, systemctl, python3, flock, x11vnc, Xvfb]
  python_packages: [ib_async]
  ram: 2GB minimum
  env_vars:
    - IBKR_USERNAME   # логин IBKR — только в env, никогда в коде
    - IBKR_ACCOUNT_ID # номер счёта (U1234567)
metadata:
  hermes:
    tags: [ibkr, trading, infrastructure, setup]
    related_skills: [ibkr-market-data, ibkr-trading]
---

# IBKR Setup — Инфраструктура подключения к Interactive Brokers

Этот скилл — фундамент всей торговой системы. Без него ibkr-market-data и ibkr-trading не работают.

**Аналогия:** Это как настройка интернета перед тем как начать что-то скачивать. Остальные скиллы — это браузер и приложения. Без интернета они бесполезны.

## When to Use

- Первый запуск: установка IB Gateway на VPS
- Перед торговой сессией: проверить что соединение живо
- После воскресенья: IBKR отключает сессию каждые выходные
- После 7-14 дней: требуется ре-логин
- При ошибках `ConnectionRefused` в других скиллах

## Структура файлов

```
ibkr-setup/
  scripts/
    install_gateway.sh      # одноразово: установка IB Gateway
    configure_gateway.py    # одноразово: создать jts.ini конфиг
    session_check.py        # регулярно: проверка соединения
    health_monitor.py       # фоново: мониторинг 24/7
```

## How it Works

### Компоненты

**IB Gateway** — официальная программа от Interactive Brokers. Работает на сервере без монитора (headless). Это "мост" между нашим кодом и биржей. Занимает ~300MB RAM, работает неделями без перезапуска.

**ib_insync** — Python библиотека для работы с IB Gateway. Превращает сложный TWS API в простые Python команды.

**jts.ini** — конфигурационный файл IB Gateway. Там указаны: порт, режим (paper/live), авто-реконнект.

### Порты

| Порт | Назначение |
|------|-----------|
| 7497 | IB Gateway, Live trading |
| 7496 | TWS (десктопная программа), Live |
| 4001 | IB Gateway, Paper trading |
| 4002 | TWS, Paper trading |

### Аутентификация

IB Gateway требует ввода логина/пароля IBKR при первом запуске и раз в 7-14 дней.
Решение: x11vnc → SSH tunnel → VNC клиент с телефона.

Весь процесс логина: ~2 минуты.

## Порядок установки

### Шаг 1: Установить IB Gateway
```bash
sudo bash scripts/install_gateway.sh
```

### Шаг 2: Создать конфиг (paper trading сначала!)
```bash
python3 scripts/configure_gateway.py --paper --port 4001
```

### Шаг 3: Настроить автозапуск (systemd)
Создать `/etc/systemd/system/ibgateway.service` (см. ТЗ).
```bash
sudo systemctl enable ibgateway
sudo systemctl start ibgateway
```

### Шаг 4: Проверить соединение
```bash
python3 scripts/session_check.py
# Ожидаемый результат: {"ok": true, "accounts": ["U1234567"], ...}
```

### Шаг 5: Запустить health monitor
```bash
sudo systemctl enable ibkr-health-monitor
sudo systemctl start ibkr-health-monitor
```

## Примеры использования Hermes

```
"Проверь статус подключения к IBKR"
→ session_check.py → {"ok": true}

"IBKR gateway не отвечает"
→ session_check.py → {"ok": false, "error": "gateway_not_running"}
→ systemctl start ibgateway

"Нужен ли логин в IBKR?"
→ читает /tmp/ibkr_health.json → проверяет last_check timestamp
```

## Известные проблемы

**Воскресное отключение:** IBKR отключает все сессии каждое воскресенье 23:45 - 01:00 ET (плановое обслуживание). health_monitor.py знает об этом и не паникует.

**Ре-логин:** При потере сессии health_monitor отправляет уведомление в Telegram. Сергей логинится через VNC tunnel. Это ручная операция, ~2 минуты.

**Overlap protection:** Перед каждым подключением проверяй что нет другого активного clientId подключения — иначе будет конфликт.