DEV Community: apiTON

How .ton domains expire, and how to find expired ones

apiTON — Thu, 05 Nov 2026 15:00:00 +0000

A .ton domain is not rented from a registrar. It is an NFT that lives in a smart contract on
the TON blockchain, and its "registration period" is a timestamp stored inside that contract.
This article explains the exact rule, what happens on expiry, and why finding expired domains is
harder than it sounds.

A domain is an NFT in the root DNS collection

Every .ton name is an item of one NFT collection, the TON DNS root:

raw:          0:b774d95eb20543f186c06b371ab88ad704f7e256130caf96189368a7d0cb6ccf
bounceable:   EQC3dNlesgVD8YbAazcauIrXBPfiVhMMr5YYk2in0Mtsz0Bz

The collection follows the NFT standard (TEP-62)
and the DNS standard (TEP-81).
One detail matters a lot for everything below: the index of a domain item is not a running
counter (0, 1, 2, …) but a hash of the name. Given a name you can compute the item address
directly (get_nft_address_by_index with the hashed name), but you cannot walk the collection
from item 0 to item N and list every domain.

The one-year rule

Each domain item stores last_fill_up_time — the moment the owner last "filled up" the
domain. The domain is valid for one year after that. In apiton the expiry is computed as:

expires_at = last_fill_up_time + 31 622 400 seconds   (366 days)

You can read the timestamp yourself with the get-method get_last_fill_up_time on the domain's
NFT item. Two practical notes:

Actions of the owner that rewrite the item — for example changing a DNS record, which is what "renew" buttons in wallets and DNS managers do — set last_fill_up_time to "now" and start a fresh year.
get_last_fill_up_time == 0 does not mean "expired decades ago". It means the item was never initialised. Always check t > 0 before you compare t + 31622400 with the current time.

On apiton.org every domain page shows the expiry date and the days left; the hub
Domains expiring soon lists names whose year ends within the next 30 days.

What happens after expiry

Nothing happens automatically at the exact second a domain lapses — there is no on-chain "expired"
event. The contract (nft-item.fc in ton-blockchain/dns-contract)
simply starts accepting a special message once more than a year has passed:

Anyone may send dns_balance_release (op 0x4ed14b65) to the expired item, attaching at least the contract's minimum price for that name (get_min_price, which depends on the name's length).
That sender becomes the first bidder, the previous owner loses the domain, and a new auction starts with a duration of one week.
Each next bid must be at least 5 % higher than the current one. A bid in the last hour moves the end so that at least one hour remains.
When the auction ends, the highest bidder becomes the owner, and last_fill_up_time starts a new year.

Until someone sends that first message, an expired domain just sits there with its old owner
recorded. That is why "expired" really means "claimable", not "gone".

Why the op-code trick does not find expired domains

A popular idea is to scan the chain for dns_balance_release messages and treat their destinations
as expired domains. We tested this against live data: of the 50 most recent destinations, none
was expired — all 50 were active, because the message itself starts the release auction that
re-assigns the domain. The op-code tells you which domains were just re-claimed, not which are
available now.

How to actually find expired domains

There is no network-wide "list of expired domains" you can ask a liteserver for. Workable options:

Check a specific name. Hash the name, get the item address from the root collection, read get_last_fill_up_time. If the item does not exist, the name has never been registered; if t > 0 and t + 31622400 < now, it is expired. Feed a wordlist to this check and you get free names without enumerating the chain.
Use an index of known domains. apiton keeps a catalog of domains it has seen (from an indexer, from liteserver reads and from every lookup made through the API) and re-checks their expiry. The Expired .ton domains hub lists the ones whose year has run out; short and numeric names have their own hubs. The catalog only covers domains it has observed, so it is a good starting list, not a complete registry.
Ask the bot. Send any name.ton to @apitonBot — it reads the item live and shows the owner, the expiry date and any sale or auction.

Before you bid, re-check the domain live: catalog data is cached, and someone else may already
have started the release auction.

Summary

A .ton domain is valid for 366 days after last_fill_up_time; the owner renews by updating the item.
After expiry, anyone can start a one-week release auction with dns_balance_release and a minimum bid.
Domains are hash-indexed, so you check names, you do not enumerate them.
Browse expired and expiring domains on apiton.org, and check any name live in @apitonBot.

