Case Study: Mothers – A Telegram Mini App Showcase for Tasks, Referrals and Collectible Characters

The Telegram Mini App Opportunity and the Need for Transparent Case Studies

Most case studies published by Web3 development agencies rely on unverifiable marketing metrics: vague claims of "20x active users," simulated engagement surges, and cherry-picked vanity numbers. For crypto founders and product owners preparing a launch, these narratives obscure the operational realities and engineering requirements of building software inside Telegram.

The platform's audience scale is documented. According to TechSpot reporting on platform data, Telegram passed 1 billion monthly active users (MAU) in March 2025. Mini Apps have driven a significant portion of this activity: data published by Game World Observer shows that more than 500 million of Telegram's roughly 950 million MAU interacted with Mini Apps in 2024.

Despite this reach, crypto airdrop mini apps and tap-to-earn systems often fail due to structural exploitation. Projects routinely encounter the same technical bottlenecks:

• Sybil scripts and bot farms: Automated accounts hitting API routes to drain reward pools.
• Spoofed task verification: Client-side triggers bypassed by users claiming rewards without executing the required actions.
• Referral loop manipulation: Nested fake accounts farming tier rewards without generating authentic activity.
• UX drop-off from mandatory wallet connections: Forcing Web3 wallet authorization on step one instead of tracking progress through secure in-app state.

Demonstrating Architecture via the Mothers Showcase

To address these vulnerabilities with concrete code rather than theoretical advice, WEB3 Build Studio engineered Mothers (mothersuniverse.xyz). Mothers is a studio showcase, not a client project. Rather than embedding simulated counter widgets to manufacture social proof, the live deployment intentionally displays its real database state—showing 0 participants—functioning as a clean technical reference implementation.

The project demonstrates how to structure a production-grade Telegram referral app and collectible progression system:

By prioritizing server-verified integrity over client trust, the showcase provides a transparent blueprint for teams building Telegram-native Web3 infrastructure.

Unified Codebase: Serving Web and Telegram Mini App from a Single Next.js Application

Maintaining distinct codebases for a desktop marketing presence and an embedded Telegram Mini App introduces duplicate domain logic, split API surfaces, and deployment synchronization overhead. For Mothers (mothersuniverse.xyz), the platform unifies both interfaces within a single Next.js 15 application using React 19, Prisma 6, and PostgreSQL.

Monolithic Route Distribution

The Next.js App Router delivers responsive web pages to external desktop browsers while serving the Telegram-specific client inside Telegram's embedded WebView. Both environments share TypeScript interfaces, backend mutation handlers, and database models:

• Public Web Routes (/): Deliver the desktop landing page, brand presentation, and onboarding direct links to the Telegram bot.
• Telegram Mini App Routes (/app): Render viewport-locked, touch-optimized layouts configured to handle Telegram WebApp window events and theme variables.
• Shared API Routes (/api): Provide shared endpoints for authentication, task processing, and administrative controls.

Self-Hosted Infrastructure via Coolify on Hetzner

The production stack runs on a Hetzner cloud server provisioned and managed through Coolify. Rather than using external serverless hosting with cold starts and connection-pool constraints, this architecture hosts compute and storage in a private network environment.

Zero-Downtime Deployments and Pre-Deployment Migrations

Database schema changes must occur without taking the application offline or exposing inconsistent schema states to live users. Prisma database migrations run automatically inside Coolify as a pre-deployment execution command:

npx prisma migrate deploy

If a migration fails, Coolify aborts the build process before the new container receives incoming traffic.

### Health Probing and Connection Verification

Operational readiness is tracked through a dedicated `/api/health` route. Coolify's container health checks query this endpoint to ensure that the Node.js runtime is responsive and that Prisma maintains an active connection to the PostgreSQL pool:

