> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/user-position-data/batchportfoliostates.md).

# batchPortfolioStates

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

{% hint style="info" %}

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

{% endhint %}

## POST Request

<table><thead><tr><th width="163.06915283203125">Field</th><th width="135.80908203125">Type</th><th width="471.56585693359375">Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"batchPortfolioStates"</code></td></tr><tr><td><code>users</code></td><td>array</td><td>Array of Ethereum addresses</td></tr><tr><td><code>dex</code></td><td>string</td><td>(Optional) Perp DEX name. Omit for native DEX (default). Use a specific dex name (e.g., <code>"xyz"</code>) to fetch that dex only, or <code>"ALL_DEXES"</code> to fetch clearinghouse state across all dexes (native + all HIP-3 dexes) in one request.</td></tr></tbody></table>

### Limits

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

{% tabs %}
{% tab title="cURL" %}

```bash
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"
    ]
  }'
```

{% endtab %}

{% tab title="Python" %}

```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())
```

{% endtab %}

{% tab title="Javascript" %}

```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);
}
```

{% endtab %}
{% endtabs %}

***

## 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                                            |

<details>

<summary>Response</summary>

```json
{
  "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"
  ]
}
```

</details>

<details>

<summary>Response ALL_DEXES</summary>

```json
{
  "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": []
}
```

</details>

<details>

<summary>userAbstraction values</summary>

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)                                                             |

</details>