Tron Address Balance API

Sunsetting 10 August 2026 — migrate now

Tron.BalanceUpdates is scheduled to sunset on 10 August 2026. It still returns live data today, so existing queries have not broken yet — but they will stop working on that date.

Move to Tron.Balances and Tron.Holders (documented on this page). They read from aggregate-state tables and return the current balance directly, so you no longer sum deltas yourself. The same sunset applies to EVM.BalanceUpdates and EVM.TokenHolders.

See the migration mapping for the query-by-query equivalents.

The Balances API returns current and historical token balances for an address on Tron. To return only non-zero balances, add Amount(selectWhere: { gt: "0" }) on the Balance field (not in where). Use dataset: combined or dataset: archive as follows:

Dataset	When to use
combined	Latest balances. Queries realtime and archive databases and merges results.
archive	Historical snapshots with Block.Date, and balances for addresses not recently active.

Portfolio of a Tron Wallet

Returns balances for all the currecies owned by a wallet address. Use Amount(selectWhere: { gt: "0" }) to exclude zero balances and dataset: combined for the latest balances.

Run in IDE

query TronWalletPortfolio($address: String) {
  Tron(dataset: combined) {
    Balances(
      where: {
        Balance: { Address: { is: $address } }
      }
      orderBy: { descending: Balance_AmountInUSD }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
        Native
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
        Address
      }
    }
  }
}

Variables

{
  "address": "TFXttAWURRrXrd9JvFPVLEh1esJK8NHxn7"
}

Parameters

• dataset: combined: Merges realtime and archive data for the latest balance state.
• Balance.Address: Wallet address to query.

Returned fields

• Currency.Name, Currency.Symbol, Currency.SmartContract: Token metadata.
• Balance.Amount, Balance.AmountInUSD: Token balance and USD value (use selectWhere to filter non-zero amounts).

Native TRX Balance

Returns the native TRX balance for a wallet (not TRC10 or TRC20 tokens). Filter with Currency: { Native: true } instead of a token contract address.

Run in IDE

query {
  Tron(dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf" }
        }
        Currency: { Native: true }
      }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
        Address
      }
    }
  }
}

Balance on a Specific Date

Use Block.Date.till for a point-in-time snapshot. Use dataset: archive for historical dates and addresses not recently active.

Run in IDE

query {
  Tron(dataset: archive) {
    Balances(
      where: {
        Balance: {
          Address: { is: "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf" }
        }
        Block: { Date: { till: "2025-06-01" } }
      }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
      }
    }
  }
}

Balance for a Specific Token

Add a Currency.SmartContract filter. Always use the contract address, not the token name.

Run in IDE

query {
  Tron(dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "TUTQj7VJ1QjR3t2GJByvrP25yZNFcj38VJ" }
        }
        Currency: {
          SmartContract: { is: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }
        }
      }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
        Address
      }
    }
  }
}

Balance History by Date

Returns balance snapshots over time for an address. Use dataset: archive. Order by Block_Date descending and use limit to paginate. Add Currency.SmartContract under Currency to filter by a specific token.

Run in IDE

query {
  Tron(dataset: archive) {
    Balances(
      where: {
        Balance: {
          Address: { is: "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf" }
        }
        Currency: {}
      }
      orderBy: { descending: Block_Date }
      limit: { count: 100 }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
      }
      Block {
        Date
      }
    }
  }
}

Wallet Balance for a Specific Token on a Date

Use dataset: archive, Block.Date.till, orderBy: { descending: Block_Date }, and limit: { count: 1 } to get the balance as of that date.

Run in IDE

query {
  Tron(dataset: archive) {
    Balances(
      where: {
        Block: { Date: { till: "2025-06-01" } }
        Balance: {
          Address: { is: "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf" }
        }
        Currency: {
          SmartContract: { is: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }
        }
      }
      limit: { count: 1 }
      orderBy: { descending: Block_Date }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
        Address
      }
    }
  }
}

Total Holder Count of a Tron Token

Count the total number of unique addresses holding a Tron TRC20 token with a positive balance. Use the Holders API instead of the deprecated BalanceUpdates aggregates.

Run in IDE

