MMashDiv

Installing the Tron addon

Activate the licence, enable the chain row, set the four environment variables, create and fund the master wallet, import your TRC-20 tokens, then prove it with the diagnostics probe.

6 min readUpdated 3 August 2026install, licence, trongrid, master-wallet, diagnostics

Tron is gated three times. The addon code must be present, the licence file must exist, and the database row must be enabled. All three are checked, they are checked separately, and two of them produce the same unhelpful message when they fail. Work through them in order.

Everything on this page assumes Ecosystem is already installed and its vault is unlocked. Creating a Tron wallet encrypts key material immediately; a locked vault fails the operation partway through.

Before you begin

    • A working Bicrypto install with Ecosystem enabled and its vault unlocked
    • The Tron addon purchased and its licence activatable on this machine
    • Shell access to the project root — the .env edits have no admin-panel equivalent
    • A TronGrid account, for the mainnet API key
    • TRX to fund the master wallet, on the network you are configuring

1. Install the addon code and activate the licence

  1. Extract the addon. The chain service lives at backend/src/blockchains/tron.ts and its compiled counterpart in backend/dist. Ecosystem loads it through a safe import, so an install that never received the files reports "Chain service installed: no" in the diagnostics rather than failing at boot.

  2. Activate the licence. Admin → System → Extensions, open the Tron entry and verify the licence. Activation writes lic/54577641.lic — an encrypted, machine-bound file. 54577641 is the seeded product ID for Tron.

  3. Apply it. From the project root:

    pnpm updator

    This is also what creates the ecosystem_blockchain rows if the Ecosystem seeders have never run on this install.

2. Enable the chain

Admin → Ecosystem → Blockchains lists the seeded chains with their product IDs. Every one of them ships with status: false; enabling flips the row.

Enables or disables a blockchain by product ID. Refuses with 403 if the licence file is absent.

The licence check happens before the write, so a 403 here means the .lic file was never created — go back to activation rather than editing the database.

Both gates are then read together by the service on first use, and the result is cached for five minutes. A chain you just enabled can still report itself inactive for a few minutes; the service re-checks its own status on the next call once it has seen an inactive result, so it recovers without a restart.

3. Set the environment variables

Add these to the project root .env. None of them appear in .env.example.

TRON_NETWORK="mainnet"
TRON_MAINNET_RPC="https://api.trongrid.io"
TRON_API_KEY="your-trongrid-api-key"
Which Tron network the service runs against. Accepts mainnet, shasta or nile and nothing else — any other value throws while the service is being constructed and kills every Tron flow on the install.
Full-host URL used as the TronWeb fullHost and as the base for every direct REST call. Defaults to the public TronGrid host.
TronGrid API key, sent as the TRON-PRO-API-KEY header on every request. Effectively mandatory on mainnet.

The RPC variable is per network and only the selected one is read. TRON_SHASTA_RPC defaults to https://api.shasta.trongrid.io and TRON_NILE_RPC to https://api.nileex.io. Full details in the environment reference.

The service resolves its host from TRON_NETWORK inside its constructor. An unrecognised value throws there, so the singleton is never built and every call site — deposit monitor, withdrawal queue, master wallet creation, admin balance lookups — fails with "Tron service not available". The diagnostics page reports this explicitly; nothing else does.

Why the API key matters more than it looks

Both deposit endpoints are plain REST calls to TronGrid, and the deposit monitor polls them every 30 seconds per watched address. Without a key you are on the anonymous quota.

The monitor handles this gracefully at first — a 429 doubles its interval, a 403 triples it, up to a five-minute ceiling. But after ten consecutive errors it logs "Max consecutive errors reached" and deletes its own polling loop. Deposits on that address then stop being detected until the user reopens the deposit page or the background scanner reaches it.

Restart the backend after editing .env. The service is a singleton constructed on first use, and nothing re-reads these values.

pm2 restart backend

4. Create and fund the master wallet

Generates, encrypts and stores a master wallet for a chain

Admin → Ecosystem → Wallets → Master Wallets, choose TRON. One per chain is enforced; a second attempt returns 409.

The Tron master wallet is generated by the chain service itself — a fresh BIP-39 mnemonic and a key at m/44'/195'/0'/0/0, encrypted with the Ecosystem vault key and stored in ecosystem_master_wallet.data. It is not an HD parent. Unlike the EVM chains, no user address is derived from it, so its role here is narrower than the master wallet guide describes for EVM: on Tron it is a gas tank and nothing else.

Fund it with TRX. How much depends entirely on your TRC-20 volume and whether you stake — see Energy and bandwidth. Start with enough for a few hundred transfers and watch what it actually burns.

A Tron install with an empty master wallet still pays out native TRX perfectly well. Only TRC-20 payouts stall. The symptom is selective — USDT withdrawals sit in the queue while TRX ones complete — which reads like a token configuration problem and is not.

5. Import your tokens

Tron token contracts are imported, never deployed. The deployment endpoint supports EVM chains and Solana only.

Registers an existing on-chain token contract as an Ecosystem token

Admin → Ecosystem → Tokens → Import. Supply chain TRON, the contract address, the currency symbol, decimals and precision. Native TRX is imported with contractType: NATIVE and no contract address.

Get decimals right. It is used to convert raw on-chain integers into a balance, to compute the deposit dust floor, and to convert a withdrawal amount back into the smallest unit. A wrong value does not error — it credits and debits the wrong number.

Set the token's fee object deliberately. It is denominated in the token, it is the only thing the user is charged, and it is where you recover the TRX the master wallet burns on their behalf. The network cost is never added to a customer's debit.

6. Verify

Full per-chain requirements report — every variable the runtime reads and every non-environment prerequisite
Runs live read-only probes against the chain and returns per-flow readiness

Admin → Ecosystem → Blockchains → Requirements, select Tron, run the test. It performs four checks:

Check What it proves
Network configured TRON_NETWORK resolves to a real host and that host is a valid http(s) URL
Node liveness POST /wallet/getnowblock returns a block height
TronGrid REST + API key The account-transactions endpoint answers 200 — this is the exact path deposit polling uses
Chain service installed / licence + DB toggle The addon files are present and both gates pass

The REST check passes with a warning when there is no API key: it works, and it will not keep working under load. Treat that warning as a failure on a production install.

Readiness is then reported per flow — deposits and withdrawals — and the overall result is a pass only when every check passed and no flow is broken. An RPC that answers is not a pass while the vault is locked or the master wallet is missing, because a customer still cannot get their money out.

Finally, open the deposit page for a Tron-backed currency as a real user. You should get a base58 address starting with T. Send a small amount, watch it credit, and withdraw it back out. Do this on Shasta or Nile first if you can — set TRON_NETWORK="shasta", restart, and use a public faucet for test TRX.

Tron addresses are the same format on every network, and the platform's token-network guard treats Tron as network-agnostic, so nothing warns you. After changing TRON_NETWORK, existing addresses are still issued and still look correct — they are simply being watched on a chain where the user's coins are not. Decide the network before you take real deposits.