Get Transaction Status for Single-Chain Swaps

Learn how to retrieve the final transaction status of a single-chain swap using transaction hash (txhash) via OKX DEX API.

API Endpoint

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

Request Parameters

Parameter	Type	Required	Description
`chainIndex`	String	Yes	Unique chain identifier (e.g., `1` for Ethereum). Supported chains
`chainId`	String	Yes	(Deprecated) Alternative chain identifier.
`txHash`	String	Yes	Transaction hash from an OKX DEX API swap.
`isFromMyProject`	Boolean	No	Set `true` to filter transactions under your API key. Default: `false`.

👉 Optimize your DEX transactions with OKX's powerful API suite

Response Parameters

Parameter	Type	Description
`chainIndex`	String	Chain identifier.
`chainId`	String	(Deprecated) Chain identifier.
`txHash`	String	Transaction hash.
`height`	String	Block height of the transaction.
`txTime`	String	Unix timestamp (ms) of transaction time.
`status`	String	`pending`/`success`/`fail`.
`txType`	String	Transaction type: `Approve`, `Wrap`, `Unwrap`, or `Swap`.
`fromAddress`	String	Sender's wallet address.
`dexRouter`	String	Smart contract interaction address.
`toAddress`	String	Recipient's address.
`fromTokenDetails`	Array	Details of the swapped token:
> `symbol`	String	Token symbol.
> `amount`	String	Amount in smallest units (e.g., wei).
> `tokenAddress`	String	Token contract address.
`toTokenDetails`	Array	Details of the received token:
> `symbol`	String	Token symbol.
> `amount`	String	Received amount in smallest units.
> `tokenAddress`	String	Token contract address.
`referalAmount`	String	Referral bonus amount.
`errorMsg`	String	Error message (if failed).
`gasLimit`	String	Gas limit set for the transaction.
`gasUsed`	String	Actual gas consumed (in smallest units).
`gasPrice`	String	Gas price per unit.
`txFee`	String	Total fee paid in chain's native currency.

Example Request

curl -X GET "https://web3.okx.com/api/v5/dex/aggregator/history?chainIndex=1&chainId=1&txHash=0x123...abc"

Example Response

{
  "chainIndex": "1",
  "chainId": "1",
  "txHash": "0x123...abc",
  "height": "15348921",
  "txTime": "1657823045000",
  "status": "success",
  "txType": "Swap",
  "fromAddress": "0x456...def",
  "dexRouter": "0x789...ghi",
  "toAddress": "0x012...jkl",
  "fromTokenDetails": [
    {
      "symbol": "ETH",
      "amount": "1000000000000000000",
      "tokenAddress": "0xEeeeeEeeeEeEee..."
    }
  ],
  "toTokenDetails": [
    {
      "symbol": "USDC",
      "amount": "1500000000",
      "tokenAddress": "0xa0b86991c6218b36..."
    }
  ],
  "gasUsed": "21000",
  "gasPrice": "50000000000",
  "txFee": "0.00105"
}

👉 Explore advanced DEX trading strategies with OKX

FAQs

How long does it take to get transaction status?

Transaction status updates in near-real-time, typically within 2-3 block confirmations.

What if my transaction shows "pending" for too long?

This usually indicates network congestion. Check the blockchain explorer for gas fees or consider speeding up the transaction.

Can I track cross-chain swaps with this API?

No, this endpoint only supports single-chain transactions. For cross-chain swaps, use OKX's Bridge API.

Why is `chainId` marked as deprecated?

The ecosystem is transitioning to standardized chainIndex values. Update your integration accordingly.

How do I handle failed transactions?

Check the errorMsg field for details. Common issues include insufficient gas or slippage tolerance being exceeded.

Is historical data available through this API?

Yes, you can query transactions as far back as the blockchain's history allows.