TelegramBot — Your Trade-Close Notifier

A focused, notification-only channel that posts every closed trade straight to your Telegram chat — no remote commands, no clutter, no operator-induced surprises.

The TelegramBot does one thing well: it posts a clean, formatted message to your Telegram chat every time a trade closes. No remote commands. No noisy alerts. No dashboards to log into when you just want to know “did anything happen overnight?”. The simplicity is the feature.

What the TelegramBot does for you

The TelegramBot is your always-on trade-close feed. While the TradingBot is busy executing your strategy, the TelegramBot watches the closed-trade ledger and forwards each new round-trip to your phone — with the buy price, sell price, profit, and your running totals all pre-formatted for you.

You don’t need to refresh the dashboard. You don’t need to be at your desk. You don’t need to interpret raw exchange data. The message you receive is already the answer.

For an operator running a bot 24/7 across many trading days, this single, predictable, low-friction notification stream is the difference between actively trusting the system and constantly checking on it. The peace of mind compounds.

Posts every closed trade

Every round-trip the TradingBot completes — buy filled, all sell rungs done, position closed — produces exactly one Telegram message in chronological order.

Includes running totals

Each notification shows your cumulative profit and cumulative trade volume since the bot started — so you always know where you stand without opening anything.

Survives Telegram rate limits

If Telegram throttles outgoing messages during a busy hour, the bot queues, waits for the indicated cooldown, and resumes — no messages dropped on the floor.

Splits long batches automatically

If many trades close at once (e.g., a market-wide breakout), the bot batches messages into Telegram’s 4096-character limit and splits cleanly into multiple posts.

Boots gracefully

On startup, waits for the database schema to be ready — handles the case where the TelegramBot starts before the TradingBot has created its tables. No noisy startup errors.

Reads from local database only

The bot polls your local PostgreSQL every 5 seconds. Authoritative trade data is local; Telegram is just a delivery channel on top.

Why it’s notification-only — and why that’s a feature

The TelegramBot does not accept commands from your Telegram chat. You cannot type /start, /stop, /buy BTC, or any other instruction at it.

This was a deliberate design decision. Earlier prototypes exposed remote-command features, and they were removed in favor of a clean, focused, one-way notification channel.

The reason: Telegram is not a hardened admin surface. Anyone who gets your phone — or compromises your Telegram session — would otherwise have access to your trading bot. By keeping the channel notification-only, the worst-case if your Telegram chat leaks is that someone reads your trade history. They cannot place trades, change capital, or touch the kill switch.

Operator control lives in your Dashboard, behind your authentication. Telegram is a read-only window onto your bot’s results. The two roles are separated on purpose — control surface and visibility surface should never be the same surface, because they have different threat models.

Why this matters for your security posture

Your phone is one of the most-stolen and most-compromised devices you own. Phones get lost, sessions get phished, malware gets installed.

Asking yourself “what’s the worst-case if my Telegram session is fully compromised?” should produce the answer “the attacker can read my trade history.” Not “the attacker can place trades on my behalf.”

Many bot platforms blur this line — they let you /buy BTC 1000 from Telegram. That convenience comes at a security cost. unCoded chose against the convenience.

Why this matters for your operator discipline

Remote-command bots make impulsive trading easier. Sitting on the train, you see a price move, you whip out your phone, type /buy ETH 5000 — and now you’re trading on emotion, not on rules.

The TelegramBot’s notification-only design forces a small but valuable speed bump: to act, you have to log into the Dashboard. That extra friction means impulsive operator-induced trades are harder. The system is built to let the bot do its rule-bound thing, not to make operator-driven discretion frictionless.

What you receive — the exact message format

Every closed trade produces a block like this in your Telegram chat:

-------------------------------
ID: 12473
Symbol: BTCUSDT
-------------------------------
Buy Price: 67234.55000000
Sell Price: 68512.30000000
-------------------------------
Sell Quantity: 0.0149
Sell USD: 1020.83370
-------------------------------
Profit: 19.04132 USD
Profit Percentage: 1.901%
-------------------------------
Buy Time: 2026-04-29 14:32:18
Sell Time: 2026-04-30 03:11:42
-------------------------------
Total Profit: 1842.55738 USD
Total Volume: 184725.41 USD
-------------------------------

Every field comes directly from the closed-trade record in your local database. There is no “interpretation,” no rounding-for-presentation that hides precision. The buy and sell prices are exact to 8 decimals; the profit calculation is the exact USD-equivalent net gain after exchange fees.

