> 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/seamless-energy/api-integration.md).

# API 接入

接入无感能量很简单：**将原 TRON 广播节点的域名替换为 CatFee 无感能量节点域名。**

交易签名、接口路径、请求方式和请求体都不需要修改。

## 一眼看懂

假设原广播地址是：

```http
https://api.trongrid.io/wallet/broadcasttransaction
```

接入后改为：

```http
https://{NodeSlug}.catfee.vip/wallet/broadcasttransaction
```

只更换前面的节点域名：

```diff
- https://api.trongrid.io
+ https://{NodeSlug}.catfee.vip
```

后面的广播路径保持不变：

```
/wallet/broadcasttransaction
```

{% hint style="info" %}
如果您的系统可以单独配置广播节点，只需更换广播节点域名；查询余额、区块和交易等接口可以继续使用原节点。
{% endhint %}

## 接入步骤

1. 在 CatFee 用户中心申请无感能量节点。
2. 获取专属节点域名，例如 `https://{NodeSlug}.catfee.vip`。
3. 将已签名交易的广播节点域名替换为该域名。
4. 发起一笔小额交易进行验证。

完成以上步骤后，无感能量节点会根据交易需要自动准备 ENERGY（能量）或 BANDWIDTH（带宽），再将原交易广播到 TRON 网络。

## HTTP 接入

### JSON 格式交易

```http
POST https://{NodeSlug}.catfee.vip/wallet/broadcasttransaction
```

### Hex 格式交易

```http
POST https://{NodeSlug}.catfee.vip/wallet/broadcasthex
```

接口路径和请求体均保持 TRON 原格式。

## 请求示例

```bash
curl -X POST "https://{NodeSlug}.catfee.vip/wallet/broadcasttransaction" \
  -H "Content-Type: application/json" \
  -H "CF-NODE-KEY: {AccessKey}" \
  -d '{
    "raw_data_hex": "...",
    "signature": ["..."]
  }'
```

使用 API KEY 鉴权时，需要增加以下请求头：

```http
CF-NODE-KEY: {AccessKey}
```

如果使用绑定地址或不鉴权模式，则不需要添加该请求头。

## gRPC 接入

gRPC 的接入方式同样简单：**将原 TRON gRPC 服务地址替换为无感能量节点地址**，原有 Protobuf 定义、交易签名和广播方法保持不变。

{% hint style="warning" %}
标准无感能量 gRPC API 节点 `{NodeSlug}.catfee.vip:443` 只能通过 SSL/TLS 调用。TronLink App 手机版使用专用的明文 gRPC 节点 `{NodeSlug}.catfee.pro:50051`，请参考[钱包接入](/seamless-energy/wallet-integration.md)。
{% endhint %}

```
服务器：{NodeSlug}.catfee.vip
端口：443
SSL/TLS：开启
广播方法：/protocol.Wallet/BroadcastTransaction
```

配置示例：

```yaml
target: "{NodeSlug}.catfee.vip:443"
tls: true
method: "/protocol.Wallet/BroadcastTransaction"
```

使用 API KEY 鉴权时，在 gRPC metadata 中增加：

```
CF-NODE-KEY: {AccessKey}
```

如果使用绑定地址或不鉴权模式，则不需要添加该 metadata。

接入前后只有服务地址发生变化：

```diff
- 原 TRON gRPC 服务地址
+ {NodeSlug}.catfee.vip:443
```

已有的 Stub、已签名交易对象和 `BroadcastTransaction` 调用逻辑可以继续使用。

## 接入前后对比

| 项目        | 接入前            | 接入后                         |
| --------- | -------------- | --------------------------- |
| 节点域名      | 原 TRON 节点域名    | `{NodeSlug}.catfee.vip`     |
| gRPC 服务地址 | 原 TRON gRPC 地址 | `{NodeSlug}.catfee.vip:443` |
| HTTP 广播路径 | 保持原样           | 保持原样                        |
| gRPC 广播方法 | 保持原样           | 保持原样                        |
| 请求体       | 保持原样           | 保持原样                        |
| 交易签名      | 本地完成           | 本地完成                        |
| 资源准备      | 自行处理           | 自动准备能量或带宽                   |

## 注意事项

* 发送给无感能量节点的交易必须已经签名。
* CatFee 不需要也不会获取您的私钥或助记词。
* 请勿修改原交易的地址、金额、签名或合约参数。
* 建议先用小额交易完成验证，再切换正式流量。

需要了解异常处理，请查看[常见问题](/seamless-energy/faq.md)。