apiton guide
How to build a TON Site and put it on a .ton domain
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.tonaddresses through magic.org's gateway, a server running TON's referencerldp-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
Links: relative, never your own address
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
Locationas it is, soLocation: http://shop.ton/en/does not open there, andhttps://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-Policywithupgrade-insecure-requestssends every picture and script tohttps://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-Securitymeans 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
widthandheight; - 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-Typeon 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 andapplication/octet-streamincluded.
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.tonname — 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:imageand<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-proxysends no request to a server that does not say it supports RLDP2 (apiton's servers do since 2 November 2026); - answers with either
Content-LengthorTransfer-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-requestsin 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
siterecord 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
GETandHEAD, 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
siterecord 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.txtwithDisallow: /and marks every pagenoindex. 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.