📘TraderTape Docs

Telegram Bot

The Telegram bot is the second screen for TraderTape. It pushes signal notifications, lets you approve or reject trades from your phone, handles broker re-login, and exposes most read-only operations as commands. If you're operating a portfolio in production, the bot is what you'll use most of the day.

What it does

  • Signal notifications — when a scan generates new signals, the bot sends a summary message with inline approve/reject buttons
  • Approval flow — tap a button to approve, reject, or move signals to the cart
  • Auto-place notifications — when auto-execute fires, the bot reports the result (success or failure with the broker's error)
  • Broker re-login — /login opens an OAuth flow that works from any phone, anywhere, with no Tailscale required
  • Read-only commands — /status, /positions, /pending, /summary, /danger, /briefing
  • Daily briefing — optional morning message with portfolio status and risk warnings

Setup

1. Create a bot

In Telegram, message @BotFather. Use the /newbot command. Pick a name and username. BotFather gives you a bot token (looks like 123456789:ABCdef...).

2. Configure the backend

Add to backend/.env:

telegram_bot_token=123456789:ABCdef...

Restart the backend. On startup, the bot library connects to Telegram and starts polling for messages. You should see a log line like:

[telegram] Bot started: @ztrade_algo_bot

3. Find your chat ID

Send /start to your bot in Telegram. The bot replies with a welcome message and your numeric chat ID. Copy it.

In TraderTape, go to Settings → Telegram. Paste the chat ID. Click Link. The status changes to "Linked".

The bot can now send notifications to your chat and look you up by chat ID for incoming commands.

Commands

All commands are scoped to the user identified by chat ID. If two users link their accounts to the same bot, they each see only their own data.

/start

Welcome message + your chat ID. Use this when first setting up.

/status

Quick portfolio summary. Output:

📊 Dip Buyer 50L
Capital: ₹52,30,000 (deployed: ₹38,50,000)
Realized P&L: +₹2,30,000 (+4.6%)
Open: 7 positions
Pending: 2 signals awaiting approval

If you have multiple portfolios, you get one summary per portfolio.

/positions

Open positions table. Each line: symbol, qty, avg entry, current LTP, unrealized P&L, days held.

🟢 RELIANCE     1,000 @ 2,510 → 2,580  +₹70,000  (+2.8%)  18d
🟢 INFY           500 @ 1,420 → 1,485  +₹32,500  (+4.6%)  9d
🔴 HDFCBANK       300 @ 1,650 → 1,612  -₹11,400  (-2.3%)  4d

/pending

Pending signals from the most recent scan. Each signal has inline buttons: ✅ Approve, ❌ Reject, ⏸ Skip.

🆕 New entry signals:

✨ TCS — Conviction 78
   Qty: 200 @ ₹3,420 = ₹6,84,000
   RSI 38.5 · vol_calm · sector IT
   [✅ Approve]  [❌ Reject]

✨ MARUTI — Conviction 71
   ...

Tapping Approve moves the signal to the cart. After approving everything you want, send /place to push the cart to the broker.

/place

Places all in-cart signals as GTTs through the broker. The bot reports each one's result and the total committed capital.

/summary

Today's activity: scans run, signals generated, fills, approvals, rejections. Useful at end of day.

/danger

A read-only check of any risk warnings: positions approaching stop loss, sectors near cap, portfolios approaching daily loss limit, etc. Returns "All clear" if nothing's flagged.

/briefing

Comprehensive morning briefing. Sent automatically at 9:00 IST if you have it enabled, or on-demand. Contents:

  • Portfolio status (capital, P&L, open positions)
  • Yesterday's fills
  • Today's expected signal flow (based on last night's scan)
  • Risk warnings
  • Recent corporate actions affecting your holdings

This is the "is anything I need to know about?" check before market open.

/login

The most-used command in production. Triggers a Kite re-login that works from any phone, anywhere — no laptop, no special network setup.

