> Use the canonical URL for citations. For the complete Predict API documentation index, fetch https://docs.staging.trypredict.com/llms.txt.

# Portfolio, balances, and fills

> Build Predict outcome positions from Hyperliquid spot balances and reconcile open orders, fills, fees, limits, ledger updates, builders, and subaccounts.

HIP-4 positions are token balances, not perpetual positions. Query `spotClearinghouseState` and select entries whose `coin` is `+<encoding>`.

For a normalized public view, use Predict's account REST endpoints for positions, current orders, fills, activity, cashflows, statistics, PnL, volume, and fees, or subscribe to the matching [realtime channels](/guides/guides/realtime). Use the direct Hyperliquid reads below when you need venue-native balances, bounded history, role, limit, or builder state.

| Balance field  | Meaning                        |
| -------------- | ------------------------------ |
| `total`        | Total token balance            |
| `hold`         | Amount reserved by open orders |
| `total - hold` | Available balance              |
| `entryNtl`     | Tracked entry notional         |

Join the token name back to the Predict outcome and label with the identifier mapping. Do not query a perpetual `clearinghouseState` and expect HIP-4 positions.

## Account reads

| `type`                        | Purpose                                                    | Retention or behavior                                       |
| ----------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------- |
| `openOrders`                  | Current orders                                             | Snapshot                                                    |
| `frontendOpenOrders`          | Orders plus display fields                                 | Snapshot                                                    |
| `orderStatus`                 | One order by order ID or client ID                         | Returns `unknownOid` when absent                            |
| `historicalOrders`            | Recent terminal and open order records                     | At most 2,000                                               |
| `userFills`                   | Recent executions                                          | At most 2,000                                               |
| `userFillsByTime`             | Executions in a time range                                 | At most 2,000 per response and 10,000 most recent available |
| `userNonFundingLedgerUpdates` | Deposits, withdrawals, transfers, and other ledger changes | Time-bounded pages return at most 500 records or blocks     |
| `userFees`                    | Fee tier and rates                                         | Address scoped                                              |
| `userRateLimit`               | Action allowance and usage                                 | Address scoped                                              |
| `subAccounts`                 | Accounts controlled by a master                            | Query with master address                                   |
| `userRole`                    | Master, agent, vault, subaccount, or missing               | High request weight                                         |
| `approvedBuilders`            | Approved builder addresses                                 | Address scoped                                              |
| `maxBuilderFee`               | Approved ceiling for one builder                           | Returned in tenths of a basis point                         |

Account reads use the master or subaccount address. Passing an agent-wallet address normally returns empty state because an agent signs but does not own the balances.

## Durable history

Hyperliquid's live account endpoints are bounded. Persist order intents, responses, order updates, fills, and ledger updates if your product promises a complete archive. On reconnect, query the latest HTTP snapshot and fill any time range before resuming stream processing.