> 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/en/solutions/transaction-handoff.md). # Transaction Handoff ## Product Overview Transaction Handoff provides TRON Energy and Bandwidth on demand for your business system. Through the API, you receive signed but unbroadcast resource delegation transactions, control when to broadcast them, and integrate resource delivery into transfers, payments, swaps, or other smart contract workflows. In this document, “partner” refers to an organization, team, or developer integrating Transaction Handoff. “Business system” means the application or service the partner uses to build, broadcast, and query TRON transactions. Exchanges, wallets, DApps, and payment platforms are examples of such systems. The terms “user” and “end user” refer to the partner’s end user. Transaction Handoff supports two payment methods: **Partner Balance Payment** and **Partner End-User Payment**. {% hint style="info" %} Partner Balance Payment is enabled by default. To let your end users pay the resource fee, contact CatFee customer support to enable Partner End-User Payment. {% endhint %} ## Key Difference from Other Energy Services After an order is created, CatFee returns **signed but unbroadcast Energy or Bandwidth delegation transaction data**. CatFee does not broadcast the delegation transaction to the TRON network. The partner decides when to broadcast the transaction and how to combine it with its own transfer, swap, or smart contract flow. **Partner-controlled broadcasting is the key difference between Transaction Handoff and other Energy service models.**
Transaction Handoff workflow: a business system initiates a TRON transaction as needed; CatFee returns a signed but unbroadcast resource delegation transaction; the partner broadcasts the energy or bandwidth delegation first, then the business transaction; the TRON network confirms the transactions.

CatFee returns a signed resource delegation transaction, and the partner controls broadcast timing within its existing flow.

