For developers working within the Ethereum ecosystem, efficiently accessing blockchain data is a fundamental task. This guide provides a detailed overview of how to utilize specific API endpoints to retrieve lists of transaction records and their detailed information, which is crucial for building applications like explorers, wallets, or analytical tools.
Understanding the Core API Endpoints
Two primary endpoints are essential for fetching transaction data from an Ethereum-compatible blockchain. These interfaces are designed to be universal, working across various chains within the broader Ethereum network.
Fetching a List of Transactions
The first endpoint allows you to retrieve a paginated list of transactions associated with a specific blockchain address.
Endpoint: /v1/transaction_action/universal_list
HTTP Method: GET
Key Request Parameters
To successfully call this endpoint, you must include specific parameters in your request. The most critical parameters are the address and an identifier for the blockchain.
address: The wallet address for which you want to query transactions.blockchain_idorchain_id: A unique identifier for the target blockchain network (e.g., Ethereum Mainnet, a testnet, or an EVM-compatible sidechain). You only need to provide one of these identifiers.count: The number of transaction records to return per page.page: The page number for pagination, starting from 0.contract_address(Optional): To filter transactions related to a specific smart contract.type(Optional): To filter transactions by a specific type.
Understanding the Response Data
A successful API call returns a JSON object containing an array of transaction records. Each transaction object includes a wealth of data, such as:
- Transaction Hash (
hash): The unique identifier of the transaction. - Block Information (
block_number,block_hash): Confirms which block the transaction is included in. - Parties Involved (
from,to): The sender and recipient addresses. - Value Transferred (
value,decimal,symbol): The amount of the native cryptocurrency (e.g., ETH) sent, along with its denomination. - Gas Details (
gas,used_gas,gas_price,fee): Information about the computational effort required and the fee paid for the transaction. - Status (
status): Indicates the finality of the transaction. A status of1typically means success,0indicates failure,2means pending, and99is unknown.
This data is indispensable for tracking fund movements and auditing wallet activity. For developers looking to integrate real-time data streams directly into their applications, exploring advanced data solutions can provide a significant advantage. You can access powerful blockchain data tools here to enhance your project's capabilities.
Retrieving Detailed Transaction Information
While the list endpoint provides a summary, the details endpoint offers a deeper dive into a specific transaction's metadata.
Endpoint: /v1/transaction_action/universal
HTTP Method: GET
Key Request Parameters
This endpoint requires identifiers that pinpoint one exact transaction on the chain.
hash: The transaction hash (unique ID) of the specific transaction you want to query.blockchain_idorchain_id: The identifier for the blockchain network.block_hash: The hash of the block containing the transaction (adds an extra layer of specificity).
Key Details in the Response
The response for the detail endpoint contains all the information found in the list view, plus additional context that might be available for that specific transaction type, such as more nuanced input data (input) which is critical for interpreting smart contract interactions.
Frequently Asked Questions
Q1: What is the difference between chain_id and blockchain_id?
A1: In the context of these APIs, chain_id and blockchain_id serve the same purpose: to specify the network. You only need to supply one of them in your request. The chain_id often refers to the standard EIP-155 identifier, while blockchain_id might be a proprietary network identifier used by the API provider.
Q2: What does a transaction status of '2' (pending) mean?
A2: A status of '2' indicates that the transaction has been broadcast to the network but has not yet been included in a block. It is still in the mempool and等待 confirmation. The status will eventually change to either success (1) or failure (0) once mined.
Q3: How can I filter transactions that involve a specific token?
A3: You can use the contract_address parameter in the transaction list request. Set this parameter to the address of the token's smart contract. This will filter the results to show only transactions that interacted with that specific contract, such as token transfers or approvals.
Q4: What does log_index represent and why is it sometimes -1?
A4: The log_index indicates the position of a transaction's event log within its block. For simple native asset transfers (e.g., sending ETH), no event log is emitted by the Ethereum Virtual Machine (EVM), so this value is typically set to -1. For smart contract transactions that emit events, it will be a positive integer.
Q5: The input field is often filled with hex data. How can I decode it?
A5: The input field contains the data payload sent with a transaction. For smart contract interactions, this data encodes the function to be called and its parameters. Decoding it requires the Application Binary Interface (ABI) of the specific contract. Various online tools and web3 libraries (like web3.js or ethers.js) can decode this data if you have the correct ABI.
Q6: My request returns no data. What should I check first?
A6: First, verify that the address parameter is correct and that the wallet has conducted transactions on the specified network (blockchain_id). Ensure you are querying the correct API endpoint for the network (e.g., testnet vs. mainnet). Finally, double-check that your request structure and parameters are formatted correctly.