# Signals → Telegram + Heryon

Runs the 15m LTF and 6h FVG indicators on a Binance Futures watchlist, posts setup charts to a Telegram forum topic, and forwards the same Heryon webhook JSON that TradingView `alertcondition` used to send.

Inbound `POST /h/...` is still accepted for manual/debug payloads. Those requests are **not** forwarded to Heryon (avoids doubles if TradingView is still on).

## Quick start (Docker / VPS)

1. Copy env and fill Telegram + Heryon values:

```bash
cp .env.example .env
```

```env
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=-100...
TELEGRAM_MESSAGE_THREAD_ID=...
WEBHOOK_SECRET=...
GERYON_WEBHOOK_URL=http://geryon:PORT/path   # empty = Telegram only
GERYON_ORDER_TYPE=bbo
GERYON_ACCOUNT_ID_LTF=...
GERYON_SECRET_LTF=...
GERYON_ACCOUNT_ID_FVG=...
GERYON_SECRET_FVG=...
```

2. Edit [`watchlist.yaml`](watchlist.yaml): symbols and optional `telegram_thread_id` per strategy (15m vs 6h topics).

3. Build and run:

```bash
mkdir -p data
docker compose up -d --build
```

4. Health check:

```bash
curl http://127.0.0.1:8000/health
```

On first start the scanner **primes** the last closed bar per symbol and does not replay history. The next closed 15m / 6h bar can fire a signal.

After it is stable, turn off the TradingView alerts that used to hit this service and Heryon.

## Local run (without Docker)

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill values
mkdir -p data
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

## Scanner

| Strategy | Timeframe | Risk | Heryon TPs |
|---|---|---|---|
| `ltf` (`428th_v16_LTF`) | 15m + 6h filters | SL = 16h low/high; TP 1.75 / 2 / 4 R | `tp1/2/3_fix` 30% / 30% / 40%, `sl_to_bk=tp1` |
| `fvg` (`428th_v16`) | 6h | live SL 2R from ATR×1 stick; TP1 2R | `tp1_fix` 30%, empty tp2/tp3 (leftover until reverse) |

- Poll interval: `SCANNER_POLL_SECONDS` (default 20). Only **closed** candles are evaluated.
- State: `data/scanner.db` (last bar + Heryon nonces). Restart does not re-send the primed bar.
- Same-side lock matches live Pine (`open_side` on LTF, `use_lock_until_sl` on FVG).
- Tickers in Telegram / Heryon: `{SYMBOL}.P` (e.g. `BTCUSDT.P`).
- Size: `round(RISK_USD / abs(entry−sl)/entry)` with `RISK_USD=40`.

Set `SCANNER_ENABLED=false` to run as a webhook-only Telegram bridge.

### Heryon payload (LTF)

```json
{
  "action": "buy",
  "ticker": "BTCUSDT.P",
  "account_id": "admin1",
  "order_type": "bbo",
  "position_size_usd": "5000",
  "stop_loss": "...",
  "tp1": "...", "tp1_fix": "30%",
  "tp2": "...", "tp2_fix": "30%",
  "tp3": "...", "tp3_fix": "40%",
  "sl_to_bk": "tp1",
  "nonce": "BTCUSDT.P-limit-long-1721736000",
  "secret": "..."
}
```

FVG omits `tp2` / `tp3` and their `_fix` fields. Empty string keys are not sent.

## Manual / debug webhook

`POST /h/<WEBHOOK_SECRET>` or `POST /h/<WEBHOOK_SECRET>/<thread_id>` still accepts the Telegram JSON body (including TradingView `text/plain`). Telegram only — no Heryon forward.

```json
{
  "ticker": "BTCUSDT.P",
  "action": "long",
  "entry_price": "65034.7",
  "current_price": "65034.7",
  "stop_loss_price": "63904.9",
  "take_profit_1_price": "66085.9",
  "take_profit_2_price": "67209.2",
  "take_profit_3_price": "68355.5",
  "visual_timeframe": "15",
  "signal_sequence": 1,
  "signal_time": 1721736000
}
```

`take_profit_2_price` / `take_profit_3_price` are optional (omit or `""` for TP1-only FVG-style setups).

Caption emoji/labels are built from `action` + `signal_sequence`.

| Field | Description |
|---|---|
| `ticker` | TV form (`BTCUSDT.P`, `BINANCE:ETHUSDT`, …) → Binance Futures for the chart; caption keeps the original |
| `action` | `long` or `short` |
| `*_price` | strings; TP2/TP3 optional |
| `visual_timeframe` | `15`, `360`, `15m`, `6h`, … |
| `signal_sequence` | `1` = setup; `>1` = control update |
| `signal_time` | unix seconds of the seq-1 bar open (UTC) |

## Caption format

**seq `1` (setup):** `💚 Buy` / `💔 Sell` — Price / SL (risk %) / TP1 and TP2/TP3 when present.

**seq `>1` (control):** `🌱 Buy Seq: N` / `🥀 Sell Seq: N` — Entry / live Price / `Current profit`.

Prices: `$` and thousand spaces (`65034.7` → `$65 034.7`).

## Behavior

1. Scanner (if enabled): closed bar → indicator → Telegram chart + Heryon JSON
2. Inbound webhook: validate secret, `200` immediately, background Telegram only
3. Chart: ~90 USDT-M klines; on failure, text-only Telegram
4. Telegram or Heryon failure is logged (webhook HTTP already returned `200`)

## Endpoints

- `GET /health` → `{"status":"ok"}`
- `POST /h/<WEBHOOK_SECRET>` → debug payload; topic from `TELEGRAM_MESSAGE_THREAD_ID`
- `POST /h/<WEBHOOK_SECRET>/<thread_id>` → same; topic from path (`thread_id` >= 1)