Install and enable TON

The two activation gates, the four environment variables, the master wallet and the Toncoin token row — in the order that avoids a half-configured chain.

7 min readUpdated 3 August 2026install, license, env, master-wallet, toncenter

TON is off on a fresh install and stays off until four separate things are true: the service code is present, the licence file exists, the database row is enabled, and the endpoint is configured. Miss any one and the chain reports itself inactive with a message that names the gate — but only if you go looking for it.

Do these in order. Several of them fail quietly out of order: the status toggle refuses without a licence, and address generation refuses without a token row.

Before you begin

Ecosystem is installed and its extension is enabled
The Ecosystem vault is unlocked — Ecosystem overview → Initiate Vault
You bought the TON Blockchain addon and can activate its licence
You have a Toncenter API key for the network you intend to run
You can restart the backend (pm2 restart backend)

The vault matters more than it looks. TON key material is encrypted with the vault key before it is written, and the encrypted blob in wallet_data is the only copy. A locked vault means the platform cannot create a TON address and cannot sign a TON withdrawal — see Master wallets and the vault.

1. Confirm the service code is installed

The chain service lives at backend/src/blockchains/ton.ts and is loaded through a guarded import — if the file is absent, the platform does not crash, it simply behaves as though TON does not exist. Every TON entry point then answers with a 503 "TON service not available".

The diagnostics console reports this directly as Chain service installed. If it says no, the addon archive was never extracted over the install, or an update extracted over the top and left the old tree behind.

2. Activate the licence

Activation writes an encrypted, machine-bound file:

lic/55715370.lic

55715370 is the TON product ID. It is also the value used as the path parameter when you toggle the chain, and the name shown against TON in the seeded blockchain list.

Two things follow from the file being machine-bound. Copying an install to a new server invalidates it — reactivate there. And the licence result is cached for five minutes, so a freshly activated licence can take that long to be believed by an already-running backend.

3. Enable the chain row

Admin → Ecosystem → Blockchains. The four licensed chains are seeded with status: false, so TON is listed but off.

Enables or disables a seeded blockchain. The path parameter is the product ID, not the chain symbol.

Enabling checks for lic/55715370.lic before it writes anything. Without the file you get:

403 — Cannot enable blockchain: License not activated. Please activate your
license first.

That is the licence gate, not a permission problem. Disabling is not gated, so a chain can always be turned off.

4. Configure the endpoint

Add these to the project root .env. They are not in .env.example — you type them yourself.

TON_NETWORK="mainnet"
TON_MAINNET_RPC="https://toncenter.com/api/v2/jsonRPC"
TON_MAINNET_RPC_API_KEY="your-toncenter-key"

For testnet, set TON_NETWORK="testnet" and fill the testnet pair instead:

TON_NETWORK="testnet"
TON_TESTNET_RPC="https://testnet.toncenter.com/api/v2/jsonRPC"
TON_TESTNET_RPC_API_KEY="your-testnet-key"

TON_NETWORK is a two-value switch and it fails safe in one direction only: the literal string testnet selects the testnet pair, and anything else — including unset, misspelled or empty — selects mainnet. There is no third option and no error.

Both RPC variables have working defaults (https://toncenter.com/api/v2/jsonRPC and its testnet equivalent), so the chain will function with only TON_NETWORK set. It will function badly. Anonymous Toncenter is limited to roughly one request per second, shared across every deposit poll, every balance read and every withdrawal confirmation attempt on the install.

The deposit monitor stops itself after ten consecutive errors, and the withdrawal confirmation loop gives up after ten attempts spaced ten seconds apart. Both budgets are consumed by HTTP 429s. Set the key.

5. Restart the backend

The TON service is a singleton. It reads the endpoint and API key once, at construction, and never re-reads them.

pm2 restart backend

One nuance worth knowing: the chain's active state is re-checked whenever the service is asked for while inactive, so enabling the row in step 3 is picked up without a restart. Changing TON_NETWORK, the RPC URL or the API key is not.

6. Create the TON master wallet

Admin → Ecosystem → Wallets → Master Wallets, then choose TON.

Creates a master wallet for a chain and stores its encrypted key material

Lists the chains that can still have a master wallet created

The TON master wallet is a real TON wallet, created through the same service as a user wallet, and its balance is read live on the master wallet screen. What it is not is a gas payer: TON withdrawals are signed by the user's own address and never touch it. It exists so the chain has an owner-held address, and so the diagnostics have something to check.

Create it anyway. The requirements console downgrades Withdrawals to failed when a chain has no master wallet or the vault is locked, regardless of whether the RPC is healthy, so a missing master wallet leaves the chain permanently reporting broken.

Custodial wallets do not apply. TON is on the excluded list for custodial deployment, because there is no contract for the platform to deploy.

7. Activate the Toncoin token row

Admin → Ecosystem → Tokens. The seeder creates one TON row — native Toncoin, contract sentinel 0x0000000, status: false.

Bulk-enables or disables Ecosystem token rows

Edits a token's decimals, precision, fee and limits

Enable it, then fix two fields before anyone uses it:

Precision. The seeded row records decimals: 18, which is not TON's scale — TON is 9. Crediting is unaffected (the service converts from nanotons directly), but precision falls back to decimals when it is null, and that fallback is what the withdrawal endpoint uses to reject amounts with "too many decimal places" and to round the debit. Set precision to 9 explicitly rather than relying on the fallback.
Fee. The token's fee object holds percentage and min. The platform charges max(amount × percentage, min) in TON, on top of the amount, and that is the only fee the user is debited. The network fee is taken from the user's own address by the network itself. Leave fee empty and every TON withdrawal is free to the customer.

The row's network column says mainnet even on a testnet install, and that is harmless: TON is treated as network-agnostic by the token eligibility rule, so the row is never filtered out for disagreeing with TON_NETWORK. The chains that are filtered are the EVM ones.

8. Run the diagnostics

Admin → Ecosystem → Blockchains → Requirements, select TON, run the test.

Per-chain requirements report — every variable the runtime reads, whether it is set, and the non-environment prerequisites

Live read-only probes plus per-flow readiness

The TON test calls getMasterchainInfo against the configured endpoint with the API key attached and reports the masterchain seqno on success. It labels the check "NO KEY (anonymous, ~1 req/s)" when the key is absent, and distinguishes HTTP 401 (invalid key) from HTTP 429 (rate limited) so you are not left guessing which one you hit. It then adds the service-installed and licence checks, and derives readiness for Deposits and Withdrawals from all of them.

Read the readiness rows, not the green ticks. A reachable RPC with a locked vault still means nobody can withdraw.

9. Prove it end to end

Do not skip this, and do it with an amount you are willing to lose.

Open the deposit page for TON as a normal user. An address is generated on first view and shown to you.
Send a small amount from an external wallet. Leave any memo or comment field blank — the platform matches on the destination address alone.
Watch it credit. The session monitor polls once a minute, and TON deposits are credited without waiting for confirmations.
Withdraw a smaller amount back out, leaving enough TON at the address to cover the network fee. Confirm the transaction reaches COMPLETED with a hash, not FAILED.

If step 4 lands on FAILED with "Transaction hash could not be retrieved", read Withdrawals and fees before retrying — the coins may well have moved.