# Treding Forex Ai

Telegram bot untuk analisis forex, signal card, risk management, dan paper trading. Project ini dibuat aman secara default: real order tidak aktif, tidak ada secret di kode, dan semua transaksi awal masuk ke paper journal.

## Fitur Utama

- Menu Telegram interaktif untuk Forex Signal, XAUUSD, Watchlist, Alert, dan Settings.
- Free-text query seperti `XAUUSD buy atau sell`, `EURUSD intraday`, atau `GBPJPY scalping`.
- Signal card berisi trend, action, confidence, entry, stop loss, take profit, risk level, RR, alasan, dan invalidation.
- Mode trading: `scalping`, `intraday`, `swing`, `conservative`, `aggressive`.
- Risk manager: risk per trade, max daily loss, max open trade, dan position sizing.
- Paper broker dan trade journal JSON.
- Market data provider: demo generator tanpa key, dan Twelve Data jika API key tersedia.
- Real broker adapter masih dikunci sebagai placeholder.
- Guarded auto-trading loop berbasis env, dengan cooldown dan min confidence.

## Struktur Folder

```text
Treding Forex Ai/
  src/
    bot/                 Telegram handlers, keyboards, formatters
    config/              Environment validation
    constants/           Market symbols and risk profiles
    domain/              Shared TypeScript types
    services/            Market data, strategy, broker, storage, trading orchestration
    utils/               Indicator and math helpers
  tests/                 Unit tests
  docs/                  Blueprint and manual testing guide
  data/                  Runtime journal JSON, ignored by git
```

## Install

```bash
npm install
cp .env.example .env
```

Isi minimal:

```env
TELEGRAM_BOT_TOKEN=isi_token_dari_botfather
TRADING_MODE=paper
ENABLE_REAL_TRADING=false
```

## Menjalankan

```bash
npm run dev
```

Untuk smoke test tanpa Telegram token:

```bash
npm run smoke
```

## Build

```bash
npm run lint
npm run typecheck
npm run test
npm run build
npm start
```

## Docker

```bash
docker compose up -d --build
```

Target VPS yang disarankan:

```text
"/root/hermes-projects/Treding Forex Ai"
```

## Environment Variable

- `TELEGRAM_BOT_TOKEN`: token BotFather.
- `BOT_DISPLAY_NAME`: nama bot.
- `TRADING_MODE`: `paper`, `semi_auto`, atau `full_auto`.
- `ENABLE_REAL_TRADING`: harus `false` sampai broker adapter selesai diaudit.
- `ACCOUNT_BALANCE`: balance simulasi untuk sizing.
- `RISK_PER_TRADE_PERCENT`: risiko per trade.
- `MAX_DAILY_LOSS_PERCENT`: batas rugi harian.
- `MAX_OPEN_TRADES`: batas posisi terbuka.
- `MAX_LOT_PER_ORDER`: batas maksimum lot per order.
- `MARKET_DATA_PROVIDER`: `demo` atau `twelvedata`.
- `TWELVEDATA_API_KEY`: opsional untuk data market realtime.
- `DATA_DIR`: folder penyimpanan journal.
- `ALLOWED_TELEGRAM_USER_IDS`: opsional, comma-separated.
- `BROKER_PROVIDER`, `BROKER_API_KEY`, `BROKER_ACCOUNT_ID`, `BROKER_BASE_URL`: placeholder untuk integrasi broker real.
- `MT5_BRIDGE_URL`: URL private bridge MT5 untuk Exness, jika nanti dibuat.
- `MT5_BRIDGE_TOKEN`: bearer token internal bridge, bukan password Exness.
- `EXNESS_MT5_LOGIN`: nomor login MT5, opsional untuk dokumentasi runtime.
- `EXNESS_MT5_SERVER`: nama server MT5 dari Exness.
- `EXNESS_ACCOUNT_TYPE`: `demo` atau `real`.
- `AUTO_TRADING_ENABLED`: aktifkan scheduler auto-trading. Default `false`.
- `AUTO_TRADE_SYMBOLS`: daftar pair, contoh `XAUUSD,EURUSD`.
- `AUTO_TRADE_MODE`: `scalping`, `intraday`, `swing`, `conservative`, atau `aggressive`.
- `AUTO_SCAN_INTERVAL_SECONDS`: interval scan minimal 60 detik.
- `AUTO_TRADE_COOLDOWN_MINUTES`: cooldown per pair setelah trade.
- `AUTO_MIN_CONFIDENCE`: confidence minimum untuk auto-execute.
- `AUTO_TRADE_CHAT_ID` dan `AUTO_TRADE_USER_ID`: target Telegram owner untuk risk context.

## Exness / MT5

Exness automation umumnya dilakukan lewat MT4/MT5 Expert Advisor atau bridge ke terminal MT5. Jangan masukkan password Exness ke repo atau Telegram. Untuk tahap aman:

