Guides
  1. Staking Voting and Rewards

Unstaking & cancellation

How to unstake TRX, withdraw expired funds, cancel pending unstake operations, and how unstaking affects your TRON Power and ongoing votes.

📘

Prerequisites

After staking your TRX, you can unstake at any time. Unstaking is a two-step process: initiate the unstake, wait for the period configured on the selected network, then withdraw the matured TRX into your spendable balance. Stake 2.0 also supports canceling pending unstake operations and re-staking the funds before the period ends.

How to unstake TRX

Use wallet/unfreezebalancev2 to start unstaking:

BASE_URL=https://nile.trongrid.io   # Nile testnet; the example account exists on this network
curl -X POST ${BASE_URL}/wallet/unfreezebalancev2 \
  -d '{
    "owner_address": "TTGhREx2pDSxFX555NWz1YwGpiBVPvQA7e",
    "unfreeze_balance": 100000000,
    "resource": "ENERGY",
    "visible": true
  }'

The unstaked TRX enters a pending period before it can be withdrawn. The delay is controlled by chain parameter #70 and can be changed by an SR vote. Query wallet/getchainparameters and read getUnfreezeDelayDays for the selected network. Currently, the delay is 1 day on Nile and 14 days on Shasta and Mainnet.

After the pending period ends, withdraw the unstaked TRX with wallet/withdrawexpireunfreeze:

BASE_URL=https://nile.trongrid.io   # Nile testnet; the example account exists on this network
curl -X POST ${BASE_URL}/wallet/withdrawexpireunfreeze \
  -d '{
    "owner_address": "TTGhREx2pDSxFX555NWz1YwGpiBVPvQA7e",
    "visible": true
  }'

This moves all unstaked TRX that has cleared the pending period into your spendable balance.

Unstaking constraints and automatic withdrawals

  • Partial unstaking is supported — you don't have to unstake all your stake in one operation.
  • Maximum 32 ongoing unstake operations at any time. Once you've reached the limit, wait for at least one pending period to end before initiating another unstake; you do not need to withdraw the matured funds separately first. Query wallet/getavailableunfreezecount for the number of slots remaining. The value 32 is a fixed java-tron protocol limit (UNFREEZE_MAX_TIMES), not a chain parameter, so it cannot be queried or changed through a proposal.
  • Delegated TRX cannot be unstaked. If you want to unstake delegated TRX, you must first undelegate it (see Delegating resources).
  • Unstaking reclaims TRON Power — see TRON Power reclamation below.
  • Combined automatic withdrawal — when you initiate a new unstake and previous unstakes have already cleared the selected network's pending period, the network automatically withdraws the cleared amount in the same transaction. No separate withdrawexpireunfreeze call is needed. The auto-withdrawn amount appears in withdraw_expire_amount of the transaction info (queryable via wallet/gettransactioninfobyid).

TRON Power reclamation

When you unstake TRX from Stake 2.0, the same amount of TRON Power (TP) is reclaimed from your account. The system reclaims TP in this priority order:

  1. Idle (unused) TP first. If you have TP that hasn't been voted, it goes first.
  2. Then voted TP, proportionally from each SR you voted for.

The formula for revoking votes from an SR you voted for:

Votes revoked from a given SR =
  Total votes to revoke
  × (Votes you cast for that SR / Total votes you cast across all SRs)

Proportional TRON Power reclamation example

Account A has staked 2,000 TRX, giving 2,000 TP. Of those:

  • 1,000 TP voted (600 votes for SR 1, 400 votes for SR 2)
  • 1,000 TP idle

Account A unstakes 1,500 TRX → 1,500 TP must be reclaimed:

  • First 1,000 TP is reclaimed from idle TP (depleting the idle pool).
  • Remaining 500 TP is reclaimed proportionally from voted TP:
    • From SR 1: 500 × (600 / 1,000) = 300 votes revoked
    • From SR 2: 500 × (400 / 1,000) = 200 votes revoked

After the unstake, Account A has 500 TP remaining, all of it voted: 300 votes for SR 1 and 200 votes for SR 2.

How to cancel pending unstake operations

Stake 2.0 lets you cancel all pending unstake operations and re-stake the funds immediately, without waiting for the pending period to end. Use wallet/cancelallunfreezev2:

BASE_URL=https://nile.trongrid.io   # Nile testnet; the example account exists on this network
curl -X POST ${BASE_URL}/wallet/cancelallunfreezev2 \
  -d '{
    "owner_address": "TTGhREx2pDSxFX555NWz1YwGpiBVPvQA7e",
    "visible": true
  }'

What happens:

  • All unstake operations still in the pending period are canceled. Their TRX is immediately re-staked, recovering the same Bandwidth/Energy and TP as before the unstake.
  • Unstake operations that have already cleared the pending period will not be canceled — that TRX is automatically withdrawn to your spendable balance as part of the same transaction.

The transaction info reports two relevant fields (queryable via wallet/gettransactioninfobyid):

  • cancel_unfreezeV2_amount — an object whose BANDWIDTH, ENERGY, and TRON_POWER keys report the re-staked amount for each resource type, in sun
  • withdraw_expire_amount — the amount withdrawn from expired unstake operations, in sun

The cancelallunfreezev2 API is gated by chain parameter #77 (getAllowCancelAllUnfreezeV2). It is already active on Mainnet.

Note on Stake 1.0 unstakes

Use the Stake1.0 API (not unfreezebalancev2) for any TRX still staked under Stake 1.0. Note that Stake 1.0 unstakes revoke all of your votes at once — unlike Stake 2.0, which reclaims TP proportionally.

Related resources

Updated 8 days ago