> For the complete documentation index, see [llms.txt](https://docs.catfee.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catfee.io/en/api-reference/reclaim-energy.md).

# 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.

{% openapi src="/files/6qXC6RrOuqtzIYmAmGSc" path="/v1/reclaim/{id}" method="post" %}
[api.json](https://4164384423-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa332YYkbT2p9snj9atS0%2Fuploads%2Fgit-blob-686dfe3c6ef251a9d69c042fbd858c32a092401d%2Fapi.json?alt=media)
{% endopenapi %}

### 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](/en/getting-started/buy-energy-via-api-on-catfee/api-overview.md) for signature rules.

Example request (replace the order ID, authentication details, and timestamp):

```http
POST /v1/reclaim/your_order_id HTTP/1.1
Host: api.catfee.io
CF-ACCESS-KEY: your_api_key
CF-ACCESS-SIGN: generated_signature
CF-ACCESS-TIMESTAMP: current_utc_timestamp
```

### Response and Result Confirmation

The endpoint returns order data with the same fields described in [Order Details](/en/api-reference/order-detail.md).

* `code=0` means the reclaim request succeeded. **It does not mean reclamation is complete on-chain.** See [API Error Codes and Handling](/en/getting-started/buy-energy-via-api-on-catfee/api-error-codes.md) 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.

{% openapi src="/files/6qXC6RrOuqtzIYmAmGSc" path="/v1/reclaim" method="post" %}
[api.json](https://4164384423-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa332YYkbT2p9snj9atS0%2Fuploads%2Fgit-blob-686dfe3c6ef251a9d69c042fbd858c32a092401d%2Fapi.json?alt=media)
{% endopenapi %}

### 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](/en/getting-started/buy-energy-via-api-on-catfee/api-overview.md) for signature rules.

Example request (replace the receiving address, authentication details, and timestamp):

```http
POST /v1/reclaim?receiver=TJRabPrwbZy45sbavfcjinPJC18kjpRTv8&resource_type=ENERGY HTTP/1.1
Host: api.catfee.io
CF-ACCESS-KEY: your_api_key
CF-ACCESS-SIGN: generated_signature
CF-ACCESS-TIMESTAMP: current_utc_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:

```json
{
  "code": 0,
  "msg": "",
  "data": {
    "matched_count": 3,
    "accepted_count": 2,
    "failed_order_ids": ["failed_order_id"]
  }
}
```

| 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](/en/getting-started/buy-energy-via-api-on-catfee/api-error-codes.md) 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.