In the dynamic world of Web3 and blockchain technology, accessing reliable and detailed on-chain information is crucial. For developers, analysts, and enthusiasts working with token inscriptions, the ability to query specific transaction details by hash is a fundamental need. This process provides transparency and verifiable data directly from the blockchain.
This guide explains the methods and parameters required to successfully retrieve detailed information about inscription transactions across various protocols, including Runes, BRC-20, SRC-20, ARC-20, and Ordinals NFTs on the Bitcoin chain.
Understanding the API Endpoint for Transaction Queries
The primary method for fetching inscription transaction details is through a specific API request. This GET request is sent to a dedicated endpoint designed to parse transaction hashes and return a structured set of data.
The request path is:GET https://web3.okx.com/api/v5/wallet/post-transaction/inscription-transaction-detail-by-txhash
Essential Request Parameters
To receive accurate data, your API call must include several required parameters. Each parameter plays a vital role in filtering and returning the correct information from the blockchain.
| Parameter | Type | Required | Description |
|---|---|---|---|
chainIndex | String | Yes | The unique identifier for the blockchain you are querying. |
txHash | String | Yes | The unique transaction hash of the inscription transaction you wish to investigate. |
protocol | String | Yes | This specifies the protocol type. Options include: 1 for BRC-20, 2 for ARC-20, 3 for Runes, 4 for Ordinals NFT, and 5 for SRC-20. If omitted, it defaults to BRC-20. |
cursor | String | No | A pagination cursor used to retrieve the next set of results. |
limit | String | No | The number of transaction entries to return. The default is 20, and the maximum allowed is 100. |
Interpreting the Response Data
A successful API response returns a JSON object containing a wealth of information about the queried transaction. The main container is an array of transactionDetails.
| Parameter | Type | Description |
|---|---|---|
transactionDetails | Array | The main array containing the detailed transaction objects. |
>txStatus | String | The final state of the transaction: success or fail. Note: Pending transactions are not supported. |
>from | String | The sender's address. For multi-signature addresses, multiple addresses are separated by commas. |
>to | String | The receiver's address. For multi-signature addresses, multiple addresses are separated by commas. |
>eventType | String | The type of transaction event (e.g., deploy, mint, transfer for BRC-20; Etch, Mint for Runes). |
>protocol | String | The protocol type identifier (e.g., 1 for BRC-20). |
>txHash | String | The transaction hash you queried. |
>blockHash | String | The hash of the block that includes this transaction. |
>height | String | The block height at which the transaction was confirmed. |
>txTime | String | The transaction timestamp in Unix time (milliseconds). |
>amount | String | The amount of tokens involved in the transaction. |
>symbol | String | The ticker or name of the token (e.g., "ordi"). |
>tokenInscriptionId | String | The unique inscription ID. For Runes, this is the Rune ID; for BRC-20, it's the Inscription ID; for ARC-20, it's the Atomical ID. |
>inscriptionNumber | String | The inscription number involved in the transaction. |
>outputIndex | String | The UTXO index for Runes token transfers (specific to the Runes protocol). |
cursor | String | A cursor for paginating through large sets of results. |
Practical Application and Use Cases
Why is this data so valuable? Querying inscription transactions is essential for a variety of Web3 activities.
- Portfolio Tracking: Users can verify the status and details of their own asset transfers.
- Market Analysis: Analysts can track the movement of large volumes of specific tokens to understand market trends.
- Application Development: Developers building wallets, explorers, or DeFi platforms need this data to display accurate user information.
- Auditing and Verification: Projects and individuals can audit transaction histories for compliance or proof of ownership.
👉 Explore more strategies for on-chain data analysis
Frequently Asked Questions
What is the difference between txHash and blockHash?
The txHash is the unique identifier for a specific transaction. The blockHash is the identifier for the block that contains that transaction, along with many others. The height parameter tells you the block number in the chain where the transaction is located.
Why does my query return an empty or error response?
This can happen for several reasons. The transaction hash may be incorrect, the transaction may not yet be confirmed (pending status is not supported), or the protocol type might be misconfigured for the asset you are trying to query. Double-check all required parameters.
How do I handle pagination for large sets of transactions?
Use the limit parameter to control the number of results per page. If there are more results available, the response will include a cursor value. Use this cursor in your next API request to retrieve the subsequent page of results.
What does the outputIndex mean and when is it used?
The outputIndex is specifically relevant for the Runes protocol. It refers to the index of the Unspent Transaction Output (UTXO) that holds the rune tokens after a transfer, which is necessary for tracking their state on the Bitcoin blockchain.
Can I query testnet transactions with this API?
The ability to query testnet chains depends on the API provider's infrastructure. You would need to use the correct chainIndex that corresponds to a testnet environment, such as Bitcoin Testnet, if it is supported by the service.