Query User Protocol-Level Position List

In the rapidly evolving world of decentralized finance (DeFi), accessing accurate, real-time data about user positions across protocols is essential for developers, analysts, and institutional investors. One of the most powerful tools in this space is the "Query User Protocol-Level Position List" API, which enables seamless retrieval of asset holdings by protocol and user wallet address. This guide walks you through everything you need to know about this critical Web3 API endpoint — from structure and parameters to practical use cases and integration tips.

Whether you're building a portfolio tracker, conducting on-chain analytics, or developing a wallet-as-a-service solution, understanding how to leverage this API efficiently can significantly enhance your application’s functionality and user experience.

What Is the Protocol-Level Position API?

The User Protocol-Level Position List API returns detailed information about a user's asset holdings within a specific DeFi protocol. Unlike generic balance checks, this endpoint provides structured insights into investment types such as liquidity pools, staking, yield farming, and lending positions — all broken down by chain and token.

This makes it ideal for applications that require granular visibility into user engagement with DeFi ecosystems.

👉 Discover how easy it is to integrate powerful DeFi data into your platform.

Endpoint Overview

HTTP Method: POST
API URL: https://web3.okx.com/api/v5/defi/user/asset/platform/detail

This secure endpoint requires authentication and returns structured JSON responses containing asset-level details across multiple blockchains.

Request Parameters

To retrieve accurate position data, the following parameters must be included in the request body:

• analysisPlatformId (String, required)
  The unique identifier for the DeFi protocol (e.g., Uniswap, Aave) you want to query.

• walletAddressList (Array, required)
  A list of wallet addresses whose positions you wish to analyze. Each entry includes:

  • chainId (String, required): The blockchain network ID (e.g., Ethereum Mainnet = "1").
  • walletAddress (String, required): The public wallet address (e.g., "0x...").

These parameters allow precise targeting of cross-chain user behavior across supported networks.

Response Structure

The API returns a comprehensive JSON object with nested fields detailing user positions. Here's a breakdown of the key components:

Top-Level Response Fields

• networkHoldVoList (Array)
  Contains per-network holding data, including:

  • network: Human-readable network name (e.g., "Ethereum").
  • chainId: Chain identifier.
  • platformName: Name of the DeFi protocol.
  • analysisPlatformId: Protocol ID used in the request.
  • platformLogo: URL to the protocol’s logo.
  • platformUrl: Official website link for the protocol.

Investment Details: investTokenBalanceVoList

Each entry represents a specific investment position:

• investType (String)
  Indicates the type of investment:

  • 1: Deposit (e.g., savings)
  • 2: Liquidity Pool
  • 3: Mining/Farming
  • 4: Vault (aggregated yield strategies)
  • 5: Staking

• Token Information:

  • tokenSymbol: Ticker symbol (e.g., USDC).
  • tokenLogo: URL to token icon.
  • coinAmount: Quantity held.
  • currencyAmount: Value in USD.
  • tokenPrecision: Decimal precision (e.g., 6 for USDT).
  • tokenAddress: Smart contract address.
  • network: Associated blockchain.
• totalValue (String)
  Total USD value of all positions within that network and protocol.

This level of detail supports advanced analytics like risk exposure assessment, yield tracking, and cross-protocol comparison.

Common Use Cases

Portfolio Aggregation Tools

Wallet dashboards and portfolio trackers use this API to display real-time DeFi positions across chains and protocols, giving users a unified view of their investments.

Risk Monitoring & Compliance

Financial institutions leverage this data to assess creditworthiness, monitor collateral health, or detect overexposure to volatile assets.

Automated Investment Bots

Yield optimizers and automated vaults analyze position data to rebalance strategies dynamically based on market conditions.

👉 See how integrating real-time DeFi position data can power next-gen financial tools.

SEO Keywords Identified

Core keywords naturally integrated throughout this article:

• DeFi API
• Web3 API
• user position list
• protocol-level holdings
• wallet-as-a-service
• blockchain data API
• on-chain analytics
• DeFi portfolio tracker

These terms reflect high-intent search queries related to developer tools in the decentralized finance ecosystem.

Frequently Asked Questions (FAQ)

Q: Which blockchains are supported by this API?

A: The API supports major EVM-compatible chains including Ethereum, BSC, Polygon, Arbitrum, Optimism, and others. Chain support may vary based on the protocol being queried.

Q: Can I query multiple wallets at once?

A: Yes — simply include multiple wallet objects in the walletAddressList array. This allows batch processing for institutional-grade analysis.

Q: Is there rate limiting on this endpoint?

A: Yes, usage is subject to API rate limits designed to ensure system stability. Developers should implement exponential backoff strategies for high-frequency requests.

Q: How up-to-date is the data?

A: Position data is refreshed in near real-time using on-chain event indexing. Delays are typically under 30 seconds depending on network congestion.

Q: Does this API support historical position tracking?

A: While the current endpoint provides snapshot data, historical trends can be derived by storing periodic responses. For full time-series analysis, consider pairing with blockchain explorers or dedicated indexing services.

Q: Are testnet environments supported?

A: Yes — use the appropriate chainId for test networks (e.g., Goerli, Mumbai). Ensure your analysisPlatformId corresponds to testnet versions of protocols.

Best Practices for Integration

1. Validate Inputs Early
   Always verify chainId, walletAddress, and analysisPlatformId formats before sending requests to avoid errors.
2. Handle Variable Precision
   Use tokenPrecision when formatting display values to prevent incorrect decimal representation.
3. Cache Responsibly
   Since on-chain data changes frequently, set short TTLs (Time-to-Live) for cached responses — ideally between 15–60 seconds.
4. Secure Your API Keys
   Never expose credentials in client-side code. Use backend proxies for production deployments.
5. Monitor Schema Changes
   Subscribe to API changelogs to stay informed about updates to response structures or deprecated fields.

Final Thoughts

The Query User Protocol-Level Position List API is a cornerstone tool for any application interacting with DeFi ecosystems. By offering structured access to complex on-chain positions — from liquidity pools to staking vaults — it empowers developers to build smarter, more responsive financial services in the Web3 space.

With clear documentation, robust parameter support, and scalable performance, this endpoint exemplifies what modern blockchain APIs should deliver.

👉 Start building smarter DeFi applications today with reliable, high-performance API access.