How to get a webhook when a TON address changes

apiTON — Wed, 04 Nov 2026 15:00:00 +0000

Most code that follows something on TON ends up as a loop: read the address, compare it with what
you saw last time, sleep, repeat. v2.Watch in the apiton API does that
loop for you. You name an address, and apiton stores an event for every change and pushes it to
your server, or keeps it for you to collect.

This is the walkthrough: a key, a watch, a handler that checks the signature, and what to do if you
have no server at all.

What you can watch

A watch is one address, and the server works out what kind it is:

An NFT item (a Telegram username, a +888 number, a .ton domain, a gift or any other NFT) is watched for its sale and auction.
Any other address is watched for its transactions, above an amount you choose.

Event	Means
`listed`	put on sale
`price`	the sale price changed
`delisted`	the sale or auction ended with the same owner
`sold`	the sale or auction ended with a new owner
`auction_start`	an auction began
`bid`	a higher bid
`auction_ending`	under 2 hours left
`tx`	a wallet's transaction

Step 1: get a key

Send /get_api to @apitonBot. The key looks like 123456789:aB3dE… and
goes in a header on every call. v2.Watch needs one: a watch has to belong to somebody.

Step 2: create a watch

curl -X POST https://app.apiton.org/v2.Watch/Create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 123456789:aB3dE…' \
  -d '{"address":"UQCdqXGvONLwOr3zCNX5FjapflorB6ZsOdcdfLrjsDLt3AF4",
       "webhook_url":"https://example.com/apiton","min_amount":1}'

The answer has the watch and a webhook_secret starting with whsec_. It is shown once, so
store it now. It signs your deliveries, and it is not your API key.

For a wallet, min_amount is the smallest amount that raises an event, in GRAM, 1 by default. 0
means every transaction. The webhook_url must be HTTPS on port 443 or 8443 on a public host, and
redirects are not followed.

The watch starts from the state it finds: what happened before Create raises nothing.

Step 3: receive the webhook

Each event arrives as a POST of JSON with three headers: X-Apiton-Signature,
X-Apiton-Timestamp and X-Apiton-Event-Id. The signature is sha256= plus the hex HMAC-SHA256
of <timestamp>.<body>, keyed with your secret.

Check it over the raw body, as received. Parsing the JSON and serialising it again gives
different bytes.

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["APITON_WEBHOOK_SECRET"]
seen = set()  # use your database


def verify(headers, body: bytes) -> bool:
    ts = headers.get("X-Apiton-Timestamp", "0")
    if abs(time.time() - int(ts)) > 300:
        return False  # a replayed request
    want = hmac.new(SECRET.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + want, headers.get("X-Apiton-Signature", ""))


@app.post("/apiton")
def apiton():
    body = request.get_data()
    if not verify(request.headers, body):
        abort(401)
    event = request.get_json()
    if event["id"] not in seen:
        seen.add(event["id"])
        queue_for_later(event)  # your slow work goes here, not in this request
    return "", 204

Two things in that handler are deliberate.

Delivery is at least once. If your 2xx gets lost, the same event comes again with the same id.
So remember the ids you have processed.

Answer first, work later. Only a 2xx within 5 seconds counts as delivered. A slow handler counts
as a failure even if its work finished.

To try it, call Test. It sends a test event right away and tells you what your endpoint answered:

curl -X POST https://app.apiton.org/v2.Watch/Test \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 123456789:aB3dE…' -d '{"id":"41"}'

When your endpoint is down

A failed delivery is retried after 1, 5 and 30 minutes, then every 30 minutes. After about 24 hours
of failures the webhook is paused and nothing is pushed until a Test gets through. Nothing is lost
in the meantime: events stay readable for 7 days, as the next section shows. List shows each
webhook's state and last error.

No server? Use a cursor

Leave out webhook_url. Every event is stored anyway, so you can collect them from a script or a
cron job:

curl -X POST https://app.apiton.org/v2.Watch/Poll \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 123456789:aB3dE…' \
  -d '{"after_id":"0","limit":50}'

Send next_after_id as the next after_id. Ids only grow, so a stored cursor never skips an event.
Keep an eye on the cost: each Poll is one request of your plan, while webhook deliveries cost none.
A free key's 10,000 requests a month is one Poll every 4½ minutes and nothing else.

