MMashDiv

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.

11 min readUpdated 26 August 2026install, license, env, master-wallet, toncenter

TON is off on a fresh install and stays off until four separate things are true: the licence is activated, the release is installed, the chain is switched on, 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 enable switch refuses without a licence, and address generation refuses until the Toncoin token is enabled.

Before you begin

  • Ecosystem is installed and its extension is enabled
  • The Ecosystem vault is unlocked — Ecosystem overview → Initiate Vault
  • You have the purchase code for the TON Blockchain addon, from your MashDiv dashboard
  • You have a Toncenter API key for the network you intend to run
  • You have a shell on the server — the install needs pnpm updator, and step 6 needs 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. Open the Extension Manager

Admin → System → Extension Manager (/admin/system/extension). The page heading is Add-ons & Integrations, and every add-on, blockchain and exchange provider is a card in its grid. Use the Blockchains tab or the search box to find the TON Blockchain for Ecosystem Addon card — product ID 55715370 — and click it to open the product page. Until its licence is activated the card's chip reads Activate and its switch is disabled, with a tooltip that says Activate license first.

  1. The TON card — click it to open the product page
  2. Its switch stays disabled until the licence is activated

2. Activate the licence

The unlicensed product page shows a License Required chip and an Activate License button. Press it — the licence screen opens, headed Activate Your License, with the product's name and product ID (55715370) shown. Two methods, as tabs:

  • Purchase Code — paste the purchase code from your MashDiv dashboard, optionally add a Notification Email for update notifications, and press Activate License. The screen confirms License Activated! and sends you back to the product page a couple of seconds later.
  • License File — for a server with no outbound access at activation time: download the licence certificate from your MashDiv dashboard, place it as license.txt in the /lic folder at the project root, and press the button on that tab.
  1. Paste the purchase code here
  2. Activate License — then wait for the redirect back to the product page
  3. The offline route, for a server with no outbound HTTPS

Activation writes the encrypted, machine-bound licence file lic/55715370.lic, and two things follow from it 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. Install the release

Back on the product page — now the licensed view, with the version, an Enabled switch in the heading and the Overview, Releases and Capabilities tabs — the Overview tab has a release panel. If it offers Install v…, press it; if it says Up to date on a product you have only just licensed, press Check for Updates once, then install whatever it offers. The Releases tab holds the notes for the version you are being offered — read them first.

Install downloads the release, verifies it and extracts it over the project root. It runs no migrations, builds nothing and restarts nothing, so finish it from a shell on the server:

pnpm updator

That is the finalise chain — stop, dependencies, schema, seed data, frontend build, start. If the panel still says Up to date after the check, there is nothing to download — the release already on the server is current — and you move on.

Install is what puts the chain service, backend/src/blockchains/ton.ts, on the server. It 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, and every TON entry point answers with a 503 "TON service not available". The diagnostics console (step 9) reports this directly as Chain service installed — if it says no, the release was never installed on this server, and this step is the fix.

  1. Check for Updates, then Install v… when it is offered
  2. Releases — the notes for the version you are about to install
  3. The Enabled switch — step 4, not yet

4. Switch the chain on

Turn the Enabled switch on — in the product page heading, or on the card in the Extension Manager, which is usable now that the licence is verified. Enabling is what switches TON on for the Ecosystem addon: until it is on, TON appears under Admin → Ecosystem → Blockchains but stays inactive, and no TON address can be generated.

PUT/api/admin/ecosystem/blockchain/{id}/statuspermission: edit.ecosystem.blockchain
Enables or disables a blockchain. The path parameter is the product ID, not the chain symbol.

55715370 — the product ID you activated in step 2 — is the value used as the path parameter when you toggle the chain, and the name shown against TON in the blockchain list.

Enabling checks the licence first. Without an activated licence 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.

5. 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.

6. 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 switching the chain on in step 4 is picked up without a restart. Changing TON_NETWORK, the RPC URL or the API key is not.

7. Create the TON master wallet

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

POST/api/admin/ecosystem/wallet/masterpermission: create.ecosystem.master.wallet
Creates a master wallet for a chain and stores its encrypted key material
GET/api/admin/ecosystem/wallet/master/optionspermission: view.ecosystem.master.wallet
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.

8. Activate the Toncoin token row

Admin → Ecosystem → Tokens. TON has exactly one row here — native Toncoin, contract sentinel 0x0000000 — and it starts switched off.

PUT/api/admin/ecosystem/token/statuspermission: edit.ecosystem.token
Bulk-enables or disables Ecosystem token rows
PUT/api/admin/ecosystem/token/{id}permission: edit.ecosystem.token
Edits a token's decimals, precision, fee and limits

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

  1. Precision. The row ships recording 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.

  2. 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.

9. Run the diagnostics

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

GET/api/admin/ecosystem/blockchain/requirementspermission: view.ecosystem.blockchain
Per-chain requirements report — every variable the runtime reads, whether it is set, and the non-environment prerequisites
POST/api/admin/ecosystem/blockchain/requirements/testpermission: view.ecosystem.blockchain
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.

10. Prove it end to end

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

  1. Open the deposit page for TON as a normal user. An address is generated on first view and shown to you.

  2. Send a small amount from an external wallet. Leave any memo or comment field blank — the platform matches on the destination address alone.

  3. Watch it credit. The session monitor polls once a minute, and TON deposits are credited without waiting for confirmations.

  4. 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.

Next