This API reference provides detailed information on how to retrieve recent transaction data for a specific token from decentralized exchanges (DEXs). It is designed for developers building applications that require real-time or historical trade data.
API Endpoint
The endpoint for accessing recent trades data is a GET request to the following URL:
https://web3.okx.com/api/v5/dex/market/trades
Required Request Parameters
To successfully call this API, you must include the following parameters in your request.
| Parameter | Type | Required | Description |
|---|---|---|---|
chainIndex | String | Yes | The unique identifier for the blockchain network. For example, 1 represents Ethereum. |
tokenContractAddress | String | Yes | The contract address of the token. For EVM-compatible chains, ensure the address is in all lowercase. |
Optional Request Parameters
You can use these parameters to refine the data returned by your API call.
| Parameter | Type | Required | Description |
|---|---|---|---|
after | String | No | Used for pagination. Returns records that are older than the provided trade ID. |
limit | String | No | The number of trade records to return per request. The default is 100, and the maximum allowed is 500. |
Understanding the Response
A successful API call returns a list of recent trades with the following data points for each transaction.
| Parameter | Type | Description |
|---|---|---|
id | String | A unique identifier for the trade. |
chainIndex | String | The unique identifier for the blockchain where the trade occurred. |
tokenContractAddress | String | The contract address of the token that was traded. |
txHashUrl | String | A URL to view the on-chain transaction hash for the trade. |
userAddress | String | The wallet address that authorized the transaction. |
dexName | String | The name of the decentralized exchange where the trade was executed. |
poolLogoUrl | String | A URL to the logo image of the liquidity pool involved. |
type | String | The type of trade, either buy or sell. |
changedTokenInfo | String | Information about the tokens that were exchanged. |
> amount | String | The amount of the token that was exchanged in the trade. |
> tokenSymbol | String | The symbol of the token that was exchanged. |
> tokenContractAddress | String | The contract address of the token that was exchanged. |
price | String | The price of the token at the time of the trade. |
volume | String | The total USD value of the trade. |
time | String | The timestamp of the trade, in Unix milliseconds. |
isFiltered | String | Indicates if the trade was filtered for price calculations. 0 for not filtered, 1 for filtered. |
How to Make a Request
Construct your API call by appending the required and any optional parameters to the base URL. Ensure all parameters are correctly formatted to avoid errors.
Example API Call Structure:https://web3.okx.com/api/v5/dex/market/trades?chainIndex=1&tokenContractAddress=0x382bb369d343125bfb2117af9c149795c6c65c50&limit=100
Sample Response
A typical response will be a JSON object containing an array of trade objects, each populated with the data fields described in the response parameters table.
{
"code": "0",
"msg": "",
"data": [
{
"id": "12345",
"chainIndex": "1",
"tokenContractAddress": "0x382bb369d343125bfb2117af9c149795c6c65c50",
"txHashUrl": "https://etherscan.io/tx/0x...",
"userAddress": "0xabcd...1234",
"dexName": "Uniswap V3",
"poolLogoUrl": "https://example.com/logo.png",
"type": "buy",
"changedTokenInfo": "...",
"price": "1500.50",
"volume": "3050.25",
"time": "1640995200000",
"isFiltered": "0"
}
]
}Common Use Cases and Applications
This API is fundamental for developers creating:
- Portfolio Trackers: To display a user's recent trading activity and current holdings.
- Trading Bots: To analyze recent market activity and execute trades based on specific conditions.
- Analytics Dashboards: To chart trading volume, price movements, and liquidity trends for specific tokens.
- Research Tools: To gather historical trade data for market analysis and strategy backtesting.
For developers looking to integrate real-time market data into their applications, this API provides a reliable stream of on-chain trade information 👉 explore more strategies.
Frequently Asked Questions
What is the chainIndex parameter?
The chainIndex is a unique number that identifies a specific blockchain network. It ensures your API request queries the correct ledger. For instance, a chainIndex of 1 always refers to the Ethereum mainnet.
Why does my request return an error?
Common errors are caused by incorrect parameter formatting. Double-check that the tokenContractAddress is a valid, all-lowercase string and that the chainIndex corresponds to a supported network. Also, ensure you are not exceeding the limit of 500 records.
How does pagination work with the after parameter?
The after parameter is used to retrieve older trades. To paginate, take the id of the last trade from your current response and use it as the after value in your next request to fetch the previous batch of records.
What does isFiltered mean?
A trade marked as filtered (isFiltered=1) is typically excluded from official price and K-line calculations. This often happens with very large or very small trades that could skew the perceived market price, ensuring the data remains representative of typical market activity.
Can I get trades for any token?
Yes, as long as you have the correct contract address for the token and it has been traded on a DEX integrated with this API. You must also use the appropriate chainIndex for the blockchain on which the token resides.
How current is the trade data returned by this API?
The API provides data on recent transactions. The latency is typically very low, offering near real-time insights into market activity as trades are confirmed on the blockchain.