```typescript
// app/api/health/route.ts
import { NextResponse } from 'next/server';
import prisma from '@/lib/prisma';

export async function GET() {
  try {
    await prisma.$queryRaw`SELECT 1`;
    return NextResponse.json({ status: 'ok', database: 'connected' }, { status: 200 });
  } catch (error) {
    return NextResponse.json(
      { status: 'error', database: 'unreachable' },
      { status: 503 }
    );
  }
}

The reverse proxy routes traffic to the updated container only after `/api/health` returns an HTTP 200 status code, preventing downtime during releases.

## Cryptographic Passwordless Authentication via Telegram initData

Traditional Web3 on-ramps often create drop-off points by prompting users to connect external browser extensions or sign seed-phrase transactions before accessing an interface. In Mothers, wallet connections are not implemented; user balances remain entirely in-app. Instead of relying on manual credentials, magic links, or Web3 wallet sign-ins, the platform relies on Telegram’s native cryptographic handshake through `window.Telegram.WebApp.initData`.

### The HMAC-SHA256 Verification Flow

When a user opens the Mini App, Telegram injects a signed query string containing user identity data, timestamps, and an authentication hash. The backend validates this payload through a standard two-step HMAC-SHA256 process:

1. **Secret Key Derivation**: Compute an HMAC-SHA256 hash using the constant string literal `"WebAppData"` as the key and the Telegram bot token as the message.
2. **Data-Check String Assembly**: Strip the incoming `hash` parameter from the query string. Sort the remaining key-value pairs alphabetically in ascending order and join them using newline characters (`\n`) in `key=value` format.
3. **Signature Validation**: Hash the data-check string using the derived secret key and compare it against the received `hash`.

```typescript
import crypto from "node:crypto";

export function verifyTelegramInitData(initData: string, botToken: string): boolean {
  const params = new URLSearchParams(initData);
  const hash = params.get("hash");
  if (!hash) return false;

  // Reject duplicate keys to avoid parameter pollution
  const keys = Array.from(params.keys());
  if (new Set(keys).size !== keys.length) return false;

  // Validate auth_date freshness (1 hour window)
  const authDate = Number(params.get("auth_date"));
  const now = Math.floor(Date.now() / 1000);
  if (!authDate || now - authDate > 3600) return false;

  params.delete("hash");
  const dataCheckString = Array.from(params.entries())
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join("\n");

  const secretKey = crypto
    .createHmac("sha256", "WebAppData")
    .update(botToken)
    .digest();

  const calculatedHash = crypto
    .createHmac("sha256", secretKey)
    .update(dataCheckString)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(calculatedHash, "hex"),
    Buffer.from(hash, "hex")
  );
}

Defensive Validation Checks

Mothers applies three strict security filters before parsing user records:

• Parameter Integrity: Standard URL parsers may overwrite or group duplicate parameters. The validation routine enforces unique keys to prevent HTTP parameter pollution.
• Replay Protection: The auth_date timestamp is verified against the server clock. Signatures older than 3,600 seconds (one hour) are discarded immediately.
• Constant-Time Comparison: The incoming hex signature is checked using crypto.timingSafeEqual to eliminate timing-attack vectors that could expose signature bytes.

Session Persistence via PostgreSQL

Passing and parsing initData on every HTTP request creates processing overhead. Once validated, Mothers transitions the client to a managed session:

• Token Generation: The server generates a high-entropy, cryptographically random session token (32 bytes).
• One-Way Hashing: Only the SHA-256 hash of this token is stored in the PostgreSQL database via Prisma. Raw session tokens are never saved on the server.
• HttpOnly Cookies: The client receives the raw token inside an httpOnly, Secure, SameSite=Lax cookie.

If an account requires immediate de-authentication, clearing the hashed record in PostgreSQL invalidates the session without rotating the Telegram bot token.

Clean Referral Ingestion via start_param

Deep links structured with Telegram referral parameters (such as t.me/bot?startapp=ref_user123) arrive inside initData as the start_param field. During the initial account creation handshake, Mothers parses this prefix (ref_), links the new user record to the corresponding inviter, and initialises the referral pipeline inside an atomic database transaction. Because the start_param is enclosed in the signed payload, referral codes cannot be injected or modified by the client.