Limits

Plan	Watches	Each address read every	Webhook pushes per hour	Price for 30 days
free	3	3 minutes	10	0
builder	30	30 seconds	100	5 GRAM or 1,000 Stars
pro	30	30 seconds	100	30 GRAM or 6,000 Stars

Events above the hourly cap are not lost: they stay in Poll. Builder and pro also raise the
general API limits; /upgrade in @apitonBot shows them.

Worth knowing

A status change arrives one read later. listed, sold and the like are reported when two reads in a row agree, so one bad read cannot fire delisted and listed. Prices and bids need only one.
A busy wallet. One read returns up to 16 transactions. A wallet with more between two reads gets the newest 16 and truncated: true; read the rest with Address/Transactions.
Amounts are in GRAM, the coin of TON, formerly Toncoin. The API's symbol for it stays TON.

If you only want the alert in Telegram and no code, send the address to
@apitonBot and tap Watch. The full reference is at
docs.apiton.org.

What anonymous +888 numbers are and how Fragment auctions work

apiTON — Tue, 03 Nov 2026 15:00:00 +0000

Telegram accounts are tied to phone numbers. Anonymous numbers in the +888 range are phone
numbers that do not belong to any mobile carrier: they exist only as NFTs on the TON blockchain and
are sold through Fragment. Whoever holds the NFT can use the number to sign
up for or log in to Telegram — no SIM card involved.

What you actually own

Each +888 number is an item of the "Anonymous Telegram Numbers" NFT collection. Most numbers have
eleven digits (+888 0123 4567); some are shorter. Owning the item means:

the number is linked to your TON wallet, and you can move it to another wallet like any NFT;
you can list it for sale or put it up for auction;
login codes for a Telegram account on that number are delivered through Fragment to the owner of the NFT instead of by SMS.

Because the owner is a wallet address, the chain shows which wallet holds a number, but not
which Telegram account uses it.

On apiton.org every known number has a page, for example
+888 0000 1312, and the numbers hub lets you browse
numbers for sale, numbers on auction and series such as
+888 0….

How the on-chain auction works

Fragment sells numbers and collectible usernames with the telemint contracts published by
Telegram (TelegramMessenger/telemint). The auction
state is stored in the NFT item itself, so anyone can read it with get-methods
(get_telemint_auction_config, get_telemint_auction_state). The config has these fields:

Field	Meaning
`beneficiary`	who receives the winning bid
`initial_min_bid`	the smallest first bid
`max_bid`	a "buy now" price: a bid at or above it ends the auction at once (0 = none)
`min_bid_step`	how much larger, in percent, the next bid must be
`min_extend_time`	a late bid pushes the end so at least this much time remains
`duration`	the length of the auction

From the contract code: the next minimum bid is the larger of "current bid + 1 💎" and "current
bid increased by min_bid_step percent". When someone outbids you, your bid is sent back to your
wallet with an "outbid" notification. When the auction ends, the NFT goes to the highest bidder
and the beneficiary receives the funds (minus royalties, if any).

The apiton API returns this as TeleAuction: last_bid (amount, bidder, time), next_min_bid,
end_time and the config above. See @apitonBot for the same data in
Telegram.

Fixed-price listings, on-chain and off

A number can also be offered at a fixed price:

On-chain sale contract. The owner transfers the NFT to a marketplace sale contract that releases it to whoever pays the price. The price is readable on-chain.
Off-chain Fragment listing. Fragment also lets owners list a number while the NFT stays in their wallet. There is no sale contract to read, so apiton takes the asking price from the public Fragment page and marks it "per fragment.com".

Where a price comes from explains the three sources in detail.

Checking a number

Open its page on apiton.org — /number/888… with digits only — or send +888 … to @apitonBot.
Read the status: not listed, for sale (with the price and its source) or on auction (current bid, next minimum bid, end time).
Before paying, confirm the live state: on-chain reads are authoritative, catalog data is cached.

Numbers that do not exist as NFTs (never minted) show "not found": the +888 range is not fully
issued.

Summary

+888 numbers are NFTs on TON; the holder can use them to log in to Telegram without a SIM.
Auctions run inside the NFT contract (telemint): minimum step in percent, extension on late bids, instant finish at max_bid, automatic refunds for outbid bidders.
Browse numbers for sale and auctions, and get alerts in @apitonBot.

