Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypernode-docs.polynode.dev/llms.txt

Use this file to discover all available pages before exploring further.

/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

ParameterTypeRequiredDescription
user (or address)stringyesWallet address (checksum or lowercase)
keystringnoAPI 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

FieldTypeDescription
perpobjectFull clearinghouse state — positions, margin summary, withdrawable. Same shape as HyperLiquid’s clearinghouseState.
spotobjectSpot token balances. Same shape as spotClearinghouseState.
openOrdersarrayAll open resting orders across perp and spot. Same shape as openOrders.
abstractionstringAccount 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

FieldTypeRequiredDescription
usersstring[]yesWallet addresses (max 2,500 per request)
keystringnoAPI key (optional if passed via header)
drybooleannoIf 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

LimitValue
Max wallets per request2,500
Body size cap2 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).