Server-Side Task Verification, Anti-Abuse Referral Loops, and Reward Idempotency

Telegram mini apps handling distribution mechanics frequently encounter automated scripts, repeated network calls, and sybil accounts. To secure the Mothers showcase, the system moves all validation logic to the backend, isolates referral attribution behind strict execution requirements, and processes reward events through an append-only, idempotent ledger.

Engineering the Seven Task Types

The task engine in Mothers supports seven distinct operational task classifications:

• Daily Check-in: The only client-completed action in the app, restricted by an enforced 24-hour server cooldown timestamp.
• Join Telegram Channel: Verified server-side via Telegram Bot API checks (getChatMember).
• Follow Social Accounts: Validated server-side through configured API integrations.
• Invite Friends: Tied directly to qualified referral state transitions.
• Community Mission: Ecosystem engagement milestones verified against platform data.
• Quiz Completion: Question datasets evaluated and scored strictly on the server before awarding status.
• Targeted Campaign Actions: Time-bounded promotional tasks governed by dynamic start and end dates alongside maximum total completions.

Accepting client-reported completion invites exploitation. In Mothers, task requests pass through Prisma to PostgreSQL, where active dates, completion caps, and cooldown windows are verified. Except for the daily check-in, every task requires server-side validation against respective external APIs or internal state before updating.

Anti-Sybil Referral State Machine

Referral abuse distorts distribution metrics when allocations credit immediately upon registration. Mothers implements a deterministic state machine where new invite rows begin strictly in a PENDING state:

User Shares ref_code ──> Invitee Registers (PENDING) │ ┌───────────────────┴───────────────────┐ ▼ ▼ Task Verified + Clean Signals High-Severity Abuse Flag │ │ ▼ ▼ VALIDATED REJECTED

A referral transitions from PENDING to VALIDATED only when two conditions are met:

1. The invited user successfully completes an authenticated, server-verified task.
2. The invited account registers zero unresolved high-severity abuse signals.

State changes execute within atomic database transactions. If an abuse signal triggers or criteria go unmet, the attribution transitions to REJECTED, preventing double payouts and sybil exploitation.

Planning a verified Telegram task engine or referral mini app? WEB3 Build Studio develops production-ready Telegram Mini Apps starting from $700 (standard tiers $1,000–$1,500; pro setups from $2,000). View our delivery scopes on our pricing page or submit project specifications via our contact form.

Reward Ledger Integrity and Idempotency

Point allocations and balances avoid direct, unindexed counter updates. Every reward event is written as an explicit ledger row containing:

• Reward Source: base_airdrop, referral, task, campaign, or admin_adjustment.
• Status: pending, credited, or revoked.
• Idempotency Key: A unique compound hash constructed from the user identifier, task or event ID, and execution cycle.

When network latency causes clients or webhooks to retry an endpoint, PostgreSQL evaluates the unique constraint on the idempotency key. Duplicate requests return the existing record without creating duplicate entries, guaranteeing consistent balances across all distributed tasks.

Gamification Engine: Shared Goals, Evolution Tiers, and Server-Keyed Hatching

The gamification architecture in Mothers balances viral participation with server-enforced game mechanics. Users nurture digital assets across four distinct character families: Pepe, Cat, Axo, and Dino. Progression follows a strict linear state transition: Feeding, Hatching, and Evolution.

Characters advance through five developmental stages (Baby to Legendary), mapping against five distinct rarity tiers spanning Common to Legendary.

Deterministic Rarity and Anti-Tamper Hatching

A recurring vulnerability in casual Telegram games is client-side state manipulation. If egg hatching or rarity rolls occur within the Mini App webview, players can inspect local state, intercept payloads, or replay requests until favorable outcomes occur.

To eliminate client-side tampering, Mothers determines character metadata entirely on the backend using a server-keyed HMAC. When a player initiates hatching, the server calculates a pseudo-random seed using the user ID, the egg entity ID, and the exact timestamp of the hatching transaction:

import crypto from "crypto";