How to check who owns a Telegram username

apiTON — Sun, 01 Nov 2026 22:14:28 +0000

Since 2022 Telegram has sold short and memorable usernames on Fragment as
collectible usernames. Each one is an NFT on the TON blockchain. That makes one question easy
to answer — which wallet owns @name — and leaves another, which person is behind it, mostly
unanswered. Here is what you can find out and how.

Two kinds of usernames

Ordinary usernames are set for free in Telegram settings. They are not on any blockchain, and nobody outside Telegram can see who reserved one except by opening t.me/<name>.
Collectible usernames were auctioned on Fragment. The name is an NFT in the "Telegram Usernames" collection, owned by a TON wallet. The owner can attach it to a Telegram account or channel, transfer it, sell it or auction it.

Everything below is about collectible usernames. If a lookup says "not found", the name is most
likely an ordinary username or not taken at all.

Step 1: look up the NFT

Pick one:

apiton.org — open apiton.org/username/<name> (lowercase, without @). The page shows the owner wallet, the status and the price if it is listed. Browse the usernames hub, for example 4-character usernames.
Telegram — send @name to @apitonBot. The card shows the same data read live from the chain, with buttons for the owner's transactions and alerts.
API — one request, no key needed for a quick check:

curl -X POST https://app.apiton.org/v2.Nft/Username \
  -H 'Content-Type: application/json' \
  -d '{"username":"beijing"}'

The response contains address (the NFT item), owner_address, status and, for listed names,
a sale object with the price or an auction object with the auction state.

Step 2: read the owner field correctly

owner_address is a wallet, shown in the non-bounceable form (UQ…). See Reading a TON address for why the same wallet can be written three ways.
When a username is for sale through an on-chain sale contract, the NFT technically sits in that contract. apiton reports the seller as the owner, not the contract, so you see the real holder.
During a Fragment auction the NFT stays in its item contract; the current highest bidder is a separate field (last_bid.address) and becomes the owner only when the auction ends.

Step 3: what the chain does not tell you

The blockchain links the username to a wallet. It does not record which Telegram account the
owner assigned the name to. To see the account or channel currently using the name, open
https://t.me/<name>. The account using a name and the wallet owning it can belong to different
people — for example when a company holds names in a treasury wallet.

A wallet's history can still tell you a lot: when it received the name, what else it holds and
whether it trades actively. In @apitonBot, tap the owner address on a
username card to see its transactions and NFTs.

Step 4: statuses you will see

Status	Meaning
Not listed	the NFT exists and is not offered for sale
For sale	fixed price: on-chain sale contract, or an off-chain Fragment listing ("per fragment.com")
On auction	Fragment auction: current bid, next minimum bid, end time
Not found	no collectible username with this name

Lists by status: usernames for sale and
username auctions.

Get notified instead of checking again

If you are waiting for a name to be listed or its price to drop, open it in
@apitonBot and tap Watch. The bot tells you when it is listed, sold,
re-priced or when an auction gets a new bid — see
Getting alerts with @apitonBot.

I built a TON explorer where every page is a public API call

apiTON — Sun, 25 Oct 2026 17:11:30 +0000

A surprising part of Telegram lives on a blockchain. Collectible @usernames, anonymous +888 phone numbers and gifts are NFTs on The Open Network (TON), and so are .ton domains. They change hands every minute — yet simple questions like "which 4-letter usernames are on auction right now?" or "which .ton domains expired this month?" usually mean clicking through marketplaces one item at a time.

apiton.org is my answer to that: an explorer that lists all of it with a status (not listed, for sale, on auction, expired), a price and a history, plus a directory of live TON Sites with screenshots. As of 25 October 2026 it tracks:

Kind	Total	For sale	On auction
Telegram usernames	674,469	44,460	16,871
Anonymous +888 numbers	136,566	440	84
.ton domains	199,832	28,734	120

…plus 28,623 expired .ton domains, 64,596 Telegram gifts and 382 live TON Sites.

But the part I want to talk about is how it is built: the website has no database access at all. It is a separate Go program that renders every page from the same public API anyone can call. The Telegram bot @apitonBot works the same way. When the site needs something new, it becomes an API method first.

The rule: the site is just another API client