Why every field is here

• ID — the auto-incrementing trade ID. Useful when cross-referencing in the Dashboard or in your tax export.
• Symbol — the trading pair. Tells you which symbol made the trade.
• Buy Price / Sell Price — to 8 decimals so even sub-cent symbols are accurate.
• Sell Quantity / Sell USD — the position size and its USD value, so you can sanity-check sizing.
• Profit / Profit Percentage — both the absolute USD figure and the percentage. Useful different ways: absolute for tax/accounting, percentage for “is this trade in line with the mode’s expected ladder rungs?”
• Buy Time / Sell Time — when the trade opened and closed. The hold duration is the difference; useful for understanding “is this mode trading on the timescale I expected?”
• Total Profit / Total Volume — the running cumulative figures, calculated up to and including this trade. So every notification updates your “current state” without requiring you to add anything mentally.

The format is non-negotiable on purpose. Operators who scan dozens of these messages a day need predictable structure — same fields, same order, same separators, every time.

The running Total Profit and Total Volume are cumulative since the TradingBot’s first trade, not since the start of the day or month. If you want a daily/monthly view, the Dashboard’s analytics panels are where that lives — Telegram is the firehose, the Dashboard is the dashboard.

What the TelegramBot does NOT notify

The TelegramBot’s scope is intentionally narrow. It only notifies on closed trades — full round-trips. It does NOT notify on:

• ❌ Trade opens (the moment a buy order fills) — only the eventual close
• ❌ Per-rung sell fills (when one of the sell-ladder rungs fills, but the position isn’t fully closed yet)
• ❌ System events (TradingBot restarts, exchange disconnects, kill-switch toggles)
• ❌ Errors (failed orders, API rejections, configuration problems)
• ❌ Daily summaries — there is no scheduled summary post; only individual trade closes
• ❌ Strategy events (a SignalEditor strategy publishing a new configuration)
• ❌ Drawdown warnings or risk alerts
• ❌ Capital-allocation changes
• ❌ Mode parameter edits

If you need any of the above, the Dashboard is your source. Telegram is for “what closed?”, not “what’s going on?”.

The list of what the bot does not do is longer than what it does. That’s intentional.

How it stays in sync

The TelegramBot polls your local database every 5 seconds for new closed trades. When it finds new rows, it processes them in chronological order, batches them into messages, and posts to your chat. The cursor (last-processed trade ID) is held in memory — efficient, simple, no extra database tables to maintain.

What happens during a Telegram outage

If Telegram’s API is unreachable, the bot’s outbound messages fail. The bot logs the error, sleeps briefly, and retries on the next polling cycle. Trades continue to close on your TradingBot — your trading is unaffected. The notifications simply queue up and deliver when Telegram comes back.

During very long outages, the message queue is held in memory; on bot restart the cursor is re-initialized from the most recent trade ID, so trades that closed during downtime are not retroactively notified. This is an acceptable trade-off — your local database is always the authoritative trade log.

What happens during a TelegramBot restart

On startup, the bot reads the most recent trade ID from the database to set its cursor. Trades that closed while the bot was down are skipped in Telegram — they’re already in your local database and visible in the Dashboard.

This keeps the bot simple and crash-resilient: there’s no persisted cursor to corrupt, no message-replay state to manage. The trade-off is that a long downtime creates a gap in your Telegram feed, not in your trade record.

If you need durable notification that survives restarts, the Dashboard’s notifications panel and your local database both retain the full record permanently.

What happens during a TradingBot pause

If you stop the TradingBot but leave the TelegramBot running, no new trades close, so no new notifications fire. The bot continues polling silently — when you resume the TradingBot and the next trade closes, the next notification arrives.

What happens during high-volume periods

If 50 trades close in the same 5-second window (e.g., a market-wide event firing your kill switch), the bot fetches them in batches of 100, formats them into multi-block messages, splits them at the 4096-character Telegram limit, and queues them with a 50ms delay between sends to respect Telegram’s throttle. You’ll receive the full batch as multiple sequential messages, in chronological order — none missed.

This batch behaviour means a high-volume minute might produce 2–4 sequential Telegram messages instead of 50 — far easier to read on a phone, and respectful of Telegram’s rate limits.

What happens during database connection drops

If the local database is briefly unreachable (rare, but happens during database container restarts), the bot logs the error and retries on the next polling cycle. Once the database is back, the bot picks up where it left off — no messages lost, just a brief notification gap matching the database downtime.

