> ## 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 clearinghouse state, spot balances, and account-abstraction mode in a single request.

> [card] Credit Cost
>
> 1 per call

> [card] Processing
>
> Realtime

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](https://goldrush.dev/docs/pricing-calculator.md?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fportfolio-state).

> [!NOTE]
>
> * GoldRush-native composite — not part of the original Hyperliquid API. It bundles three upstream calls into one round-trip: [clearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/clearinghouse-state.md), [spotClearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/spot-clearinghouse-state.md), 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.

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

**type** `string` *required* (default: portfolioState)

Always `"portfolioState"`.

**user** `string` *required*

Ethereum address (0x-prefixed, 42 characters).

**dex** `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.

### Example

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

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

**clearinghouseState** `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).

**spotClearinghouseState** `object`

The wallet's spot balances.

**properties**

**balances** `array\<object\>`

One entry per held spot token.

**properties**

**coin** `string`

Coin symbol.

**token** `int`

Token index.

**total** `string`

Total balance (decimal string).

**hold** `string`

Amount on hold (decimal string).

**entryNtl** `string`

Entry notional (decimal string).

**userAbstraction** `string`

The wallet's account-abstraction mode. One of:

**values**

**unifiedAccount** `string`

Single balance per asset across all DEXes; all cross-margin positions share collateral.

**portfolioMargin** `string`

Portfolio margin — a single portfolio unifying eligible assets with borrowing / LTV.

**disabled** `string`

Abstraction disabled — separate perp and spot balances.

**default** `string`

Default mode.

**dexAbstraction** `string`

DEX abstraction mode (legacy, being discontinued).

### `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"
}
```

## Related endpoints

> [card] [batchClearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/batch-clearinghouse-state.md)
>
> fetch perpetuals account state for up to 50 wallets in a single request.

> [card] [batchSpotClearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/batch-spot-clearinghouse-state.md)
>
> fetch spot account balances for up to 50 wallets in a single request.

> [card] [clearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/clearinghouse-state.md)
>
> fetch a single user's perpetuals account state by wallet address.

> [card] [spotClearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid-info/spot-clearinghouse-state.md)
>
> fetch a single user's spot account balances by wallet address.

See all Hyperliquid endpoints: [Overview hub](https://goldrush.dev/docs/goldrush-hyperliquid/overview.md) · [Info API reference](https://goldrush.dev/docs/goldrush-hyperliquid/info-api/overview.md)

*Last reviewed: 2026-08-17*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.