> 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/getting-started/seamless-energy/application-integration.md).

# Application Integration

When developers integrate Seamless Energy, most scenarios only require replacing the **broadcast domain** used for the original TRON node with the Seamless Energy node domain. The path and request body remain in the original TRON API format.

If you enable API KEY, production-grade rate limiting and retries, strict error handling, or multi-address authentication policies, you also need to handle authentication, timeout, retry, and exception branches.

The main point: **Seamless Energy enhances the signed transaction broadcast stage.**\
If your system currently only queries balances, queries blocks, constructs transactions, or leaves broadcasting to a third-party wallet, first confirm where the real broadcast entry point is.

## Applicable scenarios

* Applications that directly interact with TRON nodes through gRPC.
* Self-built gateways, proxy layers, or transaction relay services.
* DApp backends that forward signed transactions on behalf of users.
* Wallet service providers that manage the broadcast flow centrally.

## Recommended integration order

1. Locate the final broadcast entry point for signed transactions in your system.
2. Confirm whether the broadcast API uses HTTP or gRPC.
3. Apply for a Seamless Energy node and choose an authentication method.
4. Store the node domain and AccessKey in server-side configuration or a secret management system.
5. Only replace the broadcast domain. Keep the original path, request body, signing logic, and transaction parameters unchanged.
6. Complete end-to-end verification with a small TRC20 transfer, approval, or low-risk contract call.
7. Before production, verify exception branches such as insufficient balance, disabled node, authentication failure, rate limiting, and broadcast failure.

## Authentication and permissions

Seamless Energy nodes support three authentication methods:

* API KEY: suitable for developers, wallet service providers, and large-scale address businesses. Requests must pass `CF-NODE-KEY: {AccessKey}` in the HTTP header or gRPC metadata, and the value must match the 41-character random `AccessKey` stored for the node.
* Bound address: suitable for wallet scenarios with a small number of addresses, or clients that do not support custom headers. The owner address of the first transaction in the request must be bound to the node.
* No authentication: suitable for temporary testing.

If you use API KEY, pass it in the HTTP header or gRPC metadata:

```http
CF-NODE-KEY: {AccessKey}
```

`AccessKey` is a 41-character random string generated for the node. You can view or reset it in the CatFee User Center.

## Use AI to assist the integration

If the codebase is large, ask AI to help locate the broadcast entry point first, and then generate the minimal integration plan. Sanitize the context before giving it to AI. In particular, do not provide private keys, mnemonic phrases, keystore files, real AccessKeys, or production node domains.

Ask AI to focus on these checks:

* Which part of the current code actually calls the TRON broadcast API.
* Whether only the broadcast domain was replaced, without changing signing or transaction construction logic.
* Whether `CF-NODE-KEY` is only read from server-side environment variables or a secret management system.
* Whether normal query requests still use the original query node or follow your node plan.
* Whether small contract transactions, regular TRX transfers, and exception branches all have verification plans.

For detailed prompts, read [AI-Assisted Integration](/en/getting-started/seamless-energy/ai-assisted-integration.md).

## Confirm whether your scenario is suitable

The following scenarios are a good fit for Seamless Energy:

* You already have a stable wallet signing flow.
* You can control which broadcast node the transaction is finally sent to.
* You want to automatically prepare ENERGY for contract transactions without changing signing logic.

The following scenarios need boundary confirmation first:

* You only read on-chain data, such as balances, blocks, or transactions.
* You only construct transactions, while broadcasting is completed by a third-party wallet.
* Your wallet or SDK does not allow replacing the broadcast target node.

## HTTP integration

The examples below mainly describe the main flow.\
If your system needs strict handling for insufficient balance, disabled node, authentication failure, rate limiting, on-chain broadcast failure, and similar branches, verify error handling during integration based on CatFee's actual responses.

### Broadcast paths

```http
POST https://{NodeSlug}.catfee.vip/wallet/broadcasthex
POST https://{NodeSlug}.catfee.vip/wallet/broadcasttransaction
```

### `/wallet/broadcasttransaction` example

```bash
curl -X POST "https://bright-blue-river.catfee.vip/wallet/broadcasttransaction" \
  -H "Content-Type: application/json" \
  -H "CF-NODE-KEY: {AccessKey}" \
  -d '{
    "raw_data_hex": "...",
    "signature": ["..."]
  }'
```

