Telegram Mini App Security: A Pentesting Checklist

Video transcript

A Telegram Mini App that moves crypto is a payments system wearing a chat interface. Securing it starts with one rule: trust nothing from the client.

The app runs on the user's device, so attackers can read and change everything client side. Only the signed initData is trustworthy, and only after your server validates it.

Validate it on the backend, every request. Build the data-check-string, derive a secret key from your bot token, compare the hash in constant time, and check the auth date to block replay.

Validated initData authenticates a user. It does not authorize an action. Test access control, withdrawal races and replay, referral bonuses that run twice, and fuzzed inputs.

Connecting a wallet is not proof of control. Require a signed, single-use ton proof challenge. Keep the bot token on the server, and protect the webhook with a secret token.

In September 2024, the Telegram trading bot Banana Gun lost about three million dollars from eleven users. The offchain path, not the contracts, was the story.

Guardian's offchain team, led by HackTricks creator Carlos Polop, pentests the web app, API and automation behind Mini Apps. Our Avantis offchain review returned sixty-eight findings, two of them Critical.

Read the full checklist below, or talk to Guardian about pentesting the Mini App behind your bot.

A Telegram Mini App is a web app that Telegram loads in an in-app browser, with a bot and a backend behind it.

When it holds balances, runs a trading bot or moves crypto, it is a custody and payments system wearing a chat-app interface.

Start from one fact: the app runs on the user’s device. A motivated user, or an attacker who phishes one, can read and modify everything client-side.

The only cryptographically trustworthy input is the signed initData, and only after your server validates it.

So authentication, authorization, balances and entitlements all belong on the backend. The client is a rendering layer, not a source of truth.

This checklist follows Telegram’s Mini Apps documentation, the OWASP Web Security Testing Guide and the TON Connect documentation.

Validate initData on the server

Telegram passes two objects to a Mini App. initData is a raw signed string; initDataUnsafe is a parsed object the docs explicitly say should not be trusted.

Validation uses the raw string. On your backend:

1. Build the data-check-string: every field except hash, sorted alphabetically, each as key=<value>, joined by a line feed (0x0A).
2. Derive the secret key as the HMAC-SHA256 of the bot token, using the constant string WebAppData as the HMAC key.
3. Compute HMAC-SHA256(data_check_string, secret_key) and compare its hex to the received hash.
4. Check auth_date, the Unix timestamp of issue, and reject anything older than a short window.

Reviewers test what goes wrong in practice: client-side validation, a comparison that is not constant-time, a missing auth_date check that allows replay, and identity taken from initDataUnsafe.

Any of these lets an attacker present another user’s ID and take over their account.

If a third party must validate the data without your bot token, Telegram provides an Ed25519 signature field, verified against its published production public key. The same auth_date check applies.

Backend and API security

Once identity comes from validated initData, the backend is an ordinary high-value web API. The decisions that cost money live here, so this is where most findings land.

• Authorization on every action. Horizontal, vertical and object-level checks: can one user’s forged request reach another user’s balance, order or withdrawal?
• Value-moving flows. Withdrawals, transfers and trades: step ordering, replay, and races when two requests arrive together.
• Business logic. Skippable steps, limits enforced only in the interface, and bonus, referral or airdrop logic that runs twice.
• Input handling. Every parameter fuzzed for injection and unsafe parsing, including anything that reaches a database query or an onchain transaction.

Validated initData authenticates a user. It does not authorize an action.

In the answerWebAppQuery flow, query_id ties a result to one Mini App session. Bind actions to the validated session, not a client-supplied identifier.

Wallets and key custody

Mini Apps that move crypto either custody keys or connect to the user’s wallet. Both need care.

• Prove wallet ownership. Connecting a wallet is not proof of control. With TON Connect, use ton_proof: the wallet signs a single-use payload your backend issued.
• Verify the proof. Check the Ed25519 signature, the app domain, a short timestamp window (around ten minutes) and the network before binding the address.
• Re-prove on restore. A restored connection is not an authenticated session. Require a fresh proof.
• Keep keys off the client. The bot token stays on the server.
• SecureStorage. For user-specific sensitive values, it uses the iOS Keychain and Android Keystore and encrypts at rest (Bot API 9.0, April 2025), up to ten items per user.
• Not for secrets. CloudStorage (up to 1024 items) and DeviceStorage (up to 5 MB) are convenient but not designed to hold secrets.
• Custody is its own system. If the backend holds keys or uses MPC, share handling, signing policy and recovery are tested as a custody service.

