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.
05Costs not included in the price: who pays
The item price covers the source code and this documentation. Everything below runs under your accounts and is billed to you by its provider. Check each provider's current pricing; usage above a free tier is yours to pay.
| Service | Needed? | Who pays, and what for |
|---|---|---|
| VPS, domain, TLS, static hosting | Required | You, to your hosting and domain providers: the API and PostgreSQL (Docker), https for the API, the Mini App and the admin. |
| Telegram Bot API | Required | No charge at the time of release. One bot per campaign from @BotFather; Telegram's terms apply. |
| Telegram Stars | Optional | Players pay in Stars; Telegram pays your developer share (about $0.013 per Star at release) through Fragment, on Telegram's schedule. |
| TON network fees | For an airdrop | You (operator wallet): about 0.1 TON attached to each deploy, fund and owner message, partly refunded. Players pay their own claim, net about 0.03 TON. See TON costs. |
| The jetton you distribute | For an airdrop | You or your client: the tokens in the distributor. |
| toncenter API key | Optional | Free tier at the time of release; higher limits are a paid toncenter plan. Turns on the two wallet anti-bot checks. |
| Adsgram | Optional | Your own publisher account; Adsgram pays you for rewarded ads under its terms. |
| Contract audit, legal opinion | Recommended | You, before mainnet value and before the first client. |
Nothing is paid to MIKODES per campaign, player or transaction. The code has no revenue share and sends no data to the author.
06Operating system
Developed and tested on macOS and Linux. On Windows, run the commands in WSL 2 (Ubuntu); the production server is Linux with Docker.