Campaign Kit
from bot token to fair airdrop.
Everything you need to install, host and run the MIKODES Campaign Kit: a white-label Telegram Mini App campaign with seasons, squads, quests and a bot-filtered, auditable airdrop claim on TON. Read it top to bottom the first time. After that, press / and search.
01What the Campaign Kit is
The Campaign Kit runs a token project's pre-launch campaign inside Telegram. Players tap and farm points, buy upgrades with points, keep a daily streak, solve a daily puzzle, complete quests, invite friends (two referral tiers), join squads, progress through a season with a cosmetic season pass, and can buy cosmetic items with Telegram Stars. The campaign ends with a bot-filtered, auditable airdrop claim on TON.
One installation runs many campaigns. Each campaign has its own Telegram bot, brand, economy, quests, shop and airdrop, all managed from one admin panel. That makes it suitable for agencies that run campaigns for several clients.
You host everything. The server never holds a private key and never signs a transaction: your wallet deploys and funds the airdrop contract, and each player claims with their own wallet.
| Part | Path | What it does |
|---|---|---|
| API | apps/api | Hono 4 on Node 22 + PostgreSQL 16. Player auth (Telegram initData), game, quests, referrals, seasons, squads, puzzles, achievements, Stars, ads, wallets, bot webhook, admin API with roles and audit log, analytics, tracked links, client reports, broadcast worker, sponsors, revenue. Port 8787. |
| Mini App | apps/miniapp | The player app inside Telegram (React 19, Vite, Tailwind v4). Tabs Play · Quests · Squad · Airdrop (Fairness Center), plus Season pass, Boost and Friends pages and a Profile sheet. Port 5173 in development. |
| Admin | apps/admin | The operator panel (React 19). Launch checklist, seasons, events, quests, puzzles, squads, players, anti-bot, fairness, airdrop, economy, broadcasts, shop, reports, links, sponsors, revenue, clients, team, audit log. Also serves the public client report page /r/<token>. Port 5174 in development. |
| Anti-bot + airdrop | packages/airdrop | Explainable abuse signals, fairness multipliers, snapshot, allocation, publish. |
| TON claim | packages/ton-claim | Tact Merkle distributor contract for one TEP-74 jetton, plus TypeScript builders for deploy, fund, claim and withdraw. |
| Shared | packages/shared, packages/db | Economy math, API schemas, database schema and SQL migrations. |
02Rules the product enforces
These rules are enforced in the code, not just recommended. They protect you and your clients, and they are part of what you sell: a fair, bot-filtered airdrop.
- Stars buy cosmetics only. Never points, energy, boosts, XP or airdrop allocation. The premium season pass unlocks cosmetics and badges only. The API has no code path that gives points for Stars.
- No paid randomness. No paid spins or mystery boxes.
- Server-authoritative game. Taps are capped by rate and energy on the server. The client is never trusted.
- Honest data. No seeded players, squads, leaderboards or statistics. Empty screens say so.
- Private by default. Admin lists redact usernames, Telegram IDs and wallets; every reveal is written to the audit log. TON Connect analytics are off.
- Non-custodial. Deploy and funding are signed by the operator's wallet, claims by each player's wallet.
- Airdrop from lifetime points. Allocation uses points earned by playing (lifetime total), so spending points on upgrades never lowers a player's airdrop basis.
03What is in the source
| Folder / file | What it is |
|---|---|
apps/api, apps/miniapp, apps/admin | The three applications (see the table above). Each has its own README.md. |
packages/* | Shared libraries: airdrop, ton-claim, shared, db (schema + migrations in packages/db/migrations). |
e2e/ | One end-to-end airdrop test that runs the real API, database and contract in a TON sandbox. |
docker-compose.yml, apps/api/Dockerfile | Production deployment of PostgreSQL + API. |
.env.example | Template for the single configuration file every app reads. Copy it to .env. |
docs/CONTRACT.md, docs/CONTRACT-V2.md | Technical contract between the parts (API routes, schemas). For developers. |
docs/v2/BUSINESS-MODEL.md | "How you can earn": revenue streams with sourced benchmarks. Summarised on Revenue & how you earn. |
| This documentation | Open index.html in any browser. It also works offline, including search. |
A server (VPS) with Docker, a domain with https, one Telegram bot per campaign (free, from @BotFather), a TON wallet for the operator, and, for an airdrop, the TEP-74 jetton you distribute and the TON for network fees. Optional: your own toncenter API key and an Adsgram account. None of these are included.
04The six-step path
- Install the toolsNode.js 22, pnpm 10, PostgreSQL 16. See Requirements.
- Run it locallyInstall, create the database, start everything, create your owner account. See Quick start.
- Create the botOne bot per campaign from @BotFather, connected in the admin's Launch checklist. See Telegram bot & first campaign.
- Deploy on httpsAPI + PostgreSQL with Docker Compose behind a TLS reverse proxy, Mini App and admin on static hosting. See Production deployment and Configuration.
- Run the campaignBranding, economy, quests, seasons, events, squads, shop, ads, tracked links, broadcasts, client reports. See Running a campaign and Growth & clients.
- Finish with the airdropAnti-bot review, fairness rules, snapshot, publish, deploy and fund the distributor from your wallet, players claim. Testnet first. See Fairness and Airdrop runbook.
05How to read these docs
- Commands in dark boxes are meant to be copied. Use the Copy button in the top-right corner of each box. Run them from the repository root unless the text says otherwise.
- Text in angle brackets, like
<slug>, is a placeholder. Replace it, brackets included. example.comhostnames are examples. Use your own domain.- Required marks steps you cannot skip.
- Screenshots come from a local test installation. Names and numbers in them are sample data.
06Before real value is involved
- The distributor contract has an automated test suite and a self-review checklist, but no independent security audit. Have it audited by a third party before it holds meaningful value, and run the whole airdrop on testnet first.
- Legal compliance is your responsibility as the operator: points, Telegram Stars, rewarded ads and a later token distribution can be regulated differently in each country. Get one legal opinion for your jurisdiction before your first client.
- Never promise players money, profit or a token price. Talk about points, rewards and airdrop eligibility.