For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Request resource reclamation

post
Authorizations
CF-ACCESS-KEYstringRequired
CF-ACCESS-SIGNstringRequired
CF-ACCESS-TIMESTAMPstringRequired
Path parameters
idstringRequired

Order ID.

Header parameters
CF-ACCESS-KEYstringRequired

Your API key for authentication.

Example: your api key
CF-ACCESS-SIGNstringRequired

Request signature generated with HMAC-SHA256 and encoded in Base64. See the request signing guide for details.

Example: signature
CF-ACCESS-TIMESTAMPstringRequired

Request timestamp in UTC, for example 2008-08-08T08:08:08.888Z.

Responses
200

API response. Check code and msg for the result of the request.

application/json
codeinteger · int32Optional

Result code. 0 indicates a successful API request; any other value indicates an error.

msgstringOptional

Result message, with error details if the request fails.

sub_codestringOptional
sub_msgstringOptional
post/v1/reclaim/{id}
POST /v1/reclaim/{id} HTTP/1.1
Host: api.catfee.io
CF-ACCESS-KEY: text
CF-ACCESS-SIGN: text
CF-ACCESS-TIMESTAMP: text
Accept: */*
200

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 the data.id returned when the order was created. Do not use client_order_id.

  • Include the three authentication headers: CF-ACCESS-KEY, CF-ACCESS-SIGN, and CF-ACCESS-TIMESTAMP. This endpoint does not require a request body.

  • Generate the signature using the HTTP method POST and 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=0 means 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}. Check reclaim_hash, reclaim_timestamp, and on-chain resource information to confirm the reclamation result.

  • status and confirm_status describe delegation progress. They may remain DELEGATE_SUCCESS and DELEGATION_CONFIRMED after reclamation. Do not wait for these fields to change to a reclamation status or use them to infer that energy is still available.

  • balance is 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.

Request resource reclamation by receiving address

post

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.

Authorizations
CF-ACCESS-KEYstringRequired
CF-ACCESS-SIGNstringRequired
CF-ACCESS-TIMESTAMPstringRequired
Query parameters
receiverstringRequired

A valid TRON address receiving the resources.

Example: TJRabPrwbZy45sbavfcjinPJC18kjpRTv8
resource_typestring · enumOptional

Optional resource type. Defaults to ENERGY; specify BANDWIDTH to reclaim bandwidth.

Default: ENERGYExample: ENERGYPossible values:
Header parameters
CF-ACCESS-KEYstringRequired

Your API key for authentication.

Example: your api key
CF-ACCESS-SIGNstringRequired

Request signature generated with HMAC-SHA256 and encoded in Base64. See the request signing guide for details.

Example: signature
CF-ACCESS-TIMESTAMPstringRequired

Request timestamp in UTC, for example 2008-08-08T08:08:08.888Z.

Responses
200

Batch result; no matching orders returns zero counts and an empty failure list.

application/json
codeinteger · int32Optional

Result code. 0 indicates a successful API request; any other value indicates an error.

msgstringOptional

Result message, with error details if the request fails.

sub_codestringOptional
sub_msgstringOptional
post/v1/reclaim
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: */*
200

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.

Parameter
Type
Required
Description

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_SUCCESS are 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_SUCCESS alone 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:

Field
Type
Description

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=0 does not mean every order was accepted or that reclamation is complete on-chain. Check both counts and failed_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, and failed_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 check reclaim_hash, reclaim_timestamp, and on-chain resource information before deciding whether to retry. Do not rely on status and confirm_status alone to determine reclamation completion.

Last updated