Setting up your Telegram bot

The TelegramBot expects three pieces of configuration: a bot token (from Telegram’s BotFather), a chat ID (where messages should land), and the connection to your local database. The Dashboard’s onboarding flow walks you through getting all three.

1. Create your Telegram bot via BotFather

   On Telegram, search for @BotFather, send /newbot, follow the prompts (give your bot a name and a username), and you’ll receive a bot token that looks like 123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Save this token securely — it’s the equivalent of a password for your bot.

   BotFather will also offer you the option to set a profile picture, a description, and an “About” text. These are cosmetic — skip if you want, customize if you enjoy it.

2. Create a private Telegram chat or group

   Make a new Telegram group (or use an existing private one). The recommended pattern is a private group — even if you’re the only member — because it’s easier to add a witness later (a partner, an accountant) without re-creating the bot.

   Add your bot to the group. Send any message in the chat (this is required so Telegram registers the bot as a participant).

3. Find your chat ID

   The Dashboard’s onboarding flow includes a “Get my chat ID” helper, or you can use Telegram’s getUpdates API to read it from the chat metadata. The chat ID is a number — typically negative for groups (e.g., -1001234567890).

   For a 1-on-1 chat with the bot, the chat ID is positive (your user ID).

4. Configure the TelegramBot container

   In your VPS environment configuration, set the bot token, chat ID, and database connection. The Dashboard’s setup flow handles this for you, or you can edit the .env file directly.

5. Verify with a test trade

   Once the TelegramBot is running, the next trade your TradingBot closes will produce a Telegram message. To verify earlier — without waiting for a real close — you can manually send a test message via the Dashboard’s TelegramBot panel.

6. Pin a setup message in the chat

   Pin a single message at the top of the chat with your trading rules, capital amounts, and operator notes. This is your reminder to yourself, visible every time you open the chat. Examples of what operators pin:

   • “Mode 4 BasicMode on BTCUSDT, $20k capital,$10k reserve”
   • “Kill switch lives at https://dashboard.yourdomain.com — bookmark”
   • “Tax export end of every month”

Use a private group, not a 1-on-1 chat with the bot. Why: groups give you the option to add another trusted person (e.g., a partner, an accountant) as a read-only witness to your trade activity, without needing to share the bot token. You can also pin specific notifications, mute the chat at certain hours, or archive the chat for tax-record purposes.

Operator routines built around the Telegram feed

The Telegram feed is the rhythm of your day-to-day operation. Here’s how operators typically use it.

Daily — quick scan, no action

Most operators look at their Telegram chat 1–3 times a day for 30 seconds:

• Scroll through the trades that closed since the last check.
• Glance at the running Total Profit to confirm it’s tracking your expectations.
• If anything looks weird (very large loss, unexpectedly long hold time, symbol you didn’t expect), tag that for later review in the Dashboard.

The goal is not to make decisions from Telegram — it’s to confirm “the bot is doing what I expect” in 30 seconds instead of 5 minutes of dashboard inspection.

Weekly — structured review

Once a week, do a more substantial review:

• Cross-check the Telegram running total against the Dashboard’s analytics. They should agree to the cent.
• Identify your worst trade of the week. Open the Dashboard, find it in the order ledger, look at the buy and sell rungs. Did the mode behave as designed, or was there an anomaly?
• Identify your best trade. Same exercise — was it the mode hitting expected rungs, or was it riding an unusually large move?
• Confirm the symbols you expected to be trading actually traded. A symbol that goes a week without closing a trade is often a signal that capital sizing or mode configuration needs review.

Monthly — tax archive

At month-end:

• Pull the Tax Report from the Dashboard for the month.
• Cross-check the report’s total against the Telegram running total at the last trade of the month.
• Archive the report (CSV or JSON) to a designated folder.
• Optionally, take a screenshot of the last Telegram trade of the month and archive alongside the report — provides a third source of truth for that month’s closing balance.

Yearly — full audit

At year-end:

• Pull the full-year Tax Report.
• Verify total against the sum of monthly archives.
• Verify total against the Telegram running total at year-end.
• All three should agree. If they don’t, this is a flag to investigate — usually the cause is a data-restoration boundary (e.g., the local database was restored mid-year and the running total reset).
• Send to your accountant.

Privacy and operational considerations

What information is in your Telegram chat

