tvsignals-to-tg/README.md

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:

cp .env.example .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: symbols and optional telegram_thread_id per strategy (15m vs 6h topics).

3. Build and run:

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

4. Health check:

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)

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)

{
  "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.

{
  "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)