### `/wallet/broadcasthex` example

```bash
curl -X POST "https://bright-blue-river.catfee.vip/wallet/broadcasthex" \
  -H "Content-Type: application/json" \
  -H "CF-NODE-KEY: {AccessKey}" \
  -d '{"transaction":"..."}'
```

`/wallet/broadcasthex` can currently be used for hexadecimal transaction broadcasting. Different clients may wrap requests differently. During integration, follow the actual format that works for your client, and preferably standardize on one request format for your business side.

## Which transactions trigger resource preparation

* Triggers: signed broadcast transactions whose first contract is `TriggerSmartContract`.
* Does not trigger: regular TRX transfers, account operations, and other non-contract transactions.
* Needs additional confirmation: complex transaction structures outside the current support scope.

## gRPC integration

```
Server: {NodeSlug}.catfee.vip
Port: 443
SSL/TLS: enabled
Broadcast path: /protocol.Wallet/BroadcastTransaction
```

If you use API KEY, attach `CF-NODE-KEY` in gRPC metadata.

## Broadcast behavior

1. The client constructs and signs the transaction locally.
2. The client sends the signed transaction to the Seamless Energy node.
3. CatFee identifies the node by domain and performs authentication.
4. For supported contract transactions, CatFee estimates ENERGY and prepares resources first.
5. After the energy transaction is broadcast successfully, CatFee waits about 2 seconds before forwarding the original transaction.
6. The original transaction is forwarded unchanged to CatFee's TRON node.
7. The response remains in the TRON broadcast API format.

## Common integration mistakes

* Treating Seamless Energy as a signing service. It is not; signing still happens locally.
* Switching all TRON requests to Seamless Energy. The key point is the broadcast entry point.
* Forcing API KEY when the wallet does not support custom headers. In this case, bound address is usually the better option.
* Ignoring the insufficient balance policy, which directly affects transaction failure behavior and cost outcome.
* Going to production before verifying error responses and retry behavior, which increases the risk of timeout and exception branches.

## Insufficient balance policy

You can configure two policies in the CatFee User Center:

* Continue broadcast: CatFee skips ENERGY purchase and continues forwarding the original transaction.
* Stop broadcast: CatFee returns `402 PAYMENT_REQUIRED`.

Only the "insufficient balance and continue broadcast is enabled" case skips ENERGY purchase and continues forwarding. Other resource handling failure scenarios do not continue broadcasting the original transaction.

## Common statuses

* Node domain does not exist: the node is invalid, usually because the domain is incorrect or the node was deleted.
* Node disabled: re-enable it in the User Center first.
* Member balance insufficient: recharge, or confirm whether continuing broadcast is allowed.
* Requests too fast: the node frequency limit has been exceeded.
* Non-contract transaction: no ENERGY is purchased, and the transaction is forwarded directly.

## Integration checklist

1. A node has been applied for in "User Center -> Seamless Energy".
2. The Seamless Energy node access domain has been obtained.
3. An authentication method has been selected.
4. The wallet or backend only sends signed transactions to Seamless Energy.
5. HTTP broadcast paths keep the original TRON paths, with only the domain replaced.
6. `CF-NODE-KEY` is carried when API KEY is used.
7. gRPC calls have configured server, port, and SSL/TLS.
8. The insufficient balance policy has been configured.
9. End-to-end verification has been completed with a small contract transaction.

## Runtime boundaries

* Currently only the first contract is processed, and its type must be `TriggerSmartContract`.
* Successful resource preparation does not guarantee that the contract execution will succeed.
* The about 2-second wait is used to help resources arrive before broadcasting, but arrival time may still be affected by TRON network conditions.
* Before production integration, it is recommended to additionally verify error responses, rate limiting behavior, timeout retries, and duplicate submission handling.

## Related content

* First-time integration: [Quick Start](/en/getting-started/seamless-energy/quick-start.md).
* Wallet configuration: [Wallet Settings](/en/getting-started/seamless-energy/wallet-settings.md).
* Risk boundaries: [Security](/en/getting-started/seamless-energy/security.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.catfee.io/en/getting-started/seamless-energy/application-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.