Bot and webhook security

The bot is the other half of the system, and its control plane is often the weakest point.

• Protect the webhook. Set a secret_token in setWebhook. Telegram sends it in the X-Telegram-Bot-Api-Secret-Token header on every update, so you can reject forged requests.
• Guard the bot token. It is a full credential. Keep it in a secret store, rotate it if exposed, and never ship or commit it.
• Authorize bot commands. Admin actions need server-side authorization keyed to a verified user, not chat membership alone.
• Link opening. openLink runs only on user interaction. Check that deep links and navigation cannot be driven to phish the user.

The Banana Gun exploit

In September 2024 the Telegram trading bot Banana Gun lost about $3 million from 11 users’ wallets.

The team first suspected a front-end vulnerability, then pointed to a potential vulnerability in the Telegram message oracle it used. It said its back-end systems were not compromised.

It switched off its EVM and Solana bots, then brought them back after a patch with a two-hour transfer delay and two-factor authentication for transfers.

It refunded affected users from its treasury.

The contracts were not the story; the offchain path between the user and the chain was. Guardian makes the same point about DeFi in onchain vs offchain crypto hacks.

The Telegram Mini App pentest checklist

Confirm each of these before an external engagement.

• initData is validated server-side on every request, with the correct HMAC-SHA256 construction and constant-time comparison.
• auth_date is checked against a short window to block replay.
• User identity comes only from validated initData, never initDataUnsafe or client fields.
• Every value-moving action enforces server-side authorization and object-level ownership checks.
• Withdrawals, trades and transfers are safe against replay, reordering and concurrent-request races.
• Wallets are verified with a signed, single-use challenge (for example ton_proof) bound to domain, timestamp and network.
• The bot token and any private keys never reach the client.
• Secrets use a server-side store or SecureStorage, not CloudStorage or DeviceStorage.
• The webhook enforces the X-Telegram-Bot-Api-Secret-Token header and rejects forged updates.
• Bonus, referral and airdrop logic cannot be replayed or driven from the client.
• Custody or MPC key handling, if present, is tested as its own system.

How Guardian pentests Mini Apps

Guardian’s offchain security department is led by Carlos Polop, creator of HackTricks and the PEASS suite.

Its web application pentest maps every form, background request, socket and wallet interaction a user can reach, at every privilege level, then tests each one.

The bot’s backend falls under the API pentest, and the relayers and bots that submit transactions under the offchain automation pentest.

On the Avantis offchain review, two independent teams reviewed the backend between a trader and the chain: order engines, risk engine and relayer.

It returned 68 findings, including two Critical and six High severity issues. Both Criticals were fixed while the review was still running.

Related: crypto wallet pentesting and the MCP pentesting checklist.

Frequently Asked Questions

How do I secure a Telegram Mini App?

Validate initData on your backend on every request, never trust initDataUnsafe, and take user identity only from validated data. Authorize every value-moving action server-side, verify wallets with a signed challenge such as ton_proof, and protect the bot token and webhook.

What is initData and how do I validate it?

It is a signed query string Telegram passes to the Mini App. On the server, build the data-check-string, compute its HMAC-SHA256 with a key derived from the bot token and WebAppData, compare it to the received hash, and check auth_date.

Can I trust initDataUnsafe in a Telegram Mini App?

No. Telegram’s documentation says data from initDataUnsafe should not be trusted. Validate the raw initData string on the bot server, and only then use the data.

Where should a Telegram Mini App store secrets and keys?

Not in the client. The bot token stays on the server, and user-specific secrets go in SecureStorage, not CloudStorage or DeviceStorage. Private keys for funds belong behind the user’s own wallet or in a reviewed custody service.

Sources

• Telegram: Telegram Mini Apps documentation
• Telegram: Bot API, setWebhook and secret_token
• TON: Authenticate users with ton_proof
• OWASP: Web Security Testing Guide (WSTG 4.2)
• The Block: Banana Gun to refund $3 million after exploit (September 25, 2024)
• Guardian: Avantis offchain review case study
• Guardian: Web application pentest
• Guardian: API pentest