How to Check Your DEX Transaction Status Using an API

For anyone interacting with decentralized exchanges (DEX), confirming the final status of a transaction is a critical step. Whether you're a developer integrating swap functionalities or a user tracking your trades, understanding how to query transaction status efficiently can save time and reduce uncertainty.

This guide walks you through the essential elements of checking transaction status on a DEX using an API, covering the request process, parameters, response data, and common troubleshooting tips.

Understanding Transaction Status Queries

When you initiate a token swap on a DEX, your transaction is broadcast to the blockchain. However, the final outcome—success, failure, or pending—can take time to confirm. Querying via API provides a programmatic way to fetch this status reliably.

Key details you can retrieve include:

• Current status (pending, success, or fail)
• Block height and timestamp
• Gas used and transaction fee
• Token amounts and addresses involved

This is especially useful for developers building applications that need to display real-time transaction updates or reconcile transaction histories.

API Request Endpoint and Parameters

To check the status of a transaction, you need to make a GET request to the appropriate API endpoint. Below is a breakdown of the required and optional parameters.

Request URL:

GET https://web3.okx.com/api/v5/dex/aggregator/history

Request Parameters:

Interpreting the API Response

The response from the API includes detailed information about the transaction. Here’s what each field represents:

👉 Explore more strategies for tracking blockchain transactions

Step-by-Step Request Example

To query a transaction, you need the transaction hash (txHash) and the correct chainIndex for the blockchain involved. For instance, to check a transaction on Ethereum:

1. Identify your txHash (e.g., 0x1234...abcd).
2. Set chainIndex to 1 for Ethereum.
3. Optionally, set isFromMyProject to true to validate the transaction against your project.

Here’s how a typical request might look:

GET https://web3.okx.com/api/v5/dex/aggregator/history?chainIndex=1&txHash=0x1234...abcd

Response Example

A successful API response returns a JSON object containing the transaction details. Below is a simplified example:

{
  "chainId": "1",
  "txHash": "0x1234...abcd",
  "height": "15678900",
  "txTime": "1678881123000",
  "status": "success",
  "txType": "Swap",
  "fromAddress": "0x5678...ef01",
  "dexrouter": "0x9abc...3456",
  "toAddress": "0xdef0...6789",
  "fromTokenDetails": [
    {
      "symbol": "ETH",
      "amount": "1000000000000000000",
      "tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
    }
  ],
  "toTokenDetails": [
    {
      "symbol": "USDC",
      "amount": "1850000000",
      "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
  ],
  "gasUsed": "21000",
  "gasPrice": "50000000000",
  "txFee": "0.00105"
}

This response indicates a successful swap of 1 ETH for 1850 USDC, along with details about gas and fees.

Frequently Asked Questions

How long does a transaction stay in 'pending' status?
Transaction pending time varies based on network congestion. It can take from a few seconds to several minutes. If it remains pending for too long, it might eventually drop from the mempool.

What should I do if the transaction fails?
Check the errorMsg field in the response for details. Common reasons include insufficient gas, slippage tolerance too low, or liquidity issues. You may need to adjust parameters and resubmit.

Can I check transactions from any wallet?
The API can query any transaction made through the DEX API. However, using the isFromMyProject parameter lets you filter transactions associated with your specific API key.

Why is 'chainId' being deprecated?
The chainId parameter is being phased out in favor of chainIndex, which provides a more standardized way to identify blockchains. Always use chainIndex for new integrations.

What units are used for token amounts and gas?
All amounts are returned in the smallest unit of the blockchain (e.g., wei for Ethereum). You may need to convert them to readable decimals using the token’s decimal value.

Is historical transaction data available via this API?
This API is designed for checking the status of recent transactions. For deep historical data, consider using a blockchain explorer or specialized archive node.

Best Practices for Developers

When integrating this API, keep these tips in mind:

• Always handle pending states in your UI to keep users informed.
• Use the isFromMyProject flag to add an extra layer of validation for your application.
• Implement error handling for failed transactions and display helpful messages to users.
• Cache responses where appropriate to reduce redundant calls and improve performance.

👉 Get advanced methods for API integration and debugging

Understanding how to query transaction statuses ensures smoother user experiences and more robust applications. By leveraging this API, you can build more reliable and transparent DeFi solutions.