apiton.org (Go, html/template) ─┐
@apitonBot (Go)                 ├──► POST https://app.apiton.org/v2.<Service>/<Method>
your script, curl, an AI agent ─┘          │
                                           ├── Postgres catalog: usernames, numbers, domains, gifts, TON Sites
                                           └── TON liteservers: live on-chain state

Why bother with this discipline on a one-person project?

The API can't rot. If a field breaks, my own pages break first, and I see it before anyone else does.
Every site feature is an API feature. Expired-domain lists, the sales feed, gift collection floors, TON Site status — all of them are public methods, because the site has no other way to get them.
A small blast radius. The site imports no backend package. It can be cached, restarted or rewritten without touching the data layer.

Try it: no key, just curl

The API speaks Connect, the HTTP-friendly sibling of gRPC: every call is a POST with a JSON body to https://app.apiton.org/v2.<Service>/<Method>. gRPC and gRPC-Web clients generated from the same protos work too. Anonymous calls are allowed — 1 request per second and 10,000 a month per IP.

How big is the catalog?

curl -s -X POST https://app.apiton.org/v2.Catalog/Summary \
  -H 'Content-Type: application/json' -d '{}'

{
  "kinds": [
    {"kind": "username", "total": "674469",
     "by_status": {"auction": "16871", "not_listed": "613138", "sale": "44460"}},
    ...
  ],
  "live_sites": "382"
}

These are the numbers from the table above, and the ones on the apiton.org home page.

The cheapest .ton domains for sale

curl -s -X POST https://app.apiton.org/v2.Catalog/List \
  -H 'Content-Type: application/json' \
  -d '{"kind":"domain","statuses":["sale"],"sort":"price_asc","limit":2}'

{
  "items": [
    {
      "kind": "domain",
      "name": "prommeteeev",
      "nft_address": "UQBt9bwjG5fTpT166sh76zjM0zKQ5rvhr44_vQcE0vPK8SyN",
      "owner_address": "UQBixgxoacPjMpiqOjr3t7FDnFsYP_Pbxg8VgK2mxckIQspb",
      "sale_contract": "UQCfowehxX68MXv1HGmVMdrBt2HNQdyxIWI7M41HpKiQYiuA",
      "status": "sale",
      "price": 0.468,
      "price_source": "chain",
      "expires_at": "2027-10-19T16:45:46Z",
      "name_len": 11
    },
    ...
  ],
  "total": "28734"
}

price is in the network's own coin (shown as 💎 on the site), and price_source says whether it came from a sale contract on chain or from a Fragment listing. List filters by kind (username, number, domain, gift), statuses, name_len, digits_only, prefix and an expiry window, and sorts by name, price_asc, price_desc, expires_asc or changed. Two more recipes:

# 4-letter usernames on auction
curl -s -X POST https://app.apiton.org/v2.Catalog/List \
  -H 'Content-Type: application/json' \
  -d '{"kind":"username","statuses":["auction"],"name_len":4}'

# expired .ton domains, most recently changed first
curl -s -X POST https://app.apiton.org/v2.Catalog/List \
  -H 'Content-Type: application/json' \
  -d '{"kind":"domain","statuses":["expired"],"sort":"changed"}'

The full list of fields is in this guide on the apiton blog and in the API reference.

What just sold

curl -s -X POST https://app.apiton.org/v2.Catalog/Events \
  -H 'Content-Type: application/json' \
  -d '{"types":["sold"],"limit":3}'

Pass a kind and a name instead and you get the history of one item: listed, delisted, re-priced, sold, bids, expiry, renewal.

Live state of one item

The catalog is refreshed in the background. For the state of a single item right now, the v2.Nft methods read the chain:

curl -s -X POST https://app.apiton.org/v2.Nft/Domain \
  -H 'Content-Type: application/json' \
  -d '{"domain":"apiton.ton"}'

{
  "address": "UQABUZhK7peJbJzDxChcbitG9oJUgxWmk1TqZwU76aMEKALt",
  "owner_address": "UQAyJ9vVRMGVKg9-6R-KO3alF2ITcccDBAhAi1Qj4HCpVP5Q",
  "time_expire": "2027-10-08T16:16:31Z",
  "site": {
    "kind": "adnl",
    "status": "live",
    "title": "apiton — TON explorer: names, gifts and TON Sites",
    "uptime_30d": 1,
    "live_since": "2026-10-07T16:18:19.961661Z",
    "gateway_url": "https://site.apiton.org/apiton.ton/"
  }
}

