Understanding blockchain activity at the address level is essential for developers, analysts, and security teams working in Web3. Whether you're monitoring wallet behavior, verifying transaction authenticity, or building decentralized applications, accessing accurate on-chain information is critical. This guide dives into how to retrieve transaction history by address using a powerful Wallet-as-a-Service (WaaS) Web3 API.
With this endpoint, you can query all transactions associated with a specific blockchain address across supported chains, filter results by token type or time range, and paginate through large datasets efficiently.
Querying Transaction History by Address
The primary function of this API is to fetch transaction records linked to a given wallet address. Transactions are returned in descending chronological order, meaning the most recent activity appears first—ideal for real-time dashboards or audit trails.
All data is pulled directly from the blockchain ledger, ensuring transparency and accuracy. This makes it perfect for use cases like fraud detection, compliance reporting, portfolio tracking, and smart contract interaction analysis.
👉 Discover powerful on-chain analytics tools to enhance your Web3 development workflow.
Endpoint Overview
Use the following RESTful GET request to retrieve transaction data:
GET https://web3.okx.com/api/v5/wallet/post-transaction/transactions-by-addressThis secure, scalable endpoint supports both single-chain and cross-chain queries, returning structured JSON responses optimized for programmatic processing.
Request Parameters Explained
To tailor your query, several optional and required parameters are available:
address(String, Required)
The wallet address you want to investigate. Must be a valid blockchain address format (e.g., Ethereum-style hex address).chainIndex(String, Optional)
Specifies the target blockchain. For example:ETH=3. If omitted, the system may default to mainnet or return multi-chain results depending on configuration.tokenAddress(String, Optional)
Filter transactions involving a specific token contract. If provided, only transfers of that ERC-20 or equivalent token will be returned.Note: If empty, returns transactions involving the chain’s native currency (e.g., ETH). If not passed at all, includes all transaction types.
begin(String, Optional)
Start timestamp (Unix time in milliseconds) to filter transactions from a specific date onward.end(String, Optional)
End timestamp (Unix time in milliseconds) to limit results up to a certain point in time.If neither
beginnorendis provided, the API defaults to fetching transactions before the current time.cursor(String, Optional)
Used for pagination. Pass the cursor value from a previous response to retrieve the next page of results.limit(String, Optional)
Number of records to return per call:- Maximum 20 for single-chain queries.
- Up to 100 when querying multiple chains simultaneously.
- Defaults to 20 if not specified.
These parameters allow granular control over data retrieval—perfect for building responsive user interfaces or batch-processing historical data.
Understanding the Response Structure
The API returns a standardized JSON object containing two main components: transactionList and cursor.
Transaction List Details
Each item in transactionList includes comprehensive metadata:
chainIndex: Unique identifier for the blockchain where the transaction occurred.txHash: The transaction hash—your immutable reference ID on-chain.iType: Classifies transaction type:0: Outer main chain coin transfer (e.g., sending ETH between EOA wallets)1: Contract inner main chain coin transfer (e.g., depositing ETH into a smart contract)2: Token transfer (e.g., ERC-20 transfers)
methodId: Function selector called within a smart contract (if applicable).nonce: Sequence number of the sender’s transaction history.txTime: Timestamp in Unix milliseconds (e.g.,1597026383085= July 10, 2020 10:26:23 AM UTC).
Input & Output Breakdown
Transactions include full from and to arrays:
from.address: Sender(s); comma-separated in multi-sig cases.from.amount: Value sent from each input.to.address: Recipient(s); supports multiple outputs.to.amount: Respective amounts received.
Additional fields:
tokenAddress: Contract address of transferred token (null for native asset transfers).amount: Quantity transferred.symbol: Ticker symbol (e.g., USDT, ETH).txFee: Total gas or network fee paid.txStatus: One of:successfailpending
Security indicators:
hitBlacklist: Boolean flag indicating if any involved address is flagged.tag: Deprecated field; previously used to classify risk types like phishing or contract vulnerabilities.
Finally, the top-level cursor enables seamless pagination through large datasets.
Practical Use Cases
This API powers a wide range of applications:
- Wallet Analytics Dashboards: Visualize incoming/outgoing flows over time.
- Compliance & AML Monitoring: Flag suspicious patterns or blacklisted addresses.
- DeFi Integrations: Track yield farming rewards or liquidity pool changes.
- Smart Contract Auditing: Verify external interactions during testing.
- User Onboarding Flows: Auto-detect past activity to personalize onboarding experiences.
👉 Access advanced blockchain data tools that streamline Web3 development and analysis.
Frequently Asked Questions (FAQ)
What does "descending chronological order" mean?
It means the most recent transactions appear first in the response list. This is ideal for displaying live activity feeds or detecting recent suspicious behavior.
Can I query multiple tokens at once?
Not directly through the tokenAddress parameter—it accepts only one contract address. However, omitting this field returns all token and native currency transfers, which you can filter client-side.
How far back can I retrieve transaction history?
There is no fixed limit—the API accesses full blockchain records as long as the node infrastructure supports it. Use begin and end parameters to define your desired time window.
Why is the tag field marked as deprecated?
The tag field was previously used to categorize blacklisted addresses (e.g., phishing sites). It's now deprecated in favor of more robust risk-scoring systems outside this endpoint.
Is there rate limiting on this API?
Yes. To ensure fair usage and system stability, rate limits apply based on your access tier. Check official documentation for details on request quotas and burst limits.
How do I handle pagination with large datasets?
Use the cursor parameter. Each response includes a cursor value. Include it in your next request to fetch the following page of results until no more data is returned.
Final Thoughts
Accessing detailed on-chain transaction history by address empowers developers and analysts with real-time insights into wallet behavior. By leveraging this Web3 API endpoint effectively, you can build secure, transparent, and user-centric blockchain applications.
Whether you're verifying fund flows, detecting anomalies, or enriching user profiles, having reliable access to transaction history, wallet activity, and blockchain metadata is foundational in today’s decentralized ecosystem.
👉 Unlock deeper insights with real-time blockchain data and developer tools built for scale.