能量直达

产品介绍

Transaction Handoff（能量直达）为您的业务系统按需提供 TRON 能量与带宽。接入方通过 API 获取已签名、未广播的资源代理交易，自主安排广播时机，将资源交付融入转账、支付、兑换或其他智能合约操作流程。

本文所称“合作方”，是指接入能量直达服务的机构、团队或开发者；“业务系统”是指合作方用于构建、广播和查询 TRON 交易的应用或服务。交易所、钱包、DApp 和支付平台只是其中的应用示例。

本文所称“用户”，是指合作方的终端用户。

能量直达支持两种支付方式：合作方余额支付和合作方终端用户支付。

能量直达默认开通合作方余额支付方式。如需由合作方终端用户支付资源费用，请联系 CatFee 客服申请开通。

与其他能量模式的核心区别

CatFee 创建订单后，返回的是已签名但未广播的能量或带宽代理交易数据。CatFee 不会直接将这笔代理交易广播到 TRON 网络。

合作方取得交易数据后，可以结合自己的业务流程，决定广播时机，并将代理交易与用户的转账、兑换或其他合约交易配合执行。由合作方自主广播代理交易，是 Transaction Handoff 与其他能量模式最大的区别。

CatFee 返回已签名的资源代理交易，由合作方自主控制广播时机并嵌入原有交易流程。

图中展示资源交付的主流程：合作方先广播能量或带宽代理交易，再广播用户业务交易，并分别查询链上结果。两种支付方式均使用这一资源交付流程；付款和结算步骤见下文。

产品优势

• 体验简单：资源服务可以直接嵌入业务系统原有的交易流程。

• 接入灵活：自主安排广播时机与业务衔接方式，为转账、支付、兑换等场景提供多种接入可能。

• 即时补充：根据每笔交易的实际需要申请能量或带宽。

• 自主广播：合作方自行控制代理交易的广播时机和业务组合方式。

• 支付灵活：支持合作方统一结算，也支持合作方终端用户按单支付。

• 链上可查：代理交易及合作方终端用户的付款交易均可在 TRON 链上查询。

适用场景

能量直达适合需要按需补充资源并自主控制交易广播的业务系统，例如转账服务、支付系统、资产管理工具、自动化业务脚本，以及提供兑换或其他智能合约操作的应用。

业务交易既可以由终端用户发起，也可以由系统根据业务规则触发。无论通过何种产品形态接入，都可以将资源购买与广播纳入原有流程。

接入准备

接入前，请先完成以下准备：

• 登录 CatFee 用户中心（Dashboard），申请开通能量直达服务。

• 在用户中心的 API 信息 中查看 API 凭证。

• 按照 API 概览 完成接口签名和鉴权。

• 业务系统具备 TRON 交易构建、签名、广播和查询能力。

• 业务系统能够估算用户业务交易所需的能量或带宽。

• 用户的资源接收地址已经在 TRON 网络激活。

支付方式一：合作方余额支付（默认）

方式说明

合作方余额支付是能量直达的默认支付方式。合作方需要在 CatFee 账户中保持充足余额，资源交付成功后，系统自动从账户余额中扣除本次费用。

使用这种方式时，合作方终端用户不需要额外发起资源费付款交易。业务系统是否向用户收费、采用何种收费方式，由合作方根据自己的产品方案决定。

如果资源交付失败，订单会取消，不会按成功订单扣费。

业务流程

1. 用户通过业务系统发起一笔链上交易，或由系统根据业务规则触发交易。

2. 业务系统估算本次交易所需的能量或带宽，并向 CatFee 查询资源费用。

3. 业务系统创建能量直达订单，CatFee 检查合作方账户余额。

4. CatFee 返回订单信息和已签名、未广播的能量或带宽代理交易数据。

5. 合作方结合自己的业务流程，先广播代理交易，再广播用户原本要执行的业务交易。

6. 资源交付确认后，CatFee 从合作方账户余额自动扣费。

7. 业务系统查询能量直达订单及用户业务交易的最终结果。

开发接入

1. 查询资源费用

调用 POST /v1/mate/open/transaction/estimate，传入资源类型和所需数量。接口返回预计费用，可用于内部计费或向用户展示。

预估结果仅供参考，订单费用以创建订单接口的返回结果为准。详细参数参见 预估资源费用。

2. 创建能量直达订单

调用 POST /v1/mate/open/transaction，传入资源接收地址、资源数量和资源类型。建议同时传入业务系统侧唯一的 client_order_id。

