GuidesAPI ReferenceCommunityDiscordBlogFAQBug BountyAnnouncements
Guides
Chinese(中文版)
  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 (which begins a 14-day pending period), then withdraw the unstaked TRX into your spendable balance. Stake 2.0 also supports canceling pending unstake operations and re-staking the funds without waiting.

How to unstake TRX

Use wallet/unfreezebalancev2 to start unstaking:

BASE_URL=https://api.trongrid.io   # example — replace with any TRON node (TronGrid, third-party, or self-hosted)
curl -X POST ${BASE_URL}/wallet/unfreezebalancev2 \
  -d '{
    "owner_address": "TTGhREx2pDSxFX555NWz1YwGpiBVPvQA7e",
    "unfreeze_balance": 100000000,
    "resource": "ENERGY",
    "visible": true
  }'

The unstaked TRX enters a 14-day pending period before it can be withdrawn. The 14-day delay is chain parameter #70 (UNFREEZE_DELAY_DAYS) and can be changed by an SR vote — query the current value via wallet/getchainparameters.

After 14 days, withdraw the unstaked TRX with wallet/withdrawexpireunfreeze:

BASE_URL=https://api.trongrid.io   # example — replace with any TRON node (TronGrid, third-party, or self-hosted)
curl -X POST ${BASE_URL}/wallet/withdrawexpireunfreeze \
  -d '{
    "owner_address": "TTGhREx2pDSxFX555NWz1YwGpiBVPvQA7e",
    "visible": true
  }'

This moves all unstaked TRX that has cleared its 14-day pending period into your spendable balance.

Constraints to know

  • Partial unstaking is supported — you don't have to unstake all your stake in one operation.
  • Maximum 32 ongoing unstake operations at any time. This cap (UNFREEZE_MAX_TIMES = 32) is hardcoded in the actuator — it is not a chain parameter and cannot be adjusted by governance. Once you've reached 32 pending unstakes, you must wait for some to clear before initiating a new one. Query wallet/getavailableunfreezecount for the number of slots remaining.
  • 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 you have previous unstakes that have already cleared their 14-day 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)

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 14-day period to clear. Use wallet/cancelallunfreezev2:

BASE_URL=https://api.trongrid.io   # example — replace with any TRON node (TronGrid, third-party, or self-hosted)
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 14-day 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 — TRX re-staked from canceled unstake operations
  • withdraw_expire_amount — TRX withdrawn from already-expired unstake operations

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 7 days ago