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.

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.

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.

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.

• 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.

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.

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.

Partner Balance Payment Sequence

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).

Partner End-User Payment Sequence

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.