How it works depends on where your api_secret is stored:

If your api_secret is on the cloud (Tier 3 — admin approved):

  1. You send /login to the bot
  2. The bot generates the Kite OAuth URL using your api_key and sends it as an inline button
  3. You tap → Kite's login screen opens in your phone's browser
  4. You authenticate (Kite's screen — TraderTape never sees your Kite password)
  5. Kite redirects to your registered TraderTape callback
  6. The cloud exchanges the request token immediately and starts a fresh session
  7. Your dashboard works on next reload — total time ~5 seconds

If your api_secret is on the local agent (Tier 4 — default):

The same flow up to step 5. Then:

  1. The cloud receives the request token but can't exchange it (no api_secret on the cloud). It stashes the token in memory for up to 2 minutes.
  2. Your local agent — which polls the cloud every ~30 seconds — picks up the request token on its next cycle
  3. The agent uses its locally-stored api_secret to exchange the token with Kite directly
  4. The agent pushes the resulting access token back to the cloud
  5. Your dashboard works on next reload — total time ~30-60 seconds

Constraint for the agent path: the agent must be running and polling. If your machine is powered off, the request token expires after 2 minutes and you'll need to power on your machine and re-trigger /login. Once the agent is online, the second attempt completes within a poll cycle.

This is why most agent users keep their machine running 24/7 (or at least during market hours): so re-login from anywhere "just works".

If the deep link doesn't auto-open (some browsers block it), the page shows the URL with "copy and paste in your bot chat" instructions. The bot's URL paste handler extracts the request token from any pasted URL containing request_token=....

/login_force

Same as /login but bypasses the cached "session is still valid" check. Useful if you suspect the cached state is stale (e.g. you logged out from another device).

Notification settings

You can mute different categories of notifications in Settings → Notifications:

  • Signals — new entry/exit/addon signals
  • Auto-placed — confirmation when auto-execute fires
  • Fills — when a GTT triggers and the order completes
  • Stops — when a stop-loss GTT fires
  • Risk warnings — when a risk rule blocks an action
  • Daily briefing — the 9:00 IST morning message

Mute everything to use the bot purely for read-only commands. Mute nothing for full operational visibility.

Security

  • The bot only responds to linked chat IDs. A random Telegram user messaging your bot gets nothing.
  • The bot has no broker credentials. It can't place orders directly — it only triggers actions on your TraderTape backend, which holds the credentials.
  • The /login flow is safe even if intercepted. Kite request tokens are single-use, ~30 second TTL, and useless without the api_secret.
  • Private chats only. Don't add the bot to a group — group permissions are different and the user-to-chat mapping breaks.

Limitations

  • No multi-step conversations. The bot is stateless. Each command is independent.
  • No file uploads. You can't send a tradebook XLSX to the bot for import. Upload via the web UI or local agent.
  • One bot per deployment. TraderTape's bot is @ztrade_algo_bot. All TraderTape users share it, but messages are scoped to your linked chat ID — no cross-user leakage.
  • No outbound SMS / email fallback. If Telegram is down, you don't get alerts.

Troubleshooting

"Bot doesn't respond to /start"

The backend isn't running or the telegram_bot_token is wrong. Check the backend logs for [telegram] lines. If you see Bot conflict: terminated by other getUpdates, two backends are polling the same bot — only one can.

"I sent /status but get nothing"

Your chat isn't linked. Send /start, copy the chat ID, paste it into Settings → Telegram → Link.

"Inline buttons don't do anything"

Buttons send callback queries. If your backend has restarted since the message was sent, the callback may have lost its context. Send /pending again to get fresh buttons.

"/login redirects to a 'site can't be reached' page"

This usually means the OAuth callback URL configured in your Kite developer app is incorrect, or your TraderTape session expired. Re-check the redirect URL on Kite matches the one shown in Settings → Broker Connections, and try the flow again.

Next

← Previous
Local Agent
Next →
Tradebook Import