Yes, the explorer is a TON Site itself — more on that below. v2.Nft/Username, Number and Gift work the same way, and v2.Address covers wallets: balance, jettons, NFTs and transactions.

Three JSON gotchas

The responses are proto3 JSON, which surprises people coming from hand-written REST APIs:

int64 arrives as a string: "total": "28734". Parse it; don't compare it to a number.
Zero values are omitted. An empty list is {}, not {"items": [], "total": "0"}.
Errors use the Connect envelope with a proper HTTP status:

curl -s -X POST https://app.apiton.org/v2.Catalog/List \
  -H 'Content-Type: application/json' -d '{"kind":"planet"}'
# HTTP 400
# {"code":"invalid_argument","message":"unknown kind \"planet\" (username | number | domain | gift)"}

Too many requests is resource_exhausted (HTTP 429). unavailable means the TON liteservers are lagging; retry after a second or two. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

What public liteservers taught me

Live reads go to the public TON liteservers. They are free, and they are moody. Between 23 and 25 October, 54–83 % of my liteserver requests were answered with error 651 — "the node is behind". That rate did not change when I tripled my own background load, so it was not me.

What made the API usable anyway:

A pool with failover. Keep four connections open; a 429 or a 651 is retried on another server, not on the same one.
Don't read the newest block. Reads run on a masterchain block about 10 seconds behind the head, which a node that is slightly behind can still serve. If six servers refuse, the answer comes from an older block (at most 45 seconds old). The one exception: before a send, a wallet's own state is read on the newest block only, or the send fails before anything is signed.
One chain read per question. A 45-second live cache sits in front of the item methods. Identical concurrent requests share a single chain read that is detached from the caller's context, so a client hanging up doesn't cancel it for everyone else. Errors are never cached.
The pool's answer is final. No retry loops stacked on top of it — that is how a bad minute becomes a retry storm. Clients get a clear unavailable instead, and the bot retries once after 1.5 seconds.

The other lesson was quieter and more expensive. For months, every sale and auction price read silently returned nothing, because of a typo in the default URL of the archive endpoint those reads went through. "No price" looked like a valid answer, so nothing alerted. The fix was a rule rather than a patch: state and get-method reads go to liteservers only, and the archive is used for old transactions only.

.ton domains can't be listed from the chain

You'd think the 199,832 domains came from iterating the DNS collection. They can't. The root .ton collection indexes each item by hash(name) rather than a counter, so there is no 0..N to walk. A domain also lapses silently: it is valid for a year after its last renewal (last_fill_up_time), and no transaction marks the moment it expires.

So the catalog learns about domains as they show up on chain — transfers, sales, DNS changes — and then re-reads each one on a schedule to compute its expiry. A small trap on the way: get_last_fill_up_time returning 0 means the item was never initialized, not that it expired long ago.

TON Sites: a directory of the "other" web

A .ton domain can point to a website through its DNS site record — an ADNL address or a TON Storage bag. apiton reads that record for every domain, probes each site over RLDP-HTTP or TON Storage, tells parked pages from live ones, ranks them and takes screenshots with a headless Chrome whose only way out is a .ton-only proxy. The result is apiton.org/sites/: 382 live sites today. Sites with clearly illegal content are listed by name with a reason, and never opened or previewed.

apiton.org is one of them. apiton.ton is served by a small Go program that speaks ADNL and RLDP-HTTP and reverse-proxies the regular website, GET and HEAD only. Without a TON proxy, you can open it through the gateway: site.apiton.org/apiton.ton/.

The bot and the limits

@apitonBot is the second client of the same API. Send it a wallet address, an @username, a +888 number, a name.ton or a gift link and you get a card. You can also watch items and wallets (listed, sold, new bid, incoming transaction), set price alerts, see a wallet's portfolio, and get an API key with /get_api. It answers in Russian for CIS languages and in English for everyone else.

With a key (Authorization: Bearer <tg_id>:<secret>) you get your own quota instead of sharing one with your IP:

free — 1 request/s, 10,000 a month;
builder — 10 requests/s, 300,000 a month;
pro — 100 requests/s, 3,000,000 a month.