export function resolveCharacterRarity(
  userId: string,
  eggId: string,
  hatchTimestamp: number,
  rarityWeights: { tier: string; weight: number }[]
): string {
  const payload = `${userId}:${eggId}:${hatchTimestamp}`;
  const hash = crypto
    .createHmac("sha256", process.env.HATCHING_SECRET_KEY!)
    .update(payload)
    .digest("hex");

  const roll = parseInt(hash.substring(0, 8), 16) % 10000; // 0 - 9999 basis points
  let cumulative = 0;

  for (const entry of rarityWeights) {
    cumulative += entry.weight;
    if (roll < cumulative) return entry.tier;
  }
  return "Common";
}

The threshold values governing rarity distributions are never hardcoded in client bundles. Instead, configurable drop-rate weights reside in PostgreSQL administrative configuration tables, allowing team operators to adjust drop rates dynamically without redeploying application code.

In-App Ledger Architecture Without Wallet Dependencies

While Mothers serves as a showcase for crypto airdrop mechanics, it deliberately does not implement Web3 wallet connections or on-chain token contracts. All user progression, feeding points, and airdrop allocations reside strictly within the relational database schema.

Managing balances in-app avoids transaction fees, chain latency, and third-party RPC dropouts that degrade onboarding in Telegram webviews. The community leaderboard computes rankings directly from verified internal database ledgers rather than external wallet queries, keeping reads fast and reliable.

Telegram Bot Integration, Automated Cron Queues, and Administrative Control

Operating a Telegram Mini App requires handling incoming interactions and scheduled outbound engagement without bottlenecking the application server or triggering platform-level rate caps. In Mothers, communication between the Telegram platform and the backend relies on an asynchronous event architecture decoupled from primary application state updates.

Decoupled Notification Architecture

Inbound commands hit a dedicated webhook protected by a secret path token. Rather than making blocking HTTP calls to Telegram's Bot API during real-time user gameplay, outbound messages are written as pending records to PostgreSQL. An asynchronous cron queue runs every 10 minutes, processing batched records against Telegram's messaging endpoints.

To maintain user retention and avoid bot mutes, delivery logic checks granular per-user notification preferences before sending. The engine routes communications through nine structured message templates:

• Welcome: Dispatched on initial bot activation with deep links to launch the Mini App.
• Egg Reminder: Alerts players when an egg is ready for feeding or interactions.
• Referral Update: Confirms when an invited user completes validation conditions.
• Task Reminder: Prompts players regarding refreshed daily missions or upcoming resets.
• Energy Milestone: Notifies users when energy stores have fully replenished.
• Hatching Start: Alerts the player that the incubation countdown has commenced.
• Character Hatched: Broadcasts the reveal and rarity of an unlocked character.
• Evolution Complete: Confirms completion of a character evolution cycle.
• Campaign Broadcast: Transmits administrator-initiated ecosystem announcements.

Abuse Signals and Postgres Rate Limiting

To prevent script automation from skewing task analytics or draining reward pools, the database layer enforces strict execution limits. Task completions are throttled at the PostgreSQL level to a maximum of 15 submissions per minute per user. Submissions exceeding this threshold are rejected immediately.

Alongside rate limiting, the platform logs automated abuse signals. Suspicious patterns—such as abnormal execution velocities or referral clustering—are recorded with low, medium, or high severity flags. High-severity signals immediately pause automated reward validations for the associated account until cleared.

Administrative Control

System parameters, task structures, and reward ledgers are managed through a dedicated administrative dashboard built into the Next.js application.

The administrative console provides control over four operational domains:

White-Label Investment Architecture: Voltex Software Showcase

Beyond casual tap games and airdrop distribution mechanics, Telegram Mini Apps can host structured financial dashboards, asset management tools, and white-label investor portals. Voltex is a technical showcase built to demonstrate this architecture.

To be clear on compliance: Voltex is not an active investment fund, security, or yield-generating offer. It manages no real money and promises no financial returns, performance statistics, or yields. This review covers software architecture only, not financial or legal advice. Voltex is strictly a white-label software template that operators can buy, brand, and self-host on their own infrastructure.

