Skip to main content
The Account Adapter (adapter.account) gives you read access to a wallet’s state on HIP-4 prediction markets. You can fetch open positions (held outcome tokens), the last 30 days of trade activity, raw spot balances including USDC, and currently resting orders. You can also subscribe to live position updates, which the adapter delivers by polling: the first result right away, then every 10 seconds. All methods accept a wallet address parameter, so you can query any account without authentication.

fetchPositions(address)

Returns a wallet’s open HIP-4 positions. Positions are derived from the spot clearinghouse state - each non-zero outcome token balance becomes a PredictionPosition. Midpoint prices and the event list are fetched in parallel to populate the prices and the event and market names.

Parameters

string
required
The wallet address to query.

Return type

Promise<PredictionPosition[]>
string
required
The outcome ID extracted from the token coin string.
string
required
The balance coin as Hyperliquid reports it in spot balances (e.g. "+5160"). parseSideCoin() parses it.
string
required
Side name from sideSpecs, as Hyperliquid sends it (e.g. "Yes", "Hypurr", "template:Yes").
string
Readable side name. Template sides are rendered from Hyperliquid’s template registry ("template:Yes" reads "Yes"); other sides repeat outcomeName. Use this for display. Available from 1.3.0.
string
required
Number of outcome tokens held, formatted to 6 decimal places.
string
required
Average cost per token (entryNtl / totalShares), formatted to 6 decimal places.
string
required
The side’s live midpoint price from allMids, or "0" when it has none. Spot balances name side coins +<coin> while mids use #<coin>, and the SDK maps one to the other. Releases before 1.3.0-beta.0 returned "0" for outcome positions.
string
required
(currentPrice - avgCost) * shares, formatted to 6 decimal places.
string
required
Maximum payout if the outcome resolves in your favor. Equal to shares (each token pays out 1 USDC).
string
required
Always "active" in the current implementation. No settlement status check is performed.
string
required
Title of the event the market belongs to, from adapter.events.fetchEvents().
string
Readable event title, from the event’s parsedTitle. Available from 1.3.0.
string
required
Question text of the market, from the same event list.
string
Readable question text, from the market’s parsedQuestion. Available from 1.3.0.
fetchPositions reads the first 200 events (fetchEvents({ limit: 200 })). For a position in a market outside those events, or if the event fetch fails, the event and market names are empty strings. Look the market up with adapter.events.fetchEvent() in that case.

Example


fetchActivity(address)

Returns the wallet’s trade fills on HIP-4 outcome coins from the last 30 days, newest first. Fills on other markets are filtered out. Hyperliquid returns at most 2,000 fills per request (before filtering), so a very active wallet may get less than 30 days of history.

Parameters

string
required
The wallet address to query.

Return type

Promise<PredictionActivity[]>
string
required
Trade ID from the Hyperliquid tid field.
string
required
Always "trade" in the current implementation.
string
The outcome ID extracted from the fill’s coin.
string
Raw coin string (e.g. "#5160").
string
"buy" or "sell".
string
Execution price.
string
Fill size.
string
Never populated in the current implementation.
number
required
Fill time in milliseconds.

Example


fetchBalance(address)

Returns the raw spot clearinghouse balances for a wallet, including USDC and all outcome tokens. Use this when you need the full picture of what the wallet holds, not just open prediction positions.

Parameters

string
required
The wallet address to query.

Return type

Promise<Array<{ coin: string; total: string; hold: string }>>: one entry per spot balance.

Example


fetchOpenOrders(address)

Returns the currently resting (unfilled) orders for a wallet across all Hyperliquid markets, not only HIP-4. Use the oid field to build cancel requests.

Parameters

string
required
The wallet address to query.

Return type

A promise for an array of open orders. The SDK keeps these fields from Hyperliquid’s frontendOpenOrders response:

Example


subscribePositions(address, cb)

Polls the wallet’s positions and delivers each result to your callback. The first poll runs right away; each later poll starts 10 seconds after the previous one finishes. Each poll calls fetchPositions, which requests spotClearinghouseState and allMids and reads the event list (cached for 30 seconds). Errors during a poll are silently swallowed and the polling continues.

Parameters

string
required
The wallet address to poll.
(positions: PredictionPosition[]) => void
required
Callback invoked after each successful poll. Receives the current PredictionPosition[].

Return type

Unsubscribe - a () => void function. Call it to stop the polling loop.
The polling interval is fixed at 10 seconds. The first delivery arrives as soon as the first poll completes, so you don’t need a separate fetchPositions() call before subscribing.

Example