> 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/solutions/transaction-handoff.md). # 能量直达 ## 产品介绍 Transaction Handoff（能量直达）为您的业务系统按需提供 TRON 能量与带宽。接入方通过 API 获取已签名、未广播的资源代理交易，自主安排广播时机，将资源交付融入转账、支付、兑换或其他智能合约操作流程。 本文所称“合作方”，是指接入能量直达服务的机构、团队或开发者；“业务系统”是指合作方用于构建、广播和查询 TRON 交易的应用或服务。交易所、钱包、DApp 和支付平台只是其中的应用示例。 本文所称“用户”，是指合作方的终端用户。 能量直达支持两种支付方式：**合作方余额支付**和**合作方终端用户支付**。 {% hint style="info" %} 能量直达默认开通合作方余额支付方式。如需由合作方终端用户支付资源费用，请联系 CatFee 客服申请开通。 {% endhint %} ## 与其他能量模式的核心区别 CatFee 创建订单后，返回的是**已签名但未广播的能量或带宽代理交易数据**。CatFee 不会直接将这笔代理交易广播到 TRON 网络。 合作方取得交易数据后，可以结合自己的业务流程，决定广播时机，并将代理交易与用户的转账、兑换或其他合约交易配合执行。**由合作方自主广播代理交易，是 Transaction Handoff 与其他能量模式最大的区别。**
能量直达流程：业务系统按业务需求发起 TRON 交易，CatFee 返回已签名但未广播的资源代理交易，合作方先广播能量或带宽代理交易，再广播业务交易，最终由 TRON 网络确认。

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

