Get History by Address: Transaction & On-chain Data Query via Web3 API

Understanding blockchain transaction history is essential for developers, analysts, and crypto enthusiasts alike. Whether you're auditing wallet activity, tracking token movements, or building decentralized applications, accessing accurate on-chain data is crucial. This guide dives into how to retrieve transaction history by address using a robust Web3 API—providing structured, real-time insights into wallet activities across multiple chains.

With the right tools, querying blockchain data doesn't have to be complex. By leveraging a powerful Wallet-as-a-Service (WaaS) API, you can effortlessly pull detailed transaction records sorted in chronological order—enabling deeper analysis and faster integration into your applications.

How to Query Transaction History by Address

The core functionality revolves around a simple yet powerful GET request that returns all transactions associated with a specific wallet address. The endpoint retrieves data in descending time order—showing the most recent transactions first—making it ideal for dashboards, analytics platforms, or security monitoring systems.

🔗 API Endpoint

GET https://web3.okx.com/api/v5/wallet/post-transaction/transactions-by-address

This RESTful endpoint allows seamless integration into web and mobile applications, supporting both single-chain and cross-chain queries.

👉 Discover how easy it is to integrate blockchain transaction lookup into your app.

Request Parameters Explained

To tailor your query and retrieve precise results, several optional and required parameters are available:

• address (String, Required)
  The wallet address for which you want to fetch transaction history.
• chainIndex (String, Optional)
  Specifies the blockchain network (e.g., ETH=3). If not provided, the API may default to querying across multiple supported chains.
• tokenAddress (String, Optional)
  Filter results by a specific token contract address. Leave empty to include mainnet currency transfers (like ETH), or omit entirely to retrieve all transaction types.
• begin, end (String, Optional)
  Unix timestamps (in milliseconds) defining the time range for the query. If neither is specified, the system fetches transactions up to the current moment.
• cursor (String, Optional)
  Used for pagination. Pass the cursor from a previous response to fetch the next batch of results.

• limit (String, Optional)
  Controls the number of records returned:

  • Up to 20 per request for single-chain queries.
  • Up to 100 when querying across multiple chains.
  • Defaults to 20 if not specified.

These parameters make the API flexible enough for everything from lightweight user interfaces to enterprise-grade forensic analysis.

Understanding the Response Structure

Each successful request returns a structured JSON response containing a list of transactions and metadata for pagination.

Key Response Fields

• transactionList (Array)
  An array of individual transaction objects.

  Inside each transaction:

  • chainIndex: Identifier of the blockchain where the transaction occurred.
  • txHash: Unique transaction hash for verification on explorers.

  • iType: Indicates transaction type:

    • 0: Outer main chain coin transfer
    • 1: Contract internal main chain coin transfer
    • 2: Token transfer (ERC-20, etc.)
  • methodId: Function call identifier within smart contracts.
  • nonce: Sequential number of the sender’s transaction.
  • txTime: Timestamp in Unix milliseconds.
  • from.address, from.amount: Sender(s) and input amount(s).
  • to.address, to.amount: Recipient(s) and output amount(s).
  • tokenAddress, symbol, amount: Token details involved in the transfer.
  • txFee: Network fee paid for the transaction.
  • txStatus: Can be success, fail, or pending.
  • hitBlacklist, tag: Security flags indicating if the address is linked to phishing or vulnerable contracts (note: tag is deprecated)
• cursor (String)
  Pagination token for retrieving the next page of results.

This rich dataset enables advanced use cases such as fraud detection, compliance reporting, and portfolio tracking.

Practical Use Cases

1. Wallet Activity Monitoring

Developers can build real-time alerts or visual timelines showing incoming and outgoing transactions for user wallets.

2. Multi-Chain Portfolio Trackers

By omitting the chainIndex, applications can aggregate activity across EVM-compatible networks—ideal for users managing assets on Ethereum, BSC, Polygon, and more.

3. Security Audits

Leverage hitBlacklist and transaction patterns to identify suspicious behavior or interactions with known risky addresses.

4. Token Flow Analysis

Using tokenAddress filtering, track how a specific ERC-20 token moves through wallets—useful for project teams and market analysts.

👉 See how top Web3 apps streamline on-chain data retrieval with a few lines of code.

Frequently Asked Questions (FAQ)

Q: Can I query historical transactions from two years ago?

Yes. As long as you provide the correct Unix timestamps in the begin and end parameters, you can retrieve older transaction data—subject to blockchain availability and API retention policies.

Q: What does iType = 1 mean compared to iType = 0?

iType = 0 refers to direct native coin transfers between external accounts. iType = 1 indicates a native coin transfer occurring inside a smart contract execution (e.g., during a swap or deposit).

Q: How do I handle pagination with large result sets?

Use the cursor field returned in each response. Include it in your next request to continue fetching subsequent pages without duplication.

Q: Is there a rate limit on this API?

While not specified here, most production APIs enforce rate limits. Always refer to official documentation or developer portals for throttling rules and authentication requirements.

Q: Can I filter only successful transactions?

Not directly via a parameter—but you can filter results client-side using the txStatus field (success, fail, pending) after receiving the response.

Q: Why is the tag field marked as deprecated?

It means this field may be removed in future versions. Avoid relying on it in new integrations; instead, focus on hitBlacklist for security checks.

Best Practices for Integration

• Always validate input addresses using checksums where applicable.
• Cache responses when appropriate to reduce redundant calls.
• Handle pending transactions carefully—they may change status.
• Monitor API updates for changes in deprecation notices or new features.

For developers building decentralized identity tools, DeFi dashboards, or NFT marketplaces, this API serves as a foundational layer for transparent and reliable blockchain interaction.

👉 Start building smarter Web3 experiences with instant access to on-chain insights.

Core Keywords

• Transaction history by address
• On-chain data query
• Web3 API
• Wallet API
• Blockchain transaction lookup
• EVM transaction types
• Multi-chain query
• Wallet-as-a-Service (WaaS)

By integrating these keywords naturally throughout this guide, we ensure strong alignment with search intent while maintaining readability and technical accuracy.

Whether you're debugging user transactions or analyzing market trends, having instant access to structured on-chain data transforms how you interact with blockchain ecosystems. With scalable APIs like this one, the complexity of decentralized networks becomes accessible—one address at a time.