> 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/getting-started/buy-energy-via-api-on-catfee/api-overview.md).

# API概览

### **1. 介绍**

CatFee.IO 提供了一套安全、标准化的 API，支持高效的资源访问。通过该 API，用户可以进行诸如订单创建、账户查询等多种操作。所有请求都需要通过签名验证机制，确保请求的安全性和有效性。

### **2. 如何申请并查看 API 信息** <a href="#apply-api-info" id="apply-api-info"></a>

注册并登录 CatFee 后，进入用户中心页面，点击右侧菜单中的 **“API”**，然后选择 **“API 配置”**。在该页面，您可以：

* 查看您的 **API Key** 和 **API Secret**；
* 设置 **IP 白名单**，限制 API 的访问来源，增强安全性，防止 API 信息泄露带来的潜在损失。

请妥善保管您的 API 信息，并务必开启 IP 白名单功能，保障账户和资产安全。

### **3. Base URL 说明**

CatFee 提供 **生产环境** 和 **Nile 测试环境**，供开发者根据实际需要选择使用。请注意，两者的账号体系和 API Key 不互通，需分别注册获取。

| 项目                   | 生产环境                                          | 测试环境（Nile）                                              |
| -------------------- | --------------------------------------------- | ------------------------------------------------------- |
| **网站地址**             | [https://catfee.io](https://catfee.io/)       | [https://nile.catfee.io](https://nile.catfee.io/)       |
| **API Base URL**     | `https://api.catfee.io`                       | `https://nile.catfee.io`                                |
| **API Key / Secret** | 注册生产环境账号后在【个人中心】⟶【API】获取                      | 注册测试环境账号后在【个人中心】⟶【API】获取                                |
| **波场区块链浏览器**         | [https://tronscan.org](https://tronscan.org/) | [https://nile.tronscan.org](https://nile.tronscan.org/) |
| **测试币领取地址**          | ❌ 无需                                          | <https://nileex.io/join/getJoinPage>每天可领取 2000 TRX      |

***

#### 🔧 使用说明与注意事项

1. **调用环境选择**
   * 正式上线或主网部署时，请使用生产环境接口 `https://api.catfee.io`；
   * 本地开发或功能测试时，请使用测试环境 `https://nile.catfee.io`。
2. **账号和密钥注册说明**
   * **生产环境和测试环境需分别注册账号**，两者的数据、API Key 不通用；
   * 注册后在对应网站的【个人中心】中获取 API Key 与 Secret。
3. **测试币领取方式**
   * 前往 [Nile Faucet](https://nileex.io/join/getJoinPage) 领取波场测试币 TRX；
   * 每天可免费领取最高 2000 个 TRX；
   * 测试币到账后可在 [nile.tronscan.org](https://nile.tronscan.org/) 上进行余额查询和交易验证。

### **4. 签名机制**

为了确保 API 调用的安全性，CatFee.IO 使用 HMAC-SHA256 签名机制对请求进行身份验证。请求需要提供正确的签名，以确保请求未被篡改，并且有效。

### **5. 签名生成规则**

#### **5.1 签名字符串拼接规则**

签名字符串是由以下部分拼接而成：

```
sign = timestamp + method + requestPath
```

* **timestamp**：请求的时间戳，格式为 ISO 8601，例如：`2023-08-26T12:34:56.789Z`。
* **method**：HTTP 方法，例如 `GET`、`POST`、`PUT` 或 `DELETE`。
* **requestPath**：API 请求路径，包含查询参数（如果有）。例如：
  * `/v1/order?quantity=65000&receiver=TRON_ADDRESS&duration=1h`
  * 注意：query parameters 应包括在 requestPath 中。

#### **5.2 签名生成流程**

签名的生成步骤如下：

1. 拼接签名字符串：`timestamp + method + requestPath`。
2. 使用 HMAC-SHA256 算法，对拼接后的字符串进行加密，使用您的 API Secret 作为密钥。
3. 对加密结果进行 Base64 编码，生成最终的签名。

#### **5.3 示例**

假设我们有以下信息：

* `timestamp = 2023-08-26T12:34:56.789Z`
* `method = POST`
* `requestPath = /v1/order?quantity=65000&receiver=TRON_ADDRESS&duration=1h`

拼接后的签名字符串为：

```
2023-08-26T12:34:56.789ZPOST/v1/order?quantity=65000&receiver=TRON_ADDRESS&duration=1h
```

然后，使用 HMAC-SHA256 算法和 API Secret 对该字符串进行加密，最后对结果进行 Base64 编码，得到最终的签名。

### **6. 请求头参数**

每次请求都必须包含以下 HTTP 请求头：

* **Content-Type**：请求的内容类型，一般为 `application/json`。
* **CF-ACCESS-KEY**：您的 API Key。
* **CF-ACCESS-SIGN**：请求的签名值。
* **CF-ACCESS-TIMESTAMP**：请求的 UTC 时间戳。

### **7. 示例请求**

#### **7.1 示例 POST 请求**

假设您要创建一个订单，API 请求的路径为 `/v1/order`，并且包含以下查询参数：

* `quantity=65000`
* `receiver=TRON_ADDRESS`
* `duration=1h`

生成请求 URL：

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

请求头应包含以下内容：

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

#### **7.2 示例 GET 请求**

假设您要查询账户信息，API 请求的路径为 `/v1/account`，并且没有查询参数。生成请求 URL：

```
https://api.catfee.io/v1/account
```

请求头应包含以下内容：

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

[更多API](/api-reference/account.md)

### **8. 响应数据格式**

所有请求的响应数据通常包含以下结构：

```json
{
  "code": "0",
  "msg": "",
  "data": {
    "key": "value"
  }
}
```

* **code**：响应代码，`0` 表示请求成功。
* **msg**：响应消息，可能包含错误信息或说明。
* **data**：返回的实际数据，通常是一个包含键值对的 JSON 对象。

### **9. 并发**

每个API\_KEY支持30r/s,如果不能满足您的需求，请联系客服 [@CatFee\_James](https://t.me/CatFee_James).

<table data-column-title-hidden data-view="cards" data-full-width="true"><thead><tr><th></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Java调用示例</strong></td><td><strong>Java调用示例</strong></td><td></td><td></td><td><a href="/pages/tqIgogIjDEmIt74oKvnI">/pages/tqIgogIjDEmIt74oKvnI</a></td></tr><tr><td><strong>Python调用示例</strong></td><td><strong>Python调用示例</strong></td><td></td><td></td><td><a href="/pages/PGSuvmlyCuxlgvsJFg8I">/pages/PGSuvmlyCuxlgvsJFg8I</a></td></tr><tr><td><strong>PHP调用示例</strong></td><td><strong>PHP调用示例</strong></td><td></td><td></td><td><a href="/pages/WMp2gXetyAuuiriNh4JB">/pages/WMp2gXetyAuuiriNh4JB</a></td></tr><tr><td><strong>Node.js调用示例</strong></td><td>Node.js调用示例</td><td></td><td></td><td><a href="/pages/qamgfBos2Gw6RdZyM6az">/pages/qamgfBos2Gw6RdZyM6az</a></td></tr><tr><td><strong>Go调用示例</strong></td><td>Go 调用示例</td><td></td><td></td><td><a href="/pages/zk0gyGzC5bQZgsIRpH0X">/pages/zk0gyGzC5bQZgsIRpH0X</a></td></tr></tbody></table>