# 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**! 🚀


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catfee.io/en/getting-started/api-supports-idempotent-requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.