Explore in Telegram

apiton guide

How to build a TON Site and put it on a .ton domain

Updated

Open in @apitonBotcheck any username, number or domain live in Telegram

A TON Site is an ordinary website — HTML, CSS, pictures — served inside the TON network instead of the web: the site record of a .ton domain points to an ADNL server reached over RLDP, or to a TON Storage bag. Any website can be put there, but not every website works once it is: visitors reach it through a proxy or a gateway, over http://, and often without the rest of the web. This guide has two parts: how to design a website so that it works as a TON Site, and three ways to put it on a .ton name. The rules come from what apiton runs itself: the servers behind apiton.ton and its customers' sites, the ton.direct gateway and the probe behind Live TON Sites.

How visitors reach a TON Site

The same site is opened at three kinds of address (more in How to open a TON Site):

  • http://shop.ton/ — with a TON proxy on the computer or a wallet with a TON browser. The proxy finds the server through the DHT and fetches the page over RLDP.
  • https://shop-dton.magic.org/ — in Telegram, which opens .ton addresses through magic.org's gateway, a server running TON's reference rldp-http-proxy.
  • https://shop.ton.direct/ — apiton's gateway, behind the View button of Live TON Sites, in any browser.

Each address is a different origin, reached through software you do not control, with rules of its own. A page that works at all three is a page that does not care which one it is on.

Part 1. Design a website that works as a TON Site

Write links to your own pages as paths: /about/, about.html, /css/site.css. They work at every address above. An absolute link to your own address breaks somewhere: https://shop.example.com/about/ takes the visitor out to the ordinary web, and http://shop.ton/about/ opens only with a TON proxy. ton.direct turns links to .ton hosts into its own addresses, but nothing turns links that JavaScript builds while the page runs. Keep <base href> off, or relative.

Link other TON Sites as http://name.ton/: that is the form ton.direct rewrites, and apiton counts such links between sites when it ranks Live TON Sites.

Redirects: stay on the same host

A redirect to another page of your site is fine when its Location is a path: Location: /en/. A redirect to an absolute address is not:

  • Telegram's gateway passes Location as it is, so Location: http://shop.ton/en/ does not open there, and https://shop.example.com/en/ takes the visitor off the TON Site;
  • apiton's probe marks a home page that answers with an HTTP redirect to another host as parked, not live. A small or placeholder page that leaves TON by <meta http-equiv="refresh"> or by a script is parked too, and a page that leaves TON gets no screenshot.

apiton's nodes turn a redirect to the website's own web address into a path; another server may not.

Resources from other hosts

Fonts from a font service, a script or a stylesheet from a CDN, an analytics counter, a map, an embedded video, an API on another domain: each loads only when the visitor's TON browser can reach the ordinary web, and some visitors use TON exactly because they cannot. Serve your own copies of fonts, scripts and stylesheets from your site, and let the page read well without the rest. A page that is nothing but an <iframe> of an ordinary website shows an empty frame without the web — apiton has met such TON Sites.

http://, cookies and headers

