Buy Energy

Create resource order

Buy energy

post

Authorizations

API_KEY & API_SIGN & API_TIMESTAMP

CF-ACCESS-KEYstringRequired

CF-ACCESS-SIGNstringRequired

CF-ACCESS-TIMESTAMPstringRequired

Query parameters

quantityinteger · int32 · min: 65000Required

delegation energy quantity,must >= 65000

receiverstringRequired

Address to receive the resource

durationstringRequired

Duration of the order: allowed values are 1h

client_order_idstringOptional

Client order id，For Idempotent verification（length <= 64）

activatebooleanOptional

Whether activation is required. Defaults to true.If set to false and the recipient address is not activated, an error will be returned.

Default: true

Header parameters

CF-ACCESS-KEYstringRequired

The API Access key as a string

Example: your api key

CF-ACCESS-SIGNstringRequired

The Base64-encoded signature (see signing messages subsection for details)

Example: signature

CF-ACCESS-TIMESTAMPstringRequired

The UTC timestamp of your request .e.g : 2008-08-08T08:08:08.888Z

Responses

200

OK

application/json

post

/v1/order

HTTPcURLJavaScriptPython

POST /v1/order?quantity=1&receiver=text&duration=text HTTP/1.1
Host: api.catfee.io
CF-ACCESS-KEY: text
CF-ACCESS-SIGN: text
CF-ACCESS-TIMESTAMP: text
Accept: */*

200

OK

{
  "code": 1,
  "msg": "text",
  "sub_code": "text",
  "sub_msg": "text",
  "data": {
    "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
  }
}

Key API: Create Order (POST /v1/order)

When creating an order via CatFee.IO’s API, please pay special attention to the following return values:

id (Payment Hash / Order ID):

• A unique identifier for each order.

• You can retrieve the order details using the GET /v1/order/{id} endpoint.

status (Order Status):

• Reflects the execution progress of the order.

• If status is DELEGATE_SUCCESS, the energy delegation has been successfully submitted to the TRON blockchain.

Note: There is a very small chance (~0.1%) that the transaction may fail to be broadcast to the blockchain.

confirm_status (On-Chain Confirmation Status):

• Confirms whether energy has been successfully delivered to the target address.

• If confirm_status is DELEGATION_CONFIRMED, the energy has been successfully sent and confirmed on-chain.

client_order_id (Client-defined Order ID):

• For idempotent requests. See: API Idempotency Support

---

❓How to Ensure Energy Has Been Successfully Sent?

You can confirm energy delivery through two methods:

1. Query the energy balance of the target address via TRON API:

Use the official TRON API or wallet tools (e.g., TronLink) to check the energy balance of the target address.

Sample API Request (TRON Official Endpoint):

curl --request POST \
     --url https://api.trongrid.io/wallet/getaccountresource \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "address": "TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
  "visible": true
}'

Check fields such as energy_limit and energy_used in the response.

2. Check the confirm_status of the order:

Use GET /v1/order/{id} to retrieve order details.

If confirm_status is DELEGATION_CONFIRMED, the energy has been successfully confirmed on-chain.

---

Example Workflow

1. Create Order

Request:

POST /v1/order?count=1&target_address=TRON_ADDRESS&period=1
Host: https://api.catfee.io
Headers:
  Content-Type: application/json
  CF-ACCESS-KEY: {api_key}
  CF-ACCESS-SIGN: {signature}
  CF-ACCESS-TIMESTAMP: {timestamp}

Response:

{
  "code":0,
  "data":{
    "id": "abcd1234",
    "status": "DELEGATE_SUCCESS",
    "confirm_status": "UNCONFIRMED"
  }
}

2. Query Order Status

Request:

GET /v1/order/abcd1234
Host: https://api.catfee.io
Headers:
  Content-Type: application/json
  CF-ACCESS-KEY: {api_key}
  CF-ACCESS-SIGN: {signature}
  CF-ACCESS-TIMESTAMP: {timestamp}

Response:

{
  "code":0,
  "data":{
    "id": "abcd1234",
    "status": "DELEGATE_SUCCESS",
    "confirm_status": "DELEGATION_CONFIRMED"
  }
}

3. Confirm Successful Energy Transfer

If confirm_status is DELEGATION_CONFIRMED, energy has been successfully sent.

You may also use the TRON API to verify the target address’s energy balance.

---

FAQs

Q: Order status is DELEGATE_SUCCESS but energy hasn’t arrived?

• Reason: The transaction might not have been successfully broadcast (~0.1% probability).

• Solution: Wait for a while and re-check the order status or verify on-chain via TRON block explorers.

Q: Energy arrival is delayed?

• Reason: Potential TRON network congestion.

• Solution: Ensure confirm_status is DELEGATION_CONFIRMED. This confirms energy delivery.

---

By tracking the id and confirm_status values and using on-chain validation, you can ensure energy transfers are reliable. If you still have questions, please contact CatFee customer support: @CatFee_James