query TokenHolderCount {
  Tron(dataset: combined) {
    Holders(
      where: {
        Currency: { SmartContract: { is: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" } }
        Balance: { Amount: { gt: "0" } }
      }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
      }
      holders: uniq(of: Holder_Address)
    }
  }
}

Top Token Holders of a Token

Returns the top holders of a token ranked by current balance. Use the Holders API with orderBy and limit.

Run in IDE

query TopTokenHolders {
  Tron(dataset: combined) {
    Holders(
      where: {
        Currency: { SmartContract: { is: "TXL6rJbvmjD46zeN1JssfgxvSo99qC8MRT" } }
        Balance: { Amount: { gt: "0" } }
      }
      orderBy: { descending: Balance_Amount }
      limit: { count: 10 }
    ) {
      Holder {
        Address
      }
      Currency {
        Name
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
      }
    }
  }
}

Deprecated: BalanceUpdates Queries

The examples below use Tron.BalanceUpdates, which sunsets on 10 August 2026. They run today and will stop working on that date. Use Tron.Balances and Tron.Holders (sections above) instead — they answer the same questions without summing deltas.

Balance of an Address on Tron

Run Query ➤

Migrated query — use this. BalanceUpdates sunsets 10 August 2026.

{
  Tron(dataset: combined, aggregates: yes) {
    Balances(
      where: {Balance: {Address: {is: "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf"}}}
      orderBy: { descending: Balance_Amount }
    ) {
      Currency {
        Name
      }
      Balance { Amount(selectWhere: {gt: "0"}) }
    }
  }
}

Old BalanceUpdates version (stops working 10 August 2026)

{
  Tron(dataset: combined, aggregates: yes) {
    BalanceUpdates(
      where: {BalanceUpdate: {Address: {is: "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf"}}}
      orderBy: {descendingByField: "balance"}
    ) {
      Currency {
        Name
      }
      balance: sum(of: BalanceUpdate_Amount, selectWhere: {gt: "0"})
    }
  }
}

Total Holder Count of a Tron Token

Count the total number of unique addresses holding a Tron TRC20 token with a positive balance. A foundational metric for token-health dashboards.

Run the query here.

query TokenHolderCount {
  Tron(dataset: combined, aggregates: yes) {
    BalanceUpdates(
      where: {
        Currency: { SmartContract: { is: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" } }
      }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
      }
      holders: uniq(
        of: BalanceUpdate_Address
        selectWhere: { gt: "0" }
      )
    }
  }
}

Historical Balance of a Tron Address at a Specific Time

Reconstruct the balance of a wallet as of a past block time — useful for audits, airdrop snapshot eligibility, retroactive analytics, and tax tooling.

Try the query here.

query HistoricalBalanceTron($address: String, $until: DateTime) {
  Tron(dataset: combined, aggregates: yes) {
    BalanceUpdates(
      where: {
        BalanceUpdate: { Address: { is: $address } }
        Block: { Time: { till: $until } }
      }
      orderBy: { descendingByField: "balance" }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
      }
      balance: sum(of: BalanceUpdate_Amount, selectWhere: { gt: "0" })
    }
  }
}
{
  "address": "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf",
  "until": "2025-06-01T00:00:00Z"
}

Full Multi-Token Portfolio of a Tron Wallet

Return the complete TRC10 + TRC20 portfolio of any Tron address with USD valuation — the building block of Tron portfolio trackers and wallet UIs.

Run the query here.

query TronWalletPortfolio($address: String) {
  Tron(dataset: combined, aggregates: yes) {
    BalanceUpdates(
      where: { BalanceUpdate: { Address: { is: $address } } }
      orderBy: { descendingByField: "balance_usd" }
    ) {
      Currency {
        Name
        Symbol
        SmartContract
        Native
      }
      balance: sum(of: BalanceUpdate_Amount, selectWhere: { gt: "0" })
      balance_usd: sum(of: BalanceUpdate_AmountInUSD, selectWhere: { gt: "0" })
    }
  }
}
{
  "address": "TFXttAWURRrXrd9JvFPVLEh1esJK8NHxn7"
}

Top Token Holders of a token

This query fetches you the top 10 token holders of the token TXL6rJbvmjD46zeN1JssfgxvSo99qC8MRT. Check out the query here.

Migrated query — use this. BalanceUpdates sunsets 10 August 2026.

query MyQuery {
  Tron(dataset: combined) {
    Balances(
      limit: {count: 10}
      orderBy: { descending: Balance_Amount }
      where: {Currency: {SmartContract: {is: "TXL6rJbvmjD46zeN1JssfgxvSo99qC8MRT"}}}
    ) {
      Balance { Amount(selectWhere: {gt: "0"}) }
      Balance {
        Address
      }
    }
  }
}

Old BalanceUpdates version (stops working 10 August 2026)

query MyQuery {
  Tron(dataset: combined) {
    BalanceUpdates(
      limit: {count: 10}
      orderBy: {descendingByField: "balance"}
      where: {Currency: {SmartContract: {is: "TXL6rJbvmjD46zeN1JssfgxvSo99qC8MRT"}}}
    ) {
      balance: sum(of: BalanceUpdate_Amount, selectWhere: {gt: "0"})
      BalanceUpdate {
        Address
      }
    }
  }
}

Frequently Asked Questions

How do I check a Tron wallet balance?

Query Tron.Balances with the wallet address. Add a Currency.SmartContract filter for TRC20 balances, or Currency.Native: true for TRX.

Can I track balance changes over time?

Use historical balance queries with Block.Date and dataset: archive, documented on this page.