● Start · What you need
Requirements
tools, accounts, hosting.
What must be installed on your computer and your server, which accounts you need, and what is optional.
01On your computer
| Tool | Version | Why |
|---|---|---|
| Node.js | 22 or newer (engines: node >=22) | Runs the API, builds the web apps. |
| pnpm | 10 (the repo pins pnpm@10.33.2; corepack enable installs it) | Workspace package manager. npm and yarn are not supported. |
| PostgreSQL | 16 | Database for local development and tests. |
| OpenSSL | any | Generates the secrets in .env. |
| A modern browser | Chrome, Edge, Firefox or Safari | Admin panel, TON Connect. |
02On your server
| Item | Notes |
|---|---|
| Linux VPS | Small is fine to start (1–2 vCPU, 2 GB RAM is a reasonable starting point, not a measured minimum). Runs PostgreSQL + API. |
| Docker Engine with the Compose plugin | docker compose up -d --build builds the API image (Node 22 Alpine) and starts PostgreSQL 16. |
| A reverse proxy with TLS | Caddy, nginx + certbot or Traefik. Telegram only loads Mini Apps and delivers webhooks over https. |
| A domain | Three hostnames under one registrable domain, for example api.example.com, play.example.com, admin.example.com. The admin must be on the same site as the API (see same-site cookie). |
| Static hosting | For the Mini App and the admin: any static host (Cloudflare Pages, Netlify, nginx, Caddy on the same VPS). |
03Accounts
| Account | Required? | What for |
|---|---|---|
| Telegram account | Required | Create bots with @BotFather; test the Mini App. |
| One Telegram bot per campaign | Required | Free from @BotFather. The same bot cannot serve two campaigns. |
| TON wallet with TON Connect | Required for the airdrop | Operator wallet that deploys, funds and withdraws the distributor (for example Tonkeeper). Players link their own wallets; supported wallet versions: v3r1, v3r2, v4r2, v5beta, v5r1. |
| TEP-74 jetton | Required for the airdrop | The token you distribute. A testnet jetton for testing. |
| toncenter API key | Optional | Turns on the two wallet anti-bot signals. Without it those checks are skipped and reported as skipped. |
| Adsgram publisher account | Optional | Rewarded ads. Only Adsgram is implemented; Monetag shows as "not supported yet". |
04Only if you change the contract
The compiled contract and its TypeScript wrapper are committed in packages/ton-claim/src/generated/, so you never need the Tact compiler to build or run the kit. Only if you edit contracts/merkle_distributor.tact, run pnpm --filter @kit/ton-claim build (Tact compiler, installed as a dev dependency) and then have the change audited.
05Running costs you pay
- Server, domain and hosting at your provider's prices.
- TON network fees: about 0.1 TON attached to each deploy, fund and owner message (the unused part is refunded where the chain allows it). Players attach 0.1 TON to a claim and get most of it back; the measured net cost is about 0.03 TON. See TON costs.
- Nothing is paid to MIKODES per campaign, player or transaction. The code has no revenue share.