Telegram notifications
WheelTrading can send you a short Telegram message when something important happens with your orders or your IBKR gateway – free, low latency, no extra app needed. These notifications are pure status pushes: they never place orders and contain no sensitive account data besides symbol, strike and quantity.
What you need
- A Telegram account.
- Your own bot, created via @BotFather in Telegram (
/newbot) –
you receive a bot token.
- Send your bot any message once (
/start) so Telegram assigns you a
chat ID. You can read the chat ID via @userinfobot or https://api.telegram.org/bot<token>/getUpdates.
Enter both values in the WebApp under Settings ▸ Notifications. Both are stored encrypted (Fernet / AES); we can't read them in plain text either.
Events you'll receive
The WebApp pushes the events you usually aren't watching the screen for:
| Event | When |
|---|---|
FILLED | Order fully executed (with fill price when known) |
PARTIAL FILL | Partial execution |
REJECTED | Broker rejected the order (with reason) |
ASSIGNED | Option got assigned |
EXPIRED (worthless) | Option expired worthless |
AUTO-CANCEL (3 days) | 3-day cleanup discarded an open order |
CLEANUP FAILED | 3-day cleanup failed (e.g. gateway down) – retry scheduled |
BROKER NO LONGER OPEN | Broker no longer reports the order (manually cancelled?) |
IBKR gateway expiring | Less than 4 hours left on your IBKR session |
IBKR gateway auth lost | Gateway is running but no longer authenticated |
IBKR maintenance active | IBKR reports a maintenance window – login is temporarily blocked |
IBKR maintenance ended | Maintenance is over – please re-authenticate in the WebApp (2FA) |
Gateway warnings are throttled to at most one every 4 hours, so you don't get spammed but still have enough lead time to re-authenticate (2FA in the WebApp). This throttle now also survives server restarts.
Turning gateway notifications off: Under Settings ▸ API keys & Telegram (where you enter your bot token and chat ID) there is a "Gateway notifications (Telegram)" switch. Turn it off if you don't want the IBKR gateway auth lost and IBKR gateway expiring messages – for example because you re-authenticate when you open the app anyway. Order events (fills, assignments) and the IBKR maintenance notices are not affected by this switch.
Quiet hours (23:00–07:00): Right below it you'll find the "Quiet hours (23:00–07:00)" switch (on by default). It suppresses the two gateway status warnings at night between 23:00 and 07:00 (Europe/Berlin). Background: IBKR resets the session during its nightly maintenance window as expected – without quiet hours you'd otherwise be woken every 4 hours (e.g. 01:41, 05:46). After 07:00 you get one regular reminder. The switch only takes effect while the gateway notifications above are enabled.
During an official IBKR maintenance window we suppress the generic auth lost message and instead send exactly two pushes: one when maintenance starts and one when it ends (so you know it's safe to re-authenticate again). This way you instantly know whether the issue is on your side or a global IBKR outage.
Per-account on/off switch
Each IBKR account has a telegram_notify_enabled flag in its filter settings. Default: off – you have to actively turn it on once you have configured bot token + chat ID.
- Off: nothing is sent even if a bot token is configured.
- On: all events above are pushed.
- Adopted orders (placed manually in Lynx and adopted by the
system) have no account context; they are sent as long as bot token + chat ID are configured.
Earnings alerts (new)
There is an additional flag telegram_notify_earnings_enabled. When enabled, the server runs a daily job at 07:30 UTC and pushes a notification for every symbol in your portfolio (stocks or open option positions) with earnings in 7, 3, 1 or 0 days. Each (symbol + date + distance) triple is sent exactly once. Source: next_earnings_date from the nightly fundamentals refresh (yfinance).
Plan notes
- Wheel Starter: bot token can be entered, but Telegram push is not
unlocked. You still see every state change in the WebApp.
- Wheel Master and Wheel Premium: all events active (fills,
assignments, roll proposals, gateway warnings).
- Legacy accounts in the locked
freestate: no Telegram.
Example message
✅ FILLED
AAPL PUT 180 @ 2026-06-20
Qty: 2 @ $1.25
Fill: $1.23What happens on Telegram outage?
The notifier is best-effort: if sending fails (network, revoked token, wrong chat ID) the event is only logged. Order logic runs independently – your trades never depend on Telegram availability.