购买能量

Create resource order

创建订单,购买能量

post

Authorizations

API_KEY & API_SIGN & API_TIMESTAMP

CF-ACCESS-KEYstringRequired

CF-ACCESS-SIGNstringRequired

CF-ACCESS-TIMESTAMPstringRequired

Query parameters

quantityinteger · int32 · min: 65000Required

购买的能量数,不小于65000

receiverstringRequired

接收能量的地址

durationstringRequired

代理能量的最大持续时间，允许的值：1h

client_order_idstringOptional

客户自定义订单ID（长度小于等于64），保持唯一性，传入之前的客户订单号，将不创建新订单

activatebooleanOptional

是否需要激活，默认为true，如果为false且接受能量地址未激活，则返回错误信息。

Default: true

Header parameters

CF-ACCESS-KEYstringRequired

API所使用的KEY

Example: your api key

CF-ACCESS-SIGNstringRequired

使用HMAC SHA256哈希函数获得哈希值，再使用Base-64编码（请参阅签名）

Example: signature

CF-ACCESS-TIMESTAMPstringRequired

发起请求的时间（UTC），如：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",
    "client_order_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
  }
}

关键 API：创建订单（POST /v1/order）

在通过 CatFee.IO 的 API 创建订单时，需要特别关注以下三个返回值：

1. id（支付哈希/订单 ID）：

   • 每个订单的唯一标识符。

   • 可通过 GET /v1/order/{id} 接口查询该订单的详细信息。

2. status（订单状态）：

   • 反映订单的执行进度。

   • 当 status 为 DELEGATE_SUCCESS 时，表示能量交易已成功提交到波场区块链。

   • 注意：存在极小概率（约 0.1%）交易未能上链的情况。

3. confirm_status（链上确认状态）：

   • 确认能量是否已成功发送至目标地址。

   • 当 confirm_status 为 DELEGATION_CONFIRMED 时，表示能量已成功发送并在链上确认。

4. client_order_id (客户端自定义的订单 ID）:

   用户幂等请求，详见：API支持幂等请求

---

Q：如何百分百保证能量已发送到目标地址？

您可以通过以下两种方式确认能量已发送成功：

1. 通过波场 API 查询目标地址的能量余额：

   • 使用波场官方 API 或钱包工具（如 TronLink）查询目标地址的能量余额。

   • 示例 API 请求（波场官方接口）：

     Copy

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

     在返回的响应中查看能量相关字段，如 energy_limit 和 energy_used 字段。

2. 查询订单的 confirm_status：

   • 使用 GET /v1/order/{id} 接口查询订单详情。

   • 如果 confirm_status 为 DELEGATION_CONFIRMED，表示能量交易已成功在链上确认，目标地址已收到能量。

---

操作流程示例

1. 创建订单

请求示例：

Copy

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

响应示例：

Copy

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

---

2. 查询订单状态

请求示例：

Copy

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}

响应示例：

Copy

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

---

3. 确认能量是否发送成功

• 如果 confirm_status 为 DELEGATION_CONFIRMED，说明能量已发送成功。

• 您也可以通过波场 API 查询目标地址的能量余额，以进一步验证。

---

常见问题说明

1. 订单状态为 DELEGATE_SUCCESS 但能量未到账？

   • 原因：可能交易未能上链（概率约为 0.1%）。

   • 解决方案：稍等一段时间后查询订单状态或通过波场区块链查看交易详情。

2. 能量到账延迟问题？

   • 原因：可能与区块链网络拥堵有关。

   • 解决方案：确保订单状态为 DELEGATION_CONFIRMED 后即可确认能量已到账。

---

通过关注订单的 id 和 confirm_status，以及链上验证方法，您可以确保能量交易的可靠性。如果仍有问题，可联系 CatFee 客服(@CatFee_James)获取支持。