GameFi Telegram Mini App development

GameFi Telegram Mini App Development

Telegram Mini Apps opened unexpectedly effective channel for GameFi: 900 million users, native distribution via links and bots, built-in payments, and for Web3—TON wallet directly in app via TonConnect. Hamster Kombat, Notcoin, Catizen proved that tap-to-earn + referral + airdrop can gather tens of millions users in weeks.

GameFi Mini App development is intersection of three disciplines: Telegram Web Apps API, blockchain integration (usually TON, sometimes EVM via WalletConnect), and viral growth mechanics.

Telegram Mini App: Technical Context

Mini App is ordinary web app (HTML/JS) running in embedded WebView inside Telegram. Available via:

• Bot button (keyboard_button with web_app type)
• Inline button in message
• Direct link t.me/botname/appname
• @gamestore

Telegram passes app initData—string with user data and signature. Critical for GameFi: backend must verify initData to prove request comes from real Telegram user:

import crypto from 'crypto'

function verifyTelegramInitData(initData: string, botToken: string): boolean {
  const params = new URLSearchParams(initData)
  const hash = params.get('hash')
  params.delete('hash')
  
  // Sort parameters and form data-check-string
  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n')
  
  // HMAC-SHA256 with key derived from bot token
  const secretKey = crypto.createHmac('sha256', 'WebAppData')
    .update(botToken)
    .digest()
  
  const expectedHash = crypto.createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex')
  
  return hash === expectedHash
}

Without initData verification—anyone can fake requests. Security hole #1 in Mini App games.

TON Integration via TonConnect

TonConnect—standard for TON wallet connection to Mini Apps. Supported by Tonkeeper, TON Wallet (built into Telegram), MyTonWallet.

import TonConnect from '@tonconnect/sdk'

const connector = new TonConnect({
  manifestUrl: 'https://mygame.com/tonconnect-manifest.json'
})

const wallets = await connector.getWallets()
await connector.connect({ jsBridgeKey: 'tonkeeper' })

connector.onStatusChange((wallet) => {
  if (wallet) {
    updateGameState(wallet.account.address)
  }
})

Jetton transfers (TON ERC-20 equivalent):

import { toNano, beginCell, Address } from '@ton/core'

await connector.sendTransaction({
  messages: [{
    address: jettonWalletAddress,
    amount: toNano('0.05').toString(),
    payload: beginCell()
      .storeUint(0xf8a7ea5, 32) // op::transfer
      .storeUint(0, 64)          // query_id
      .storeCoins(tokenAmount)   // amount
      .storeAddress(Address.parse(recipientAddress))
      .storeAddress(Address.parse(responseAddress))
      .storeBit(0)
      .storeCoins(toNano('0'))
      .endCell()
      .toBoc()
      .toString('base64')
  }],
  validUntil: Math.floor(Date.now() / 1000) + 300
})

TON transaction model is async: messages queue between contracts, no atomic composability like EVM. For GameFi: result requires polling, can't just await receipt.

Game Loop Architecture

Frontend (React + Telegram Web Apps SDK)

const tg = window.Telegram.WebApp

useEffect(() => {
  tg.ready()
  tg.expand()
  tg.HapticFeedback.impactOccurred('light')
}, [])

const handleTap = async () => {
  tg.HapticFeedback.impactOccurred('medium')
  
  const response = await fetch('/api/tap', {
    method: 'POST',
    headers: {
      'X-Telegram-Init-Data': tg.initData
    }
  })
  const { newBalance, reward } = await response.json()
  setBalance(newBalance)
  showRewardAnimation(reward)
}

Backend (Node.js + PostgreSQL + Redis)

Game state in DB. On-chain only for withdraw or NFT mint. Main endpoints:

• POST /api/tap—register tap, return reward
• GET /api/leaderboard—top players
• POST /api/claim—withdraw to blockchain
• POST /api/referral/apply—apply referral code

Rate limiting mandatory: Redis + sliding window.

Blockchain Layer (TON/EVM)

Only for:

• Final balance storage (claim ops)
• NFT items
• Governance token

Intermediate balances—off-chain in PostgreSQL. Only approach working at millions of users.

Viral Mechanics: Referral System

Deep link: https://t.me/${BOT_USERNAME}?start=ref_${userId} Mini App link: https://t.me/${BOT_USERNAME}/${APP_NAME}?startapp=ref_${userId}

Structure: direct referrals (bigger bonus) + referrals of referrals (smaller). Limit depth to 2-3 levels max. Multi-level = MLM, bad reputation.

Daily missions + streak—retention. Daily tasks + streak bonuses.

Airdrop Mechanic: Snapshot and Distribution

Standard pattern:

1. Game for N months—no token
2. Snapshot balances on date
3. TGE—token created
4. Airdrop proportionally

For large scale (millions addresses)—merkle tree distribution. Users claim via merkle proof.

Monetization Models

Stack

HTTPS mandatory—Telegram Mini Apps work only over HTTPS.

Timeline

MVP tap-to-earn with basic mechanics, TON wallet, referral, leaderboard: 3-4 weeks.

Full GameFi Mini App with NFT, airdrop, tournament, TON jetton, governance: 2-3 months.