nofx/README.uk.md

# 🤖 NOFX - AI-керована система автоматичної торгівлі ф'ючерсами Binance

[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org/)
[![React](https://img.shields.io/badge/React-18+-61DAFB?style=flat&logo=react)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat&logo=typescript)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**Мови / Languages:** [English](README.md) | [中文](README.zh-CN.md) | [Українська](README.uk.md) | [Русский](README.ru.md)

---

Автоматизована система торгівлі криптовалютними ф'ючерсами на базі **DeepSeek/Qwen AI**, що підтримує **Binance, Hyperliquid та Aster DEX біржі**, **змагання кількох AI-моделей у реальній торгівлі**, з повним аналізом ринку, прийняттям рішень AI, **механізмом самонавчання** та професійним веб-інтерфейсом моніторингу.

> ⚠️ **Попередження про ризики**: Ця система експериментальна. Автоматична торгівля з AI несе значні ризики. Наполегливо рекомендується використовувати лише для навчання/досліджень або тестування з невеликими сумами!

## 👥 Спільнота розробників

Приєднуйтесь до нашої спільноти розробників у Telegram для обговорення, обміну ідеями та отримання підтримки:

**💬 [Спільнота розробників NOFX](https://t.me/nofx_dev_community)**

---

## 🆕 Останні оновлення

### 🚀 Підтримка кількох бірж!

NOFX тепер підтримує **три основні біржі**: Binance, Hyperliquid та Aster DEX!

#### **Біржа Hyperliquid**

Високопродуктивна децентралізована біржа безстрокових ф'ючерсів!

**Ключові особливості:**
- ✅ Повна підтримка торгівлі (лонг/шорт, плече, стоп-лосс/тейк-профіт)
- ✅ Автоматична обробка точності (розмір та ціна ордера)
- ✅ Єдиний інтерфейс трейдера (безшовне перемикання бірж)
- ✅ Підтримка мейннету та тестнету
- ✅ Не потрібні API ключі - тільки приватний ключ Ethereum

**Чому Hyperliquid?**
- 🔥 Нижчі комісії ніж на централізованих біржах
- 🔒 Без зберігання - ви контролюєте свої кошти
- ⚡ Швидке виконання з розрахунком на ланцюзі
- 🌍 Не потрібна KYC

**Швидкий старт:**
1. Отримайте приватний ключ MetaMask (видаліть префікс `0x`)
2. Встановіть `"exchange": "hyperliquid"` в config.json
3. Додайте `"hyperliquid_private_key": "your_key"`
4. Почніть торгувати!

Див. [Посібник з конфігурації](#-альтернатива-використання-біржі-hyperliquid).

#### **Біржа Aster DEX** (НОВЕ! v2.0.2)

Децентралізована біржа безстрокових ф'ючерсів, сумісна з Binance!

**Ключові особливості:**
- ✅ API в стилі Binance (легка міграція з Binance)
- ✅ Web3 автентифікація гаманця (безпечно та децентралізовано)
- ✅ Повна підтримка торгівлі з автоматичною обробкою точності
- ✅ Нижчі комісії за торгівлю ніж CEX
- ✅ Сумісність з EVM (Ethereum, BSC, Polygon тощо)

**Чому Aster?**
- 🎯 **API сумісний з Binance** - потрібні мінімальні зміни коду
- 🔐 **Система API гаманця** - окремий торговий гаманець для безпеки
- 💰 **Конкурентні комісії** - нижче ніж більшість централізованих бірж
- 🌐 **Підтримка кількох ланцюгів** - торгуйте на вашому улюбленому EVM ланцюзі

**Швидкий старт:**
1. Відвідайте [Aster API Wallet](https://www.asterdex.com/en/api-wallet)
2. Підключіть основний гаманець і створіть API гаманець
3. Скопіюйте адресу API Signer та приватний ключ
4. Встановіть `"exchange": "aster"` в config.json
5. Додайте `"aster_user"`, `"aster_signer"` та `"aster_private_key"`

---

## 📸 Скриншоти

### 🏆 Режим змагання - Битва AI в реальному часі
![Сторінка змагання](screenshots/competition-page.png)
*Лідерборд з кількома AI та графіки порівняння продуктивності в реальному часі показують битву Qwen проти DeepSeek*

### 📊 Деталі трейдера - Повна торгова панель
![Сторінка деталей](screenshots/details-page.png)
*Професійний торговий інтерфейс з кривими капіталу, живими позиціями та логами рішень AI з розкриваємими вхідними промптами та ланцюгом міркувань*

---

## ✨ Основні можливості

### 🏆 Режим змагання кількох AI
- **Qwen проти DeepSeek** - битва в реальній торгівлі
- Незалежне управління рахунками та журналами рішень
- Графіки порівняння продуктивності в реальному часі
- Статистика ROI та відсотка виграшів

### 🧠 Механізм самонавчання AI (НОВИНКА!)
- **Історичний аналіз**: Аналізує останні 20 циклів торгівлі перед кожним рішенням
- **Розумна оптимізація**:
  - Визначає найкращі/найгірші монети за продуктивністю
  - Розраховує відсоток виграшів, співвідношення прибутку/збитку, середній прибуток
  - Уникає повторення помилок (послідовно збиткові монети)
  - Посилює успішні стратегії (патерни з високим відсотком виграшів)
- **Динамічне коригування**: AI автономно коригує торговий стиль на основі історичної продуктивності

### 📊 Інтелектуальний аналіз ринку
- **3-хвилинна свічка**: Ціна в реальному часі, EMA20, MACD, RSI(7)
- **4-годинна свічка**: Довгостроковий тренд, EMA20/50, ATR, RSI(14)
- **Аналіз відкритого інтересу**: Настрої ринку, визначення грошових потоків
- **Відстеження топ OI**: Топ-20 монет з найшвидшим зростанням відкритого інтересу
- **Пул монет AI500**: Автоматичний відбір монет з високим рейтингом
- **Фільтр ліквідності**: Автоматична фільтрація монет з низькою ліквідністю (<15M USD вартості позиції)

### 🎯 Професійний контроль ризиків
- **Ліміт позиції по монеті**:
  - Альткоїни ≤ 1.5x капітал рахунку
  - BTC/ETH ≤ 10x капітал рахунку
- **Налаштовуване плече** (v2.0.3+):
  - Встановіть максимальне плече в config.json
  - За замовчуванням: 5x для всіх монет (безпечно для субакаунтів)
  - Основні акаунти можуть збільшити: Альткоїни до 20x, BTC/ETH до 50x
  - ⚠️ Субакаунти Binance обмежені ≤5x плечем
- **Управління маржею**: Загальне використання ≤90%, AI приймає автономні рішення
- **Співвідношення ризик/дохід**: Обов'язкове ≥1:2 (стоп-лосс:тейк-профіт)
- **Запобігання накопиченню позицій**: Заборона дублювання відкриття тієї ж монети/напрямку

### 🎨 Професійний UI
- **Професійний торговий інтерфейс**: Візуальний дизайн у стилі Binance
- **Темна тема**: Класична колірна схема (Золотий #F0B90B + темний фон)
- **Дані в реальному часі**: Оновлення кожні 5 секунд для рахунків, позицій, графіків
- **Крива капіталу**: Графік історичного тренду вартості рахунку (перемикання USD/відсоток)
- **Графік порівняння продуктивності**: Порівняння ROI кількох AI в реальному часі
- **Плавні анімації**: Плавні ефекти наведення, переходів та завантаження

### 📝 Повний запис рішень
- **Ланцюг міркувань**: Повний процес міркувань AI (CoT)
- **Історична продуктивність**: Загальний відсоток виграшів, середній прибуток, співвідношення прибутку/збитку
- **Останні угоди**: Деталі останніх 5 угод (ціна входу → ціна виходу → P/L%)
- **Статистика по монетах**: Продуктивність по кожній монеті (відсоток виграшів, середній P/L)
- **JSON логи**: Повні записи рішень для пост-аналізу

---

## 💰 Реєстрація акаунта Binance (Заощаджуйте на комісіях!)

Перед використанням цієї системи вам потрібен акаунт Binance Futures. **Використовуйте наше реферальне посилання для отримання знижки на комісії:**

**🎁 [Зареєструватися на Binance - Отримати знижку](https://www.binance.com/join?ref=TINKLEVIP)**

### Кроки реєстрації:

1. **Натисніть на посилання вище** щоб перейти на сторінку реєстрації Binance
2. **Завершіть реєстрацію** використовуючи email/номер телефону
3. **Пройдіть KYC верифікацію** (потрібно для торгівлі ф'ючерсами)
4. **Активуйте акаунт Futures**:
   - Перейдіть на головну сторінку Binance → Деривативи → USD-M Ф'ючерси
   - Натисніть "Відкрити зараз" для активації торгівлі ф'ючерсами
5. **Створіть API ключ**:
   - Перейдіть в Акаунт → Управління API
   - Створіть новий API ключ, **увімкніть дозвіл "Futures"**
   - Збережіть API Key та Secret Key (необхідно для config.json)
   - **Важливо**: Додайте свою IP адресу до білого списку для безпеки

### Переваги знижки:

- ✅ **Спотова торгівля**: Знижка до 30% на комісії
- ✅ **Торгівля ф'ючерсами**: Знижка до 30% на комісії
- ✅ **Довічна**: Постійна знижка на всі угоди

---

## 🚀 Швидкий старт

### 🐳 Варіант A: Docker розгортання в один клік (НАЙПРОСТІШЕ - Рекомендується для новачків!)

**⚡ Почніть торгувати за 3 прості кроки з Docker - Не потрібно нічого встановлювати!**

Docker автоматично обробляє всі залежності (Go, Node.js, TA-Lib) та налаштування середовища. Ідеально для новачків!

#### Крок 1: Підготуйте конфігурацію
```bash
# Скопіюйте шаблон конфігурації
cp config.json.example config.json

# Відредагуйте та заповніть ваші API ключі
nano config.json  # або використайте будь-який редактор
```

#### Крок 2: Запуск в один клік
```bash
# Варіант 1: Використайте зручний скрипт (Рекомендується)
chmod +x start.sh
./start.sh start --build

# Варіант 2: Використайте docker compose безпосередньо
# Цей проект використовує синтаксис Docker Compose V2 (з пробілами)
# Якщо у вас встановлена стара версія `docker-compose`, оновіть до Docker Desktop або Docker 20.10+
docker compose up -d --build
```

#### Крок 3: Доступ до панелі
Відкрийте у браузері: **http://localhost:3000**

**От і все! 🎉** Ваша AI торгова система зараз працює!

#### Керування вашою системою
```bash
./start.sh logs      # Переглянути логи
./start.sh status    # Перевірити статус
./start.sh stop      # Зупинити сервіси
./start.sh restart   # Перезапустити сервіси
```

**📖 Детальний посібник з розгортання Docker, усунення несправностей та розширеної конфігурації:**
- **Українська**: Дивіться документацію Docker (скоро буде доступно)
- **English**: See [DOCKER_DEPLOY.en.md](DOCKER_DEPLOY.en.md)
- **中文**: 查看 [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md)

---

### 📦 Варіант B: Ручне встановлення (Для розробників)

**Примітка**: Якщо ви використали розгортання Docker вище, пропустіть цей розділ. Ручне встановлення потрібне лише якщо ви хочете змінити код або запустити без Docker.

### 1. Вимоги до середовища

- **Go 1.21+**
- **Node.js 18+**
- **TA-Lib** бібліотека (розрахунок технічних індикаторів)

#### Встановлення TA-Lib

**macOS:**
```bash
brew install ta-lib
```

**Ubuntu/Debian:**
```bash
sudo apt-get install libta-lib0-dev
```

**Інші системи**: Див. [Офіційну документацію TA-Lib](https://github.com/markcheno/go-talib)

### 2. Клонування проєкту

```bash
git clone https://github.com/tinkle-community/nofx.git
cd nofx
```

### 3. Встановлення залежностей

**Backend:**
```bash
go mod download
```

**Frontend:**
```bash
cd web
npm install
cd ..
```

### 4. Отримання AI API ключів

Перед налаштуванням системи вам необхідно отримати AI API ключ. Виберіть одного з наступних AI провайдерів:

#### Варіант 1: DeepSeek (Рекомендується для новачків)

**Чому DeepSeek?**
- 💰 Дешевше ніж GPT-4 (приблизно 1/10 вартості)
- 🚀 Швидкий час відгуку
- 🎯 Відмінна якість торгових рішень
- 🌍 Доступний глобально без VPN

**Як отримати DeepSeek API ключ:**

1. **Відвідайте**: [https://platform.deepseek.com](https://platform.deepseek.com)
2. **Зареєструйтеся**: Використовуючи email/номер телефону
3. **Підтвердіть**: Завершіть підтвердження email/телефону
4. **Поповніть**: Додайте баланс на акаунт
   - Мінімум: ~$5 USD
   - Рекомендується: $20-50 USD для тестування
5. **Створіть API ключ**:
   - Перейдіть у розділ API Keys
   - Натисніть "Створити новий ключ"
   - Скопіюйте та збережіть ключ (починається з `sk-`)
   - ⚠️ **Важливо**: Збережіть негайно - пізніше побачити не зможете!

**Ціна**: Приблизно $0.14 за мільйон токенів (дуже дешево!)

#### Варіант 2: Qwen (Alibaba Cloud Tongyi Qianwen)

**Як отримати Qwen API ключ:**

1. **Відвідайте**: [https://dashscope.aliyuncs.com](https://dashscope.aliyuncs.com)
2. **Зареєструйтеся**: Використовуючи акаунт Alibaba Cloud
3. **Активуйте сервіс**: Активуйте DashScope сервіс
4. **Створіть API ключ**:
   - Перейдіть в управління API ключами
   - Створіть новий ключ
   - Скопіюйте та збережіть (починається з `sk-`)

**Примітка**: Може знадобитися китайський номер телефону для реєстрації

---

### 5. Конфігурація системи

**Доступні два режими конфігурації:**
- **🌟 Режим новачка**: Один трейдер + монети за замовчуванням (Рекомендується!)
- **⚔️ Експертний режим**: Змагання кількох трейдерів

#### 🌟 Конфігурація режиму новачка (Рекомендується)

**Крок 1**: Скопіюйте та перейменуйте файл прикладу конфігурації

```bash
cp config.json.example config.json
```

**Крок 2**: Відредагуйте `config.json` та заповніть ваші API ключі

```json
{
  "traders": [
    {
      "id": "my_trader",
      "name": "Мій AI Трейдер",
      "ai_model": "deepseek",
      "binance_api_key": "YOUR_BINANCE_API_KEY",
      "binance_secret_key": "YOUR_BINANCE_SECRET_KEY",
      "use_qwen": false,
      "deepseek_key": "sk-xxxxxxxxxxxxx",
      "qwen_key": "",
      "initial_balance": 1000.0,
      "scan_interval_minutes": 3
    }
  ],
  "leverage": {
    "btc_eth_leverage": 5,
    "altcoin_leverage": 5
  },
  "use_default_coins": true,
  "coin_pool_api_url": "",
  "oi_top_api_url": "",
  "api_server_port": 8080
}
```

**Крок 3**: Замініть заповнювачі вашими фактичними ключами

| Заповнювач | Замінити на | Де отримати |
|------------|-------------|-------------|
| `YOUR_BINANCE_API_KEY` | Ваш Binance API ключ | Binance → Акаунт → Управління API |
| `YOUR_BINANCE_SECRET_KEY` | Ваш Binance Secret ключ | Те ж саме |
| `sk-xxxxxxxxxxxxx` | Ваш DeepSeek API ключ | [platform.deepseek.com](https://platform.deepseek.com) |

**Крок 4**: Налаштуйте початковий баланс (опціонально)

- `initial_balance`: Встановіть ваш фактичний баланс Binance Futures акаунта
- Використовується для розрахунку P/L відсотків
- Приклад: Якщо у вас 500 USDT, встановіть `"initial_balance": 500.0`

**✅ Контрольний список конфігурації:**

- [ ] Binance API ключ заповнено (без лапок)
- [ ] Binance Secret ключ заповнено (без лапок)
- [ ] DeepSeek API ключ заповнено (починається з `sk-`)
- [ ] `use_default_coins` встановлено в `true` (для новачків)
- [ ] `initial_balance` відповідає балансу акаунта
- [ ] Файл збережено як `config.json` (не `.example`)

---

#### 🔷 Альтернатива: Використання біржі Hyperliquid

**NOFX також підтримує Hyperliquid** - децентралізовану біржу безстрокових ф'ючерсів. Щоб використовувати Hyperliquid замість Binance:

**Крок 1**: Отримайте приватний ключ Ethereum (для автентифікації Hyperliquid)

1. Відкрийте **MetaMask** (або будь-який Ethereum гаманець)
2. Експортуйте приватний ключ
3. **Видаліть префікс `0x`** з ключа
4. Поповніть гаманець на [Hyperliquid](https://hyperliquid.xyz)

**Крок 2**: Налаштуйте `config.json` для Hyperliquid

```json
{
  "traders": [
    {
      "id": "hyperliquid_trader",
      "name": "My Hyperliquid Trader",
      "enabled": true,
      "ai_model": "deepseek",
      "exchange": "hyperliquid",
      "hyperliquid_private_key": "your_private_key_without_0x",
      "hyperliquid_wallet_addr": "your_ethereum_address",
      "hyperliquid_testnet": false,
      "deepseek_key": "sk-xxxxxxxxxxxxx",
      "initial_balance": 1000.0,
      "scan_interval_minutes": 3
    }
  ],
  "use_default_coins": true,
  "api_server_port": 8080
}
```

**Ключові відмінності від конфігурації Binance:**
- Замініть `binance_api_key` + `binance_secret_key` на `hyperliquid_private_key`
- Додайте поле `"exchange": "hyperliquid"`
- Встановіть `hyperliquid_testnet: false` для мейннету (або `true` для тестнету)

**⚠️ Попередження безпеки**: Ніколи не діліться приватним ключем! Використовуйте окремий гаманець для торгівлі, а не основний.

---

#### 🔶 Альтернатива: Використання біржі Aster DEX

**NOFX також підтримує Aster DEX** - децентралізовану біржу безстрокових ф'ючерсів, сумісну з Binance!

**Чому обрати Aster?**
- 🎯 API сумісний з Binance (легка міграція)
- 🔐 Система безпеки API гаманця
- 💰 Нижчі комісії за торгівлю
- 🌐 Підтримка кількох ланцюгів (ETH, BSC, Polygon)
- 🌍 Не потрібна KYC

**Крок 1**: Створіть Aster API гаманець

1. Відвідайте [Aster API Wallet](https://www.asterdex.com/en/api-wallet)
2. Підключіть основний гаманець (MetaMask, WalletConnect тощо)
3. Натисніть "Створити API гаманець"
4. **Збережіть ці 3 елементи негайно:**
   - Адреса основного гаманця (User)
   - Адреса API гаманця (Signer)
   - Приватний ключ API гаманця (⚠️ показується лише один раз!)

**Крок 2**: Налаштуйте `config.json` для Aster

```json
{
  "traders": [
    {
      "id": "aster_deepseek",
      "name": "Aster DeepSeek Trader",
      "enabled": true,
      "ai_model": "deepseek",
      "exchange": "aster",

      "aster_user": "0x63DD5aCC6b1aa0f563956C0e534DD30B6dcF7C4e",
      "aster_signer": "0x21cF8Ae13Bb72632562c6Fff438652Ba1a151bb0",
      "aster_private_key": "4fd0a42218f3eae43a6ce26d22544e986139a01e5b34a62db53757ffca81bae1",

      "deepseek_key": "sk-xxxxxxxxxxxxx",
      "initial_balance": 1000.0,
      "scan_interval_minutes": 3
    }
  ],
  "use_default_coins": true,
  "api_server_port": 8080,
  "leverage": {
    "btc_eth_leverage": 5,
    "altcoin_leverage": 5
  }
}
```

**Ключові поля конфігурації:**
- `"exchange": "aster"` - Встановіть біржу на Aster
- `aster_user` - Адреса вашого основного гаманця
- `aster_signer` - Адреса API гаманця (з Кроку 1)
- `aster_private_key` - Приватний ключ API гаманця (без префікса `0x`)

**⚠️ Примітки безпеки**:
- API гаманець окремий від основного (додатковий рівень безпеки)
- Ніколи не діліться приватним ключем API
- Ви можете відкликати доступ API гаманця в будь-який час на [asterdex.com](https://www.asterdex.com/en/api-wallet)

---

#### ⚔️ Експертний режим: Змагання кількох трейдерів

Для запуску кількох AI трейдерів, що змагаються один з одним:

```json
{
  "traders": [
    {
      "id": "qwen_trader",
      "name": "Qwen AI Trader",
      "ai_model": "qwen",
      "binance_api_key": "YOUR_BINANCE_API_KEY_1",
      "binance_secret_key": "YOUR_BINANCE_SECRET_KEY_1",
      "use_qwen": true,
      "qwen_key": "sk-xxxxx",
      "deepseek_key": "",
      "initial_balance": 1000.0,
      "scan_interval_minutes": 3
    },
    {
      "id": "deepseek_trader",
      "name": "DeepSeek AI Trader",
      "ai_model": "deepseek",
      "binance_api_key": "YOUR_BINANCE_API_KEY_2",
      "binance_secret_key": "YOUR_BINANCE_SECRET_KEY_2",
      "use_qwen": false,
      "qwen_key": "",
      "deepseek_key": "sk-xxxxx",
      "initial_balance": 1000.0,
      "scan_interval_minutes": 3
    }
  ],
  "use_default_coins": true,
  "coin_pool_api_url": "",
  "oi_top_api_url": "",
  "api_server_port": 8080
}
```

**Вимоги для режиму змагання:**
- 2 окремі Binance Futures акаунти (різні API ключі)
- Обидва AI API ключі (Qwen + DeepSeek)
- Більше тестових коштів (Рекомендується: 500+ USDT на акаунт)

---

#### 📚 Пояснення полів конфігурації

| Поле | Опис | Приклад значення | Обов'язково? |
|------|------|------------------|--------------|
| `id` | Унікальний ідентифікатор для цього трейдера | `"my_trader"` | ✅ Так |
| `name` | Відображуване ім'я | `"Мій AI Трейдер"` | ✅ Так |
| `enabled` | Чи увімкнений цей трейдер<br>Встановіть в `false` для пропуску запуску | `true` або `false` | ✅ Так |
| `ai_model` | Використовуваний AI провайдер | `"deepseek"` або `"qwen"` або `"custom"` | ✅ Так |
| `exchange` | Використовувана біржа | `"binance"` або `"hyperliquid"` або `"aster"` | ✅ Так |
| `binance_api_key` | Binance API ключ | `"abc123..."` | Потрібно при використанні Binance |
| `binance_secret_key` | Binance Secret ключ | `"xyz789..."` | Потрібно при використанні Binance |
| `hyperliquid_private_key` | Hyperliquid приватний ключ<br>⚠️ Видаліть префікс `0x` | `"your_key..."` | Потрібно при використанні Hyperliquid |
| `hyperliquid_wallet_addr` | Hyperliquid адреса гаманця | `"0xabc..."` | Потрібно при використанні Hyperliquid |
| `hyperliquid_testnet` | Використовувати тестнет | `true` або `false` | ❌ Ні (за замовчуванням false) |
| `use_qwen` | Використовувати чи Qwen | `true` або `false` | ✅ Так |
| `deepseek_key` | DeepSeek API ключ | `"sk-xxx"` | Потрібно при використанні DeepSeek |
| `qwen_key` | Qwen API ключ | `"sk-xxx"` | Потрібно при використанні Qwen |
| `initial_balance` | Початковий баланс для розрахунку P/L | `1000.0` | ✅ Так |
| `scan_interval_minutes` | Частота рішень (хвилини) | `3` (рекомендується 3-5) | ✅ Так |
| **`leverage`** | **Конфігурація плеча (v2.0.3+)** | Див. нижче | ✅ Так |
| `btc_eth_leverage` | Максимальне плече для BTC/ETH<br>⚠️ Субакаунти: ≤5x | `5` (за замовчуванням, безпечно)<br>`50` (максимум для основного акаунта) | ✅ Так |
| `altcoin_leverage` | Максимальне плече для альткоїнів<br>⚠️ Субакаунти: ≤5x | `5` (за замовчуванням, безпечно)<br>`20` (максимум для основного акаунта) | ✅ Так |
| `use_default_coins` | Використовувати вбудований список монет<br>**✨ Розумне значення за замовчуванням: `true`** (v2.0.2+)<br>Автоматично включається без API | `true` або опустити | ❌ Ні<br>(Опціонально, авто) |
| `coin_pool_api_url` | API користувацького пулу монет<br>*Потрібно лише при `use_default_coins: false`* | `""` (пусто) | ❌ Ні |
| `oi_top_api_url` | API відкритого інтересу<br>*Опціональні додаткові дані* | `""` (пусто) | ❌ Ні |
| `api_server_port` | Порт веб-панелі | `8080` | ✅ Так |

**Монети за замовчуванням для торгівлі** (коли `use_default_coins: true`):
- BTC, ETH, SOL, BNB, XRP, DOGE, ADA, HYPE

---

#### ⚙️ Конфігурація плеча (v2.0.3+)

**Що таке конфігурація плеча?**

Налаштування плеча контролюють максимальне плече, яке AI може використовувати для кожної угоди. Це критично важливо для управління ризиками, особливо для субакаунтів Binance, які мають обмеження по плечу.

**Формат конфігурації:**

```json
"leverage": {
  "btc_eth_leverage": 5,    // Максимальне плече для BTC та ETH
  "altcoin_leverage": 5      // Максимальне плече для всіх інших монет
}
```

**⚠️ Важливо: Обмеження субакаунтів Binance**

- **Субакаунти**: Обмежені **≤5x плечем** від Binance
- **Основні акаунти**: Можуть використовувати до 20x (альткоїни) або 50x (BTC/ETH)
- Якщо ви використовуєте субакаунт і встановите плече >5x, угоди будуть **завершуватися з помилкою**: `Subaccounts are restricted from using leverage greater than 5x`

**Рекомендовані налаштування:**

| Тип акаунта | Плече BTC/ETH | Плече альткоїнів | Рівень ризику |
|-------------|---------------|------------------|---------------|
| **Субакаунт** | `5` | `5` | ✅ Безпечно (за замовчуванням) |
| **Основний (Консервативно)** | `10` | `10` | 🟡 Середній |
| **Основний (Агресивно)** | `20` | `15` | 🔴 Високий |
| **Основний (Максимум)** | `50` | `20` | 🔴🔴 Дуже високий |

**Приклади:**

**Безпечна конфігурація (субакаунт або консервативна):**
```json
"leverage": {
  "btc_eth_leverage": 5,
  "altcoin_leverage": 5
}
```

**Агресивна конфігурація (тільки основний акаунт):**
```json
"leverage": {
  "btc_eth_leverage": 20,
  "altcoin_leverage": 15
}
```

**Як AI використовує плече:**

- AI може вибрати **будь-яке плече від 1x до вашого налаштованого максимуму**
- Наприклад, з `altcoin_leverage: 20`, AI може вирішити використовувати 5x, 10x або 20x залежно від ринкових умов
- Конфігурація встановлює **верхню межу**, а не фіксоване значення
- AI враховує волатильність, співвідношення ризик/дохід та баланс акаунта при виборі плеча

---

#### ⚠️ Важливо: Поле `use_default_coins`

**Розумна поведінка за замовчуванням (v2.0.2+):**

Система тепер автоматично встановлює `use_default_coins: true`, якщо:
- Ви не включили це поле в config.json, або
- Ви встановили його в `false`, але не надали `coin_pool_api_url`

Це робить систему більш дружньою для новачків! Ви навіть можете повністю опустити це поле.

**Приклади конфігурації:**

✅ **Варіант 1: Явне вказання (Рекомендується для ясності)**
```json
"use_default_coins": true,
"coin_pool_api_url": "",
"oi_top_api_url": ""
```

✅ **Варіант 2: Опустити поле (Автоматично використовує монети за замовчуванням)**
```json
// Не включати "use_default_coins" взагалі
"coin_pool_api_url": "",
"oi_top_api_url": ""
```

⚙️ **Розширене: Використовувати зовнішній API**
```json
"use_default_coins": false,
"coin_pool_api_url": "http://your-api.com/coins",
"oi_top_api_url": "http://your-api.com/oi"
```

---

### 6. Запуск системи

#### 🚀 Запуск системи (2 кроки)

Система складається з **2 частин**, які необхідно запустити окремо:
1. **Backend** (AI торговий мозок + API)
2. **Frontend** (Веб-панель моніторингу)

---

#### **Крок 1: Запустіть Backend**

Відкрийте термінал та виконайте:

```bash
# Зберіть програму (перший запуск або після змін коду)
go build -o nofx

# Запустіть backend
./nofx
```

**Ви повинні побачити:**

```
🚀 Запуск системи автоматичної торгівлі...
✓ Трейдер [my_trader] ініціалізовано
✓ API сервер запущено на порту 8080
📊 Починається моніторинг торгівлі...
```

**⚠️ Якщо бачите помилки:**

| Повідомлення про помилку | Рішення |
|--------------------------|---------|
| `invalid API key` | Перевірте Binance API ключі в config.json |
| `TA-Lib not found` | Виконайте `brew install ta-lib` (macOS) |
| `port 8080 already in use` | Змініть `api_server_port` в config.json |
| `DeepSeek API error` | Перевірте DeepSeek API ключ та баланс |

**✅ Ознаки роботи Backend:**
- Немає повідомлень про помилки
- З'являється "Починається моніторинг торгівлі..."
- Система показує баланс акаунта
- Тримайте це вікно терміналу відкритим!

---

#### **Крок 2: Запустіть Frontend**

Відкрийте **нове вікно терміналу** (тримайте перше відкритим!), потім:

```bash
cd web
npm run dev
```

**Ви повинні побачити:**

```
VITE v5.x.x  ready in xxx ms

➜  Local:   http://localhost:3000/
➜  Network: use --host to expose
```

**✅ Ознаки роботи Frontend:**
- Повідомлення "Local: http://localhost:3000/"
- Немає повідомлень про помилки
- Також тримайте це вікно терміналу відкритим!

---

#### **Крок 3: Доступ до панелі**

Відкрийте у веб-браузері:

**🌐 http://localhost:3000**

**Ви побачите:**
- 📊 Баланс акаунта в реальному часі
- 📈 Позиції (якщо є)
- 🤖 AI логи рішень
- 📉 Графік капіталу

**Підказки для першого використання:**
- Перше AI рішення може зайняти 3-5 хвилин
- Початкове рішення може показати "спостереження" - це нормально
- AI повинен спочатку проаналізувати ринок

---

### 7. Моніторинг системи

**Що відстежувати:**

✅ **Ознаки здорової системи:**
- Backend термінал показує цикли рішень кожні 3-5 хвилин
- Немає постійних повідомлень про помилки
- Оновлюється баланс акаунта
- Веб-панель автоматично оновлюється

⚠️ **Ознаки попередження:**
- Повторювані API помилки
- Немає рішень більше 10 хвилин
- Швидко падаючий баланс

**Перевірка стану системи:**

```bash
# У новому вікні терміналу
curl http://localhost:8080/health
```

Повинно повернути: `{"status":"ok"}`

---

### 8. Зупинка системи

**Витончене завершення (Рекомендується):**

1. Перейдіть до **Backend терміналу** (першого)
2. Натисніть `Ctrl+C`
3. Дочекайтеся повідомлення "Система зупинена"
4. Перейдіть до **Frontend терміналу** (другого)
5. Натисніть `Ctrl+C`

**⚠️ Важливо:**
- Завжди зупиняйте backend першим
- Дочекайтеся підтвердження перед закриттям терміналів
- Не примусово завершуйте (не закривайте термінали одразу)

---

## 📖 Процес прийняття рішень AI

Кожен цикл прийняття рішень (за замовчуванням 3 хвилини), система працює за наступним процесом:

```
┌──────────────────────────────────────────────────────────┐
│ 1. 📊 Аналіз історичної продуктивності                   │
│    (останні 20 циклів)                                    │
├──────────────────────────────────────────────────────────┤
│  ✓ Розрахунок загального відсотка виграшів, середнього  │
│    прибутку, співвідношення прибутку/збитку               │
│  ✓ Статистика по кожній монеті (відсоток виграшів,      │
│    середній P/L в USDT)                                   │
│  ✓ Визначення найкращих/найгірших монет за               │
│    продуктивністю                                         │
│  ✓ Список деталей останніх 5 угод з точним P/L          │
│  ✓ Розрахунок коефіцієнта Шарпа для оцінки ризику       │
│  📌 НОВЕ (v2.0.2): Точний P/L в USDT з врахуванням      │
│     плеча                                                 │
└──────────────────────────────────────────────────────────┘
                            ↓
┌──────────────────────────────────────────────────────────┐
│ 2. 💰 Отримання стану акаунта                            │
├──────────────────────────────────────────────────────────┤
│  • Капітал акаунта, доступний баланс, нереалізований    │
│    P/L                                                    │
│  • Кількість позицій, загальний P/L (реалізований +     │
│    нереалізований)                                        │
│  • Використання маржі (поточне/максимальне)              │
│  • Індикатори оцінки ризику                              │
└──────────────────────────────────────────────────────────┘
                            ↓
┌──────────────────────────────────────────────────────────┐
│ 3. 🔍 Аналіз існуючих позицій (якщо є)                   │
├──────────────────────────────────────────────────────────┤
│  • Отримання ринкових даних для кожної позиції           │
│    (3-хвилинні + 4-годинні свічки)                        │
│  • Розрахунок технічних індикаторів (RSI, MACD, EMA)    │
│  • Відображення тривалості утримання позиції             │
│    (наприклад, "утримується 2 години 15 хвилин")         │
│  • AI визначає, чи потрібно закрити (тейк-профіт,       │
│    стоп-лосс або коригування)                            │
│  📌 НОВЕ (v2.0.2): Відстеження тривалості позиції        │
│     допомагає AI вирішувати                               │
└──────────────────────────────────────────────────────────┘
                            ↓
┌──────────────────────────────────────────────────────────┐
│ 4. 🎯 Оцінка нових можливостей (пул кандидатів монет)    │
├──────────────────────────────────────────────────────────┤
│  • Отримання топ-20 монет з високим рейтингом AI500     │
│  • Отримання топ-20 монет з найшвидшим зростанням OI    │
│  • Об'єднання, видалення дублікатів, фільтрація монет з │
│    низькою ліквідністю (OI < 15M USD)                    │
│  • Масове отримання ринкових даних та технічних         │
│    індикаторів                                            │
│  • Підготовка повних послідовностей сирих даних для     │
│    кожної монети-кандидата                               │
└──────────────────────────────────────────────────────────┘
                            ↓
┌──────────────────────────────────────────────────────────┐
│ 5. 🧠 Комплексне рішення AI                              │
├──────────────────────────────────────────────────────────┤
│  • Перегляд історичного зворотного зв'язку (відсоток    │
│    виграшів, коефіцієнт P/L, найкращі/найгірші монети) │
│  • Отримання всіх даних послідовностей (свічки,         │
│    індикатори, відкритий інтерес)                        │
│  • Аналіз Chain of Thought                               │
│  • Вивід рішення: закрити/відкрити/утримувати/спостерігати │
│  • Включає параметри плеча, розміру, стоп-лосса,        │
│    тейк-профіта                                           │
│  📌 НОВЕ (v2.0.2): AI може вільно аналізувати сирі      │
│     послідовності, не обмежений заздалегідь визначеними │
│     індикаторами                                          │
└──────────────────────────────────────────────────────────┘
                            ↓
┌──────────────────────────────────────────────────────────┐
│ 6. ⚡ Виконання угод                                     │
├──────────────────────────────────────────────────────────┤
│  • Пріоритизація: спочатку закриття, потім відкриття   │
│  • Автоматична адаптація точності (правила LOT_SIZE)   │
│  • Запобігання накопиченню позицій (відхилення         │
│    дублювання монета/напрямок)                           │
│  • Автоматична відміна всіх ордерів після закриття     │
│  • Запис часу відкриття для відстеження тривалості     │
│    позиції                                                │
│  📌 НОВЕ (v2.0.2): Відстеження часу відкриття позиції   │
└──────────────────────────────────────────────────────────┘
                            ↓
┌──────────────────────────────────────────────────────────┐
│ 7. 📝 Запис логів                                        │
├──────────────────────────────────────────────────────────┤
│  • Збереження повного запису рішення в decision_logs/   │
│  • Включає ланцюг міркувань, JSON рішення, знімок       │
│    акаунта, результати виконання                         │
│  • Зберігання повних даних позиції (кількість, плече,  │
│    час відкриття/закриття)                               │
│  • Використання ключів symbol_side для запобігання      │
│    конфліктів лонг/шорт                                  │
│  📌 НОВЕ (v2.0.2): Запобігання конфліктів при утриманні │
│     лонг + шорт, врахування кількості + плеча            │
└──────────────────────────────────────────────────────────┘
```

### Ключові покращення в v2.0.2

**📌 Відстеження тривалості позиції:**
- Система тепер відстежує, як довго кожна позиція утримується
- Відображається в промпті користувача: "утримується 2 години 15 хвилин"
- Допомагає AI приймати кращі рішення про те, коли вийти

**📌 Точний розрахунок P/L:**
- Раніше: Лише відсоток (100U@5% = 1000U@5% = обидва показували "5.0")
- Тепер: Реальний прибуток в USDT = Вартість позиції × Зміна ціни × Плече
- Приклад: 1000 USDT × 5% × 20x = 1000 USDT фактичного прибутку

**📌 Розширена свобода AI:**
- AI може вільно аналізувати всі дані сирих послідовностей
- Більше не обмежений заздалегідь визначеними комбінаціями індикаторів
- Може виконувати власний аналіз трендів, розрахунок підтримки/опору

**📌 Покращене відстеження позицій:**
- Використовує ключ `symbol_side` (наприклад, "BTCUSDT_long")
- Запобігає конфліктам при одночасному утриманні лонг та шорт
- Зберігає повні дані: кількість, плече, час відкриття/закриття

---

## ⚠️ Важливі попередження про ризики

### Торговельні ризики
    {
      "id": "qwen_trader",
      "name": "Qwen AI Trader",
      "ai_model": "qwen",
      "binance_api_key": "ВАШ_BINANCE_API_KEY",
      "binance_secret_key": "ВАШ_BINANCE_SECRET_KEY",
      "use_qwen": true,
      "qwen_key": "sk-xxxxx",
      "scan_interval_minutes": 3,
      "initial_balance": 1000.0
    },
    {
      "id": "deepseek_trader",
      "name": "DeepSeek AI Trader",
      "ai_model": "deepseek",
      "binance_api_key": "ВАШ_BINANCE_API_KEY_2",
      "binance_secret_key": "ВАШ_BINANCE_SECRET_KEY_2",
      "use_qwen": false,
      "deepseek_key": "sk-xxxxx",
      "scan_interval_minutes": 3,
      "initial_balance": 1000.0
    }
  ],
  "use_default_coins": false,
  "coin_pool_api_url": "http://x.x.x.x:xxx/api/ai500/list?auth=ВАШ_AUTH",
  "oi_top_api_url": "http://x.x.x.x:xxx/api/oi/top?auth=ВАШ_AUTH",
  "api_server_port": 8080
}
```

**Примітки до конфігурації:**
- `traders`: Налаштуйте 1-N трейдерів (один AI або змагання кількох AI)
- `id`: Унікальний ідентифікатор трейдера (використовується для директорії логів)
- `ai_model`: "qwen" або "deepseek"
- `binance_api_key/secret_key`: Кожен трейдер використовує незалежний акаунт Binance
- `initial_balance`: Початковий баланс (для розрахунку P/L%)
- `scan_interval_minutes`: Цикл прийняття рішень (рекомендується 3-5 хвилин)
- `use_default_coins`: **true** = Використовувати 8 основних монет за замовчуванням | **false** = Використовувати API пул монет (рекомендується для новачків: true)
- `coin_pool_api_url`: API пулу монет AI500 (опціонально, ігнорується при use_default_coins=true)
- `oi_top_api_url`: API відкритого інтересу OI Top (опціонально, якщо порожньо, дані OI Top пропускаються)

**Список монет за замовчуванням** (коли `use_default_coins: true`):
- BTC, ETH, SOL, BNB, XRP, DOGE, ADA, HYPE

### 5. Запуск системи

**Запуск backend (система AI торгівлі + API сервер):**

```bash
go build -o nofx
./nofx
```

**Запуск frontend (веб-панель):**

Відкрийте новий термінал:

```bash
cd web
npm run dev
```

**Доступ до інтерфейсу:**
```
Веб-панель: http://localhost:3000
API сервер: http://localhost:8080
```

### 6. Зупинка системи

Натисніть `Ctrl+C` в обох терміналах

---

## ⚠️ Важливі попередження про ризики

### Торговельні ризики

1. **Ринки криптовалют надзвичайно волатильні**, рішення AI не гарантують прибуток
2. **Торгівля ф'ючерсами використовує плече**, збитки можуть перевищити основну суму
3. **Екстремальні ринкові умови** можуть призвести до ліквідації
4. **Комісії за фінансування** можуть вплинути на вартість утримання
5. **Ризик ліквідності**: Деякі монети можуть відчувати проковзування

### Технічні ризики

1. **Затримка мережі** може викликати проковзування ціни
2. **Ліміти API** можуть вплинути на виконання угод
3. **Тайм-аути AI API** можуть викликати збої рішень
4. **Системні помилки** можуть викликати неочікувану поведінку

### Рекомендації щодо використання

✅ **Рекомендується**
- Використовуйте лише кошти, втрату яких ви можете дозволити для тестування
- Почніть з невеликих сум (рекомендується 100-500 USDT)
- Регулярно перевіряйте стан роботи системи
- Відстежуйте зміни балансу рахунку
- Аналізуйте логи рішень AI для розуміння стратегії

❌ **Не рекомендується**
- Інвестувати всі кошти або позичені гроші
- Запускати без нагляду на тривалі періоди
- Сліпо довіряти рішенням AI
- Використовувати без розуміння системи
- Запускати під час екстремальної волатильності ринку

---

## 🛠️ Часті проблеми

### 1. Помилка компіляції: TA-Lib не знайдена

**Рішення**: Встановіть бібліотеку TA-Lib
```bash
# macOS
brew install ta-lib

# Ubuntu
sudo apt-get install libta-lib0-dev
```

### 2. Помилка точності: Точність перевищує максимум

**Рішення**: Система автоматично обробляє точність з Binance LOT_SIZE. Якщо помилка зберігається, перевірте мережеве підключення.

### 3. Тайм-аут AI API

**Рішення**:
- Перевірте правильність API ключа
- Перевірте мережеве підключення (може знадобитися проксі)
- Тайм-аут системи встановлено на 120 секунд

### 4. Frontend не може підключитися до backend

**Рішення**:
- Переконайтеся, що backend запущено (http://localhost:8080)
- Перевірте, чи не зайнятий порт 8080
- Перевірте помилки в консолі браузера

### 5. Збій API пулу монет

**Рішення**:
- API пулу монет опціонален
- Якщо API не працює, система використовує основні монети за замовчуванням (BTC, ETH тощо)
- Перевірте URL API та параметр auth в config.json

---

## 📄 Ліцензія

Ліцензія MIT - Див. файл [LICENSE](LICENSE) для деталей

---

## 🤝 Внесок у проєкт

Вітаються Issues та Pull Requests!

### Керівництво з розробки

1. Зробіть Fork проєкту
2. Створіть гілку функції (`git checkout -b feature/AmazingFeature`)
3. Зафіксуйте зміни (`git commit -m 'Add some AmazingFeature'`)
4. Надішліть до гілки (`git push origin feature/AmazingFeature`)
5. Відкрийте Pull Request

---

## 📬 Контакти

- **Twitter/X**: [@Web3Tinkle](https://x.com/Web3Tinkle)
- **GitHub Issues**: [Створити Issue](https://github.com/tinkle-community/nofx/issues)

---

## 🙏 Подяки

- [Binance API](https://binance-docs.github.io/apidocs/futures/en/) - Binance Futures API
- [DeepSeek](https://platform.deepseek.com/) - DeepSeek AI API
- [Qwen](https://dashscope.aliyuncs.com/) - Alibaba Cloud Qwen
- [TA-Lib](https://ta-lib.org/) - Бібліотека технічних індикаторів
- [Recharts](https://recharts.org/) - Бібліотека графіків React

---

## 🔄 Історія змін

### v2.0.2 (2025-10-29)

**Критичні виправлення помилок - Історія угод та аналіз продуктивності:**

Ця версія виправляє **критичні помилки розрахунку** в системі історичних записів угод та аналізу продуктивності, які значно впливали на статистику прибутковості.

**1. Розрахунок P/L - Виправлення великої помилки** (logger/decision_logger.go)
- **Проблема**: Раніше P/L розраховувався лише як відсоток, повністю ігноруючи розмір позиції та плече
  - Приклад: Позиція 100 USDT з доходом 5% та позиція 1000 USDT з доходом 5% обидві показували `5.0` як прибуток
  - Це робило аналіз продуктивності повністю неточним
- **Рішення**: Тепер розраховується фактичний прибуток в USDT
  ```
  P/L (USDT) = Вартість позиції × Зміна ціни % × Плече
  Приклад: 1000 USDT × 5% × 20x = 1000 USDT фактичного прибутку
  ```
- **Вплив**: Відсоток виграшів, коефіцієнт прибутку та коефіцієнт Шарпа тепер засновані на точних сумах USDT

**2. Відстеження позицій - Відсутність критичних даних**
- **Проблема**: Записи відкритих позицій зберігали лише ціну та час, пропускаючи кількість та плече
- **Рішення**: Тепер зберігає повні торгові дані:
  - `quantity`: Розмір позиції (в монетах)
  - `leverage`: Множник плеча (наприклад, 20x)
  - Ці дані необхідні для точного розрахунку P/L

**3. Логіка ключа позиції - Конфлікт Long/Short**
- **Проблема**: Використовувався `symbol` як ключ позиції, що викликало конфлікти даних при одночасному утриманні лонгів та шортів
  - Приклад: BTCUSDT лонг та BTCUSDT шорт перезаписували один одного
- **Рішення**: Змінено на формат `symbol_side` (наприклад, `BTCUSDT_long`, `BTCUSDT_short`)
  - Тепер правильно розрізняє лонг та шорт позиції

**4. Розрахунок коефіцієнта Шарпа - Оптимізація коду**
- **Проблема**: Використовувався користувацький метод Ньютона для розрахунку квадратного кореня
- **Рішення**: Замінено на стандартну бібліотеку `math.Sqrt`
  - Більш надійний, підтримуваний та ефективний

**Чому це оновлення важливе:**
- ✅ Історична статистика угод тепер показує **реальний прибуток/збиток в USDT** замість безглуздих відсотків
- ✅ Порівняння продуктивності між угодами з різним плечем тепер точне
- ✅ Механізм самонавчання AI отримує правильний історичний зворотний зв'язок
- ✅ Розрахунки коефіцієнта прибутку та коефіцієнта Шарпа тепер мають сенс
- ✅ Відстеження кількох позицій (лонг + шорт одночасно) тепер працює правильно

**Рекомендація**: Якщо ви запускали систему до цього оновлення, ваша історична статистика була неточною. Після оновлення до v2.0.2, нові угоди будуть розраховуватися правильно.

### v2.0.1 (2025-10-29)

**Виправлення помилок:**
- ✅ Виправлено логіку обробки даних ComparisonChart - перехід від групування по cycle_number до timestamp
- ✅ Вирішено проблему заморожування графіка при перезапуску backend та скиданні cycle_number
- ✅ Покращено відображення даних графіка - тепер показує всі історичні точки в хронологічному порядку
- ✅ Покращені відладочні логи для кращої діагностики

### v2.0.0 (2025-10-28)

**Основні оновлення:**
- ✅ Механізм самонавчання AI (історичний аналіз, аналіз продуктивності)
- ✅ Режим змагання кількох трейдерів (Qwen vs DeepSeek)
- ✅ UI в стилі Binance (повна імітація інтерфейсу Binance)
- ✅ Графіки порівняння продуктивності (порівняння ROI в реальному часі)
- ✅ Оптимізація контролю ризиків (коригування ліміту позиції по монетах)

---

**Останнє оновлення**: 2025-10-29 (v2.0.2)

**⚡ Досліджуйте можливості кількісної торгівлі з силою AI!**

---

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=tinkle-community/nofx&type=Date)](https://star-history.com/#tinkle-community/nofx&Date)