> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# portfolioState | Hyperliquid Info API

> Hyperliquid portfolioState: fetch a wallet's perp state, spot balances, and account-abstraction mode in one request.

<CardGroup cols={2}>
  <Card title="Credit Cost"> 1 per call</Card>
  <Card title="Processing"> Realtime</Card>
</CardGroup>

The Hyperliquid info endpoint with `type: "portfolioState"` is used to fetch a wallet's perp clearinghouse state, spot balances, and account-abstraction mode in a single request.

<Tip>
  Estimate your monthly cost for this API using the [Pricing Calculator](/docs/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fportfolio-state).
</Tip>

<Info>
  * GoldRush-native composite — not part of the original Hyperliquid API. It bundles three upstream calls into one round-trip: <a href="https://goldrush.dev/docs/api-reference/hyperliquid-info/clearinghouse-state" target="_blank" rel="noopener noreferrer">clearinghouseState</a>, <a href="https://goldrush.dev/docs/api-reference/hyperliquid-info/spot-clearinghouse-state" target="_blank" rel="noopener noreferrer">spotClearinghouseState</a>, and `userAbstraction`.
  * Pass `dex` to scope the perp `clearinghouseState` to a single HIP-3 DEX. Pass `dex: "ALL_DEXES"` to return the perp state across the native DEX plus every HIP-3 DEX in one call, keyed by DEX name.
  * `spotClearinghouseState` and `userAbstraction` are DEX-independent and always returned once.
</Info>

Returns a single object bundling a wallet's perp account state (`clearinghouseState`), spot balances (`spotClearinghouseState`), and account-abstraction mode (`userAbstraction`) — the three calls a portfolio view typically needs, in one round-trip.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer <GOLDRUSH_API_KEY>
Content-Type: application/json
```

## Request

<ParamField body="type" type="string" required default="portfolioState">
  Always `"portfolioState"`.
</ParamField>

<ParamField body="user" type="string" required>
  Ethereum address (0x-prefixed, 42 characters).
</ParamField>

<ParamField body="dex" type="string">
  Perp DEX name. Omit for the native DEX (default). Use `"ALL_DEXES"` to fetch the perp `clearinghouseState` across the native DEX plus every HIP-3 DEX in one call.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://hypercore.goldrushdata.com/info \
    -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "portfolioState",
      "user": "0x0000000000000000000000000000000000000000"
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://hypercore.goldrushdata.com/info", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "portfolioState",
      user: "0x0000000000000000000000000000000000000000",
    }),
  });

  const portfolio = await response.json();
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.post(
      "https://hypercore.goldrushdata.com/info",
      headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"},
      json={
          "type": "portfolioState",
          "user": "0x0000000000000000000000000000000000000000",
      },
  )

  portfolio = response.json()
  ```
</CodeGroup>

## Response

An object with three keys — the perp clearinghouse state, spot clearinghouse state, and the account-abstraction mode.

```json theme={null}
{
  "clearinghouseState": {
    "marginSummary": { "accountValue": "…", "totalNtlPos": "…", "totalRawUsd": "…", "totalMarginUsed": "…" },
    "crossMarginSummary": { "…": "…" },
    "assetPositions": [],
    "time": 1234567890123
  },
  "spotClearinghouseState": {
    "balances": [
      { "coin": "USDC", "token": 0, "total": "0.02221591", "hold": "0.0", "entryNtl": "0.0" }
    ]
  },
  "userAbstraction": "unifiedAccount"
}
```

### Field descriptions

<ResponseField name="clearinghouseState" type="object">
  The wallet's perp account state — identical to the standalone `clearinghouseState` response (`marginSummary`, `crossMarginSummary`, `assetPositions`, `time`). Scoped to `dex` when supplied; a per-DEX object when `dex: "ALL_DEXES"` (see below).
</ResponseField>

<ResponseField name="spotClearinghouseState" type="object">
  The wallet's spot balances.

  <Expandable title="properties">
    <ResponseField name="balances" type="array<object>">
      One entry per held spot token.

      <Expandable title="properties">
        <ResponseField name="coin" type="string">Coin symbol.</ResponseField>
        <ResponseField name="token" type="int">Token index.</ResponseField>
        <ResponseField name="total" type="string">Total balance (decimal string).</ResponseField>
        <ResponseField name="hold" type="string">Amount on hold (decimal string).</ResponseField>
        <ResponseField name="entryNtl" type="string">Entry notional (decimal string).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="userAbstraction" type="string">
  The wallet's account-abstraction mode. One of:

  <Expandable title="values">
    <ResponseField name="unifiedAccount" type="string">Single balance per asset across all DEXes; all cross-margin positions share collateral.</ResponseField>
    <ResponseField name="portfolioMargin" type="string">Portfolio margin — a single portfolio unifying eligible assets with borrowing / LTV.</ResponseField>
    <ResponseField name="disabled" type="string">Abstraction disabled — separate perp and spot balances.</ResponseField>
    <ResponseField name="default" type="string">Default mode.</ResponseField>
    <ResponseField name="dexAbstraction" type="string">DEX abstraction mode (legacy, being discontinued).</ResponseField>
  </Expandable>
</ResponseField>

### `ALL_DEXES` response

When `dex: "ALL_DEXES"` is passed, `clearinghouseState` becomes an object keyed by DEX name — the native DEX under `"native"` plus one key per HIP-3 DEX. `spotClearinghouseState` and `userAbstraction` are unchanged.

```json theme={null}
{
  "clearinghouseState": {
    "native": { "marginSummary": {}, "crossMarginSummary": {}, "assetPositions": [], "time": 1234567890123 },
    "xyz": { "marginSummary": {}, "crossMarginSummary": {}, "assetPositions": [], "time": 1234567890123 }
  },
  "spotClearinghouseState": { "balances": [] },
  "userAbstraction": "unifiedAccount"
}
```

*Last reviewed: 2026-07-30*