Portfolio State

/v2/user/portfolio-state returns everything you need to display a trader’s full account state in a single response: perp positions, spot balances, open orders, and account abstraction mode.

When to use this

User profile pages in a trading dashboard — show perp PnL, spot holdings, and open orders without chaining multiple calls
Copy trading dashboards fetching the complete state of every leader you track
Login flows that need to populate a user’s full account in one request
Risk monitors pulling a complete picture of an account in a single round-trip

Instead of making 4 separate requests to clearinghouseState, spotClearinghouseState, openOrders, and userAbstraction, you make one.

Single user

curl -H "x-api-key: YOUR_KEY" \
  "https://hyper.polynode.dev/v2/user/portfolio-state?user=0x711d5ee8df7f0075f5393f7c9197248e961542b1"

Query parameters

Parameter	Type	Required	Description
`user` (or `address`)	string	yes	Wallet address (checksum or lowercase)
`key`	string	no	API key. Can also be passed via `x-api-key` header.

Example response

{
  "abstraction": "default",
  "openOrders": [
    {
      "coin": "BTC",
      "limitPx": "47927.0",
      "oid": 337312365621,
      "origSz": "0.00095",
      "reduceOnly": true,
      "side": "B",
      "sz": "0.00095",
      "timestamp": 1772587755752
    }
  ],
  "perp": {
    "assetPositions": [
      {
        "position": {
          "coin": "BTC",
          "entryPx": "69111.0",
          "leverage": {"type": "cross", "value": 5},
          "liquidationPx": "88027.2944556678",
          "marginUsed": "40.81055",
          "maxLeverage": 40,
          "positionValue": "204.05275",
          "cumFunding": {
            "allTime": "-0.080775",
            "sinceChange": "-0.119844",
            "sinceOpen": "-0.079252"
          }
        }
      }
    ],
    "marginSummary": {"...": "..."},
    "withdrawable": "0.0",
    "time": 1776229734000
  },
  "spot": {
    "balances": [
      {"coin": "USDC", "token": 0, "total": "125.45", "hold": "0.0"}
    ]
  }
}

Response fields

Field	Type	Description
`perp`	object	Full clearinghouse state — positions, margin summary, withdrawable. Same shape as HyperLiquid’s `clearinghouseState`.
`spot`	object	Spot token balances. Same shape as `spotClearinghouseState`.
`openOrders`	array	All open resting orders across perp and spot. Same shape as `openOrders`.
`abstraction`	string	Account abstraction mode. `"default"` for standard accounts.

Any sub-field may be null if that part of the user’s state is empty or the underlying query failed.

Batch — up to 2,500 wallets per request

For copy trading platforms and multi-user dashboards, use the batch variant to pull many wallets at once.

curl -X POST \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      "0x711d5ee8df7f0075f5393f7c9197248e961542b1",
      "0xacd89cFCB82Ae1f843467D56b58796bb928C9E1A"
    ]
  }' \
  https://hyper.polynode.dev/v2/batch/portfolio-states

Request body

Field	Type	Required	Description
`users`	string[]	yes	Wallet addresses (max 2,500 per request)
`key`	string	no	API key (optional if passed via header)
`dry`	boolean	no	If true, return stub responses for capacity testing without live queries

Response

Keyed by wallet address. Each value has the same shape as the single-user endpoint.

{
  "0x711d5ee8df7f0075f5393f7c9197248e961542b1": {
    "perp": {"...": "..."},
    "spot": {"...": "..."},
    "openOrders": [],
    "abstraction": "default"
  },
  "0xacd89cFCB82Ae1f843467D56b58796bb928C9E1A": {
    "perp": null,
    "spot": null,
    "openOrders": null,
    "abstraction": null
  }
}

Dry-run mode

Pass "dry": true to get a response with the correct shape but stub values. Useful for building and testing your parser without generating real load.

curl -X POST \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"users":["0x711d5ee8df7f0075f5393f7c9197248e961542b1"],"dry":true}' \
  https://hyper.polynode.dev/v2/batch/portfolio-states

Dry response:

{
  "0x711d5ee8df7f0075f5393f7c9197248e961542b1": {
    "_dry": true,
    "abstraction": null,
    "openOrders": [],
    "perp": {
      "_dry": true,
      "assetPositions": [],
      "marginSummary": {"accountValue": "0.0"}
    },
    "spot": {"_dry": true, "balances": []}
  }
}

Limits

Limit	Value
Max wallets per request	2,500
Body size cap	2 MB

If you need more than 2,500 at a time, use /v2/batch/clearinghouse-states which supports up to 10,000 (perp positions only, no spot or open orders).

Overview

L4 Order Book

Market Data

User Data

DeFi

Discovery

Prediction Markets

Trading

Vaults & Governance

Passthrough

Infrastructure

Additional

When to use this

Single user

Query parameters

Example response

Response fields

Batch — up to 2,500 wallets per request

Request body

Response

Dry-run mode

Limits

​When to use this

​Single user

​Query parameters

​Example response

​Response fields

​Batch — up to 2,500 wallets per request

​Request body

​Response

​Dry-run mode

​Limits

When to use this

Single user

Query parameters

Example response

Response fields

Batch — up to 2,500 wallets per request

Request body

Response

Dry-run mode

Limits