portfolioState | Hyperliquid API Docs

Get clearinghouse state, spot balances, and account abstraction mode for a single Hyperliquid user in one request. Supports both native DEX queries and ALL_DEXES aggregation.

Get perpetual clearinghouse state, spot balances, and account abstraction mode for a single user in one request.

Authenticate by including your Dwellir API key in the URL path: https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info.

When to Use This Endpoint

The portfolioState endpoint is useful when you need a full portfolio view without coordinating multiple requests yourself.

Portfolio Dashboards — Load perp state, spot balances, and account mode in one round trip
Risk Systems — Combine derivative exposure with spot collateral and account abstraction mode
Wallet Experiences — Build one portfolio summary card from a single response
Multi-DEX Views — Use dex: "ALL_DEXES" to inspect the native DEX and all operational HIP-3 DEXs together

By default, portfolioState returns the main Hyperliquid perpetuals DEX state, spot balances, and account abstraction mode for a single user. To target a specific HIP-3 market, pass a DEX name returned by perpDexs. To aggregate across the native DEX and all operational HIP-3 markets, use dex: "ALL_DEXES".

`dex` value	Returns
(omitted)	Native Hyperliquid perp state plus spot balances and account mode
Any DEX name returned by `perpDexs`	The named HIP-3 DEX state plus spot balances and account mode
`"ALL_DEXES"`	A DEX map of perp state for the native DEX plus every operational HIP-3 market, alongside top-level spot balances and account mode

`ALL_DEXES` Request

JSON

{
  "type": "portfolioState",
  "user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f",
  "dex": "ALL_DEXES"
}

`ALL_DEXES` Response Shape

JSON

{
  "clearinghouseState": {
    "native": {
      "marginSummary": {
        "accountValue": "555.13644",
        "totalMarginUsed": "0.0",
        "totalNtlPos": "0.0",
        "totalRawUsd": "555.13644"
      },
      "crossMarginSummary": {
        "accountValue": "555.13644",
        "totalMarginUsed": "0.0",
        "totalNtlPos": "0.0",
        "totalRawUsd": "555.13644"
      },
      "crossMaintenanceMarginUsed": "0.0",
      "withdrawable": "555.13644",
      "assetPositions": [],
      "time": 1776448114752
    },
    "<dex_name>": {
      "marginSummary": {
        "accountValue": "0.0",
        "totalMarginUsed": "0.0",
        "totalNtlPos": "0.0",
        "totalRawUsd": "0.0"
      },
      "crossMarginSummary": {
        "accountValue": "0.0",
        "totalMarginUsed": "0.0",
        "totalNtlPos": "0.0",
        "totalRawUsd": "0.0"
      },
      "crossMaintenanceMarginUsed": "0.0",
      "withdrawable": "0.0",
      "assetPositions": [],
      "time": 1776448114649
    }
  },
  "spotClearinghouseState": {
    "balances": [
      {
        "coin": "USDC",
        "token": 0,
        "total": "12.27568764",
        "hold": "0.0",
        "entryNtl": "0.0"
      }
    ]
  },
  "userAbstraction": "default"
}

For ALL_DEXES, clearinghouseState becomes an object keyed by DEX name while spotClearinghouseState and userAbstraction remain at the top level. The native DEX always appears under the "native" key. Additional keys are dynamic and correspond to operational HIP-3 DEX names returned by perpDexs, so discover them instead of hardcoding a single example value.

What `portfolioState` Composes

portfolioState is equivalent to combining these three requests:

clearinghouseState — perp positions and margin data
spotClearinghouseState — spot balances
userAbstraction — account abstraction mode

When dex is "ALL_DEXES", the endpoint reuses the ALL_DEXES clearinghouse aggregation and keeps the spot and abstraction data at the top level.

Common Use Cases

1. Build a Portfolio Overview

JavaScript

async function getPortfolioOverview(userAddress) {
  const response = await fetch('https://api-hyperliquid-mainnet-info.n.dwellir.com/<API-KEY>/info', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      type: 'portfolioState',
      user: userAddress,
      dex: 'ALL_DEXES'
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  const portfolio = await response.json();
  return {
    abstraction: portfolio.userAbstraction,
    perpDexes: Object.keys(portfolio.clearinghouseState),
    spotBalances: portfolio.spotClearinghouseState.balances.length
  };
}

2. Merge Spot and Perp State for UI Rendering

JavaScript

async function getDashboardState(userAddress) {
  const portfolio = await queryEndpoint({
    type: 'portfolioState',
    user: userAddress
  });

  return {
    accountValue: parseFloat(portfolio.clearinghouseState.marginSummary.accountValue),
    withdrawable: parseFloat(portfolio.clearinghouseState.withdrawable),
    balances: portfolio.spotClearinghouseState.balances,
    accountMode: portfolio.userAbstraction
  };
}

clearinghouseState — Get perpetual account state, including ALL_DEXES support
spotClearinghouseState — Get spot account balances
userAbstraction — Get account abstraction mode only
batchClearinghouseStates — Batch query multiple users

Query full Hyperliquid portfolio state with Dwellir's HyperCore Info Endpoint. Get your API key →

portfolioState - HyperCore Info Endpoint