Understanding a user’s asset positions across decentralized finance (DeFi) protocols is essential for effective portfolio management, risk assessment, and yield optimization. The DeFi API by OKX Web3 provides developers and financial platforms with a powerful tool to retrieve detailed user position data from specific protocols. This guide dives into how to use the Query User's Position List Based on Protocol endpoint effectively, including request structure, response interpretation, and real-world applications.
This API endpoint allows you to fetch a comprehensive list of a user’s asset holdings—such as staked tokens, liquidity pool deposits, and vault investments—on a given DeFi protocol across multiple blockchain networks.
Whether you're building a portfolio tracker, yield optimizer, or analytics dashboard, this API delivers structured, real-time insights into user positions with minimal latency.
👉 Discover how to integrate real-time DeFi position tracking into your application
How the API Works
The endpoint operates via a POST request to:
https://web3.okx.com/api/v5/defi/user/asset/platform/detailIt requires specific parameters in the request body to identify the protocol and wallet addresses being queried. In return, it delivers a detailed breakdown of all active positions held by the user(s) on that protocol.
Required Request Parameters
To make a successful call, include the following in your JSON request body:
analysisPlatformId(String, required): The unique identifier for the DeFi protocol (e.g., Aave, Uniswap).walletAddressList(Array, required): A list of user wallet addresses you want to query. Each entry must include:chainId: The public blockchain ID (e.g., Ethereum mainnet = 1).walletAddress: The actual wallet address (e.g., 0x...).
These parameters ensure precise targeting of cross-chain user portfolios within a specific protocol context.
Understanding the Response Structure
The API returns a structured JSON object containing network-level and asset-level details about user positions.
Key Response Fields
networkHoldVoList: An array listing all blockchain networks where the user holds positions.network: Name of the network (e.g., Ethereum).chainId: Corresponding chain ID.platformName: Name of the DeFi protocol.analysisPlatformId: Protocol ID used in the request.platformLogo: URL to the protocol’s logo image.platformUrl: Official website of the protocol.
Within each network, you’ll find:
investTokenBalanceVoList: A list of individual investment positions.investType: Type of investment:1– Save (e.g., money market deposits)2– Pool (liquidity pools)3– Farm (yield farming)4– Vaults (automated yield strategies)5– Stake (staking)
tokenSymbol: Ticker symbol of the invested asset (e.g., USDC).tokenLogo: URL to the token’s logo.coinAmount: Amount of tokens invested.currencyAmount: Value of the investment in USD.tokenPrecision: Decimal precision of the token.tokenAddress: Smart contract address of the token.network: Network on which the position exists.totalValue: Total USD value of all positions under this network and protocol.
This granular data enables advanced use cases like performance tracking, risk exposure analysis, and automated rebalancing.
👉 Unlock full DeFi portfolio visibility with seamless API integration
Practical Use Cases
Portfolio Aggregation Tools
Developers can build multi-protocol portfolio dashboards that pull position data from various DeFi platforms using this API. By aggregating positions across chains and protocols, users gain a holistic view of their DeFi holdings without manual tracking.
Risk Monitoring Systems
Financial institutions and institutional investors can monitor concentration risks. For example, if a large portion of a user’s portfolio is locked in high-risk farms or volatile vaults, alerts can be triggered based on investType and currencyAmount.
Yield Optimization Bots
Automated yield farming bots can use this data to compare returns across protocols. By analyzing current positions (investType, tokenSymbol, currencyAmount), they can suggest or execute migrations to higher-yielding opportunities.
Tax and Compliance Reporting
With accurate records of asset amounts and values in USD (currencyAmount), this API supports automated tax reporting tools that calculate capital gains, income from staking/farming, and cost basis adjustments.
Core Keywords
To align with search intent and improve discoverability, the following keywords have been naturally integrated throughout this article:
- DeFi API
- user position list
- protocol asset tracking
- blockchain portfolio API
- Web3 wallet integration
- cross-chain position data
- DeFi portfolio tracker
- OKX Web3 API
These terms reflect common queries from developers, fintech builders, and DeFi enthusiasts seeking reliable tools for managing decentralized assets.
Frequently Asked Questions
Q: Can I query multiple wallets at once?
A: Yes. The walletAddressList parameter accepts an array of wallet addresses, allowing batch queries for multiple users or multi-address portfolios under one request.
Q: Is there rate limiting on this API?
A: While specific limits depend on your access tier, most endpoints support high-frequency calls suitable for real-time dashboards. Always check OKX’s official documentation for current throttling policies.
Q: Does this API support testnets?
A: Yes, as long as the chainId corresponds to a supported network—both mainnets and select testnets are available depending on platform coverage.
Q: How up-to-date is the position data?
A: Data is refreshed in near real-time based on blockchain confirmations and protocol indexing. Delays are typically under a minute for major chains.
Q: Can I retrieve historical position data?
A: This endpoint provides current snapshots. For historical tracking, you’ll need to store responses over time or leverage additional analytics services integrated with OKX Web3.
Q: What happens if a user has no positions on the specified protocol?
A: The response will return an empty investTokenBalanceVoList array for that network, indicating zero holdings—ideal for detecting inactive accounts or unused strategies.
👉 Access real-time DeFi position data with a single API call
Final Thoughts
The ability to programmatically retrieve a user’s position list based on protocol opens doors for innovation in DeFi analytics, wealth management, and automated investing. With clean response formatting, robust parameter control, and support for multi-wallet, cross-chain queries, this OKX Web3 DeFi API endpoint stands out as a reliable solution for developers building next-generation financial tools.
By leveraging structured data like investment type, token value in USD, and network-specific holdings, you can create intuitive interfaces that empower users to understand and optimize their DeFi portfolios like never before.
Whether you're integrating into an existing platform or launching a new product, this API delivers accuracy, scalability, and speed—all critical factors in today’s fast-moving decentralized ecosystem.