The diagram shows the resource delivery flow: the partner broadcasts the energy or bandwidth delegation transaction first, then the user transaction, and checks their on-chain results separately. Both payment methods use this resource delivery flow. Payment and settlement steps are described below. ### Benefits * **Simple user experience**: Integrate the resource service into your existing transaction flow. * **Flexible integration**: Arrange broadcast timing and connect business steps to support transfers, payments, swaps, and other workflows. * **On-demand resources**: Request Energy or Bandwidth for each transaction as needed. * **Partner-controlled broadcasting**: Choose when to broadcast the delegation transaction and how it fits into the business flow. * **Flexible payment**: Settle centrally from the partner balance or let partner end users pay per order. * **On-chain visibility**: Delegation transactions and end-user payment transactions can be viewed on TRON. ### Use Cases Transaction Handoff is suitable for business systems that need resources on demand and control over transaction broadcasting. Examples include transfer services, payment systems, asset management tools, automated business scripts, and applications offering swaps or other smart contract operations. Business transactions can be initiated by end users or triggered by the system according to business rules. Resource purchases and broadcasting can be incorporated into the existing flow in either case. ## Before You Start Complete the following before integration: * Sign in to the CatFee Dashboard and apply for Transaction Handoff. * View the API credentials under **API Access** in the Dashboard. * Complete API authentication and request signing as described in the [API Overview](/en/getting-started/buy-energy-via-api-on-catfee/api-overview.md). * Make sure the business system can build, sign, broadcast, and query TRON transactions. * Make sure the business system can estimate the Energy or Bandwidth required by the user's transaction. * Make sure the resource receiver address is activated on TRON. ## Payment Method 1: Partner Balance Payment (Default) ### How It Works Partner Balance Payment is enabled by default. The partner keeps a sufficient balance in its CatFee account, and CatFee automatically deducts the order amount after resource delivery is confirmed. The partner's end user does not need to create a separate resource fee payment transaction. Whether and how the business system charges its users is determined by the partner's own product model. If resource delivery fails, the order is canceled and is not charged as a successful order. ### Business Flow 1. The user initiates a transaction through the business system, or the system triggers a transaction according to business rules. 2. The business system estimates the required Energy or Bandwidth and requests a quote from CatFee. 3. The business system creates a Transaction Handoff order, and CatFee checks the partner's account balance. 4. CatFee returns the order information and signed, unbroadcast Energy or Bandwidth delegation transaction data. 5. The partner controls broadcast timing within its business flow, broadcasting the delegation transaction first and then the user's transaction. 6. After resource delivery is confirmed, CatFee deducts the fee from the partner's account balance. 7. The business system queries both the Transaction Handoff order and the user's transaction for their final results. ### Developer Integration #### 1. Estimate the Resource Fee Call `POST /v1/mate/open/transaction/estimate` with the resource type and quantity. The returned estimate can be used for internal billing or displayed to the user. The estimate is for reference. Use the amount returned when the order is created as the final order amount. See [Estimate Order](/en/api-reference/transaction/estimate.md). #### 2. Create a Transaction Handoff Order Call `POST /v1/mate/open/transaction` with the resource receiver address, resource quantity, and resource type. We recommend also providing a unique `client_order_id` from your system. The response contains the order ID, order amount, and signed, unbroadcast Energy or Bandwidth delegation transaction data. Save the complete first successful response. If the partner balance is insufficient, the order cannot be created; add funds before trying again. See [Create Order](/en/api-reference/transaction/create-order.md). #### 3. Broadcast the Transactions After the order is created, the partner controls broadcast timing within its business flow: broadcast the delegation transaction returned by CatFee first, then the user's business transaction. CatFee does not broadcast the delegation transaction on the partner's behalf. Store and query the results of the two transactions separately. #### 4. Query the Order Call `GET /v1/mate/open/transaction/{order_id}` to query the order. Once resource delivery is confirmed, CatFee automatically settles the order from the partner balance. Do not call the payment hash endpoint for this payment method. See [Order Detail](/en/api-reference/transaction/order-detail.md). ### Partner Balance Payment Sequence ```mermaid sequenceDiagram autonumber actor u as User participant w as Business System participant f as CatFee participant t as TRON Network u->>w: Initiate smart contract transaction (unbroadcast) w->>f: Estimate the required resource fee f-->>w: Return fee details w->>f: Create Transaction Handoff order f->>f: Check partner account balance f-->>w: Return signed delegation transaction (unbroadcast) w->>t: Partner broadcasts delegation transaction w->>t: Broadcast user's smart contract transaction t-->>f: Confirm resource delivery f->>f: Deduct fee from partner balance w->>f: Query order status f-->>w: Return order and settlement result ``` ## Payment Method 2: Partner End-User Payment (Activation Required) ### How It Works Partner End-User Payment is suitable for business systems whose operators want their own end users to pay each resource fee and retain a separate on-chain payment record. This payment method is not enabled by default. Contact CatFee customer support to request activation. Once enabled, the end user pays TRX using the amount and receiving address in the order, and the business system broadcasts the payment transaction and submits its hash to CatFee. ### Business Flow 1. The user initiates a transaction through the business system, or the system triggers a transaction according to business rules. 2. The business system requests a resource quote and creates a Transaction Handoff order. 3. CatFee returns signed, unbroadcast delegation transaction data, the amount due, and the payment address. 4. The business system creates the end-user payment transaction using the order information and asks the user to confirm it. 5. The partner controls broadcast timing within its business flow, broadcasting the delegation transaction first, then the user's business transaction, and also broadcasting the payment transaction. 6. The business system submits the payment transaction hash to CatFee. 7. The business system queries the order until both resource delivery and payment are confirmed. ### Developer Integration Partner End-User Payment uses the same estimate, order creation, and order query endpoints as Partner Balance Payment, with these additional steps: 1. Use `amount_sun` and `payee_address` from the create-order response to build the end-user payment transaction. 2. After broadcasting the payment transaction, call `POST /v1/mate/open/transaction/pay/{order_id}` to submit its hash. 3. Continue querying the order until both resource and payment statuses are confirmed. A successful payment-hash request only means that CatFee has received the payment information. It does not mean the payment is confirmed. See [Submit Payment Hash (Partner End-User Payment)](/en/api-reference/transaction/pay-order.md). ### Partner End-User Payment Sequence ```mermaid sequenceDiagram autonumber actor u as User participant w as Business System participant f as CatFee participant t as TRON Network u->>w: Initiate smart contract transaction (unbroadcast) w->>f: Estimate resource fee (POST /v1/mate/open/transaction/estimate) f-->>w: Return fee details w->>f: Create delegation transaction (POST /v1/mate/open/transaction) f-->>w: Return signed delegation transaction (unbroadcast) u-->>w: Create resource fee payment transaction (unbroadcast) w->>t: Broadcast delegation transaction w->>t: Broadcast user's smart contract transaction w->>t: Broadcast resource fee payment transaction w-->>f: Submit payment hash (POST /v1/mate/open/transaction/pay/{order_id}) activate f alt Payment confirmed f->>f: Update payment status to confirmed else Payment confirmation failed f->>f: Update payment status to failed f-->>w: Return failed order status end deactivate f ``` ## Order Statuses Both payment methods use the same order query endpoint. Track the resource status and payment status separately: | Field | Status | Meaning | | ---------------- | ----------- | ------------------------------------------------------------------------------------ | | `status` | `CREATED` | The order has been created and the delegation transaction is awaiting confirmation | | `status` | `CONFIRMED` | The delegation transaction has been confirmed | | `status` | `CANCEL` | The delegation transaction failed and the order was canceled | | `payment_status` | `UNPAID` | Settlement is incomplete; for end-user payment, no payment hash has been submitted | | `payment_status` | `PAID` | The end-user payment hash has been submitted and is awaiting on-chain confirmation | | `payment_status` | `CONFIRMED` | The partner balance deduction or end-user payment has been confirmed | | `payment_status` | `FAIL` | Settlement did not complete; check the balance or payment details, or contact CatFee | `status = CONFIRMED` only means that the delegation transaction was confirmed. It does not mean the user's business transaction also succeeded. Query the user's transaction separately. ## Key Response Fields Save the following information after creating an order: | Field | Description | | --------------- | -------------------------------------------------------------- | | `order_id` | CatFee order ID used to query the order | | `hex` | Signed, unbroadcast delegation transaction data | | `hash` | Delegation transaction hash | | `amount_sun` | Resource fee for the order, in sun | | `payee_address` | Resource fee payment address used for Partner End-User Payment | `1 TRX = 1,000,000 sun`. ## Integration Notes * For Partner Balance Payment, monitor the CatFee account balance to prevent insufficient funds from affecting user transactions. * Use a unique `client_order_id` for each business transaction and store its mapping to the CatFee `order_id`. * Save `order_id`, `hex`, and the related transaction information from the first successful create-order response. * If an order creation request times out or its result is uncertain, do not create another order with a new `client_order_id`. * For Partner End-User Payment, always use the amount and payment address returned by the create-order endpoint. * After submitting a payment hash, query the order before retrying to avoid duplicate user payments. * If the delegation transaction succeeds but the user's business transaction fails, the Transaction Handoff order is still settled normally. * If an order or settlement result is unexpected, keep the order ID and transaction hashes and contact CatFee customer support.