batchPortfolioStates

Get clearinghouse states for perp and spot of multiple users in a single request.

Get clearinghouse states for perp and spot of multiple users in a single request.

💧New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.

POST Request

Field	Type	Description
type	string	Must be "batchPortfolioStates"
users	array	Array of Ethereum addresses
dex	string	(Optional) Perp DEX name. Omit for native DEX (default). Use a specific dex name (e.g., "xyz") to fetch that dex only, or "ALL_DEXES" to fetch clearinghouse state across all dexes (native + all HIP-3 dexes) in one request.

Limits

You can query 500 users at once. Note that with the ALL_DEXES field passed that limit is 100 users.

cURL

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batchPortfolioStates",
    "users": [
      "0x0000000000000000000000000000000000000001",
      "0x0000000000000000000000000000000000000002"
    ]
  }'

Python

import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'batchPortfolioStates',
        'users': [
            '0x0000000000000000000000000000000000000001',
            '0x0000000000000000000000000000000000000002'
        ]
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Javascript

import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'batchPortfolioStates',
        users: [
            '0x0000000000000000000000000000000000000001',
            '0x0000000000000000000000000000000000000002'
        ]
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}

---

Response Fields

Field	Type	Description
successful_states	array	Array of [address, portfolioState] tuples
successful_states[n][0]	string	User address
successful_states[n][1].clearinghouseState	object	Perp clearinghouse state (marginSummary, crossMarginSummary, assetPositions, time)
successful_states[n][1].spotClearinghouseState	object	Spot clearinghouse state containing balances array
successful_states[n][1].userAbstraction	string	Account abstraction mode
failed_wallets	array	Array of addresses that failed to fetch

Response

{
  "successful_states": [
    [
      "0x0000000000000000000000000000000000000001",
      {
        "clearinghouseState": {
          "marginSummary": {..},
          "crossMarginSummary": {..},
          "assetPositions": [..],
          "time": 1234567890123
        },
        "spotClearinghouseState": {
          "balances": [
            {
              "coin": "USDC",
              "token": 0,
              "total": "0.02221591",
              "hold": "0.0",
              "entryNtl": "0.0"
            }
          ]
        },
        "userAbstraction": "unifiedAccount"
      }
    ]
  ],
  "failed_wallets": [
    "0x0000000000000000000000000000000000000003"
  ]
}

Response ALL_DEXES

{
  "successful_states": [
    [
      "0x0000000000000000000000000000000000000001",
      {
        "clearinghouseState": {
          "native": {
            "marginSummary": {..},
            "crossMarginSummary": {..},
            "assetPositions": [..],
            "time": 1234567890123
          },
          "xyz": {
            "marginSummary": {..},
            "crossMarginSummary": {..},
            "assetPositions": [..],
            "time": 1234567890123
          }
        },
        "spotClearinghouseState": {
          "balances": [
            {
              "coin": "USDC",
              "token": 0,
              "total": "0.02221591",
              "hold": "0.0",
              "entryNtl": "0.0"
            }
          ]
        },
        "userAbstraction": "unifiedAccount"
      }
    ]
  ],
  "failed_wallets": []
}

userAbstraction values

The user's account abstraction mode. Possible values:

Value	Description
"unifiedAccount"	Unified account mode - single balance per asset across all DEXes, all cross margin positions share collateral
"portfolioMargin"	Portfolio margin mode - single portfolio unifying eligible assets with borrowing/LTV
"disabled"	Abstraction disabled - separate perp and spot balances
"default"	Default mode
"dexAbstraction"	DEX abstraction mode (legacy, being discontinued)