Upgrades are paid in the bot with Telegram Stars or TON. The key, together with a wallet token, also unlocks custodial wallets, sends and jetton/NFT minting.

For AI assistants: llms.txt

apiton.org/llms.txt is a Markdown map of the site, the API and the bot, written for LLMs. Point an assistant or an agent at it and it can answer "what's the cheapest 5-letter username on sale?" with a real API call instead of a guess.

The stack, briefly

Go everywhere: connect-go over h2c for the API, Postgres through Bun, Redis for caches and quotas, tongo for TON. The site is server-rendered html/template with no JavaScript framework. React is used only for the bot's Mini App.

Try it

Explorer: apiton.org — usernames, +888 numbers, .ton domains, gifts, TON Sites
API reference: docs.apiton.org
Bot: @apitonBot · news: @apiton

What would you build on top of it, and which method is missing? Tell me in the comments, or send /feedback to the bot.

How to Display NFT Gift Animations in Telegram

apiTON — Wed, 29 Jan 2025 14:33:34 +0000

How to Display NFT Gift Animations in Telegram

The introduction of NFT gifts in Telegram has raised numerous questions among developers, particularly regarding integration with the TON (The Open Network) blockchain. In this article, we’ll explore the technical aspects of working with animated NFTs and demonstrate how to implement their display in your projects.

I am the developer of the TON Blockchain Explorer, integrated into Telegram, and will guide you through one key question:

How to display NFT animations in your own projects.

Let’s examine the following NFT contract:

0:3a4f57aded85be8f7d1651b8e9d7749662014e08f6bcd3afaf2175c83188a7da

From this contract, we can extract data such as attributes, descriptions, and other metadata:

https://nft.fragment.com/gift/hexpot-10348.json

By clicking the More button, you can retrieve all available information directly:

Here, you’ll find a URL with a key and filename:

https://nft.fragment.com/gift/hexpot-10348.lottie.json

Lottie Format Basics

The animation uses the Lottie format:

Lottie is a library developed by Airbnb that renders animations in JSON format, created using Adobe After Effects. It allows developers to easily integrate high-quality animations into mobile and web apps while maintaining smooth performance and scalability.

Web Implementation Example:

https://jsfiddle.net/w5dsp16v/

<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>

<body>
    <div id="animation-container"></div>

    <script>
        const animation = lottie.loadAnimation({
            container: document.getElementById('animation-container'),
            path: 'https://nft.fragment.com/gift/hexpot-10348.lottie.json'
        });
    </script>
</body>

Telegram-Specific Solution

Telegram uses the .tgs format for stickers:

.tgs files are gzipped Lottie JSON files, playable via the rlottie library.

Implementation Workflow:

Download Lottie JSON
Compress with GZIP
Send as Telegram document

Go Code Example:

package main

import (
    "bytes"
    "compress/gzip"
    "github.com/aaapi-net/hog"
    tele "gopkg.in/telebot.v3"
)

func getTgsAnimation(lottieUrl string) ([]byte, error) {
    data, err := hog.Get(lottieUrl).AsBytes()
    if err != nil {
        return nil, err
    }

    gz, err := compress(data)
    if err != nil {
        return nil, err
    }

    return gz, nil
}

func compress(data []byte) ([]byte, error) {
    var buf bytes.Buffer

    writer := gzip.NewWriter(&buf)
    _, err := writer.Write(data)
    if err != nil {
        return nil, err
    }

    if err := writer.Close(); err != nil {
        return nil, err
    }

    return buf.Bytes(), nil
}

func sendLottieAnimation(c tele.Context, lottieUrl string) error {
    tgsAnimation, err := getTgsAnimation(lottieUrl)
    if err != nil {
        panic(err)
    }

    file := tele.FromReader(bytes.NewReader(tgsAnimation))

    photo := &tele.Document{
        File:                 file,
        MIME:                 "application/x-tgsticker",
        FileName:             "hexpot-10348.tgs",
        DisableTypeDetection: true,
    }

    return c.Send(photo)
}

Key Takeaways

Use native .tgs format for Telegram compatibility
Avoid MP4/GIF conversions to preserve quality
Leverage Telegram's built-in Lottie support

Feel free to contact about TON Blockchain development @apitonDev.

Share your implementations below!