Native Interface and Technical Stack

Voltex serves both the investor web portal and the Telegram Mini App from a shared UI entry point. The backend is engineered using Express 5, SQLite, JSON Web Tokens (JWT) for session management, and bcrypt for password hashing.

Within Telegram, the interface avoids custom simulated navigation bars by hooking directly into the Telegram WebApp client SDK:

• Native UI Controls: Integrates Telegram's native BackButton and MainButton for transactional flows.
• Haptic Feedback: Triggers device-level haptic alerts during confirmations, pin entries, and status changes.
• Signed Account Linking: Accounts can never be connected by typing an arbitrary Telegram ID. Linkage requires cryptographically signed launch data (initData) to prevent account spoofing.

Multi-Chain Ingestion and Confirmation Thresholds

Crypto payment processing is integrated via Heleket, supporting Bitcoin (BTC), Ethereum (ETH), TRON (TRX), USD Coin (USDC), and Tether (USDT on both TRC-20 and ERC-20). The service processes signed webhooks alongside a background deposit scanner targeting USDT, USDC, and BTC.

To protect the ledger against chain reorganizations, deposits remain pending until reaching strict block confirmation counts:

Defensive Accounting and Security Controls

Voltex avoids storing mutable user balances. A user's available balance is calculated on demand strictly by aggregating immutable transaction rows, with each transaction protected by a unique idempotency key.

System security rules enforce:

• Rate Limiting: Enforces limits of 5 login or registration requests and 3 password resets per 15-minute window.
• Brute-Force Protection: Automatically locks an account for 15 minutes after 5 consecutive failed access attempts.
• Enumeration-Safe Forms: Registration and recovery workflows return uniform responses to prevent scraping valid user lists.
• Strict Metric Reporting: Any missing data or unpopulated analytics counter explicitly displays "Not available" rather than fallback placeholders. Public stats remain deactivated until verified operational evidence is logged.

Engineering Lessons, Production Costs, and Studio Implementation

Building showcases like Mothers and infrastructure like Voltex highlights core architectural decisions that determine whether a Telegram Mini App functions reliably under real user activity or degrades under bot traffic.

Core Engineering Lessons

Two primary architectural lessons emerged from engineering the Mothers showcase:

1. Server-side verification must precede marketing distribution: Client-completed actions expose apps to automated scripts and falsified task completions. Except for basic daily check-ins, every referral validation, social follow, and reward credit must be verified on the server against idempotent database records and anti-abuse signals before balance crediting occurs.
2. Avoid early wallet connection friction: Forcing users to connect an external Web3 wallet on their first session creates drop-off. Mothers intentionally stores rewards, character states, and egg tiers in-app within PostgreSQL, authenticating users instantly through Telegram initData. Removing wallet connection barriers during initial acquisition enables instant onboarding, while leaving open the option to connect on-chain settlement layers later.

Studio Pricing and Deliverables

WEB3 Build Studio provides fixed-price contracts scoped to eliminate budget ambiguity. Every build includes UI/UX design, custom architecture, database schema modeling, deployment, and 30 days of bug fixes. Custom AI features and payment integrations are quoted separately.

Monthly care on studio-managed servers covers dedicated hosting, SSL management, automated daily backups, performance monitoring, and normal maintenance.

Single-Team Studio Execution

Coordinating separate design agencies, freelance frontend developers, and DevOps contractors introduces integration delays and misaligned schemas. WEB3 Build Studio handles the entire development lifecycle as a single engineering unit, taking projects from initial system architecture and interface design to database construction and server deployment.

Whether you are launching an engagement mini app or need standalone software like the Voltex white-label investment platform, review our services and fixed pricing.

To discuss your technical scope or deploy dedicated software platforms, submit your requirements through our project brief form or visit web3buildstudio.com.

Frequently Asked Questions