The chat contains:

• Every closed trade with prices, quantities, and P&L.
• Your running cumulative profit and trading volume.
• The symbols you trade.

The chat does NOT contain:

• Your exchange API keys (those live in the TradingBot’s environment, not in any notification).
• Your wallet addresses.
• Your dashboard password or session.
• Your VPS access credentials.

Treat the chat as a financial record — sensitive but not credentials. Apply the same hygiene you would to a brokerage statement.

Adding a witness — partner, accountant, advisor

Many operators add a second trusted person to the Telegram group as a read-only witness. The witness sees every trade as it closes — useful for:

• Spousal accountability. A partner who shares the household balance sheet has visibility into the bot’s contribution.
• Accountant access. Your accountant sees trades as they happen and can ask questions in real time, not just at year-end.
• Advisor visibility. A financial advisor with read access can spot operator-induced patterns you might miss yourself.

The witness has zero ability to change anything — they’re an observer. Removing the witness is a one-click Telegram action if the relationship changes.

Mute hours and quiet times

Operators in different timezones, or operators who simply want to sleep, mute the Telegram chat at the OS level:

• iOS / Android: Telegram’s chat-level “Mute” with custom-hours.
• Desktop: Same per-chat mute available.
• Telegram-wide: “Do Not Disturb” hours.

The bot continues posting; you simply don’t get pushed. Open the chat in the morning, scroll the overnight feed.

Don’t stop the TelegramBot to silence overnight notifications — that creates a gap in your record. Mute, don’t kill.

Archive vs delete

For compliance and tax purposes, never delete the Telegram chat. Archive it instead. Telegram archives are searchable, exportable, and don’t lose any data — they just get out of your active chat list.

Some operators export the Telegram chat to local archive .json files quarterly via Telegram’s built-in export tool. This gives you a portable, vendor-independent record beyond what the local database holds.

Common questions

Can I use the same bot for multiple TradingBots?

Yes, with a caveat. One TelegramBot container reads from one database and posts to one chat. If you run multiple TradingBots (e.g., one per exchange) and they all write to the same shared database, a single TelegramBot will notify on closes from all of them — but the messages won’t tag the source exchange.

For most operators with 2–3 exchanges, this is fine — the symbol naming usually disambiguates (BTCUSDT is Binance/Bybit, BTC-USDT is OKX). For more separation, run a separate TelegramBot container per exchange, each reading the relevant subset of trades.

Can I have one chat per mode?

Yes, with operator effort. Run multiple TelegramBot containers, each pointed at a different chat ID, and (with custom filtering) read only the trades for specific modes. The standard distribution is one TelegramBot per database; multi-chat-per-mode is a customization most operators don’t need.

The simpler pattern: one chat for everything, then if you want per-mode views, use the Dashboard’s analytics filters.

Can I mute the bot during sleeping hours?

Yes — but you do this in Telegram’s app, not in the bot. Mute the chat at the OS level or in Telegram’s notification settings. The bot will still post; you just won’t get pushed.

The bot itself does not have schedule-based muting. We recommend Telegram’s native mute feature because it integrates with your phone’s “Do Not Disturb” settings and stays consistent across devices.

Can I customize the message format?

The format is currently fixed. Feedback from operators has been overwhelmingly that the standard format is what they want — they scan for the symbol, the profit percentage, and the running total. If you have a specific need to customize, contact support; this is on the longer-term roadmap as an opt-in feature.

Why don't I get a notification when a buy fills?

The bot is intentionally close-trade-only. A buy fill is the start of a position, not a complete event — until the sell ladder fully fills (or the trailing stop hits), the trade is still in flight, and there’s no profit to report.

If you want to see live buy fills in real time, the Dashboard’s Live Trades panel is the right surface. The Dashboard also surfaces partial sell-ladder fills, mid-trade trailing-stop activations, and other in-flight events that don’t make sense as Telegram messages.

What if my Telegram bot token leaks?

Revoke it immediately via BotFather (/revoke), then generate a new token. Update your TelegramBot container’s environment variable and restart it. The old token is dead the moment you revoke.

What an attacker with your bot token can do: read your chat (which contains your trade history) and post fake messages into the chat. What they cannot do: place trades, change your bot configuration, withdraw funds. Your TradingBot doesn’t trust the TelegramBot — it has no path back to your exchange via Telegram.

This is a property of the architecture: the TelegramBot is downstream of everything important. Compromising it doesn’t compromise your trading.

