Integration

The chain is the only party that cannot lose the message

TON API gives a Telegram bot read access to chain state — account balances, jetton holdings and transaction history — so payments and allowlists can be verified against the network rather than against what a client reported. Everything a client tells you about a transaction is a claim until the chain agrees.

TON API integration: auth, limits and availability

Auth model: API key
Rate limit: Per API key, with substantially higher paid-tier allowances
GCC availability: No jurisdictional onboarding — reading chain state is unregulated
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

Every Telegram crypto product eventually needs the same thing: a trustworthy answer to whether something happened on chain. Did this payment arrive. Does this wallet hold the token the allowlist requires. Has the withdrawal we submitted actually confirmed. None of those can be answered by asking the user's wallet, because the wallet is software the user controls and its report is a claim.

The tempting shortcut is to fulfil on the client's success callback. The wallet says it sent the transaction, the Mini App tells the backend, the backend delivers the goods. It works in testing, it works for honest users, and it is the mechanism behind a large share of losses in Telegram-native crypto products. A client that can be modified is a client that can report a payment that never happened.

So the pattern is polling or watching rather than trusting. The backend knows what it is expecting — an amount, to an address, with a comment or memo identifying the order — and it watches the chain until it sees it at sufficient depth. That is slower than trusting the client by a few seconds and it is the difference between a product and a donation.

How the data actually moves

The expected payment is recorded before the user is asked to send anything, so a matching transaction can be recognised without the client reporting it.

An API key held as a Worker secret, used for the higher rate tiers. The key grants read access to public chain data rather than any authority to move funds, so its exposure is a service-availability problem rather than a loss of money — a useful distinction when deciding how alarmed to be about key rotation.

Auth model: API key

Their limits, and what they mean for you

Rate limits apply per API key, with substantially higher allowances on paid tiers.

Polling per user does not scale. One watcher per monitored address, shared across every order awaiting that address, is what keeps request volume proportional to accounts rather than to customers.

A transaction is visible before it is final, and finality is a function of confirmation depth.

Confirmation depth is set per amount rather than as one constant. A depth appropriate for a two-dollar tip is not appropriate for a five-figure withdrawal.

Jetton balances are held in per-wallet jetton contracts rather than on the main account.

Checking a USDT balance means resolving the jetton wallet address for that owner first. Reading the base account and finding nothing is a common and confusing early result.

Transaction comments are the conventional way to attach an order reference and are user-editable.

A comment identifies a payment; it does not authenticate one. Matching also requires the amount and the destination, because a comment can be copied by anyone watching the chain.

How it fails, and what happens when it does

The API is unreachable while a customer is waiting for confirmation.

The order stays pending and the customer is told it is still confirming rather than that it failed. Watching resumes when the API returns, because the transaction is on the chain regardless of whether we could see it.

A payment arrives with the wrong comment or none at all.

Amount and destination narrow it to a small set, and anything ambiguous escalates to a human. Automatically crediting an unidentifiable payment to the nearest pending order is how the wrong customer gets someone else's goods.

A block reorganisation invalidates a transaction already treated as confirmed.

Confirmation depth exists precisely for this, and the depth is scaled with the amount. Fulfilment at depth one is fast and occasionally wrong in the most expensive direction.

Two orders expect the same amount to the same address at the same time.

A unique per-order comment or a unique sub-address is issued so matching is unambiguous. Relying on amount alone breaks exactly when two customers behave identically, which is not rare.

Availability in the UAE and the wider GCC

Global

A public chain data provider with no jurisdictional onboarding. What you build on it may still be regulated.

United Arab Emirates

Widely used by Dubai crypto projects. Reading chain state is unregulated; holding or transmitting user funds is a VARA matter regardless of how you read the chain.

Free tier

Adequate for development and low volume. Production watching for a busy storefront needs a paid tier, and that is a line item rather than an afterthought.

Self-hosted alternatives

Running your own node removes the dependency and adds an operational burden. Worth it at scale, rarely worth it at launch.

When not to use this integration

You are fulfilling on a client-reported success. Then you do not need chain access, and you will need it shortly after your first loss.
Your product has no on-chain component. Reading a chain nothing depends on is machinery without a purpose.
You need sub-second confirmation. Chain finality has a floor, and no API removes it.
You are selling digital goods to a Telegram audience. Stars settle instantly with no chain involved at all.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Chain watching on cron and confirmation matching.
Cloudflare D1	current	Expected payments, confirmation state and the ambiguity queue.
Cloudflare KV	current	Last-seen transaction cursors per watched account.
Zod	4.4	Validation of API responses, which are external and versioned independently.

Questions that come up during scoping

Why not just trust the wallet's success callback?

Because the wallet is software the user controls, so its report is a claim rather than evidence. It works in testing and for honest users, and it is behind a large share of losses in Telegram-native crypto products. The chain is the only party that cannot be persuaded to lie.

How many confirmations before fulfilling?

It depends on the amount, and treating it as one global constant is the mistake. A depth that is sensible for a small tip is not sensible for a large withdrawal, because a reorg at depth one costs exactly what was at stake.

Why can we not see a USDT balance on the wallet address?

Jetton balances live in per-wallet jetton contracts rather than on the base account, so the jetton wallet address has to be resolved for that owner first. Reading the base account and finding nothing is the usual first result and is not an error.

Is a transaction comment enough to identify a payment?

It identifies; it does not authenticate. Comments are visible on a public chain and can be copied, so matching uses amount and destination alongside it, and anything ambiguous goes to a human rather than to the nearest pending order.

What happens if the API is down while a customer is paying?

The order stays pending and the customer is told it is still confirming, which is true — the transaction is on the chain whether or not we can currently see it. Watching resumes when the API returns.

Does polling scale to thousands of customers?

Yes, because watchers are per monitored address rather than per customer. A thousand orders awaiting payment to one address is one watcher, which is what keeps request volume proportional to accounts instead of to traffic.