Why bypass Web3 wallet connections during initial user onboarding? Mandatory wallet connections add immediate friction for non-crypto users and slow down initial distribution. Storing user balances and reward states in-app via transactional database records allows zero-click onboarding through Telegram authentication while preserving the ability to link wallets for future token events.

Is Voltex an investment fund or an operational software package? Voltex is white-label software that businesses can purchase, brand, and host on their own servers. It is not an investment fund, does not accept customer deposits, and provides no yields or financial returns.

Frequently asked questions

How long does it take to build a Telegram Mini App?

Development timelines depend on feature complexity and scope. A focused Telegram Mini App MVP with standard UI, task verification, and user profiles typically takes 1 to 2 weeks to develop. More comprehensive applications featuring multi-tier referral mechanics, custom interactive designs, and database logic usually require 2 to 4 weeks. High-tier builds incorporating custom AI agents, on-chain transactions, or marketplace logic can take 4 to 8 weeks. Because WEB3 Build Studio operates as a single lean team handling everything from architecture to production deployment without third-party handoffs, development moves fast from idea to release.

How does passwordless login work inside a Telegram Mini App?

Authentication inside a Telegram Mini App operates without traditional passwords or external login screens. When a user opens the Mini App, the Telegram client injects a cryptographically signed data payload (initData) containing the user's ID, name, username, and query validation hash. The frontend transmits this payload to your backend. The server then validates the cryptographic hash using an HMAC-SHA256 signature derived from your bot's secret token. Once verified, the backend creates or resolves the user profile in PostgreSQL and issues a secure session token. The entire process takes milliseconds and requires zero user input.

Can a Telegram referral system prevent fake accounts and bot farms?

Yes, by pairing backend validation with behavioral hurdles. Telegram's signed data payload verifies real Telegram accounts, allowing you to filter out disposable scripts. You can inspect attributes like Telegram Premium status, account age, and username presence. Additional safeguards include IP rate limiting, device fingerprinting, and requiring users to finish initial tasks—such as completing an in-app action or solving a verification challenge—before referral credits activate. Delaying reward claims and checking for suspicious clusters of identical network patterns prevents scripted bot farms from gaming distribution campaigns while keeping genuine user onboarding frictionless.

Do I need an on-chain token or wallet connection to launch an airdrop Mini App?

No, you do not need an on-chain token or a connected wallet to launch. You can track community tasks, collectible characters, and referral leaderboards off-chain using a relational database like PostgreSQL. This structure keeps initial onboarding frictionless because users avoid gas fees, wallet downloads, and blockchain confirmation delays. You can introduce non-custodial wallet connections (such as TON Connect or Solana) and deploy tokens later when you are ready to distribute assets or execute airdrop claims. This approach saves capital and validates product engagement early. This information is for educational purposes and is not financial advice.

Can I white-label investing software like Voltex under my own brand?

While some commercial platforms offer proprietary white-label solutions, WEB3 Build Studio builds dedicated, custom platforms engineered around your specific product requirements rather than pre-packaged templates. For instance, the studio engineered Meridian, an investment platform featuring strategy allocation, automated execution, and portfolio analytics. If you want an investing app or trading tool deployed under your own brand, the studio develops custom architectures using Next.js, Node.js, and secure APIs, giving you full ownership of your IP, custom logic, and data. Note that building or operating investment software involves regulatory responsibilities and this is not financial or legal advice.

What does it cost to build and host a custom Telegram Mini App?

At WEB3 Build Studio, pricing is fixed after a short scoping call. A custom Telegram Mini App starts at $700, with standard feature sets typically ranging from $1,000 to $1,500, and pro-tier applications starting from $2,000. Every project package includes UI design, full-stack engineering, production deployment, and 30 days of bug fixes. Optional add-ons like AI features or external payment integrations are priced based on requirements. Ongoing hosting and care on studio servers costs $79 per month, covering cloud hosting, SSL certificates, automated monitoring, daily backups, and routine maintenance. Review service options at pricing.

Sources

• Telegram Mini App Store Hits 500 Million MAU
• Telegram Reaches One Billion Active Users