Understanding the intricate details of a blockchain transaction is crucial for developers, analysts, and enthusiasts. Whether you're auditing smart contracts, tracking fund flows, or building a dApp, accessing decomposed transaction data is a foundational task. This guide explains how to retrieve specific transaction information using a Wallet API, which breaks down complex transactions into understandable sub-components.
How the Wallet API Processes Transactions
A single on-chain transaction can involve multiple operations. The Wallet API simplifies this by decomposing a transaction and any internal transactions into distinct sub-transactions categorized by asset type.
The primary sub-transaction types for EVM-compatible chains are:
- Type 0 (
0): Represents an outer layer mainnet coin transfer (e.g., ETH, MATIC). - Type 1 (
1): Denotes an inner layer mainnet coin transfer that occurs within a contract execution. - Type 2 (
2): Covers all token transfers (e.g., ERC-20, ERC-721).
This structured breakdown allows for precise tracking of asset movement, making it easier to understand the full scope of a transaction's impact. For a deeper dive into real-time data fetching, you can explore more strategies for implementing these API calls.
API Request Structure
To fetch transaction details, you need to make a specific API call with the required parameters.
API Endpoint
The request is made using a GET method to the following path:https://web3.okx.com/api/v5/wallet/post-transaction/transaction-detail-by-txhash
Required and Optional Parameters
Your request must include specific parameters to receive the correct data.
| Parameter | Type | Required | Description |
|---|---|---|---|
chainIndex | String | Yes | The unique identifier for the blockchain network (e.g., 1 for Ethereum Mainnet). |
txHash | String | Yes | The unique hash of the transaction you want to query. |
iType | String | No | Layer type filter. Use this to filter results by a specific sub-transaction type: 0 (outer layer), 1 (inner layer), or 2 (token transfer). |
Understanding the API Response
The response from the API is a rich dataset containing everything you need to know about the queried transaction. The data is returned in a structured JSON format.
Core Transaction Metadata
The response includes high-level information about the transaction's status and execution on the network.
chainIndex: The chain identifier confirming the network.height: The block number containing the transaction.txTime: The transaction timestamp (Unix time in milliseconds).txhash: The transaction hash.txStatus: The final status (1for pending,2for success,3for failure).gasLimit,gasUsed,gasPrice,txFee: Key gas metrics detailing the computational cost.nonce: The sender's nonce for this transaction.amount&symbol: The primary value and currency symbol transferred.methodId: The ID of the contract method called, if applicable.
Detailed Input and Output Breakdown
The API provides granular details about where assets came from and where they went.
fromDetails(Array): A list of inputs, typically for UTXO-based chains, detailing the source of funds.address: The sending address.vinIndex,preVoutIndex,txhash: UTXO-specific identifiers.isContract: Boolean indicating if the sender is a contract.amount: The amount sent from this input.
toDetails(Array): A list of outputs, detailing the recipients of the transaction.address: The receiving address.voutIndex: The index of this specific output.isContract: Boolean indicating if the receiver is a contract.amount: The amount received by this output.
Internal and Token Transfer Data
For complex transactions involving smart contracts, the API decomposes internal actions.
internalTransactionDetails(Array): Details of any internal value transfers that occurred during contract execution. Includesfrom,to, contract flags,amount, andtxStatus.tokenTransferDetails(Array): Specifics of all token transfers within the transaction. Includes token contract address, symbol, amount, and the involved addresses with their contract flags.l1OriginHash: For Layer 2 solutions, this hash points back to the originating Layer 1 transaction.
Practical Application and Use Cases
Querying transaction details is vital for numerous Web3 development scenarios. Developers use this API to build transparent audit trails for DeFi protocols, create detailed transaction history for wallets, verify the outcome of smart contract interactions, and analyze on-chain activity for data-driven insights. The ability to filter by iType is particularly useful for isolating specific types of transfers within a bulky transaction log. To streamline your development process, get advanced methods for handling and displaying this data efficiently.
Frequently Asked Questions
What is the difference between txStatus in the main response and within internalTransactionDetails?
The main txStatus reflects the overall success or failure of the entire transaction on the blockchain. An internalTransactionDetails status shows the result of that specific internal call, which could fail even if the overall transaction succeeds, or vice versa, depending on error handling.
When should I use the iType parameter?
Use the iType filter when you are only interested in a specific category of transfer within a transaction. For example, if you only want to see token transfers (ERC-20) and ignore native coin movements, set iType=2. Omitting it returns all sub-transaction types.
How do I interpret the fromDetails and toDetails for an account-based chain like Ethereum?
For Ethereum-like chains, a transaction typically has one input (fromDetails with one object) and one or more outputs (toDetails). The vinIndex and voutIndex are still provided for consistency but are less critical than in UTXO models.
What does an empty internalTransactionDetails array mean?
An empty array indicates that the transaction was a simple transfer of value (native coin or tokens) and did not involve any smart contract execution that resulted in internal value transfers.
Can I use this API to track a transaction that is still pending?
Yes, you can query a transaction while it's pending. The txStatus field will show 1, and some details like blockHeight may be unavailable until it is successfully mined into a block.
Is the amount field always in the smallest unit (e.g., wei)?
Yes, the amount fields for both native coins and tokens are typically returned in the smallest base unit (e.g., wei, satoshi, lamports) as a string to maintain precision. You will need to convert it to a human-readable format using the token's decimals.