For developers building in the decentralized finance (DeFi) space, accessing accurate and up-to-date product information is crucial. This guide explains how to use the "Query Product List" API endpoint to retrieve a paginated list of investment products based on your specific search criteria. Whether you're analyzing yield opportunities, tracking Total Value Locked (TVL), or integrating DeFi data into your application, this API provides the structured data you need.
API Endpoint Overview
The Query Product List API is a POST endpoint designed to return a filterable list of DeFi products. You can specify various parameters, including network, product type, and sorting preferences, to get precisely the data you require for your analysis or application.
HTTP Method: POST
Endpoint: https://web3.okx.com/api/v5/defi/explore/product/list
Understanding the Request Parameters
To effectively use this API, you must understand the available parameters for filtering and sorting the results.
Required Parameters
simplifyInvestType(String): This parameter filters products by their type. You must provide one of the following code values:100: Stablecoin products101: Single-asset earning products102: Multi-asset earning products103: Yield aggregator (vault) products
network(String): This specifies the blockchain network you want to query (e.g., Ethereum, BNB Smart Chain). You must obtain the valid network names from the relevant network list endpoint.limit(String): This defines the maximum number of product records to return in a single API response, enabling pagination.
Optional Parameters
poolVersion(String): Use this to differentiate between V2 and V3 liquidity pools. The default value is typicallyV2if not specified.platformIds(Array[String]): An array of platform identifiers. This allows you to filter results to show products only from specific protocols or dApps. You need to get valid platform IDs from the protocol list endpoint.sort(Struct): A complex parameter that lets you order the results based on specific properties.orders(Array[Struct]): An array of sorting instructions.direction(String): The sort direction. UseASCfor ascending order orDESCfor descending order.property(String): The field by which to sort. Valid options areTVL(Total Value Locked) orRATE(APY/APR).
tokenIds(Array[String]): An array of token identifiers. Filter the list to only include products that involve these specific tokens. Valid token IDs can be fetched from the token list endpoint.offset(String): Used for pagination. This parameter specifies the starting point within the full list of results from which to begin returning records.
Interpreting the Response Data
A successful API call returns a structured JSON response containing an array of product objects. Each product includes the following key fields:
| Parameter | Description | Data Type |
|---|---|---|
investmentId | A unique identifier for the investment product. | String |
investmentName | The name of the product. | String |
chainId | The identifier of the blockchain the product is on. | String |
rate | The current yield rate offered by the product. | String |
investType | A numeric code indicating the product category (1: Deposit, 2: Liquidity Pool, 3: Mining, 4: Vault, 5: Staking). | String |
platformName | The name of the platform or protocol offering the product. | String |
platformId | The unique identifier for the platform. | String |
rateType | Indicates how the yield is calculated (0 for APY, 1 for APR). | String |
tvl | The Total Value Locked in the product, a key metric for its size and popularity. | String |
underlyingToken | A structure detailing the token used in the product. | Struct |
>isBaseToken | A boolean indicating if the token is the network's base gas token (e.g., ETH). | Boolean |
>tokenContract | The smart contract address of the token. | String |
>tokenSymbol | The ticker symbol of the token (e.g., USDC, WBTC). | String |
total | The total number of products that match your query criteria, useful for pagination. | String |
Practical Use Cases and Implementation
This API is incredibly versatile for developers and analysts. You can use it to:
- Build a comparative dashboard showing yield rates across different protocols.
- Create alert systems for when TVL or APY reaches a certain threshold.
- Feed data into a portfolio tracking application that includes DeFi positions.
- Conduct market research by analyzing the distribution of products across networks and types.
The key to effective implementation is constructing a well-formed request. Start by defining your core filters (simplifyInvestType, network) and then use the optional parameters to narrow down the results to your exact needs. Remember to handle pagination using the limit and offset parameters if you expect more results than a single call can return.
👉 Explore more strategies for API integration
Frequently Asked Questions
What is the difference between APY and APR in the response?
APY (Annual Percentage Yield) includes the effect of compounding interest, giving you the total amount you can earn in a year. APR (Annual Percentage Rate) is a simpler figure that does not account for compounding. The rateType field tells you which calculation method is being used for a given product.
How can I find the correct values for the network parameter?
You need to make a separate API call to the network list endpoint. This will provide you with an array of supported networks and their exact names that are valid for use in the network parameter of this product list query.
Can I filter products by multiple platforms at once?
Yes, the platformIds parameter accepts an array of strings. You can provide multiple platform IDs received from the protocol list endpoint to include products from all of those specified platforms in your results.
What does 'investType' 5 (Staking) refer to?
This typically refers to direct staking of a network's native token to secure the blockchain (e.g., staking ETH or ADA). It is distinct from providing liquidity in a pool or depositing assets into a yield vault.
How often is the data from this API updated?
The update frequency can vary by platform and data point. Metrics like APY and TVL are often updated in near real-time or on a very frequent basis (e.g., every few blocks) to reflect the dynamic nature of DeFi markets.
Is there a way to get a list of all products without any filters?
No, the simplifyInvestType and network parameters are required. You must specify at least a product type and a network to query. To get a broad view, you could make sequential calls for different product types on a major network like Ethereum.