Troubleshooting TON

The status toggle looks for lic/55715370.lic in the project root before it writes anything. The file is missing, in the wrong directory, or belongs to a different machine — activation is machine-bound, so a server migration invalidates it.

Activate the licence on this machine, confirm the file exists, then toggle again. This is not a permissions problem; edit.ecosystem.blockchain grants access to the endpoint, and the licence check runs after it.

The chain service module is not installed. Every TON entry point — address generation, balance reads, withdrawals, the deposit monitor — is behind a guarded import that returns nothing when backend/src/blockchains/ton.ts is absent, so the platform degrades rather than crashing.

The requirements page reports this as Chain service installed: no. Extract the addon archive over the install. Note that updates extract over the top and never delete, so a stale tree can leave you with old code rather than none.

The licence result is cached for five minutes. If you activated the file while the backend was already running, wait it out.

If it persists, the check is a two-part gate: the file must exist and ecosystem_blockchain.status must be true for the row whose productId is 55715370. Confirm both. The requirements page shows the reason string verbatim.

Readiness for withdrawals is downgraded when the Ecosystem vault is locked or when the chain has no enabled master wallet — independently of whether the RPC answered. Unlock the vault from the Ecosystem overview, and create the TON master wallet if you skipped it.

A non-native token row exists for chain TON. Address generation for a PERMIT or NO_PERMIT token falls through to the EVM derivation path, which produces an Ethereum address and writes it into the TON slot of the wallet's address map.

Stop issuing that token immediately: disable the row, and treat any address already handed out as dead. Anything sent to it cannot be recovered, and no monitor will ever look at it. TON must have exactly one token row, NATIVE Toncoin.

The Toncoin token row is disabled. It is seeded with status: false and has to be enabled from Admin → Ecosystem → Tokens before an address can be issued.

This message is not about the token's network column. TON is treated as network-agnostic, so a row saying mainnet on a testnet install is still eligible.

Work down this list in order.

1. Is the chain active? An inactive chain throws before it fetches anything — check the requirements page.
2. Is the endpoint rate limited? Without an API key, Toncenter allows about one request per second across the whole install. Ten consecutive polling errors and the session monitor stops itself for that address until the user reopens the deposit page.
3. Which network is the platform on? TON_NETWORK selects mainnet unless it is exactly the string testnet. A deposit on the network you are not watching will never be seen.
4. How long ago was the deposit page last opened? The background scanner keeps an address in its working set for 72 hours after the last visit. Past that, nothing is polling it. Have the user reopen the deposit page.
5. Is the scanner running at all? ECOSYSTEM_BACKGROUND_SCAN=false turns it off globally.
6. Were there more than ten transactions? Each poll reads the ten most recent transactions for the address. A burst larger than that between polls can push older ones out of the window.

Reopening the deposit page is the safe universal remedy: it restarts the session monitor, re-registers the address with the background scanner, and re-scans history. Crediting is de-duplicated on the transaction hash, so a re-scan cannot double-credit.

The memo is irrelevant either way — the platform matches deposits by destination address and never reads the message body. If the coins are not showing, the cause is elsewhere in the list above.

What is worth checking is whether they sent to the address the platform issued. Users occasionally paste an address from an old session or from another exchange.

That is expected. Addresses are emitted in standard base64 rather than URL-safe base64, so those two characters can appear. It is a valid, non-bounceable TON address and every wallet accepts it.

It becomes a problem in exactly one place — the platform's own withdrawal form. See below.

The withdrawal endpoint's character gate accepts letters, digits, -, _ and : only, and it runs before any TON library sees the string. A standard-base64 address containing + or / is refused here.

Swap the characters: + becomes -, / becomes _. The result is the same address in URL-safe form and is accepted. The raw workchain:hex form works too.

This one is the TON library refusing to parse the string — a wrong length, a failed checksum, or a truncated paste. A user-friendly address is exactly 48 characters. Ask for a fresh copy rather than repairing it by hand.

The user's TON address does not hold enough, even though their platform balance does. That happens when the balance came from trading rather than a deposit.

This failure path does not refund. The wallet debit stands, the platform fee is recorded as admin profit, and a withdrawal confirmation email is sent. All three have to be reversed by hand: refund the wallet, reverse the fee record, and tell the customer to disregard the email.

Prevent it by watching per-asset coverage on the Ecosystem admin overview and funding addresses before withdrawals start failing. Remember the address also needs to keep enough TON for the network fee — it can never send its whole balance.

The transfer was broadcast, and then the platform could not find it again within about a hundred seconds. The withdrawal queue then refunded the user, so the coins are on-chain and the balance was returned.

Check the user's TON address on a block explorer for an outgoing transfer around that timestamp carrying a TON_WITHDRAWAL_ comment. If it is there, the refund was wrong and needs reversing.

The cause is almost always Toncenter rate limiting the confirmation polls. Set TON_MAINNET_RPC_API_KEY — this is what that key is for.

The recovery job deliberately does not touch stale PROCESSING TON rows, because the transaction hash is written only after a successful broadcast and re-queuing could pay the customer twice. It logs them and asks for manual review.

Check the sending address on an explorer. Transfer present: set the row COMPLETED with its hash. Transfer absent: the coins never left, so the row can be failed and refunded.

The platform creates v3R1 wallet contracts. A TON address depends on the wallet contract code as well as the key, so importing the mnemonic into a wallet that defaults to v4R2 or W5 shows a different address with no balance.

Select the v3R1 wallet version in the recovery tool. The funds are at the address the platform recorded, which is the one to check on an explorer.