How to Query a User's Full Portfolio Holdings Across Networks

·

In the rapidly evolving world of decentralized finance (DeFi), gaining a comprehensive view of a user’s asset holdings across multiple blockchains and platforms is essential for both developers and financial applications. The User Portfolio Holdings API enables seamless access to aggregated wallet data, delivering real-time insights into cross-chain assets. This guide explores how to use this powerful API endpoint to retrieve a user's full portfolio, including supported chains, platform integrations, and investment details.

Whether you're building a portfolio tracker, a risk analysis tool, or a DeFi dashboard, understanding how to efficiently query and interpret multi-network holdings can significantly enhance your application’s functionality and user experience.

👉 Discover how to integrate real-time portfolio tracking into your app today.

Understanding the Portfolio Holdings API

The User Portfolio Holdings API allows developers to request a complete list of a user’s asset positions across various blockchain networks and DeFi platforms. By submitting one or more wallet addresses, the API returns structured data detailing each platform where the user holds assets, including dollar amounts, network-specific balances, and integration status with OKX DeFi services.

This API is particularly valuable in multi-chain environments where users often distribute their assets across Ethereum, Binance Smart Chain, Solana, and other ecosystems. With growing fragmentation in Web3 wallets and protocols, having a unified view of holdings becomes critical for accurate financial reporting and investment decision-making.

Key Features

API Endpoint and Request Structure

To retrieve a user’s full portfolio, send a POST request to the following endpoint:

https://web3.okx.com/api/v5/defi/user/asset/platform/list

This endpoint expects a JSON payload containing wallet address information for one or more chains.

Required Request Parameters

The request body must include the walletAddressList array, which contains objects with two required fields:

You can submit multiple wallet addresses across different chains in a single call, making it efficient for applications managing diverse user portfolios.

Example Request Body

{
  "walletAddressList": [
    {
      "chainId": "ethereum",
      "walletAddress": "0x742d35Cc6634C0532925a3b8D4C7d2f7D3cBf9F6"
    },
    {
      "chainId": "bsc",
      "walletAddress": "0x8f3cf7ad23cd3cadbd9735aff958023239c6a063"
    }
  ]
}

This structure allows developers to batch requests and minimize API calls while retrieving comprehensive data.

👉 Learn how to streamline multi-chain portfolio queries with advanced tools.

Interpreting the Response Data

The API returns a structured JSON response containing detailed information about the user’s holdings across DeFi platforms.

Top-Level Response Field

Each item in this array includes:

Network-Level Breakdown

Within each platform entry, the networkBalanceVoList provides granular insights per blockchain:

This layered structure enables developers to build rich visualizations such as:

Practical Use Cases

1. Portfolio Dashboards

Financial dashboards can leverage this API to display real-time net worth summaries across all connected wallets and chains. Users benefit from consolidated views without manually checking each protocol.

2. Risk Assessment Tools

Lending platforms or insurance protocols can analyze exposure across DeFi ecosystems by identifying concentration risks on unsupported or volatile platforms.

3. Investment Analytics

Wealth management apps can track performance trends, calculate returns across multiple protocols, and recommend rebalancing strategies based on current holdings.

4. KYC & Compliance Reporting

Institutional services can generate audit-ready reports showing full asset disclosures across public blockchains.

Frequently Asked Questions (FAQ)

Q: Can I query holdings for multiple users at once?
A: Yes, as long as you have their wallet addresses and include them in the walletAddressList, you can retrieve data for multiple users in a single request—provided they are within your authorized scope.

Q: Is there a rate limit for this API?
A: While specific limits depend on your API key tier, standard usage allows frequent polling. For high-frequency applications, consider caching responses or using webhooks if available.

Q: How up-to-date is the balance data?
A: Balances are refreshed in near real-time based on blockchain events and indexer updates. There may be slight delays during periods of high network congestion.

Q: What happens if a wallet has no holdings on any platform?
A: The API will return an empty walletIdPlatformList array, indicating no active DeFi positions were detected.

Q: Are NFTs or ERC-20 tokens included in the response?
A: The current response focuses on fungible token balances and staked/invested positions. NFT holdings are not included in this endpoint but may be available via other APIs.

Q: Does this API support ENS or other name resolution?
A: No—only raw wallet addresses (e.g., 0x...) are accepted. You must resolve ENS names or other identifiers before making the request.

Best Practices for Integration

👉 Start building smarter DeFi analytics with powerful portfolio insights.

By leveraging the User Portfolio Holdings API, developers gain access to deep, actionable insights into cross-chain DeFi activity. Whether you're empowering individual investors or building institutional-grade tools, this endpoint provides the foundation for transparent, accurate, and scalable financial applications in Web3.

Core keywords naturally integrated: DeFi API, portfolio holdings, cross-chain assets, wallet balance, blockchain data, user portfolio, Web3 API, crypto portfolio tracker.