接口返回订单编号、订单金额，以及已签名、未广播的能量或带宽代理交易数据。合作方应完整保存首次成功响应。如果账户余额不足，订单将无法创建，补充余额后可以重新发起请求。

详细参数参见 创建代理资源交易。

3. 广播交易

创建订单成功后，由合作方根据自己的业务流程控制广播时机：先广播 CatFee 返回的能量或带宽代理交易，再广播用户业务交易。CatFee 不会代替合作方广播代理交易。两笔交易相互独立，需要分别保存和查询结果。

4. 查询订单

调用 GET /v1/mate/open/transaction/{order_id} 查询订单。资源交付成功后，系统会自动完成余额扣费，无需调用提交付款 Hash 接口。

详细参数参见 查询订单信息。

余额支付时序图

支付方式二：合作方终端用户支付（需申请开通）

方式说明

合作方终端用户支付适合希望由自己的终端用户承担每笔资源费用，并保留独立链上付款记录的业务系统。

该方式不会默认开通。如需使用，请联系 CatFee 客服申请。开通后，用户根据订单金额和收款地址支付 TRX，业务系统负责广播付款交易并向 CatFee 提交付款 Hash。

业务流程

1. 用户通过业务系统发起一笔链上交易，或由系统根据业务规则触发交易。

2. 业务系统查询资源费用并创建能量直达订单。

3. CatFee 返回已签名、未广播的代理交易数据、应付金额和收款地址。

4. 业务系统根据订单信息创建用户付款交易，并请用户确认。

5. 合作方结合自己的业务流程，先广播代理交易，再广播用户业务交易，并广播付款交易。

6. 业务系统将付款交易 Hash 提交给 CatFee。

7. 业务系统查询订单，等待资源交付和用户付款完成确认。

开发接入

合作方终端用户支付与余额支付共用询价、创建订单和查询订单接口，并增加以下处理：

1. 使用创建订单返回的 amount_sun 和 payee_address 创建用户付款交易。

2. 付款交易广播成功后，调用 POST /v1/mate/open/transaction/pay/{order_id} 提交付款 Hash。

3. 继续查询订单，直到资源状态和付款状态得到确认。

提交付款 Hash 成功只表示 CatFee 已收到付款信息，不代表付款已经确认。详细参数参见 提交支付 Hash（合作方终端用户支付）。

合作方终端用户支付时序图

订单状态

两种支付方式使用相同的订单查询接口。接入方需要分别关注资源状态和付款状态：

状态字段	状态	说明
status	CREATED	订单已创建，代理交易等待确认
status	CONFIRMED	代理交易已确认
status	CANCEL	代理交易未成功，订单已取消
payment_status	UNPAID	尚未完成结算；合作方终端用户支付时表示尚未提交付款 Hash
payment_status	PAID	合作方终端用户的付款 Hash 已提交，等待链上确认
payment_status	CONFIRMED	合作方余额扣费或合作方终端用户付款已经确认
payment_status	FAIL	结算未完成，需要检查余额、付款信息或联系 CatFee

status = CONFIRMED 只表示代理交易已经确认，不代表用户的业务交易也已经成功。业务系统仍需单独查询用户业务交易的链上结果。

主要返回信息

创建订单后，建议重点保存以下信息：

字段	说明
order_id	CatFee 订单编号，用于查询订单
hex	已签名、未广播的代理交易数据
hash	代理交易 Hash
amount_sun	本次资源费用，单位为 sun
payee_address	合作方终端用户支付方式使用的资源费收款地址

1 TRX = 1,000,000 sun。

接入注意事项

• 余额支付方式下，合作方需要关注账户余额，避免因余额不足影响用户交易。

• 每笔业务建议使用唯一的 client_order_id，并在业务系统侧保存它与 order_id 的对应关系。

• 收到创建订单响应后，及时保存 order_id、hex 和相关交易信息。

• 创建请求超时或结果不确定时，不要使用新的 client_order_id 重复创建订单。

• 合作方终端用户支付方式下，付款金额和收款地址以创建订单接口返回的信息为准。

• 提交付款 Hash 后，先查询订单状态，再决定是否重试，避免用户重复付款。

• 如果代理交易成功但用户业务交易失败，能量直达订单仍会正常结算。

• 如果订单状态或扣费结果异常，请保留订单编号和相关交易 Hash，联系 CatFee 支持人员处理。