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

# 应用集成

开发者接入无感能量时，多数场景下只需要把原来调用 TRON 节点的**广播域名**替换为无感能量节点域名，路径和请求体保持 TRON 原接口格式。

如果您启用了 API KEY、生产级限流重试、严格错误处理或多地址鉴权策略，还需要同步处理鉴权、超时、重试和异常分支。

先说结论：**无感能量的增强发生在已签名交易的广播阶段。**\
如果您的系统当前只负责查余额、查区块、构造交易，或者广播动作由第三方钱包完成，请先确认真正的广播入口在哪里。

## 适用场景

* 直接通过 gRPC 与 TRON 节点交互的应用
* 自建网关、代理层或交易中继服务
* DApp 后端代用户转发已签名交易
* 钱包服务商统一托管广播链路

## 推荐接入顺序

1. 找到系统中已签名交易的最终广播入口。
2. 确认广播接口使用 HTTP 还是 gRPC。
3. 申请无感能量节点并选择鉴权方式。
4. 将节点域名和 AccessKey 放入服务端配置或密钥管理系统。
5. 只替换广播域名，保持原路径、请求体、签名逻辑和交易参数不变。
6. 用小额 TRC20 转账、授权或低风险合约调用完成端到端验证。
7. 上线前验证余额不足、节点停用、鉴权失败、限频和广播失败等异常分支。

## 鉴权与权限

无感能量节点支持三种鉴权方式：

* API KEY：适合开发者、钱包服务商和大规模地址业务。请求必须在 HTTP header 或 gRPC metadata 中传递 `CF-NODE-KEY: {AccessKey}`，且值必须与该节点保存的 41 位随机 `AccessKey` 一致
* 绑定地址：适合地址数量较少的钱包场景，或不支持自定义 Header 的客户端。请求里的第一笔交易发起地址必须已绑定到该节点
* 不鉴权：适合临时测试

如果使用 API KEY，需要在 HTTP Header 或 gRPC metadata 中传递：

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

`AccessKey` 是节点生成的 41 位随机字符串，可在 CatFee 用户中心查看或重置。

## 使用 AI 辅助改造

如果代码库较大，建议先让 AI 帮您定位广播入口，再生成最小改造方案。给 AI 的上下文应先脱敏，尤其不要提供私钥、助记词、keystore、真实 AccessKey 或生产节点域名。

可以让 AI 重点检查这些问题：

* 当前代码中哪一段真正调用 TRON 广播接口
* 是否只替换了广播域名，而没有改签名和交易构造逻辑
* `CF-NODE-KEY` 是否只从服务端环境变量或密钥管理系统读取
* 普通查询请求是否仍走原查询节点或符合您的节点规划
* 小额合约交易、普通 TRX 转账和异常分支是否都有验证方案

详细提示词参考[AI 辅助接入](/getting-started/seamless-energy/ai-assisted-integration.md)。

## 先确认您的场景适不适合接入

以下场景最适合接入无感能量：

* 您已经有稳定的钱包签名流程
* 您可以控制交易最终发往哪个广播节点
* 您希望在不改签名逻辑的前提下，给合约交易自动准备 ENERGY

以下场景需要先确认边界：

* 您只是在读链上数据，例如查余额、查区块、查交易
* 您只负责构造交易，广播动作由第三方钱包完成
* 您的钱包或 SDK 不允许替换广播目标节点

## HTTP 调用方式

以下示例主要说明主流程。\
如果您的系统需要严格区分“余额不足、节点停用、鉴权失败、限频、链上广播失败”等异常分支，建议联调时以 CatFee 实际返回为准，并在接入前完成错误处理验证。

### 广播路径

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

### `/wallet/broadcasttransaction` 示例

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

### `/wallet/broadcasthex` 示例

```bash
curl -X POST "https://bright-blue-river.catfee.vip/wallet/broadcasthex" \
  -H "Content-Type: application/json" \
  -H "CF-NODE-KEY: {AccessKey}" \
  -d '{"transaction":"..."}'
```

`/wallet/broadcasthex` 当前可用于十六进制交易广播。不同客户端对请求包装方式可能不同，联调时请以实际可用格式为准，并优先固定为您业务侧统一使用的一种请求格式。

## 哪些交易会触发资源准备

* 会触发：交易里的第一笔 contract 为 `TriggerSmartContract` 的已签名广播交易
* 不会触发：普通 TRX 转账、账户类操作和其他非合约交易
* 需要额外确认：不在当前支持范围内的复杂交易结构

## gRPC 调用方式

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

如果使用 API KEY，请在 gRPC metadata 中附带 `CF-NODE-KEY`。

## 广播行为说明

1. 客户端在本地构造并签名交易。
2. 客户端把已签名交易发送到无感能量节点。
3. CatFee 根据域名识别节点并执行鉴权。
4. 对支持的合约交易，先预估 ENERGY 并准备资源。
5. 能量交易广播成功后，等待约 2 秒再转发原交易。
6. 原交易被原样转发到 CatFee 的 TRON 节点。
7. 响应保持 TRON 广播接口格式。

## 接入时最容易搞错的点

* 把无感能量当成签名服务：它不是，签名仍在本地完成
* 把所有 TRON 请求都切到无感能量：真正关键的是广播入口
* 钱包不支持自定义 Header，却仍想强行使用 API KEY：这时通常应改用绑定地址
* 忽略余额不足策略：这会直接影响交易失败方式和成本结果
* 在没有验证错误返回和重试行为前直接上生产：这会放大超时和异常分支的实现风险

## 余额不足策略

可以在 CatFee 用户中心配置两种策略：

* 继续广播：CatFee 跳过能量购买，继续转发原交易
* 停止广播：CatFee 返回 `402 PAYMENT_REQUIRED`

只有“余额不足且允许继续广播”这一种情况会跳过能量购买后继续转发。其余能量处理失败场景都不会继续广播原交易。

## 常见状态

* 节点域名不存在：节点无效，通常是域名写错或节点已删除
* 节点已停用：需要先在用户中心重新启用
* 会员余额不足：请充值，或确认是否允许继续广播
* 请求过快：超过节点频率限制
* 非合约交易：不会购买 ENERGY，会直接转发

## 接入检查清单

1. 已在“用户中心 -> 无感能量”申请节点。
2. 已取得无感能量节点访问域名。
3. 已选择鉴权方式。
4. 钱包或后端只把已签名交易发送到无感能量。
5. HTTP 广播路径保持 TRON 原路径，只替换域名。
6. 使用 API KEY 时已携带 `CF-NODE-KEY`。
7. gRPC 调用已配置服务器、端口和 SSL/TLS。
8. 已配置余额不足时是否继续广播。
9. 已用小额合约交易完成端到端验证。

## 运行边界

* 当前只处理第一笔 contract 且类型为 `TriggerSmartContract` 的交易
* 资源准备成功不等于合约执行一定成功
* 约 2 秒等待用于尽量让资源先到账，但到账时间仍可能受 TRON 网络状态影响
* 生产接入前，建议额外验证错误返回、限频行为、超时重试和重复提交策略

## 相关内容

* 首次接入参考[快速入门](/getting-started/seamless-energy/quick-start.md)
* 钱包配置参考[钱包设置](/getting-started/seamless-energy/wallet-settings.md)
* 风险边界参考[安全说明](/getting-started/seamless-energy/security.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/seamless-energy/application-integration.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.