Get Transaction Status | API Reference

Understanding the status of a blockchain transaction is crucial for developers building decentralized applications, especially when integrating cross-chain or single-chain swaps. This guide dives deep into how to retrieve the final transaction status of a swap using the txhash via the OKX DEX API. Whether you're debugging, verifying user transactions, or building a real-time dashboard, this endpoint provides all the critical data you need.

We’ll walk through the request structure, parameters, response fields, and practical use cases—ensuring you can seamlessly integrate and interpret transaction data with confidence.

How to Retrieve Transaction Status Using txHash

The Get Transaction Status API endpoint allows developers to fetch detailed information about a specific swap transaction on a supported blockchain. By providing the transaction hash (txHash) and chain identifier, you can monitor whether a swap is pending, successful, or failed.

This is particularly useful in environments where user experience depends on accurate, real-time feedback—such as decentralized exchanges (DEXs), portfolio trackers, or automated trading bots.

👉 Check live transaction status with powerful Web3 tools

Request Endpoint

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

This secure, public endpoint returns structured JSON data containing full transaction metadata.

Required and Optional Request Parameters

To successfully query a transaction, you must include specific parameters. Here's what’s needed:

🔹 `chainIndex` (String, Required)

A unique identifier for the blockchain network. For example:

1 = Ethereum
56 = BNB Smart Chain
137 = Polygon

For a complete list of supported chains, refer to the official chain index documentation.

🔹 `chainId` (String, Required – Deprecated Soon)

An alternative chain identifier following EIP-155 standards. Note: This field will be deprecated in future versions. Developers are encouraged to use chainIndex for long-term compatibility.

🔹 `txHash` (String, Required)

The transaction hash generated when a swap was initiated via the OKX DEX API. This 64-character hexadecimal string uniquely identifies the transaction on-chain.

🔘 `isFromMyProject` (Boolean, Optional)

Use this flag to filter results:

Set to true to verify if the transaction was initiated under your current API key.
Set to false or omit to retrieve any public transaction processed by OKX DEX API.

This adds an extra layer of security and traceability for projects managing multiple integrations.

Understanding the Response Parameters

Once the request is processed, the API returns a comprehensive JSON object detailing every aspect of the transaction. Below is a breakdown of each response field.

📦 Core Transaction Data

chainIndex: Confirms which chain the transaction occurred on.
chainId: Legacy identifier; included for backward compatibility.
txHash: The same hash provided in the request—useful for correlation.
height: Block number where the transaction was confirmed.
txTime: Timestamp in Unix milliseconds (e.g., 1712083200000 = April 2025).
status: Current state:
- pending: Transaction is still being confirmed.
- success: Swap completed successfully.
- fail: Transaction reverted or encountered an error.
txType: Action type: Approve, Wrap, Unwrap, or Swap.

🧾 Address Information

fromAddress: Wallet address initiating the swap.
toAddress: Destination address receiving swapped tokens.
dexRouter: Smart contract address used to execute the swap.

💱 Token Swap Details

`fromTokenDetails`

An array containing details about the input token:

symbol: Ticker symbol (e.g., ETH, USDT).
amount: Amount sent in base units (e.g., wei).
tokenAddress: Contract address. Use 0xEeeeeEeeeEeEeeEeEeEeeEeEeeEeeeeEeeeeEeeeE for native tokens like ETH.

`toTokenDetails`

Details of the output token:

symbol: Received token symbol.
amount: Amount received in base units.
tokenAddress: Contract address of the destination token.

⚙️ Fee and Gas Metrics

These values help assess cost efficiency and network congestion:

gasLimit: Maximum gas allowed for the transaction.
gasUsed: Actual gas consumed (in base unit).
gasPrice: Price per gas unit paid (e.g., in gwei on Ethereum).
txFee: Total transaction fee in the native currency (e.g., ETH, BNB).

❗ Error Handling

errorMsg: If status is fail, this field contains a descriptive error (e.g., "Insufficient liquidity").
referalAmount: Referral incentive amount, if applicable.

Practical Use Cases

Real-Time Swap Tracking Dashboard

Developers can build UIs that poll this endpoint periodically to show users:

Live confirmation progress
Final execution price
Gas cost breakdown
Success/failure alerts

Automated Reconciliation Systems

Finance teams or audit tools can use this API to:

Match on-chain activity with internal records
Flag failed transactions for manual review
Calculate average fees per chain

Bot Monitoring & Recovery Logic

Trading bots can implement retry logic:

If status === "fail" and errorMsg === "Slippage exceeded", rebroadcast with adjusted settings.
Use isFromMyProject=true to filter only bot-generated trades.

👉 Explore advanced transaction monitoring features

Frequently Asked Questions (FAQ)

Q: What’s the difference between chainIndex and chainId?
A: chainIndex is OKX’s internal standardized ID system. chainId follows Ethereum’s EIP-155 standard but will be deprecated soon. Always prefer chainIndex.

Q: Can I check transactions not made through my API key?
A: Yes—by omitting isFromMyProject or setting it to false, you can query any transaction processed by OKX DEX API.

Q: How often should I poll this endpoint?
A: For optimal performance, poll once every 10–15 seconds during active confirmation. Avoid excessive polling to prevent rate limiting.

Q: Why do some fields show base units instead of human-readable amounts?
A: To maintain precision across blockchains, amounts are returned in the smallest denomination (e.g., wei). Convert using 10^decimals.

Q: Is there a rate limit for this API?
A: Yes—standard rate limits apply based on your API key tier. Check your usage dashboard to avoid throttling.

Q: How soon after submission can I query a transaction?
A: You can query immediately after broadcast. If not found, it may still be propagating—wait a few seconds before retrying.

Sample Request & Response

While actual examples are not included here due to formatting constraints, typical usage involves sending an HTTP GET request with query parameters:

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

Expected response includes structured JSON with all relevant fields populated according to the transaction state.

👉 Access full API documentation and test endpoints instantly

Best Practices for Integration

Always validate status before proceeding—never assume success based on broadcast alone.
Use webhooks or event listeners where possible to reduce polling overhead.
Log errorMsg and txHash for debugging failed transactions.
Normalize token amounts using known decimals for display purposes.
Monitor gas metrics over time to optimize future transactions.

By leveraging this API effectively, developers gain full visibility into swap operations—enhancing reliability, transparency, and user trust in their applications.