应用集成
面向开发者说明如何将 CatFee 无感能量接入到 HTTP 或 gRPC 广播链路，包括鉴权、请求示例、余额策略和接入检查清单。
开发者接入无感能量时，多数场景下只需要把原来调用 TRON 节点的广播域名替换为无感能量节点域名，路径和请求体保持 TRON 原接口格式。
如果您启用了 API KEY、生产级限流重试、严格错误处理或多地址鉴权策略，还需要同步处理鉴权、超时、重试和异常分支。
先说结论：无感能量的增强发生在已签名交易的广播阶段。 如果您的系统当前只负责查余额、查区块、构造交易，或者广播动作由第三方钱包完成，请先确认真正的广播入口在哪里。
适用场景
直接通过 gRPC 与 TRON 节点交互的应用
自建网关、代理层或交易中继服务
DApp 后端代用户转发已签名交易
钱包服务商统一托管广播链路
推荐接入顺序
找到系统中已签名交易的最终广播入口。
确认广播接口使用 HTTP 还是 gRPC。
申请无感能量节点并选择鉴权方式。
将节点域名和 AccessKey 放入服务端配置或密钥管理系统。
只替换广播域名，保持原路径、请求体、签名逻辑和交易参数不变。
用小额 TRC20 转账、授权或低风险合约调用完成端到端验证。
上线前验证余额不足、节点停用、鉴权失败、限频和广播失败等异常分支。
鉴权与权限
无感能量节点支持三种鉴权方式：
API KEY：适合开发者、钱包服务商和大规模地址业务。请求必须在 HTTP header 或 gRPC metadata 中传递
CF-NODE-KEY: {AccessKey}，且值必须与该节点保存的 41 位随机AccessKey一致绑定地址：适合地址数量较少的钱包场景，或不支持自定义 Header 的客户端。请求里的第一笔交易发起地址必须已绑定到该节点
不鉴权：适合临时测试
如果使用 API KEY，需要在 HTTP Header 或 gRPC metadata 中传递：
AccessKey 是节点生成的 41 位随机字符串，可在 CatFee 用户中心查看或重置。
使用 AI 辅助改造
如果代码库较大，建议先让 AI 帮您定位广播入口，再生成最小改造方案。给 AI 的上下文应先脱敏，尤其不要提供私钥、助记词、keystore、真实 AccessKey 或生产节点域名。
可以让 AI 重点检查这些问题：
当前代码中哪一段真正调用 TRON 广播接口
是否只替换了广播域名，而没有改签名和交易构造逻辑
CF-NODE-KEY是否只从服务端环境变量或密钥管理系统读取普通查询请求是否仍走原查询节点或符合您的节点规划
小额合约交易、普通 TRX 转账和异常分支是否都有验证方案
详细提示词参考AI 辅助接入。
先确认您的场景适不适合接入
以下场景最适合接入无感能量：
您已经有稳定的钱包签名流程
您可以控制交易最终发往哪个广播节点
您希望在不改签名逻辑的前提下，给合约交易自动准备 ENERGY
以下场景需要先确认边界：
您只是在读链上数据，例如查余额、查区块、查交易
您只负责构造交易，广播动作由第三方钱包完成
您的钱包或 SDK 不允许替换广播目标节点
HTTP 调用方式
以下示例主要说明主流程。 如果您的系统需要严格区分“余额不足、节点停用、鉴权失败、限频、链上广播失败”等异常分支，建议联调时以 CatFee 实际返回为准，并在接入前完成错误处理验证。
广播路径
/wallet/broadcasttransaction 示例
/wallet/broadcasttransaction 示例/wallet/broadcasthex 示例
/wallet/broadcasthex 示例/wallet/broadcasthex 当前可用于十六进制交易广播。不同客户端对请求包装方式可能不同，联调时请以实际可用格式为准，并优先固定为您业务侧统一使用的一种请求格式。
哪些交易会触发资源准备
会触发：交易里的第一笔 contract 为
TriggerSmartContract的已签名广播交易不会触发：普通 TRX 转账、账户类操作和其他非合约交易
需要额外确认：不在当前支持范围内的复杂交易结构
gRPC 调用方式
如果使用 API KEY，请在 gRPC metadata 中附带 CF-NODE-KEY。
广播行为说明
客户端在本地构造并签名交易。
客户端把已签名交易发送到无感能量节点。
CatFee 根据域名识别节点并执行鉴权。
对支持的合约交易，先预估 ENERGY 并准备资源。
能量交易广播成功后，等待约 2 秒再转发原交易。
原交易被原样转发到 CatFee 的 TRON 节点。
响应保持 TRON 广播接口格式。
接入时最容易搞错的点
把无感能量当成签名服务：它不是，签名仍在本地完成
把所有 TRON 请求都切到无感能量：真正关键的是广播入口
钱包不支持自定义 Header，却仍想强行使用 API KEY：这时通常应改用绑定地址
忽略余额不足策略：这会直接影响交易失败方式和成本结果
在没有验证错误返回和重试行为前直接上生产：这会放大超时和异常分支的实现风险
余额不足策略
可以在 CatFee 用户中心配置两种策略：
继续广播：CatFee 跳过能量购买，继续转发原交易
停止广播：CatFee 返回
402 PAYMENT_REQUIRED
只有“余额不足且允许继续广播”这一种情况会跳过能量购买后继续转发。其余能量处理失败场景都不会继续广播原交易。
常见状态
节点域名不存在：节点无效，通常是域名写错或节点已删除
节点已停用：需要先在用户中心重新启用
会员余额不足：请充值，或确认是否允许继续广播
请求过快：超过节点频率限制
非合约交易：不会购买 ENERGY，会直接转发
接入检查清单
已在“用户中心 -> 无感能量”申请节点。
已取得无感能量节点访问域名。
已选择鉴权方式。
钱包或后端只把已签名交易发送到无感能量。
HTTP 广播路径保持 TRON 原路径，只替换域名。
使用 API KEY 时已携带
CF-NODE-KEY。gRPC 调用已配置服务器、端口和 SSL/TLS。
已配置余额不足时是否继续广播。
已用小额合约交易完成端到端验证。
运行边界
当前只处理第一笔 contract 且类型为
TriggerSmartContract的交易资源准备成功不等于合约执行一定成功
约 2 秒等待用于尽量让资源先到账，但到账时间仍可能受 TRON 网络状态影响
生产接入前，建议额外验证错误返回、限频行为、超时重试和重复提交策略
相关内容
Last updated