Reclaim Energy
Request reclamation of rented energy or bandwidth by order ID or receiving address
Request reclamation of energy or bandwidth by order ID, or in batches by receiving address and resource type.
Reclamation by Order ID
Use POST /v1/reclaim/{id} to request energy reclamation for a specified order.
Order ID.
Your API key for authentication.
your api keyRequest signature generated with HMAC-SHA256 and encoded in Base64. See the request signing guide for details.
signatureRequest timestamp in UTC, for example 2008-08-08T08:08:08.888Z.
API response. Check code and msg for the result of the request.
Result code. 0 indicates a successful API request; any other value indicates an error.
Result message, with error details if the request fails.
POST /v1/reclaim/{id} HTTP/1.1
Host: api.catfee.io
CF-ACCESS-KEY: text
CF-ACCESS-SIGN: text
CF-ACCESS-TIMESTAMP: text
Accept: */*
API response. Check code and msg for the result of the request.
{
"code": 1,
"msg": "text",
"sub_code": "text",
"sub_msg": "text",
"data": {
"id": "text",
"client_order_id": "text",
"resource_type": "ENERGY",
"source_type": "TRANSFER",
"pay_timestamp": 1,
"receiver": "text",
"delegate_hash": "text",
"delegate_timestamp": 1,
"reclaim_hash": "text",
"reclaim_timestamp": 1,
"pay_amount_sun": 1,
"activate_amount_sun": 1,
"quantity": 1,
"staked_sun": 1,
"duration": 1,
"expired_timestamp": 1,
"status": "PAYMENT_SUCCESS",
"activate_status": "DEACTIVATE",
"confirm_status": "UNCONFIRMED",
"balance": 1
}
}Request Details
Replace
{id}in the path with thedata.idreturned when the order was created. Do not useclient_order_id.Include the three authentication headers:
CF-ACCESS-KEY,CF-ACCESS-SIGN, andCF-ACCESS-TIMESTAMP. This endpoint does not require a request body.Generate the signature using the HTTP method
POSTand the full path with the actual order ID, such as/v1/reclaim/your_order_id. See API Overview for signature rules.
Example request (replace the order ID, authentication details, and timestamp):
Response and Result Confirmation
The endpoint returns order data with the same fields described in Order Details.
code=0means the reclaim request succeeded. It does not mean reclamation is complete on-chain. See API Error Codes and Handling for nonzero codes and recommended actions.After submitting the request, query the order with
GET /v1/order/{id}. Checkreclaim_hash,reclaim_timestamp, and on-chain resource information to confirm the reclamation result.statusandconfirm_statusdescribe delegation progress. They may remainDELEGATE_SUCCESSandDELEGATION_CONFIRMEDafter reclamation. Do not wait for these fields to change to a reclamation status or use them to infer that energy is still available.balanceis the user's current balance in SUN (1 TRX = 1,000,000 SUN), not an amount reclaimed by this request.
If a timeout, network disconnection, or uncertain outcome occurs, query the original order first. Contact support if the result remains unclear, and avoid repeatedly submitting reclaim requests.
Batch Reclamation by Receiving Address
Use POST /v1/reclaim to request reclamation of the current member's orders by receiving address and resource type, without submitting each order ID separately.
Selects up to 100 orders belonging to the current member with the specified receiving address, resource type, and internal status DELEGATE_SUCCESS, without filtering confirmation status. code=0 does not mean all orders were accepted or reclamation is complete on-chain. Check the counts and failed_order_ids.
A valid TRON address receiving the resources.
TJRabPrwbZy45sbavfcjinPJC18kjpRTv8Optional resource type. Defaults to ENERGY; specify BANDWIDTH to reclaim bandwidth.
ENERGYExample: ENERGYPossible values: Your API key for authentication.
your api keyRequest signature generated with HMAC-SHA256 and encoded in Base64. See the request signing guide for details.
signatureRequest timestamp in UTC, for example 2008-08-08T08:08:08.888Z.
Batch result; no matching orders returns zero counts and an empty failure list.
Result code. 0 indicates a successful API request; any other value indicates an error.
Result message, with error details if the request fails.
POST /v1/reclaim?receiver=text HTTP/1.1
Host: api.catfee.io
CF-ACCESS-KEY: text
CF-ACCESS-SIGN: text
CF-ACCESS-TIMESTAMP: text
Accept: */*
Batch result; no matching orders returns zero counts and an empty failure list.
{
"code": 0,
"msg": "",
"data": {
"matched_count": 3,
"accepted_count": 2,
"failed_order_ids": [
"failed_order_id"
]
}
}Request Details
Pass parameters in the URL query string. No request body is required.
receiver
string
Yes
A valid TRON address receiving the resources.
resource_type
string
No
ENERGY or BANDWIDTH. Defaults to ENERGY; specify BANDWIDTH to reclaim bandwidth.
Include the same three authentication headers as for single-order reclamation. Generate the signature using the HTTP method POST and the request path including the full query string, with parameter order and encoding matching the actual request. See API Overview for signature rules.
Example request (replace the receiving address, authentication details, and timestamp):
Processing Scope
Only orders belonging to the authenticated member with the specified receiving address, resource type, and internal status
DELEGATE_SUCCESSare selected. Confirmation status is not filtered, so orders whose delegation is not yet confirmed may also match.Each request selects up to 100 orders and processes them individually. Orders without successful delegation, orders being reclaimed, and reclaimed orders are excluded. Since Order Details maps internal reclamation statuses, a returned
status=DELEGATE_SUCCESSalone does not indicate whether an order will match.Each order is first submitted for immediate reclamation. If reclamation fails or is not executed, its expiration time is brought forward to the current time for background processing; already expired orders keep their existing expiration time.
If updating the expiration time or reloading an individual order fails, its ID is added to the failure list and processing continues for other orders. A failure to query the batch still returns an error.
Response and Result Confirmation
The response data contains the batch result, not order details. Example response with an order that was not accepted:
matched_count
integer
Orders matched by this request, up to 100; not the total number of orders for the address.
accepted_count
integer
Orders accepted for immediate reclamation or successfully handled by the expiration fallback; does not indicate on-chain completion.
failed_order_ids
string[]
IDs of orders that could not be accepted by this request; an empty array if all were accepted.
code=0does not mean every order was accepted or that reclamation is complete on-chain. Check both counts andfailed_order_ids. See API Error Codes and Handling for nonzero codes.When no orders match, the response contains
code=0,matched_count=0,accepted_count=0, andfailed_order_ids=[].When
matched_count=100, more orders may remain; call the endpoint again to process them. Orders handled by the expiration fallback may match again if their internal status has not changed, so do not add counts across requests to calculate the total number of reclaimed orders.For failed orders or uncertain outcomes, first query
GET /v1/order/{id}and checkreclaim_hash,reclaim_timestamp, and on-chain resource information before deciding whether to retry. Do not rely onstatusandconfirm_statusalone to determine reclamation completion.
Last updated