Accessing accurate and timely blockchain transaction history is essential for developers, analysts, and businesses operating in the Web3 ecosystem. Whether you're auditing wallet activity, tracking token movements, or building decentralized applications, having a reliable method to retrieve on-chain data is crucial. This guide explores how to use the Wallet as a Service (WaaS) Web3 API to fetch comprehensive transaction history by account across multiple chains.
With this powerful endpoint, you can query all or specific chain transactions under an account dimension, returned in descending chronological order—ensuring you always get the most recent activity first.
Retrieve On-Chain Transaction History via API
The primary endpoint for fetching transaction records is:
GET https://web3.okx.com/api/v5/wallet/post-transaction/transactionsThis RESTful API allows developers to programmatically access detailed on-chain transaction data without running their own node infrastructure. It supports filtering by chain, token type, time range, and pagination control—making it ideal for integration into dashboards, compliance tools, or analytics platforms.
👉 Discover how easy it is to integrate real-time blockchain data into your application
Request Parameters: Customize Your Query
To tailor the results to your needs, several optional and required parameters are available:
accountId(String, required)
The unique identifier for the wallet or user account. This is the core input that defines whose transaction history you're retrieving.chainIndex(String, optional)
Specify the blockchain network using its index (e.g.,ETH=3). If omitted, the response includes cross-chain activity.tokenAddress(String, optional)
Filter results by a specific token contract address. Leave empty to query native coin transfers (like ETH), or omit entirely to retrieve all transactions.begin(String, optional)
Start timestamp in Unix milliseconds. Only transactions after this time will be included.end(String, optional)
End timestamp in Unix milliseconds. Only transactions before this time will be returned. If neitherbeginnorendis provided, the system defaults to fetching recent transactions up to the current moment.cursor(String, optional)
Used for pagination. Pass the cursor from a previous response to retrieve the next page of results.limit(String, optional)
Number of records per request. Default is 20; maximum allowed is also 20. Helps manage payload size and improve performance.
These parameters give fine-grained control over data retrieval—perfect for compliance checks, forensic analysis, or real-time monitoring.
Understanding the Response Structure
The API returns a structured JSON response containing two main components: transactionList and cursor.
Transaction List Breakdown
Each item in transactionList includes rich metadata about the transaction:
chainIndex: The blockchain network ID where the transaction occurred.txHash: Unique transaction hash for verification on explorers.iType: Indicates the EVM layer transaction type:0: External main chain coin transfer1: Internal contract-based main chain coin transfer2: Token transfer (ERC-20, etc.)
methodId: Smart contract function identifier (if applicable).nonce: Sequential number of transactions sent from the sender’s address.txTime: Timestamp in Unix milliseconds (e.g.,1597026383085).
Input and Output Details
from: Array of sender addresses and input amounts.address: One or more comma-separated addresses involved in the input.amount: Value transferred from each input.
to: Array of recipient addresses and output amounts.address: One or more comma-separated receiving addresses.amount: Respective value sent to each output.
Additional fields include:
tokenAddress: Contract address of the token involved (null for native coin transfers).amount: Transaction amount in human-readable format.symbol: Ticker symbol (e.g., ETH, USDT).txFee: Network fee paid for the transaction.txStatus: Current status — success, fail, pending, etc.hitBlacklist: Boolean flag indicating if the transaction involves blacklisted addresses.tag: Deprecated field previously used to classify risks like phishing or contract vulnerabilities.
The cursor value at the root level enables seamless pagination for large datasets.
Practical Use Cases for Account-Based History Queries
This API isn’t just for viewing past transactions—it powers real-world applications across industries:
1. Fraud Detection & Risk Monitoring
By analyzing transaction patterns and checking hitBlacklist, security teams can flag suspicious behavior early.
2. User Activity Dashboards
DApps and custodial platforms can display clean, sorted histories for users—enhancing transparency and trust.
3. Compliance & Audit Logging
Regulated entities can generate tamper-proof logs of financial flows aligned with KYT (Know Your Transaction) standards.
4. Token Flow Analytics
Track how specific tokens move across wallets after airdrops, ICOs, or staking rewards.
👉 See how blockchain APIs can transform your data workflow instantly
Frequently Asked Questions
Q: Can I query transactions across multiple blockchains at once?
A: Yes. By omitting the chainIndex parameter, the API returns aggregated transaction history across all supported chains associated with the account.
Q: How far back can I retrieve historical data?
A: The API provides access to full on-chain history since the account’s first transaction. There are no hard retention limits—data availability depends only on blockchain immutability.
Q: What does a "pending" transaction mean in the response?
A: A txStatus of "pending" indicates the transaction has been broadcast but not yet confirmed on-chain. These typically resolve within minutes depending on network congestion.
Q: Is there rate limiting on this API?
A: While not specified in the documentation, best practices suggest implementing exponential backoff and caching to avoid overloading. For high-frequency access, consider enterprise-tier plans.
Q: How do I handle multi-signature wallet transactions?
A: Multi-sig transactions are supported—the from and to fields will list multiple comma-separated addresses when applicable.
Q: Why is the tag field marked as deprecated?
A: The risk classification logic has moved off this field. While it may still appear, reliance on hitBlacklist combined with external threat intelligence is recommended for security assessments.
Best Practices for Integration
When integrating this API into production systems:
- Always validate the
accountIdformat before sending requests. - Use
beginandendfilters to reduce response size during bulk processing. - Implement cursor-based pagination to avoid missing records due to real-time updates.
- Cache results where appropriate to minimize redundant calls.
- Monitor
txStatuschanges for critical financial operations.
Final Thoughts
Efficient access to on-chain transaction history empowers smarter decision-making in Web3 environments. With robust filtering, clear structure, and scalable design, this Wallet API delivers precise account-level insights across chains.
Whether you're building a secure wallet interface, monitoring corporate treasury movements, or analyzing DeFi interactions, this tool provides the foundation you need.