wallet/unfreezebalancev2 | TRON API Docs

Unstake TRX to reclaim resources (bandwidth/energy) on TRON network via Dwellir's optimized RPC endpoint with Stake 2.0 support.

Unstake (unfreeze) TRX to reclaim bandwidth or energy resources using TRON's Stake 2.0 mechanism. This is a native TRON wallet API endpoint -- there is no direct EVM-compatible (JSON-RPC) equivalent for staking operations.

Understanding TRON resource economics

TRON's bandwidth and energy model is central to its fee structure. Unlike Ethereum where every transaction burns gas, TRON users can stake TRX via wallet/freezebalancev2 to obtain reusable energy and bandwidth, making transactions effectively free. Unstaking reverses this, reclaiming TRX at the cost of losing those resources after a 14-day waiting period.

Endpoint

Text

POST /wallet/unfreezebalancev2

Request Parameters

Request

owner_addressstring

Account address initiating unstaking (base58)

resourcestring

Resource type: "BANDWIDTH" or "ENERGY"

unfreeze_balancenumber

Amount to unstake in SUN (1 TRX = 1,000,000 SUN)

Response Body

Response

txIDstring

Transaction identifier for the unsigned unstake transaction.

raw_dataobject

Raw transaction payload, including contract, reference block data, and timestamps.

visibleboolean

Indicates whether address fields use Base58Check encoding.

# Basic unstaking request for energy    curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/unfreezebalancev2 \      -H "Content-Type: application/json" \      -d '{        "owner_address": "TYourAddress...",        "resource": "ENERGY",        "unfreeze_balance": 1000000000,        "visible": true      }'    # Unstake bandwidth    curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/unfreezebalancev2 \      -H "Content-Type: application/json" \      -d '{        "owner_address": "TYourAddress...",        "resource": "BANDWIDTH",        "unfreeze_balance": 500000000,        "visible": true      }'    # Unstake delegated resources    curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/unfreezebalancev2 \      -H "Content-Type: application/json" \      -d '{        "owner_address": "TYourAddress...",        "resource": "ENERGY",        "unfreeze_balance": 2000000000,        "receiver_address": "TReceiverAddress...",        "visible": true      }'    # Check pending withdrawals (via getaccount)    curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/getaccount \      -H "Content-Type: application/json" \      -d '{        "address": "TYourAddress...",        "visible": true      }'    # Withdraw expired unfrozen balance    curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/withdrawexpireunfreeze \      -H "Content-Type: application/json" \      -d '{        "owner_address": "TYourAddress...",        "visible": true      }'

{  "visible": true,  "txID": "8f3c4f9e2b8a7d6c5e4f3b2a1d9c8e7f6b5a4d3c2e1f9a8b7c6d5e4f3a2b1c9d",  "raw_data": {    "contract": [      {        "parameter": {          "value": {            "owner_address": "TYourAddress...",            "unfreeze_balance": 1000000000,            "resource": "ENERGY"          },          "type_url": "type.googleapis.com/protocol.UnfreezeBalanceV2Contract"        },        "type": "UnfreezeBalanceV2Contract"      }    ],    "ref_block_bytes": "5a4b",    "ref_block_hash": "3c2d4f9e8b7a6d5c",    "expiration": 1702456849000,    "timestamp": 1702456789000  }}

Important Notes

Unstaking Process

14-Day Waiting Period: After unstaking, TRX enters a 14-day withdrawal period
No Resources During Wait: Resources are lost immediately, TRX remains locked
Manual Withdrawal: After 14 days, must call withdrawexpireunfreeze to claim TRX
Partial Unstaking: Can unstake portions of staked amount

Resource Implications

Bandwidth/Energy is removed immediately upon unstaking
Cannot re-stake the same TRX during withdrawal period
Consider keeping minimum stake for basic operations

Implementation Examples

Bash

# Basic unstaking request for energy
curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/unfreezebalancev2 \
  -H "Content-Type: application/json" \
  -d '{
    "owner_address": "TYourAddress...",
    "resource": "ENERGY",
    "unfreeze_balance": 1000000000,
    "visible": true
  }'

# Unstake bandwidth
curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/unfreezebalancev2 \
  -H "Content-Type: application/json" \
  -d '{
    "owner_address": "TYourAddress...",
    "resource": "BANDWIDTH",
    "unfreeze_balance": 500000000,
    "visible": true
  }'

# Unstake delegated resources
curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/unfreezebalancev2 \
  -H "Content-Type: application/json" \
  -d '{
    "owner_address": "TYourAddress...",
    "resource": "ENERGY",
    "unfreeze_balance": 2000000000,
    "receiver_address": "TReceiverAddress...",
    "visible": true
  }'

# Check pending withdrawals (via getaccount)
curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/getaccount \
  -H "Content-Type: application/json" \
  -d '{
    "address": "TYourAddress...",
    "visible": true
  }'

# Withdraw expired unfrozen balance
curl -X POST https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY/wallet/withdrawexpireunfreeze \
  -H "Content-Type: application/json" \
  -d '{
    "owner_address": "TYourAddress...",
    "visible": true
  }'

Unstaking Timeline

mermaid

graph LR
    A[Staked TRX] --> B[Initiate Unstaking]
    B --> C[14-Day Waiting Period]
    C --> D[Withdrawal Available]
    D --> E[Execute Withdrawal]
    E --> F[TRX in Wallet]
    
    style A fill:#4CAF50
    style C fill:#FF9800
    style F fill:#2196F3

Best Practices

1. Plan Unstaking Carefully

Resources are lost immediately
Cannot re-stake during withdrawal period
Keep minimum stake for basic operations

2. Monitor Withdrawal Periods

Track 14-day waiting periods
Set reminders for withdrawal dates
Batch withdrawals for efficiency

3. Resource Management

JavaScript

// Keep minimum operational resources
const MIN_ENERGY_STAKE = 5000; // TRX
const MIN_BANDWIDTH_STAKE = 1000; // TRX

function calculateSafeUnstake(current, minimum) {
  return Math.max(0, current - minimum);
}

4. Error Handling

Check account has staked balance
Verify resource type is correct
Handle insufficient stake errors

Common Errors

Error	Description	Solution
`No frozen balance`	Account has no staked TRX	Check staking status first
`Invalid resource type`	Resource must be BANDWIDTH or ENERGY	Use correct resource string
`Insufficient frozen balance`	Trying to unstake more than available	Check current stake amount
`Invalid address`	Malformed TRON address	Verify base58 format

Use Cases

Resource Optimization: Unstake excess resources not being used
Liquidity Management: Free up TRX for trading or transfers
Delegation Cleanup: Reclaim delegated resources from inactive accounts
Portfolio Rebalancing: Adjust resource allocation between bandwidth/energy
Emergency Liquidity: Access staked TRX when needed (with 14-day delay)

wallet/freezebalancev2 - Stake TRX for resources
wallet/getaccountresource - Check resource status
wallet/delegateresource - Delegate resources to others

wallet/unfreezebalancev2 - Unstake TRX for Reso...