In today’s fast-evolving blockchain ecosystem, accessing accurate, real-time on-chain data is essential for developers, analysts, and businesses building decentralized applications (dApps). One of the most powerful tools available is the address dimension query API, which enables users to retrieve comprehensive transaction histories tied to a specific wallet address across multiple blockchains. This guide dives into how to leverage this functionality effectively using a robust Web3 API service.
Whether you're auditing smart contracts, monitoring fund flows, or analyzing user behavior, understanding how to extract and interpret on-chain data by address is a foundational skill in the world of Web3 development.
👉 Discover how easy it is to access real-time blockchain data with powerful API tools.
What Is an Address Dimension Query?
An address dimension query allows developers to fetch all transactions associated with a given blockchain address. These queries are particularly useful for tracking asset movements, detecting suspicious activity, or integrating wallet history into dApps and analytics platforms.
The results are typically returned in chronological order—most recent first—and include detailed metadata such as transaction hashes, timestamps, input/output addresses, token types, fees, and status.
This type of API endpoint supports multi-chain environments, meaning you can pull data from various networks like Ethereum, BSC, Polygon, and more in a single request—streamlining development and reducing latency.
Core Features of the Transaction-by-Address API
Supported Chains and Multi-Network Flexibility
The API supports querying across up to 50 different blockchain networks simultaneously. By specifying chain identifiers in the chains parameter, developers can target precise ecosystems relevant to their use case—whether that’s EVM-compatible chains or emerging Layer 1 solutions.
This cross-chain capability makes it ideal for DeFi dashboards, portfolio trackers, and compliance monitoring systems.
Granular Filtering Options
You can refine your query using several optional parameters:
tokenAddress: Filter results by native coin (e.g., ETH) or specific ERC-20/BEP-20 tokens.beginandend: Define a time window using Unix timestamps (in milliseconds) to retrieve historical data within a specific period.limit: Control pagination by setting the number of records returned per call (up to 100 for single-chain queries).cursor: Use cursor-based pagination for efficient traversal of large datasets without duplicates or gaps.
These filters enhance performance and reduce unnecessary data transfer—critical for high-frequency applications.
Request Structure and Parameters
Endpoint URL
GET https://web3.okx.com/api/v5/wallet/post-transaction/transactions-by-addressRequired Parameters
| Parameter | Type | Description |
|---|---|---|
address | String | The wallet address to query (e.g., 0x...). |
chains | String | Comma-separated list of chain IDs (e.g., eth,bsc). |
Optional Parameters
| Parameter | Type | Description |
|---|---|---|
tokenAddress | String | Leave empty for all tokens + native coin; set to " " for native coin only; specify contract address for token-specific lookups. |
begin | String | Start timestamp (ms) — returns transactions after this time. |
end | String | End timestamp (ms) — returns transactions before this time. |
cursor | String | Pagination cursor from previous response. |
limit | String | Number of results per page (default: 20). |
Example Request
GET https://web3.okx.com/api/v5/wallet/post-transaction/transactions-by-address?address=0x123...&chains=eth,polygon&limit=50&begin=1672531200000This retrieves the 50 most recent transactions on Ethereum and Polygon after January 1, 2023, for the specified address.
Understanding the Response Format
Each API response includes a structured array of transaction records and a cursor for pagination.
Key Response Fields
transactionList[]: Array of transaction objects.chainIndex: Identifier for the blockchain (e.g.,eth).txHash: Unique transaction hash.iType: Transaction type:0: Outer-layer native coin transfer1: Inner contract-based native coin transfer2: Token transfer (e.g., ERC-20)
methodId: Smart contract function called.nonce: Sequence number of sender’s transactions.txTime: Timestamp in Unix milliseconds.from[]: Input addresses and amounts.to[]: Output addresses and amounts.tokenAddress,amount,symbol: Token details.txFee: Transaction fee paid.txStatus: Status (success,fail,pending).hitBlacklist: Boolean flag indicating if involved address is blacklisted.tag: Deprecated field; previously used for labeling malicious addresses (e.g., phishing, scam contracts).
cursor: Token for fetching the next page of results.
Sample Use Case: Fraud Detection
By checking the hitBlacklist flag and reviewing transaction patterns (e.g., frequent small transfers to many addresses), security teams can identify potential scams or compromised wallets—enabling proactive risk mitigation.
👉 See how blockchain APIs can help detect risky transactions in real time.
Frequently Asked Questions (FAQ)
What is an address dimension query used for?
An address dimension query retrieves all on-chain activities linked to a specific wallet. It's commonly used in wallet apps, forensic analysis, compliance tools, and DeFi platforms to monitor balances, trace fund flows, or audit user interactions.
Can I query both native coins and tokens at once?
Yes. If you leave the tokenAddress parameter empty or omit it, the API returns transactions involving both the chain’s native currency (like ETH) and any ERC-20/BEP-20 tokens sent or received by the address.
How far back can I retrieve transaction history?
There is no fixed limit—the API accesses full node data archives. However, performance depends on the time range and volume of transactions. Using begin and end parameters with pagination ensures smooth retrieval over long periods.
Is there rate limiting on this API?
Yes. To maintain system stability, usage is subject to fair-access policies based on subscription tiers. Developers should implement caching and batch requests where possible to optimize throughput.
How do I handle multi-signature wallet transactions?
The response handles multi-sig transactions by listing all input (from) and output (to) addresses separated by commas within the respective arrays. The structure remains consistent, allowing automated parsing regardless of wallet type.
What does a "pending" transaction status mean?
A pending status indicates the transaction has been broadcast but not yet confirmed on-chain. Your application should periodically recheck until it transitions to success or fail.
Practical Applications Across Industries
- DeFi Platforms: Integrate real-time balance updates and transaction feeds into user interfaces.
- Compliance & AML Tools: Monitor for exposure to blacklisted addresses or high-risk behaviors.
- Analytics Dashboards: Visualize user activity, inflow/outflow trends, and asset distribution.
- Wallet Services: Power non-custodial wallet features with reliable history sync across chains.
Developers can combine this API with others—such as balance lookup or NFT inventory endpoints—to build full-featured Web3 experiences.
👉 Start building smarter dApps with seamless blockchain data integration.
Final Thoughts
Accessing transaction history by address is more than just viewing a list of trades—it's about unlocking insights from public ledger data. With powerful filtering, cross-chain support, and detailed metadata, the address dimension query API becomes a cornerstone of modern Web3 infrastructure.
As blockchain adoption grows, so does the need for reliable, scalable APIs that turn raw on-chain data into actionable intelligence. Whether you're debugging smart contracts or building the next generation of financial tools, mastering these capabilities gives you a significant edge.
Core Keywords: address dimension query, transaction history API, on-chain data lookup, blockchain wallet API, Web3 developer tools, multi-chain transaction tracking, real-time blockchain data, wallet analytics