Telegram App

TRUE inside Telegram — a bot that authenticates users and hands off to the full True Finance Mini App with a signed Telegram auth token.

What this is

The TRUE Telegram bot is a thin authentication and entry surface that hands users into the True Finance Mini App running inside Telegram’s WebView. The bot itself has a minimal command set; everything substantial — chat, signals, swaps, agents, staking — runs inside the Mini App with the same UI as the standalone web app.

Commands

Command	What it does
`/start`	Captures Telegram identity, mints a signed auth token, and returns an inline keyboard with a single “Ask True AI” button that opens the Mini App.

The bot is intentionally minimal. Every other action lives inside the Mini App because that’s where the wallet, the agents, and the signing flows live.

Auth handoff

Capture identity

On /start, the bot reads ctx.from (id, username, first/last name, language_code, photo url).

Build auth payload

Standard Telegram authentication-data fields plus a unix auth_date.

HMAC hash

HMAC-SHA256 over the data-check-string with a key derived from BOT_TOKEN, per Telegram's Login Widget spec.

JWT mint

Sign a JWT (HS256, key = BOT_TOKEN) carrying { user, hash, auth_date }.

Inline keyboard

Reply with a Mini App button whose URL contains ?telegramAuthToken=<encoded JWT>.

Mini App auto-login

useTelegramAutoLogin reads the token from URL on load, calls signInWithTelegram(), Dynamic.xyz verifies and provisions a wallet (forceCreateUser: true on first run).

The wallet that backs the Telegram session is a Dynamic-managed embedded wallet, not the bot’s. The user can export and self-custody at any point.

What surfaces inside the Mini App

The Mini App is the same React app as the standalone TRUE web app, opened inside Telegram’s WebView with the auth token applied. Everything ships:

Chat with the DARS agent system — see Chat.
Signals — see Signals.
True Agents wizard for autonomous strategies — see True Agents.
Swaps via Jupiter — see Swaps.
Staking wizard — see Staking.
Highlighted Stories shelf and viewer.

The Mini App uses Telegram’s BackButton API to drive its SPA navigation, so the native Telegram back chevron behaves as expected.

Message format

The bot uses HTML parse mode. The welcome reply is a brand image plus a one-line headline:

<b>Welcome to True Trading!</b>

There is no command-driven trading flow in the bot itself. Anything that signs or moves value happens inside the Mini App, where the wallet UI is available.

Deployment

Aspect	Setting
Framework	Telegraf (`telegraf` library).
Update mode	Long polling (`bot.launch()`). No `setWebhook` is configured.
Health check	HTTP 200 on port 3000 for host uptime monitoring (Railway-compatible).

Telegram is the entry, not the trust boundary

Telegram identity is used to bootstrap a wallet session, but Telegram is not a trust root for fund movement. Every transaction is still signed by the user’s wallet inside the Mini App. Losing access to a Telegram account does not give anyone the ability to move funds — they would still need the wallet’s signing material.

For Developers

Deep-link pattern

https://t.me/<your-bot>?start=<payload>

The start payload is forwarded to the Mini App URL by the bot, which then arrives at the Mini App as part of the launch params. Use this to deep-link to specific surfaces inside the app (e.g. a particular signal or agent draft).

Rate limits

The bot inherits Telegram’s bot-API rate limits (≈30 messages/sec global, 1 message/sec per chat). Heavy fan-out should be batched server-side.

Source

The bot lives at artifacts/telegram-bot/src/bot.ts. The Mini App auto-login hook is artifacts/true-finance-ai/src/telegram/useTelegramAutoLogin.tsx.

Safety, limits, failure modes

Token replay window. The Telegram auth-data auth_date is checked server-side; stale tokens are rejected.
HMAC mismatch. A tampered userData field will fail the HMAC check and the Mini App login will refuse.
Long-polling lag. Polling latency for replies is bounded but variable; a switch to webhooks would reduce p99 latency at the cost of public ingress.
Embedded-wallet recovery. If the user does not export the Dynamic-managed wallet, account recovery is bound to the Telegram identity. Encourage export for any meaningful position.