> 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/transaction/reclaim-transaction.md).

# Reclaim Resources

Request reclamation of Energy or Bandwidth for Transaction Handoff orders by order ID, or in batches by receiving address and resource type. Both Partner Balance Payment and Partner End-User Payment are supported.

## Reclamation by Order ID

{% openapi src="/files/JXQUb3rAUG5kFSlvK6LF" path="/v1/mate/open/transaction/reclaim/{order\_id}" method="post" %}
[mate-transaction-api.json](https://4164384423-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa332YYkbT2p9snj9atS0%2Fuploads%2Fgit-blob-9a731052184568a4a1fe7415c7a54c2469e19793%2Fmate-transaction-api.json?alt=media)
{% endopenapi %}

### Request

* Use the `data.order_id` returned when creating the order, not the delegation transaction `data.hash` or `client_order_id`. Only orders belonging to the current account can be reclaimed.
* No request body is required. Include the API authentication headers. Sign with `POST` and the full path containing the actual order ID; see [API Overview](/en/getting-started/buy-energy-via-api-on-catfee/api-overview.md).

### Reclamation Result

`code=0` means the reclaim request was accepted. **It does not mean reclamation is complete on-chain.** If reclamation cannot proceed immediately, the order expires early for subsequent processing. You can also request early reclamation before delegation is confirmed.

The response `data` contains the order information. Use [Get Order Detail](/en/api-reference/transaction/order-detail.md) to check `confirm_status`:

| `confirm_status`         | Meaning                                                        |
| ------------------------ | -------------------------------------------------------------- |
| `RECLAIM_CONFIRMING`     | The reclamation transaction is awaiting on-chain confirmation. |
| `RECLAIM_CONFIRMED`      | Reclamation has been confirmed on-chain.                       |
| `RECLAIM_CONFIRMED_FAIL` | Reclamation confirmation failed; reclamation is not complete.  |

Other confirmation statuses do not indicate completed reclamation either. `status=CONFIRMED` only means delegation was confirmed. Use `confirm_status=RECLAIM_CONFIRMED` to determine whether reclamation is complete.

## Batch Reclamation by Receiving Address

Use `POST /v1/mate/open/transaction/reclaim` to request reclamation of the authenticated member's Transaction Handoff orders by receiving address and resource type, without specifying individual order IDs.

{% openapi src="/files/JXQUb3rAUG5kFSlvK6LF" path="/v1/mate/open/transaction/reclaim" method="post" %}
[mate-transaction-api.json](https://4164384423-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa332YYkbT2p9snj9atS0%2Fuploads%2Fgit-blob-9a731052184568a4a1fe7415c7a54c2469e19793%2Fmate-transaction-api.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      | TRON address receiving the resources.                                                            |
| `resource_type` | string | No       | `ENERGY` or `BANDWIDTH`. Defaults to `ENERGY`; explicitly pass `BANDWIDTH` to reclaim bandwidth. |

Include the three authentication headers: `CF-ACCESS-KEY`, `CF-ACCESS-SIGN`, and `CF-ACCESS-TIMESTAMP`. Generate the signature using the HTTP method `POST` and the **request path including the complete query string**. Parameter order and encoding must match 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/mate/open/transaction/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 Transaction Handoff orders belonging to the authenticated member, matching the receiving address and resource type, and with confirmed delegation (`confirm_status=DELEGATION_CONFIRMED`) are processed. Unlike reclamation by order ID, batch reclamation excludes orders whose delegation has not yet been confirmed.
* Each request matches and processes up to 100 orders.
* Reclamation is attempted first. If it cannot proceed immediately, the order's expiration time is brought forward for background processing. Acceptance does not mean reclamation is complete on-chain.

### Response and Result Confirmation

The response `data` contains the batch result, not order details. The following example shows a batch in which one order 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   | Number of orders matched in this request, up to 100; not the total number of orders for the address. |
| `accepted_count`   | integer   | Number of orders accepted for reclamation; does not mean reclamation is complete on-chain.           |
| `failed_order_ids` | string\[] | Order IDs whose reclamation requests were not accepted. Empty when all requests were accepted.       |

* `code=0` **does not mean all orders were 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.
* If no orders match, the response contains `matched_count=0`, `accepted_count=0`, and `failed_order_ids=[]`.
* If `matched_count=100`, additional orders may remain. Query order progress before deciding whether to submit another request. Do not add accepted counts from multiple requests and treat the sum as the number of orders reclaimed.
* For failed orders or uncertain results, use `GET /v1/mate/open/transaction/{order_id}` to [Get Order Detail](/en/api-reference/transaction/order-detail.md). Use `confirm_status=RECLAIM_CONFIRMED` to determine whether reclamation is complete on-chain. Neither `status=CONFIRMED` nor the batch accepted count establishes completed reclamation.