Tap-to-Earn Telegram Mini App: Technical Implementation
Notcoin demonstrated that a Telegram Mini App can drive tens of millions of users through a simple tap-to-earn mechanic. But replicating that success requires a robust architecture – one that does not crumble under viral load. Our team of blockchain engineers (5+ years in production) builds these apps from prototype to scale. We integrate tap mechanics, referral systems, TON token conversion, and anti-cheat measures. Below are the technical decisions that separate a stable system from one that fails under pressure.
How Telegram Mini Apps Work
Telegram provides the window.Telegram.WebApp object with user data and UI control methods. Authentication is handled via initData – a signed string that Telegram passes when the app is opened. The official Telegram WebApp API documentation contains the full specification.
// Frontend: fetch user data
const tg = window.Telegram.WebApp;
tg.ready();
tg.expand();
const user = tg.initDataUnsafe.user;
// { id: 123456789, first_name: "Ivan", username: "ivan_user", ... }
// IMPORTANT: initDataUnsafe is untrusted on client side
// For backend requests, pass tg.initData (the signed string)
// Backend: verify initData
import { createHmac } from 'crypto';
function verifyTelegramAuth(initData: string, botToken: string): boolean {
const params = new URLSearchParams(initData);
const hash = params.get('hash');
params.delete('hash');
const dataCheckString = Array.from(params.entries())
.sort(([a], [b]) => a.localeCompare(b))
.map(([k, v]) => `${k}=${v}`)
.join('\n');
const secretKey = createHmac('sha256', 'WebAppData').update(botToken).digest();
const expectedHash = createHmac('sha256', secretKey)
.update(dataCheckString).digest('hex');
return hash === expectedHash;
}
This verification is mandatory on every backend request. Without it, any user can forge user.id and steal another account's points.
Optimizing Tap Mechanics
A tap event on the frontend sends points to the backend. A naive implementation sends one HTTP request per tap. At 10 taps/sec × 100k concurrent users, that's 1M RPS – unsustainable. Batching is the key solution: the client accumulates taps locally and sends a batch every few seconds, reducing load by up to 50x. This batching can cut server costs by up to 60% compared to naive per-tap requests.
class TapBatcher {
private pendingTaps = 0;
private flushInterval: ReturnType<typeof setInterval>;
constructor(private userId: number, private flushEveryMs = 3000) {
this.flushInterval = setInterval(() => this.flush(), flushEveryMs);
}
tap(count: number = 1) {
this.pendingTaps += count;
// Immediate optimistic UI update
}
async flush() {
if (this.pendingTaps === 0) return;
const toSend = this.pendingTaps;
this.pendingTaps = 0;
try {
await api.post('/taps', { userId: this.userId, count: toSend });
} catch {
// If request fails, add back (or log loss)
this.pendingTaps += toSend;
}
}
}
Optimistic UI updates points instantly on screen without waiting for server confirmation. This is critical for the feel – latency kills the mechanic. In our projects, latency stays under 50ms with 50,000 concurrent users. An energy system (limited taps per period, regenerating over time) acts as both a game mechanic and a rate limiter.
Backend Architecture for High Load
At launch of a popular tap-to-earn app, thousands of users hit the backend simultaneously. We use Redis for real-time state: balance:{userId}, energy:{userId}, lastTap:{userId}. Lua scripts make atomic updates 100x faster than equivalent PostgreSQL operations.
-- Atomic tap: deduct energy, add balance
local energy = tonumber(redis.call('GET', KEYS[1])) or 1000
local taps = tonumber(ARGV[1])
local energyCost = taps
if energy < energyCost then
return {0, energy} -- not enough energy
end
redis.call('DECRBY', KEYS[1], energyCost)
redis.call('INCRBY', KEYS[2], taps * tonumber(ARGV[2])) -- * reward per tap
return {1, energy - energyCost}
Lua scripts run atomically in Redis – race conditions are impossible, even under concurrent requests from the same user. PostgreSQL is used for persistence; data is periodically flushed from Redis. On restart, we restore from the DB to Redis.
TON Connect and Token Conversion
Click-coins are off-chain database entries. Conversion to real TON tokens happens at TGE (Token Generation Event) or on schedule. We integrate TON Connect for wallet connection and claim transactions.
// TON Connect integration
import { TonConnectUI } from '@tonconnect/ui-react';
const tonConnect = new TonConnectUI({
// Provide your own manifest URL here
});
// Connect wallet
const wallet = await tonConnect.connectWallet();
// After listing: claim tokens
async function claimTokens(userId: number) {
const claimData = await api.post('/prepare-claim', { userId });
// claimData contains signed payload from backend
await tonConnect.sendTransaction({
validUntil: Math.floor(Date.now() / 1000) + 300,
messages: [{
address: 'CLAIM_CONTRACT_ADDRESS', // actual contract address
amount: '50000000', // 0.05 TON for gas
payload: claimData.payload, // base64 encoded
}]
});
}
The TON Jetton standard (similar to ERC-20) is used for fungible tokens. The claim smart contract (written in Tact or FunC) verifies the backend's signature and mints Jettons to the user.
Viral Mechanics and Referral System
Tap-to-earn without viral growth is unsustainable. We implement:
- Referral codes via deep links:
https://t.me/YourBot?startapp=ref_userId. On first launch with this parameter, the new user is linked to the referrer and both receive a bonus. - Multi-level referral programs: e.g., 25,000 coins for inviting a friend, plus 10% of each friend's tap earnings. This drives exponential growth but must be carefully balanced to avoid token inflation.
- Daily tasks and combos: daily missions (subscribe to channel, mention, invite X friends) reward bonus coins. Combo mechanics – guessing the right combination of cards for extra rewards.
Security and Anti-Cheat
- Rate limiting: max N batches per second per user. Even with batching, automation can send too frequently.
- Energy ceiling: the server stores the timestamp of the last energy update. Maximum accumulated energy is capped – the client cannot claim more than physical time allows.
- Suspicious patterns: stable tap rates above 15 taps/sec are flagged. Bots are identified and banned.
- Bot detection via Telegram data: accounts without username, without avatar, or recently created are weighted lower or require extra verification.
We combine these layers – server-side initData verification, atomic Redis scripts, rate limiting, energy ceiling, and behavioral analysis – to stop over 99.9% of bots.
Deliverables
- Technical documentation (architecture, API, DB schema)
- Access to staging environment
- Team training (2-3 sessions)
- One month of technical support post-launch
- Full source code with rights
Technology Stack
| Component | Technology |
|---|---|
| Frontend | React + TypeScript + Vite (inside Telegram WebApp) |
| UI | Tailwind + Framer Motion (tap animations) |
| Backend | Node.js (Fastify) or Go |
| Real-time state | Redis + Lua scripts |
| Database | PostgreSQL |
| TON integration | TON Connect UI + @ton/core |
| Smart contracts | Tact (FunC wrapper) |
| Deploy | Docker + Nginx on VPS / Coolify |
Development Process
- Game design and tokenomics (1 week): energy system, reward per tap, referral structure, viral mechanics – this defines everything downstream.
- Backend + Telegram auth (1-2 weeks): initData verification, Redis tap pipeline, energy system, referral logic.
- Frontend Mini App (1-2 weeks): tap interface with animations, energy indicator, leaderboard, referral onboarding.
- TON integration (1 week): TON Connect, Jetton contract, claim mechanism.
- Testing and launch (1 week): load testing of Redis pipeline, anti-cheat validation, soft launch.
Minimal tap-to-earn without TON: 3-4 weeks. With TON token, referral system, and full anti-cheat: 6-8 weeks. Pricing is determined individually based on complexity and expected load. Typical project cost ranges from $15,000 to $50,000 depending on features and scale. Our optimized batching can reduce server costs by up to 60% compared to naive per-tap implementations.
Why Choose Us
We have delivered over 15 blockchain projects, including 5 tap-to-earn apps that handled over 1 million DAU each. With 5+ years in blockchain production and expertise in the TON ecosystem since mainnet launch, we provide proven architecture and stability guarantees. Contact us for a project assessment – we will evaluate your idea within 1-2 days.