Query Transaction Status | API Reference for DEX, Swap, and Exchange Integration

In the fast-evolving world of decentralized finance (DeFi), real-time transaction monitoring is essential for developers, traders, and platforms relying on seamless blockchain interactions. The Query Transaction Status API enables users to retrieve the final status of a cross-chain or single-chain swap by transaction hash (txHash), ensuring transparency and reliability in decentralized exchange operations.

Whether you're integrating automated trading tools, building a wallet interface, or managing smart contract executions, this API delivers accurate, structured data about transaction outcomes across supported blockchains.

How the Query Transaction Status API Works

This API endpoint allows developers to fetch detailed information about a specific transaction initiated via the OKX DEX Aggregator. By providing the txHash, you can verify whether a swap, wrap, unwrap, or approval action was successful, failed, or remains pending.

It plays a crucial role in user experience — imagine confirming instantly whether a token swap went through without manually checking block explorers.

👉 Discover how to integrate real-time transaction verification into your app today.

Endpoint Overview

HTTP Method: GET
Request URL: https://web3.okx.com/api/v5/dex/aggregator/history

This secure, authenticated endpoint returns structured JSON responses containing full transaction metadata, including status, timestamps, token details, gas usage, and error messages if applicable.

Request Parameters

To query a transaction, include the following parameters in your request:

• chainIndex (String, Required)
  Unique identifier for the blockchain. For example:

  • 1 = Ethereum
  • 56 = BNB Smart Chain
    View all supported chains in the official documentation.
• chainId (String, Required)
  Also identifies the chain but is deprecated. Use chainIndex for future-proof integrations.
• txHash (String, Required)
  The transaction hash generated when a swap is executed using the OKX DEX API. This must be a valid hexadecimal string.

• isFromMyProject (Boolean, Optional)

  • If set to true, the system checks only transactions associated with the current API key.
  • If false or omitted, it queries any transaction initiated through the OKX DEX API.

🔐 Ensure your API key has proper permissions and is securely stored. Never expose it in client-side code.

Response Structure

The API returns a comprehensive object detailing every aspect of the transaction:

• chainId (String)
  Blockchain identifier (e.g., "1" for Ethereum).
• txHash (String)
  Transaction hash used in the query.
• height (String)
  Block number where the transaction was included.
• txTime (String)
  Unix timestamp in milliseconds indicating when the transaction was confirmed.

• status (String)
  Current state of the transaction:

  • pending: Still being processed
  • success: Completed successfully
  • fail: Execution failed (see errorMsg)

• txType (String)
  Type of operation:

  • Approve
  • Wrap
  • Unwrap
  • Swap
• fromAddress, toAddress, dexrouter (String)
  Respective sender, receiver, and DEX router contract addresses involved.

• fromTokenDetails (Array)
  Input token information:

  • symbol: Token symbol (e.g., ETH)
  • amount: Amount in minimal unit (e.g., wei for Ethereum)
  • tokenAddress: Contract address (0xEeeee...EEeE for native ETH)

• toTokenDetails (Array)
  Output token details:

  • Same structure as above — symbol, amount, contract address
• referalAmount (String)
  Referral commission paid (if applicable).

• Gas-related fields:

  • gasLimit, gasUsed, gasPrice, txFee — All returned in smallest denomination (e.g., wei)
• errorMsg (String, optional)
  Descriptive message if the transaction failed (e.g., "Insufficient balance", "Slippage exceeded").

Example Use Case: Building a Real-Time Swap Tracker

Imagine you're developing a DeFi dashboard that shows live swap statuses for users. When a user initiates a token exchange:

1. Your backend captures the txHash.
2. You call the Query Transaction Status API every 5–10 seconds.

3. Once the status changes from pending to success, you update the UI with:

   • Final received amount
   • Gas fee spent
   • Confirmation time

If the status becomes fail, you display:

• The exact reason from errorMsg
• A suggestion to retry with adjusted slippage or balance check

This proactive feedback loop enhances trust and reduces support queries.

👉 See how leading apps maintain high reliability with instant status updates.

Frequently Asked Questions (FAQ)

Q: Can I use this API to track transactions not initiated by my application?

Yes. By default (isFromMyProject=false or not provided), you can query any transaction processed via the OKX DEX API. Set it to true only if you want to restrict results to transactions under your API key.

Q: What does “minimum unit” mean for token amounts?

Blockchain networks often represent token values in their smallest divisible units. For example:

• ETH uses wei (1 ETH = 10¹⁸ wei)
• BNB uses gwei
  Always convert these values before displaying them to end users.

Q: Why might a transaction remain “pending” for a long time?

A pending status usually means:

• Low gas price causing network delays
• Network congestion
• Transaction still propagating

If it stays pending beyond expected confirmation windows (e.g., >30 mins on Ethereum), consider resubmitting with higher gas.

Q: How soon after submission can I query a transaction?

You can query immediately. However, if the transaction hasn't been broadcasted or indexed yet, the response may return empty or not found. Retry after a few seconds using exponential backoff.

Q: Is there a rate limit for this API?

While specific limits aren’t disclosed publicly, excessive requests may trigger throttling. Best practice: implement caching and avoid polling more than once every 5–10 seconds per transaction.

Q: Can I use this for cross-chain swaps?

Yes! As long as the cross-chain swap was initiated via the OKX DEX Aggregator and you have the correct txHash and chainIndex, you can track its status on either source or destination chain — depending on which leg you're verifying.

Core Keywords for SEO & Search Intent

To align with common developer searches and improve discoverability, key terms naturally integrated throughout include:

• DEX API
• swap API
• transaction status API
• query txHash
• blockchain transaction lookup
• crypto exchange API
• on-chain swap verification
• API reference for DeFi

These reflect high-intent queries from developers integrating decentralized trading functionality into dApps, wallets, or analytics platforms.

Final Tips for Developers

• Always validate status and check errorMsg before assuming success.
• Use txTime to calculate confirmation latency.
• Monitor gasUsed vs gasLimit to optimize future transactions.
• Combine this endpoint with price quote APIs for full lifecycle tracking.

With robust error handling and timely status checks, your application can deliver a smooth, professional-grade DeFi experience.

👉 Start testing the transaction status API with live data now.