> 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/getting-started/api-supports-idempotent-requests.md).

# API Supports Idempotency

🚀 CatFee Energy Purchase API Now Supports **Idempotency**!By adding an optional parameter `client_order_id`, users can now ensure that the **same request will not be executed multiple times**, effectively preventing duplicate charges, inconsistent order statuses, and making transactions more **secure and reliable**.

***

### 🔍 What is Idempotency and Why is it Important?

**Idempotency** means that no matter how many times the same request is submitted, the final result is **identical**, and the request won't be re-executed. This is especially important for **payment and purchase APIs**, as it helps prevent:

* Duplicate charges due to **network timeouts**
* Inconsistent states caused by **system failures**
* **User errors** such as repeated submissions

Now, the **CatFee Energy Purchase API** uses `client_order_id` to achieve idempotency, ensuring the **same request won’t be processed more than once**. Your transactions are now **safer and more reliable**!

***

### 🛠 How to Use CatFee Energy Purchase API for Idempotent Requests?

#### 📌 Request Example

According to **CatFee.IO Rest API** rules, **all parameters are passed via query parameters**, and the **signature calculation does NOT include query parameters**.

**Example POST Request**

If a user wants to purchase **65000 ENERGY** with a `client_order_id=abc123` for idempotency, the complete request would be:

```
POST https://api.catfee.io/v1/order?quantity=65000&receiver=TRON_ADDRESS&duration=1h&client_order_id=abc123
```

***

#### 📌 Request Headers

```
Content-Type: application/json  
CF-ACCESS-KEY: your_api_key  
CF-ACCESS-SIGN: generated_signature  
CF-ACCESS-TIMESTAMP: 2023-08-26T12:34:56.789Z
```

***

#### 📌 Parameter Description

| Parameter         | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| `client_order_id` | Optional unique client-side ID used to enforce idempotency |

***

### 🔹 Idempotency Logic

* If `client_order_id` is submitted **for the first time**, the system **creates a new energy purchase order** and returns its details.
* If the same `client_order_id` is **submitted again**, the system **returns the previous order response** without charging or creating a new order.

***

### 📄 Response Example

#### 🎯 First Request - Success

```json
{
  "code": 0,
  "data": {
    "id": "xyz987",
    "client_order_id": "abc123",
    "pay_timestamp": 1700000000,
    "receiver": "TRON_ADDRESS",
    "delegate_hash": "abc123def456",
    "delegate_timestamp": 1700000050,
    "reclaim_hash": "ghi789jkl012",
    "reclaim_timestamp": 1700000100,
    "pay_amount_sun": 10500000,
    "activate_amount_sun": 10500000,
    "quantity": 65000,
    "staked_sun": 10000000,
    "duration": 1,
    "expired_timestamp": 1700003600,
    "balance": 65000,
    "resource_type": "ENERGY",
    "billing_type": "TRANSFER",
    "status": "PAYMENT_SUCCESS",
    "activate_status": "DEACTIVATE",
    "confirm_status": "UNCONFIRMED"
  }
}
```

***

#### 🔄 Duplicate Submission with Same `client_order_id`

If the user resubmits the same request (due to timeout or retry), the API returns the **original order result**, avoiding any duplicate charge:

```json
{
  "code": 0,
  "sub_code": "SUCCESS",
  "sub_msg": "Duplicate order request, returning existing order",
  "data": {
    "id": "xyz987",
    "client_order_id": "abc123",
    "pay_timestamp": 1700000000,
    "receiver": "TRON_ADDRESS",
    "delegate_hash": "abc123def456",
    "delegate_timestamp": 1700000050,
    "reclaim_hash": "ghi789jkl012",
    "reclaim_timestamp": 1700000100,
    "pay_amount_sun": 10500000,
    "activate_amount_sun": 10500000,
    "quantity": 65000,
    "staked_sun": 10000000,
    "duration": 1,
    "expired_timestamp": 1700003600,
    "balance": 65000,
    "resource_type": "ENERGY",
    "billing_type": "TRANSFER",
    "status": "PAYMENT_SUCCESS",
    "activate_status": "DEACTIVATE",
    "confirm_status": "UNCONFIRMED"
  }
}
```

✅ This effectively prevents issues such as **double charges due to user mistakes or network glitches**!

***

### 🎯 When to Use Idempotent API Calls?

#### 📌 1. Preventing Duplicate Submissions from Network Timeouts

If the user sends a purchase request but doesn’t receive a timely response, they may mistakenly assume it failed and retry.\
Using `client_order_id` ensures **no duplicate purchase is made**, even if retried.

#### 📌 2. Avoiding Repeated Charges During Batch Operations

Automated scripts may crash mid-batch and leave some requests in an uncertain state.\
With `client_order_id`, each request is uniquely tracked and won’t be executed twice.

#### 📌 3. Enhancing Reliability of API Calls

Many **payment systems and exchanges** require API requests to be idempotent.\
Now CatFee supports this too, increasing **reliability across business scenarios**.

***

### 🚀 CatFee Makes Energy Trading More Efficient and Secure!

CatFee is always focused on improving user experience. With **idempotency now supported** in the energy purchase API, you can use `client_order_id` to make **transactions safer**, avoid duplicate charges, and enjoy **more stable API calls**.

👉 Try the **CatFee Energy Purchase API** today and make your **TRON-based transactions smoother and worry-free**! 🚀