Inside TON the address is http://shop.ton/, and the browser treats the site as plain http:

  • cookies marked Secure, and cookies named __Secure-… or __Host-…, are refused;
  • a Content-Security-Policy with upgrade-insecure-requests sends every picture and script to https://shop.ton/, which does not exist;
  • a CSP or a CORS policy that names your web domain, and service workers, can break the page;
  • Strict-Transport-Security means nothing there (apiton's nodes drop it).

Through ton.direct a site gets no cookies at all: the gateway drops Set-Cookie and never passes the visitor's cookies on. In Telegram the origin is magic.org's. So do not build on cookies: no sign-in, no session, no cart kept on the server.

Read only: no forms that send data

apiton's nodes and ton.direct pass only GET and HEAD and answer anything else with 405. A form that posts — contact, sign-in, checkout, a comment — does not work there. A search form with method="get" is an ordinary GET with a query and works. For contact, give a Telegram link or an email address.

Keep pages light

Every file is a separate request through the visitor's proxy or a gateway, over UDP. In apiton's measurements of September 2026, the first request to a site on an ADNL server took 0.7–1.1 s and the next ones 0.16–0.25 s; a site in a TON Storage bag took 2 to 17 s the first time. One page view of a Next.js site — the HTML, 32 files and prefetches of the menu's links — was 50 to 100 requests in 1–2 seconds. So:

  • fewer files: bundle CSS and JavaScript, draw small icons with inline SVG;
  • compressed images with width and height;
  • no prefetching of every link on the page;
  • HTML, CSS and scripts compressed with gzip when the request accepts it: apiton's nodes pass a compressed answer as it is, and gzip passes whether or not they rewrite links;
  • a correct Content-Type on every file: ton.direct passes HTML, CSS, JavaScript, JSON, XML, text, images, fonts, audio, video, WebAssembly and PDF, and answers 415 to anything else, archives and application/octet-stream included.

The limits a page meets on the way:

Where One answer Time Also
ton.direct 10 MB; HTML and CSS 2 MB 30 s 8 requests at a time to one site
apiton's node, your website on .ton 16 MiB your website answers within 15 s 5 GB per 30 days; the other limits are on the order page
apiton's probe the first 256 KB of the home page 15 s (30 s for a Storage bag) GET /, redirects on the same host followed

Static is best

The TON Site that works everywhere is a static one: pages as files, made in advance by a static site generator or by hand. It needs no cookies and no forms, passes every proxy and gateway, and can even live in a TON Storage bag. A single-page app (React, Vue and the like) that draws the page with JavaScript works, with two catches:

  • calls to its own API at an absolute https:// address fail on the .ton name — the browser refuses such cross-origin calls; relative paths (/api/…) work;
  • apiton's probe sees an empty shell and can judge the site only by its screenshot. Pre-rendered HTML gives the text to the probe, the screenshot and the visitor at once.

Title, description, icon and your own content

apiton's probe asks for your home page with Host: shop.ton and the User-Agent apiton-tonsite-probe/1 (+https://apiton.org), every 6 hours once the site is live. From the first 256 KB it keeps:

  • the <title> — the site's name in Live TON Sites and on the domain's page;
  • <meta name="description"> — the text of the site's card;
  • og:image and <link rel="icon"> — the card's picture while there is no screenshot.

So put the title and the description near the top of <head>, and add an icon. The rank of the list weighs uptime (0.35), links from other live TON Sites (0.20), speed (0.15), content (0.10), age (0.10) and visits through apiton's gateway (0.10). Content is counted from what a person sees: words of the main text (not the menu or the footer), links to your other pages, headings <h1>–<h3> and pictures. Placeholder text (lorem ipsum, "coming soon") and a template shared word for word with other sites cut it.

What makes a home page "parked"

The probe marks a site parked instead of live when its home page:

  • answers with a redirect to another host, or is a small or placeholder page that leaves TON by a refresh or a script (above);
  • is a domain-for-sale page, or a "Transfer to name.ton" page of a wallet;
  • is an anti-bot check — "Just a moment…", "Checking your browser", Cloudflare's challenge;
  • has the bare domain name as its title, under 4 KB with less than 80 characters of text, or a placeholder title such as "Coming soon", "Under construction", "Welcome to nginx!" or "It works!" on a small page;
  • is the same page that 20 or more domains serve.

An error page sent with status 200 — a title like "404 - Page Not Found" — counts as an error, not as live. So give the home page real text of its own, and keep anti-bot checks away from it.

In Telegram

Telegram opens .ton addresses through magic.org's gateway, so a site that should open from a chat needs:

  • relative links and redirects (above);
  • a server that speaks RLDP2: since June 2026 the reference rldp-http-proxy sends no request to a server that does not say it supports RLDP2 (apiton's servers do since 2 November 2026);
  • answers with either Content-Length or Transfer-Encoding: chunked, never both — that proxy refuses an answer that carries both;
  • a server that keeps the gateway's ADNL connection open: the gateway comes back to it after minutes or hours, and a server that has closed it meanwhile makes the first open fail while a reload works. apiton's servers keep such connections for 24 hours since 15 November 2026.

A page built as a Telegram Mini App draws nothing when it is opened as a TON Site: it waits for launch data that only Telegram gives it.

A checklist

  • links and redirects to your own pages are paths;
  • fonts, scripts and stylesheets are your own files, and the page reads without the ordinary web;
  • no form that posts, no sign-in, nothing that needs a cookie;
  • no upgrade-insecure-requests in the CSP;
  • the home page has a <title>, a description, an icon and text of its own;
  • no anti-bot check, sale banner or placeholder title on the home page;
  • HTML and CSS under 2 MB, every file under 10 MB, a few dozen requests per page at most.

Part 2. Put the site in TON

Whichever way you choose, the domain's site record ends up pointing to an ADNL id — the address of the server that answers for the name — or to a TON Storage bag. The owner changes a record with one transaction from the wallet that holds the domain; about 0.05 💎 of it stays on the domain and renews it for a year.

1. Your own node

You run a reverse proxy that speaks ADNL and RLDP on a public UDP port and hands every request to your web server as plain HTTP. TON's reference C++ rldp-http-proxy has such a mode, and Tonutils Reverse Proxy is one in Go; apiton's own server for apiton.ton is written in Go after the same pattern. What running apiton.ton since 7 October 2026 has taught:

  • A public IP address and an open UDP port. The node publishes its address in the DHT, so it must be the address the world sees, not a guess.
  • The key is the site. The ADNL id in the site record is derived from the node's private key. Keep a copy: a lost key means a new id and a new transaction.
  • It must keep running. A node that has been down longer than its DHT entry lives looks to every client like "not in the DHT", although the record is right.
  • The Host header. Requests arrive with Host: shop.ton. Your web server must answer that name, or the proxy must send your web name instead. One ADNL id can serve many domains, told apart by Host.
  • No loop to https. If your web server sends every http request to its https address, point the proxy at the https port: otherwise every page is a redirect to itself (apiton's server answers such a loop with 502).
  • Telegram needs RLDP2 and the other points above.

Then set the domain's site record to the node's ADNL id, for example on dns.ton.org.

Pros: your own server, headers and limits; nobody else in the path; no fee beyond the server and the record. Cons: you run, update and watch a UDP service; when it stops, the site is gone for everyone.

2. apiton serves the website you already have, on your .ton domain

You have an ordinary website on https and a .ton domain. On Your website on .ton, you connect the wallet that holds the domain, give the website, and pay from that wallet: one transaction pays and points the domain's site record to apiton's customer node, which then takes every page from your website. The price is 1 GRAM (1 💎) per 30 days, up to 12 periods in one payment; moving the order to another website later costs 0.15 💎. The steps, the website check and what to do when the website is behind Cloudflare are in Put your website on your .ton domain.

Pros: no server in TON; your website stays on the web, where search engines index it; apiton checks it every day and, if you follow the order in @apitonBot, says when a check fails; once live, it appears in Live TON Sites and opens on ton.direct. Scripts are kept on the node for 10 minutes, so a page view does not fetch them all from your website each time — and a changed script can take that long to arrive; put a hash in its file name.

Cons:

  • only GET and HEAD, the limits in the table above;
  • apiton's node does not rewrite pages: an absolute link to your website leads to the ordinary web;
  • one second-level domain (shop.ton), no subdomains; no uptime guarantee;
  • no drugs, weapons, gambling, adult content, fraud, phishing or anything else the terms forbid.

3. A name under apiton.ton

No .ton domain? While the order page shows a price for it, take a name like shop.apiton.ton for 0.3 💎 per 30 days. There is no NFT and no record to set: every name under apiton.ton already points to apiton's customer node. Any wallet may pay, and the first payment claims the name for your order for as long as it is paid. The name is one label of 4 to 63 characters (a–z, 0–9, -, not at either end); names apiton keeps, like www, api or wallet, are refused. The website is checked and served exactly as in way 2.

Pros: the cheapest start, no domain to buy. Cons: for now such a name opens only with a TON proxy or a TON browser — not on ton.direct — and is not listed in Live TON Sites; everything else from way 2 applies.

TON Storage

A site record can also point to a TON Storage bag: the site's files themselves, handed out by the peers that hold the bag, with no server. apiton's probe and ton.direct open such sites, but a bag no peer holds does not open at all, and a cold bag took 17 s on the first request. It suits a fully static site only; apiton does not host bags, and this guide does not cover making one.

Which way to choose

Your own node Your website via apiton A name under apiton.ton
You need a server with UDP, a .ton domain an https website, a .ton domain an https website
Price the server, about 0.05 💎 for the record 1 💎 per 30 days, about 0.05 💎 for the record 0.3 💎 per 30 days
Requests what your software passes GET, HEAD GET, HEAD
ton.direct, Live TON Sites yes, once live yes, once live not yet

After the site goes live

  • apiton's catalog reads the new site record some time after the transaction; the probe then checks the site, and a live one appears in Live TON Sites and Recently live, with a View button that opens it on ton.direct.
  • The domain's page shows the latest probe — status, title, uptime and response time; see foundation.ton. To check a domain in Telegram, send its name to @apitonBot.
  • Search engines do not index TON Sites through ton.direct: it answers robots.txt with Disallow: / and marks every page noindex. For search traffic, keep a version on the web — way 2 does that by itself.
  • TON Sites about drugs, weapons, gambling, pornography, fraud and other illegal content are listed by name only in Restricted TON Sites and never opened.
Try it in @apitonBotfree: look up, watch and get alerts in Telegram

Read more on the blog

More guides

Explore the catalog

Search

Open in @apitonBot