Configuration reference

Every environment variable, token field, endpoint and timing constant the TON integration reads — and the ones it deliberately does not.

2 min readUpdated 3 August 2026reference, env, endpoints, limits, tokens

Everything on this page is read by the running platform. Where a value has a default, the default is what happens when the key is absent — TON has no "required" environment variable that halts anything, which is precisely why a misconfigured install runs happily against the wrong network.

Environment variables

None of these are in .env.example. Add them by hand to the project root .env, and restart the backend afterwards — the TON service captures its endpoint and key once, at construction.

Network selector. The literal string "testnet" selects the testnet RPC and API-key pair. Anything else — including unset, empty or a typo — selects mainnet. There is no validation and no error.

Toncenter-compatible JSON-RPC endpoint used when the network is mainnet. Drives deposit polling, balance reads, withdrawal signing and withdrawal confirmation.

Toncenter API key for mainnet, sent as the X-API-Key header. Not required by the code; effectively required in production, because anonymous Toncenter allows roughly one request per second across the whole install.

Toncenter-compatible JSON-RPC endpoint used when TON_NETWORK is "testnet".

Toncenter API key for testnet, sent as the X-API-Key header.

Two shared Ecosystem keys change TON's behaviour as well:

Set to "false" to turn off the background deposit scanner for every chain. Session monitors keep running; a deposit that arrives after the user closes the deposit page is then only found when they reopen it.

Per-second scan budget for TON in the background scanner's token bucket. Raise only with a paid Toncenter plan or your own endpoint.

How often each registered deposit address is re-scanned by the background scanner, in milliseconds. Applies to every chain.

How long an address stays in the background scanner's working set after its last deposit-page visit, in milliseconds.

Keys that do not exist for TON

Operators coming from the EVM chains reach for these. None of them are read:

Key you might expect	Reality
`TON_MAINNET_RPC_WSS`	There is no WebSocket path. Deposit detection is HTTP polling only.
`TON_EXPLORER_API_KEY`	TON has no explorer integration. The admin overview reports TON as having no explorer API.
`ETHERSCAN_API_KEY`	EVM only. It has no effect on TON.
`TON_NODE` / `TON_NODE_HOST`	No provider-abstraction layer. Point `TON_MAINNET_RPC` at your own node instead.

Transaction history for a TON address comes from the chain service reading Toncenter directly, not from the generic explorer fetcher the EVM chains use.

The Toncoin token row

The seeder creates a single TON entry with status: false. Enable it and check the fields below.

Field	Seeded value	What to do
`chain`	`TON`	Leave it
`currency`	`TON`	Leave it
`contractType`	`NATIVE`	Leave it — see the warning below
`contract`	`0x0000000`	The native sentinel. Leave it
`decimals`	`18`	Wrong for TON, which is 9. Harmless for crediting, but it is the fallback for `precision`
`precision`	unset	Set it to 9. It caps decimal places on withdrawals and rounds the debit
`network`	`mainnet`	Leave it, even on testnet — see below
`fee`	unset	Set `percentage` and `min`; the platform charges `max(amount × percentage, min)` in TON
`limits`	unset	Optional per-transaction minimum and maximum

There is no jetton support in the deposit or withdrawal path. A TON token row with PERMIT or NO_PERMIT falls through to the EVM address derivation and issues an Ethereum-style 0x… address as a TON deposit address. Funds sent there are unrecoverable.

Why network: mainnet is correct on testnet. The token eligibility rule compares a token's network column against {CHAIN}_NETWORK and hides rows that disagree — but TON is on the network-agnostic list, alongside Monero, Solana, Tron and the UTXO chains, so the comparison is skipped entirely. Editing the row to testnet changes nothing; leaving it as mainnet breaks nothing.

Endpoints

Admin, all under Ecosystem's permission scheme:

Enables or disables a seeded blockchain. The path parameter is the product ID — 55715370 for TON.

Per-chain requirements report: every variable read, whether it is set, and the non-environment prerequisites

Live read-only probes against the configured endpoint, plus per-flow readiness

Creates a master wallet for a chain

Lists chains still eligible for a master wallet

Bulk-enables or disables token rows

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

User-facing, authenticated but with no admin permission:

Returns the ECO wallet for a currency, generating the TON address on first call

Submits an on-chain withdrawal

Maximum withdrawable amount after fees

Timing and limits

Every number here is compiled in. None of them is configurable except where an environment variable is named above.

Behaviour	Value
Deposit poll interval, session monitor	60 seconds
Transactions fetched per poll	10 most recent
Poll back-off on consecutive errors	Interval doubles, capped at 16× (16 minutes)
Consecutive errors before the monitor stops	10
Processed-hash memory, for de-duplication	30 minutes
Background scan rate for TON	0.5 per second
Background scan working-set lifetime	72 hours from the last deposit-page visit
Withdrawal confirmation attempts	10, ten seconds apart (about 100 seconds)
Transactions scanned per confirmation attempt	5 most recent
Cooldown between withdrawals on the same chain	5 seconds
Stale `PROCESSING` threshold before manual review	5 minutes
Internal RPC call spacing in the service queue	1 second
Licence result cache	5 minutes

The service also runs an internal one-call-per-second queue for wallet operations, which is a second reason TON throughput is bounded regardless of how fast your endpoint is.

Chain facts the platform hard-codes

Property	Value
Symbol and currency	`TON`
Decimals	9 (amounts are converted from nanotons)
Precision used for balance rounding	9
Explorer shown in the chain registry	`https://tonscan.io`
Wallet contract version created	v3R1
Deposit address form	User-friendly, non-bounceable (`UQ…`)
Custodial contracts	Not supported — TON is on the exclusion list
Confirmation depth required for deposits	None; credited on detection

What requires a restart

Change	Restart needed
`TON_NETWORK`, either RPC URL, either API key	Yes — the service reads them once
Enabling the chain row	No — the active state is re-checked while the chain is inactive
Disabling the chain row	Yes, both processes — the flag is never re-read once the service is active, so deposits, balances and withdrawal signing keep running
Activating the licence	No, but allow up to five minutes for the cache
Enabling the token row, editing fee or precision	No
Creating the master wallet	No