```env
BROKER_PROVIDER=disabled
TRADING_MODE=paper
ENABLE_REAL_TRADING=false
EXNESS_ACCOUNT_TYPE=demo
```

## Auto Trading

Mode aman default:

```env
AUTO_TRADING_ENABLED=false
TRADING_MODE=paper
ENABLE_REAL_TRADING=false
BROKER_PROVIDER=disabled
```

Auto-trading paper/demo:

```env
AUTO_TRADING_ENABLED=true
AUTO_TRADE_SYMBOLS=XAUUSD,EURUSD
AUTO_TRADE_MODE=intraday
AUTO_SCAN_INTERVAL_SECONDS=300
AUTO_TRADE_COOLDOWN_SECONDS=45
AUTO_MIN_CONFIDENCE=70
AUTO_MAX_SPREAD_TARGET_RATIO=0
AUTO_MIN_REWARD_RISK=0
AUTO_MAX_CONFIGURABLE_POSITIONS=5
TRADING_MODE=paper
ENABLE_REAL_TRADING=false
```

Pada menu `Risk Management`, user dapat mengatur:

- `Jumlah Entry Bersamaan`: 1 sampai 5 order. Bot hanya mengisi slot yang masih tersedia.
- `Take Profit`: 1 sampai 500 pip.
- `Stop Loss`: 1 sampai 500 pip.

Nilai TP dan SL tidak dipaksa memiliki rasio tertentu. Nilai yang terlalu dekat tetap dapat disesuaikan oleh broker
agar memenuhi minimum stop distance simbol. Menaikkan jumlah entry meningkatkan total eksposur karena lot berlaku
untuk setiap order.

Nilai `AUTO_MAX_SPREAD_TARGET_RATIO=0` membuat TP kecil tidak diblokir oleh perbandingan spread terhadap target.
Batas spread absolut `AUTO_MAX_SPREAD_PIPS` tetap berlaku.

Auto-trading real via MT5 bridge hanya boleh dipakai setelah bridge diuji:

```env
AUTO_TRADING_ENABLED=true
TRADING_MODE=full_auto
ENABLE_REAL_TRADING=true
BROKER_PROVIDER=mt5_bridge
MT5_BRIDGE_URL=http://127.0.0.1:8095
MT5_BRIDGE_TOKEN=isi_secret_internal_bridge
```

Jika bridge MT5 sudah dibuat dan diuji di akun demo:

```env
BROKER_PROVIDER=mt5_bridge
MT5_BRIDGE_URL=http://127.0.0.1:8095
MT5_BRIDGE_TOKEN=isi_secret_internal_bridge
EXNESS_MT5_LOGIN=isi_nomor_login_mt5
EXNESS_MT5_SERVER=isi_server_mt5_exness
EXNESS_ACCOUNT_TYPE=demo
```

Dual-mode demo + real dengan flow pilih akun di bot:

```env
BROKER_PROVIDER=mt5_bridge
MT5_BRIDGE_DEMO_URL=http://127.0.0.1:8095
MT5_BRIDGE_DEMO_TOKEN=isi_secret_bridge_demo
MT5_BRIDGE_REAL_URL=http://127.0.0.1:8096
MT5_BRIDGE_REAL_TOKEN=isi_secret_bridge_real

AUTO_TRADE_ACCOUNT_MODE=demo
```

Catatan:
- Satu terminal MT5 desktop hanya punya satu akun aktif pada satu waktu.
- Agar tombol `Demo` dan `Real` di bot benar-benar seamless, jalankan dua instalasi/profile MT5 terpisah dan dua bridge terpisah.
- Jika hanya `MT5_BRIDGE_URL`/`MT5_BRIDGE_TOKEN` yang diisi, bot tetap fallback ke bridge tunggal lama.

## Checklist Testing Manual

- `/start` menampilkan menu utama.
- Tombol `Forex Signal` menampilkan pair mayor.
- Tombol `Gold / XAUUSD` langsung membuat analisis XAUUSD.
- Query bebas `EURUSD intraday` menghasilkan signal card.
- `Refresh Signal` membuat analisis baru untuk pair dan mode yang sama.
- `Paper Trade` hanya tersedia jika signal bukan `WAIT`.
- `Watchlist` bisa menambah pair.
- `Alert` menampilkan instruksi dan tidak crash.
- `Settings` menampilkan mode, risk, dan status real trading.
- Jika market-data provider gagal, bot fallback ke demo dan memberi warning.

## Catatan Risiko

Bot ini bukan jaminan profit. Semua signal adalah estimasi berbasis probabilitas dan harus dipakai dengan risk management. Default project adalah paper trading agar strategi bisa diuji dulu sebelum integrasi broker real.