Guides
Chinese(中文版)
  1. Integration

Exchange and custodial wallet integration

Operating an exchange, custodial wallet, or payment platform on TRON. This sub-chapter covers the architecture choice between TronGrid and a self-hosted full node, the core operations (deposit monitoring, withdrawals, balance queries, optional staking), and a pre-launch checklist.

If you operate a centralized service that holds TRX or TRC tokens for users — an exchange, a custodial wallet, a payment platform — this sub-chapter is for you. Three concerns shape every integration:

  • Asset operations — detecting user deposits within minutes and broadcasting their withdrawals
  • Balance and history queries — TRX, TRC-10, TRC-20, optionally TRC-721
  • Operational scaffolding — hot and cold wallet separation, multi-sig, resource budgeting

This page is the architecture-level overview. The full implementation guide — node configuration, every API, block parsing logic, staking endpoints — is at Exchange wallet integration.

📘

Prerequisites

1. What needs to integrate

Asset operations (every integration)

  • Deposit detection — when a user transfers TRX or a TRC token to a deposit address you control, your system must detect it within minutes and credit the user
  • Withdrawal construction — build, sign, and broadcast transactions to send TRX or a TRC token to a user's external address
  • Balance and history queries — for TRX, TRC-10, TRC-20, and any other token standards you list

Staking services (optional)

  • Stake and unstake — let users stake TRX through your platform and surface the unstake delay before withdrawal. It is controlled by chain parameter #70, currently 14 days on Mainnet; query getUnfreezeDelayDays from /wallet/getchainparameters for the current value.
  • Voting — let users assign their voting power to Super Representatives
  • Reward distribution — withdraw voting rewards and credit them to the right user balances

Operational concerns (every integration)

  • Hot and cold wallet separation — your security architecture; not TRON-specific, but TRON's permission system enables clean implementation
  • Multi-sig — for cold wallets and treasury operations, see Account permission management
  • Resource budgeting — every withdrawal transaction consumes Bandwidth; TRC-20 transfers and other contract calls also consume Energy. Plan both resources where applicable — see Resource model

2. Architecture choice: TronGrid vs self-hosted full node

DimensionTronGrid (hosted)Self-hosted full node
Setup costAPI key request and integrationHardware, ongoing ops, monitoring
Rate limitsTiered by plan — see TronGrid rate limitsNot subject to TronGrid service quotas; throughput depends on node resources and rate-limit configuration
Extension APIsAccount history, TRC-20 history, contract events, othersNot available — you build them by parsing blocks
Latency controlTronGrid'sYours
Block parsingFetch solidified block JSON through /walletsolidity/getnowblock and /walletsolidity/getblockbynum, then parse it in your application; subject to quotas and rate limitsFetch blocks through local node APIs, with control over storage and runtime settings
Best forSmall to medium volume; quick startHigh volume; need custom indexing or lowest latency

Most integrators start with TronGrid and migrate to a self-hosted node when volume or feature needs justify it. Both paths speak the same wire format, so the migration cost is small — typically a change of base URL plus your own implementation of any extension APIs you depended on.

For self-hosted setup, see Deploy a node and the broader RPC and indexer providers page.

3. Deposit-monitoring patterns

Two patterns are common:

Pattern A — Poll TronGrid account-history APIs

The simplest approach. Every few seconds, call v1/accounts/{address}/transactions for each deposit address. Follow all pagination links and retain an overlap with the previous polling window; use timestamps only to bound the query, not as unique identifiers. For top-level transactions returned by this endpoint, deduplicate by network, txID, and record type. If you also ingest TRC-20 events or internal transactions, include the event or internal-transaction index, and include the asset ID when one internal transaction carries multiple assets.

Trade-offs: easy to implement; rate-limited by your TronGrid plan; latency equals your polling interval. Suitable for small to medium volume.

Pattern B — Parse blocks as they finalize

Use /walletsolidity/getnowblock through TronGrid or a self-hosted node to obtain the latest solidified height, then fetch block JSON sequentially with /walletsolidity/getblockbynum. Walk the transactions to identify activity affecting your deposit addresses, and record the processed height so processing can resume after a restart.

Trade-offs: TronGrid access is subject to service quotas and rate limits. A self-hosted node gives you control over storage and runtime settings, with throughput depending on node resources and configuration. Both approaches require block-parsing logic. Block JSON provides top-level transactions; event logs and internal transactions must be retrieved separately from transaction execution results and parsed as distinct records.

Full implementation patterns — including the type dispatch for TransferContract, TransferAssetContract, and TriggerSmartContract — are in Exchange wallet integration § Parsing blocks.

4. Staking services — decision matrix

QuestionIf yesIf no
Will users stake TRX through your UI?Read Staking, voting, and rewards and implement the Stake 2.0 APISkip §4
Will users vote for Super Representatives?Implement the votewitnessaccount flowShow "staking only" UX
Will you accumulate voting rewards centrally and distribute?Implement withdrawbalance plus ledger accountingUsers withdraw their own rewards
Will you offer resource delegation (Energy or Bandwidth lending)?Implement delegateresource plus lockup trackingSkip

5. Resource and fee considerations

Every withdrawal transaction consumes Bandwidth. TRC-20 transfers and other smart-contract transactions also consume Energy, so their costs must account for both resources. The account can cover these resources through staking or delegation; if the applicable resource is insufficient, the protocol may burn TRX according to the corresponding resource rules.

Two resource-provisioning strategies are common:

  • Stake TRX for resources — predictable, recommended for high-volume operators. See Resource model and Staking, voting, and rewards for Stake 2.0
  • Burn TRX per transaction — simpler accounting, more expensive at volume

For smart-contract deployment and invocation transactions, fee_limit caps the caller-side Energy budget. It is not a field on ordinary TRX or TRC-10 transfers. An insufficient value can cause contract execution to fail with OUT_OF_ENERGY; see FeeLimit and Energy cost for sizing and settlement rules.

6. Pre-launch checklist

Before going live, verify the following:

  • Deposit address derivation is BIP-44-compliant; you can recover any address from a master seed if your hot system is lost
  • Withdrawal signing is performed offline, in an HSM, or by a hardware wallet — not by a key sitting in plaintext on your application server
  • You handle TRX, TRC-10, and TRC-20 separately — they are different transaction types and balances
  • You parse internal transactions when crediting deposits — a user may receive TRX or TRC-10 through a smart contract call (e.g., a swap router); these do not appear as top-level transactions
  • You read from a solidified block height, not the chain head — solidification is ~1 minute behind head and guarantees no fork rollback
  • You handle reorganization gracefully — TRON has fast finality but is not finalized on the head block
  • Your resource and fee strategy is decided before scaling traffic
  • If offering staking — the unstake delay (currently 14 days on Mainnet, query via /wallet/getchainparameters) is visible in your UI; users will ask

In this section

Related resources

Updated 18 days ago