图中展示资源交付的主流程：合作方先广播能量或带宽代理交易，再广播用户业务交易，并分别查询链上结果。两种支付方式均使用这一资源交付流程；付款和结算步骤见下文。 ### 产品优势 * **体验简单**：资源服务可以直接嵌入业务系统原有的交易流程。 * **接入灵活**：自主安排广播时机与业务衔接方式，为转账、支付、兑换等场景提供多种接入可能。 * **即时补充**：根据每笔交易的实际需要申请能量或带宽。 * **自主广播**：合作方自行控制代理交易的广播时机和业务组合方式。 * **支付灵活**：支持合作方统一结算，也支持合作方终端用户按单支付。 * **链上可查**：代理交易及合作方终端用户的付款交易均可在 TRON 链上查询。 ### 适用场景 能量直达适合需要按需补充资源并自主控制交易广播的业务系统，例如转账服务、支付系统、资产管理工具、自动化业务脚本，以及提供兑换或其他智能合约操作的应用。 业务交易既可以由终端用户发起，也可以由系统根据业务规则触发。无论通过何种产品形态接入，都可以将资源购买与广播纳入原有流程。 ## 接入准备 接入前，请先完成以下准备： * 登录 CatFee 用户中心（Dashboard），申请开通能量直达服务。 * 在用户中心的 **API 信息** 中查看 API 凭证。 * 按照 [API 概览](/getting-started/buy-energy-via-api-on-catfee/api-overview.md) 完成接口签名和鉴权。 * 业务系统具备 TRON 交易构建、签名、广播和查询能力。 * 业务系统能够估算用户业务交易所需的能量或带宽。 * 用户的资源接收地址已经在 TRON 网络激活。 ## 支付方式一：合作方余额支付（默认） ### 方式说明 合作方余额支付是能量直达的默认支付方式。合作方需要在 CatFee 账户中保持充足余额，资源交付成功后，系统自动从账户余额中扣除本次费用。 使用这种方式时，合作方终端用户不需要额外发起资源费付款交易。业务系统是否向用户收费、采用何种收费方式，由合作方根据自己的产品方案决定。 如果资源交付失败，订单会取消，不会按成功订单扣费。 ### 业务流程 1. 用户通过业务系统发起一笔链上交易，或由系统根据业务规则触发交易。 2. 业务系统估算本次交易所需的能量或带宽，并向 CatFee 查询资源费用。 3. 业务系统创建能量直达订单，CatFee 检查合作方账户余额。 4. CatFee 返回订单信息和已签名、未广播的能量或带宽代理交易数据。 5. 合作方结合自己的业务流程，先广播代理交易，再广播用户原本要执行的业务交易。 6. 资源交付确认后，CatFee 从合作方账户余额自动扣费。 7. 业务系统查询能量直达订单及用户业务交易的最终结果。 ### 开发接入 #### 1. 查询资源费用 调用 `POST /v1/mate/open/transaction/estimate`，传入资源类型和所需数量。接口返回预计费用，可用于内部计费或向用户展示。 预估结果仅供参考，订单费用以创建订单接口的返回结果为准。详细参数参见 [预估资源费用](/api-reference/transaction/estimate-fee.md)。 #### 2. 创建能量直达订单 调用 `POST /v1/mate/open/transaction`，传入资源接收地址、资源数量和资源类型。建议同时传入业务系统侧唯一的 `client_order_id`。 接口返回订单编号、订单金额，以及已签名、未广播的能量或带宽代理交易数据。合作方应完整保存首次成功响应。如果账户余额不足，订单将无法创建，补充余额后可以重新发起请求。 详细参数参见 [创建代理资源交易](/api-reference/transaction/create-transaction.md)。 #### 3. 广播交易 创建订单成功后，由合作方根据自己的业务流程控制广播时机：先广播 CatFee 返回的能量或带宽代理交易，再广播用户业务交易。CatFee 不会代替合作方广播代理交易。两笔交易相互独立，需要分别保存和查询结果。 #### 4. 查询订单 调用 `GET /v1/mate/open/transaction/{order_id}` 查询订单。资源交付成功后，系统会自动完成余额扣费，无需调用提交付款 Hash 接口。 详细参数参见 [查询订单信息](/api-reference/transaction/get-transaction.md)。 ### 余额支付时序图 ```mermaid sequenceDiagram autonumber actor c as 用户 (User) participant w as 业务系统 (Business System) participant f as CatFee participant t as TRON网络 c->>w: 发起智能合约交易 (未广播) w->>f: 查询所需资源费用 f-->>w: 返回费用详情 w->>f: 创建能量直达订单 f->>f: 检查合作方账户余额 f-->>w: 返回已签名的代理交易 (未广播) w->>t: 合作方广播代理交易 w->>t: 广播用户智能合约交易 t-->>f: 确认资源交付结果 f->>f: 从合作方账户余额扣费 w->>f: 查询订单状态 f-->>w: 返回订单和结算结果 ``` ## 支付方式二：合作方终端用户支付（需申请开通） ### 方式说明 合作方终端用户支付适合希望由自己的终端用户承担每笔资源费用，并保留独立链上付款记录的业务系统。 该方式不会默认开通。如需使用，请联系 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（合作方终端用户支付）](/api-reference/transaction/pay-transaction.md)。 ### 合作方终端用户支付时序图 ```mermaid sequenceDiagram autonumber actor c as 用户 (User) participant w as 业务系统 (Business System) participant f as CatFee participant t as TRON网络 c->>w: 发起智能合约交易 (未广播) w->>f: 查询所需资源费用 (POST /v1/mate/open/transaction/estimate) f->>w: 返回费用详情 w->>f: 创建代理资源交易 (POST /v1/mate/open/transaction) f->>w: 返回代理能量交易 (未广播) c-->>w: 创建支付资源费交易 (未广播) w->>t: 广播代理资源交易 w->>t: 广播用户智能合约交易 w->>t: 广播支付资源费交易 w-->>f: 提交支付 HASH (POST /v1/mate/open/transaction/pay/{order_id}) activate f alt 校验转账成功 f->>f: 更新订单状态为成功 else 校验转账失败 f->>f: 更新订单状态为失败 f-->>w: 返回失败订单 end deactivate f ``` ## 订单状态 两种支付方式使用相同的订单查询接口。接入方需要分别关注资源状态和付款状态： | 状态字段 | 状态 | 说明 | | ---------------- | ----------- | ------------------------------ | | `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 支持人员处理。