Predict Portfolio and Fills | Predict API Documentation

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