Is there a Discord version? Slack? Email?

Not currently. Telegram was chosen because it’s the lowest-friction option for traders globally — free, no app store gatekeeping, push notifications work reliably across devices, and the Bot API is mature.

If you have a strong need for another channel (e.g., for a corporate Slack), the local database is the source of truth and a small custom poller is straightforward to write. Contact support for help.

Does it use up my Telegram message quota?

Telegram’s bot rate limits are 30 messages per second to different chats and 1 message per second per chat for ordinary cases — far above what a normal trading bot will produce. The TelegramBot also adds a 50ms delay between sends and handles 429 Too Many Requests automatically. In normal operation you will never hit a rate limit.

Can I get a daily summary at a specific time?

Not from the TelegramBot directly. The bot is per-trade-only by design.

For a daily summary, two patterns work:

• Scroll the chat at the same time every day. Telegram makes this trivial — open the chat at 09:00, scroll back to yesterday’s 09:00 mark, you’ve seen the day.
• Pull the Dashboard’s analytics for the day. The Dashboard supports daily-windowed views with totals, win rate, average trade size, etc.

Operators who really want a Telegram-pushed daily summary build a small custom script that reads the database and posts a one-message summary at midnight. Standard pattern, well documented in the operator community.

What if I run two operators on the same bot?

Two operators sharing one TelegramBot is a special case. Each operator can be added to the Telegram group; both see the same notifications. There’s no per-operator filtering — the chat is global.

For per-operator views, use Dashboard accounts (one admin password, one viewer password — see the Dashboard module). Telegram remains the shared firehose.

Can I export the Telegram chat history?

Yes — Telegram’s desktop app has a built-in “Export chat history” feature that produces JSON or HTML. Useful for:

• Long-term archival beyond your local database.
• Tax preparation as an additional source of truth.
• Investor reporting (summarize the chat into a quarterly report).

Export quarterly or yearly — the exports are large but compress well. Store with your other operator records.

Operational footprint

Resource cost

A few hundred MB of RAM, sub-percent CPU at idle. The bot is a small lightweight process with one polling loop and one outbound queue.

Network calls

Outbound only — to Telegram’s bot API. No inbound webhooks, no exposed ports. Lives entirely on your VPS’s internal Docker network apart from outbound HTTPS.

Failure mode

If the TelegramBot crashes or stops, your trading is unaffected. The TradingBot continues placing and closing trades. You just don’t receive Telegram pings until you bring the bot back up.

Startup time

Boots in seconds. Waits for the database schema to be ready (handles the case where the TelegramBot starts before the TradingBot has created the trade tables).

Database load

A single SELECT every 5 seconds plus a few aggregate queries on each polling cycle. Negligible load on the database.

Telegram quota

Far below Telegram’s 30/sec bot rate limit even in worst-case high-volume scenarios. No concern in practice.

Best practices

• ✅ Use a private group instead of a direct chat — easier to add witnesses, archive, and search.
• ✅ Pin a single setup message at the top of the chat with your trading rules and capital — visible every time you open the chat.
• ✅ Mute the chat at the OS level during sleep hours instead of stopping the bot.
• ✅ Treat the chat as read-only — never copy-paste your bot token into the chat itself, never reply with sensitive data.
• ✅ Cross-check Telegram totals against the Dashboard weekly — if they diverge, the Dashboard is the source of truth.
• ✅ Add a witness if you have a partner, accountant, or trusted advisor who would benefit from visibility — viewer-style accountability without giving them control.
• ✅ Export the chat quarterly as an additional archive beyond the local database.
• ✅ Never delete the chat — archive instead. The chat is a tax-relevant record.
• ✅ Rotate the bot token if you suspect compromise. Revoke via BotFather, generate new, update and restart.
• ✅ Bookmark BotFather in your Telegram contacts so you can revoke quickly if needed.
• ✅ Don’t stop the TelegramBot to silence overnight pings — it creates a record gap. Mute the chat instead.

What’s next

Dashboard

Where you actually control the bot — the Telegram channel is read-only.

TradingBot

The execution engine that produces the closes you’ll see in your Telegram chat.

Quickstart

The full setup, including BotFather configuration step-by-step.

Security Philosophy

Why Telegram is intentionally a downstream-only surface.

Tax Export

The Dashboard’s tax export — the canonical source of truth for tax purposes.

Architecture

Where the TelegramBot sits in the overall stack.