Confirmation semantics
Distinguish the broadcast response, transaction inclusion, execution receipts, solidified blocks, and indexer delay so intermediate states are not treated as final results.
TRON APIs return different data at different stages. Before using a response as a final result, decide whether it represents a broadcast-call result, the transaction body, an execution receipt, solidified state, or indexed service data. Do not treat an intermediate state as final.
Prerequisites
State semantics quick reference
| Result you see | What it means | What it does not mean | Next step |
|---|---|---|---|
BroadcastTransaction returns result: true | The broadcast call completed without a reported error | It does not mean that the transaction remains in the Pending Pool or that it has propagated, been included, executed successfully, or become solidified | Keep the original txID and continue querying its status |
/wallet/gettransactionbyid returns a transaction object | The FullNode can currently return the transaction body | It does not mean that the transaction is solidified, and the transaction body is not a substitute for a receipt with complete execution details | Use /walletsolidity/gettransactionbyid to confirm inclusion in the solidified chain; for a smart-contract transaction, also query the solidified receipt |
/wallet/gettransactioninfobyid returns a receipt | The FullNode can currently return execution information for the transaction | It does not mean that the execution result is solidified | Use /walletsolidity/gettransactioninfobyid to query the solidified receipt |
/walletsolidity/gettransactionbyid returns a transaction object | The transaction body is in the solidified canonical chain | It does not contain the complete execution receipt | For a smart-contract transaction, use /walletsolidity/gettransactioninfobyid to query the solidified receipt |
/walletsolidity/gettransactioninfobyid returns a receipt | The transaction's solidified execution receipt is available | It does not necessarily mean that execution succeeded; the receipt may record a failure | Determine the outcome from the execution status and the business-relevant fields in the receipt |
/walletsolidity/gettransactionbyid returns an empty object | The current query did not find a solidified transaction body | A single empty response does not prove that the transaction was never included | Continue querying the original txID; to establish that the original transaction was not included, follow the safe rebroadcast and replacement procedure |
/walletsolidity/gettransactioninfobyid returns an empty object | The current query did not find a solidified receipt | It does not necessarily mean that the transaction body is absent | First query the transaction body through /walletsolidity/gettransactionbyid; if the transaction is solidified, continue querying the receipt |
| TronGrid returns historical transactions or Events | The index service has processed the corresponding data | It is not the same as native node state; pagination, rate limits, or indexing delay may affect the result | Verify the solidified state and execution result of critical transactions through /walletsolidity endpoints |
A broadcast response is not transaction confirmation
The broadcast API reports whether the call completed without an error. A result: true response does not establish whether the node retained or propagated the transaction, whether a block included it, whether execution succeeded, or whether the result has become solidified.
A common mistake is treating this response as final success:
{ "result": true, "txid": "..." }Continue querying the same txID, choosing the endpoint that matches the question:
- Use GetTransactionById to check whether the FullNode can currently find the transaction body. This is a latest-state observation, not final confirmation.
- To confirm solidified inclusion, use
/walletsolidity/gettransactionbyidto query the transaction body from solidified state. - To determine smart-contract execution results, or inspect fees, Energy, Events, and internal transactions, use GetTransactionInfoById (solidified state) to query the solidified receipt.
A transaction body may be available while a receipt query is still empty. Use the transaction-body endpoint to test for existence; use the receipt for execution details.
Transaction body is not execution receipt
The transaction body describes what the requester submitted. The execution receipt describes what actually happened during on-chain execution.
| Data type | Recommended API | Contains |
|---|---|---|
| Transaction body | GetTransactionById | raw_data, signatures, and contract-call parameters |
| Execution receipt | GetTransactionInfoById | Fees, Energy usage, contract execution status, Events, and internal transactions |
| Solidified execution receipt | GetTransactionInfoById (solidified state) | Execution receipt from a solidified block |
For direct TRX or TRC-10 transfers, the transaction body usually contains the recipient and amount. For TriggerSmartContract, read the receipt to determine the actual execution result.
Latest head is not solidified state
/wallet endpoints read the latest head visible to the node. This state has low latency but may not be solidified. /walletsolidity endpoints read state at the latest solidified block and usually lag the latest head by about 1 minute.
| Read target | Recommended API |
|---|---|
| Latest block display | GetNowBlock, FullNode |
| Latest solidified block | GetNowBlock (solidified state) |
| Query latest-head view by block number | GetBlockByNum, FullNode |
| Confirm whether a block number is solidified | GetBlockByNum (solidified state) |
If a flow requires final state, such as transaction confirmation, balance reconciliation, report generation, or block monitoring, base the decision on /walletsolidity queries or a local solidified-block index.
Indexed data is not native node state
TronGrid V1 API and self-hosted indexers are useful for account history, TRC-20 transfer history, Events, internal transactions, and aggregate statistics. Index services are usually more convenient than scanning blocks directly, but pagination, rate limits, retries, and index delay still matter.
When complete state judgment is required, combine them as follows:
- Use TronGrid or a self-hosted indexer to discover candidate transactions, Events, or internal transactions.
- Use solidified receipts from
/walletsolidity/gettransactioninfobyidor solidified-block scanning to confirm final state. - Store processed block numbers, transaction IDs, and log indexes locally so retries remain idempotent.
Related resources
- Sign and broadcast — the API workflow — full path for constructing, signing, broadcasting, and confirming transaction results
- Broadcast and RPC errors — troubleshooting broadcast failures, missing transactions after broadcast, and node rate limits
- Blocks — block structure, block ID, block number, and query API selection
- API task map — choose docs pages and reference APIs by task
Updated 1 day ago