Delegating resources

📘

Prerequisites

• Stake 2.0 overview

In Stake 2.0, staking and delegation are independent operations. After staking TRX to obtain resources, you can lend those resources to another account without unstaking — the original TRX stays staked under your name, but the recipient account gets to use the Bandwidth or Energy.

What can be delegated

Additional constraints enforced by the network:

• Available balance after current usage — you can delegate up to your staked Bandwidth/Energy balance minus your current usage in the 24-hour recovery window. Recently-consumed resources reduce what is delegatable until the recovery window clears.
• Minimum delegation = 1 TRX (1,000,000 sun). Smaller amounts are rejected with "delegateBalance must be greater than or equal to 1 TRX".
• Cannot delegate to yourself — receiver_address must differ from owner_address.
• Cannot delegate to a contract address — the recipient must be an externally-owned account. Contract addresses are rejected with "Do not allow delegate resources to contract addresses".
• Resource type must be Bandwidth or Energy — TP is non-delegatable as noted above.
• Stake 1.0 vs Stake 2.0 — delegation is a Stake 2.0 feature. TRX still staked under Stake 1.0 is not delegatable; you must first unstake it under Stake 1.0, then stake it again with Stake 2.0.

To check how much of a given resource you can delegate right now, query wallet/getcandelegatedmaxsize.

How to delegate

Use wallet/delegateresource:

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

The balance field is the TRX equivalent (in sun) of the resources you are delegating, not the Energy or Bandwidth amount itself. So delegating balance: 100000000 (100 TRX worth of stake) gives the recipient the Energy that 100 TRX of stake would currently produce — proportional to the network's overall Energy supply.

The lock and lock_period options

When you delegate, you can lock the delegation for a period during which the recipient is guaranteed to retain the resources.

lock_period is in blocks, not seconds. lock_period = 28800 means 28800 × 3 s = 86,400 s = 24 hours of lockup.

The maximum allowed lock_period is governed by chain parameter #78 (getMaxDelegateLockPeriod). The code default is 86,400 blocks (3 days) with a range up to 10,512,000 blocks (365 days). SRs can adjust the cap via proposal — query wallet/getchainparameters for the live Mainnet value.

📘

Re-delegating during a lockup

The network stores locked and unlocked delegations under separate database keys for each (owner, recipient, resource) triple — a key with the V2_LOCK_PREFIX for lock=true, and a key with the plain V2_PREFIX for lock=false. They coexist independently.

When you re-delegate the same resource type to the same recipient, behavior depends on the new transaction's lock flag:

• lock = true — the new lock_period must be at least equal to the remaining lockup time, or the transaction is rejected by validRemainTime. When accepted, the locked record's expireTime is replaced with now + new lock_period and the new balance is added to the existing locked delegation. A lockup can therefore be extended or matched, but never shortened; a delegator who keeps re-delegating with lock=true can keep a recipient locked indefinitely.
• lock = false (or unset) — the locked record (balance and expireTime) is unchanged. The new balance is written to the separate unlocked record, which the owner can undelegate at any time. The lock_period field is silently ignored when lock=false; it cannot be used to shorten or release an active lockup.

Recipients negotiating a delegation should clarify lockup behavior in advance and should not assume an unlocked top-up has released the original locked balance.

📘

Expired lock record cleanup

Expired locked records are auto-archived on the next delegation. If a locked record for a recipient has already expired, the next delegateresource to that recipient (whether or not lock is true) first migrates the expired locked balance to the unlocked record (unLockExpireResource) before processing the new delegation. No manual action is required, but note the recipient's resource state has moved from "locked" to "unlocked" and can be undelegated at any time.

How to undelegate

Use wallet/undelegateresource:

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

Undelegation is immediate for non-locked delegations and only permitted after the lockup expires for locked delegations. The TRX stays staked under your account; only the routing of the resource share changes.

🚧

The recipient may have used the resource

When you undelegate, the network reclaims a proportional amount of the recipient's unrecovered resources (those still in the 24-hour recovery window). This means the recipient can lose part of their resource pool when you undelegate, even though they didn't initiate the action. See Resource reclamation upon undelegation for the full formula.

A worked example

A DApp operator delegates 1,000 TRX worth of Energy to a new user so the user can interact with the DApp without staking themselves. The operator wants the delegation locked for 1 day (28,800 blocks).

# Step 1 — operator delegates Energy to user, locked for 1 day
BASE_URL=https://api.trongrid.io   # example — replace with any TRON node (TronGrid, third-party, or self-hosted)
curl -X POST ${BASE_URL}/wallet/delegateresource \
  -d '{
    "owner_address": "<DApp_operator>",
    "receiver_address": "<user>",
    "balance": 1000000000,
    "resource": "ENERGY",
    "lock": true,
    "lock_period": 28800,
    "visible": true
  }'
# → Sign and broadcast. User now has the Energy share of 1,000 TRX of stake,
#   for the next 24 hours (28,800 blocks × 3 seconds).

After 24 hours pass, the operator decides to undelegate:

# Step 2 — operator undelegates after the lockup expires
BASE_URL=https://api.trongrid.io   # example — replace with any TRON node (TronGrid, third-party, or self-hosted)
curl -X POST ${BASE_URL}/wallet/undelegateresource \
  -d '{
    "owner_address": "<DApp_operator>",
    "receiver_address": "<user>",
    "balance": 1000000000,
    "resource": "ENERGY",
    "visible": true
  }'

If the user used some of the Energy during the 24 hours and is still in the recovery window, the network deducts a proportional amount of the user's unrecovered Energy — see Resource reclamation upon undelegation for the math.

Querying delegation state

Related resources

• Stake 2.0 overview — stake TRX before delegating
• Resource reclamation upon undelegation — the formula behind reclaimed unrecovered resources
• Unstaking & cancellation — note that delegated TRX cannot be unstaked
• Staking & reward APIs — full API reference table
• Stake 2.0 Solidity SDK reference — delegate from inside a smart contract