# 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>


---

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