> 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/portfoliostate.md).

# portfolioState

Get clearinghouse state, spot clearinghouse state, and account abstraction mode for a single user in one 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

| Field  | Type   | Description                                                                                                                                                         |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Must be `"portfolioState"`                                                                                                                                          |
| `user` | string | Ethereum address (0x-prefixed, 42 characters)                                                                                                                       |
| `dex`  | string | (Optional) Perp DEX name. Omit for native DEX (default). Use `"ALL_DEXES"` to fetch clearinghouse state across all dexes (native + all HIP-3 dexes) in one request. |

### Usage

This endpoint combines three calls into one:

* `clearinghouseState` - perp positions and margin
* `spotClearinghouseState` - spot balances
* `userAbstraction` - account abstraction mode

{% 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": "portfolioState",
    "user": "0x0000000000000000000000000000000000000000"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'portfolioState',
        'user': '0x0000000000000000000000000000000000000000'
    },
    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: 'portfolioState',
        user: '0x0000000000000000000000000000000000000000'
    }, {
        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                                                                        |
| --------------------------------------------- | ------ | ---------------------------------------------------------------------------------- |
| `clearinghouseState`                          | object | Perp clearinghouse state (marginSummary, crossMarginSummary, assetPositions, time) |
| `spotClearinghouseState`                      | object | Spot clearinghouse state containing balances array                                 |
| `spotClearinghouseState.balances[n].coin`     | string | Coin symbol                                                                        |
| `spotClearinghouseState.balances[n].token`    | int    | Token index                                                                        |
| `spotClearinghouseState.balances[n].total`    | string | Total balance                                                                      |
| `spotClearinghouseState.balances[n].hold`     | string | Amount on hold                                                                     |
| `spotClearinghouseState.balances[n].entryNtl` | string | Entry notional                                                                     |
| `userAbstraction`                             | string | Account abstraction mode (see values below)                                        |

<details>

<summary>Response</summary>

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

</details>

<details>

<summary>Response ALL_DEXES</summary>

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

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