Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.outcome.xyz/llms.txt

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

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 USDH, and currently resting orders. You can also subscribe to live position updates, which the adapter delivers by polling every 10 seconds - there is no WebSocket channel for spot balances on Hyperliquid. 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 are fetched in parallel to populate currentPrice and unrealizedPnl. 
const positions = await adapter.account.fetchPositions("0xYourAddress");

​
Parameters

​
address
string
required
The wallet address to query.

​
Return type

Promise<PredictionPosition[]>
​
marketId
string
required
The outcome ID extracted from the token coin string.
​
outcome
string
required
The coin string used for lookups (e.g. "#5160").
​
outcomeName
string
required
Human-readable side name resolved from sideSpecs (e.g. "Yes", "Hypurr"). Use this for display.
​
shares
string
required
Number of outcome tokens held, formatted to 6 decimal places.
​
avgCost
string
required
Average cost per token (entryNtl / totalShares), formatted to 6 decimal places.
​
currentPrice
string
required
Current midpoint price from allMids. "0" when no mid is available.
​
unrealizedPnl
string
required
(currentPrice − avgCost) × shares, formatted to 6 decimal places.
​
potentialPayout
string
required
Maximum payout if the outcome resolves in your favor. Equal to shares (each token pays out 1 USDH).
​
eventStatus
string
required
Always "active" in the current implementation. No settlement status check is performed.
​
eventTitle
string
required
Always "". Positions are not enriched with event metadata in the current implementation.
​
marketQuestion
string
required
Always "". Same reason as eventTitle.
eventTitle and marketQuestion are always empty strings. If you need these values, call adapter.events.fetchEvent() using the marketId and cross-reference the result.

​
Example

const positions = await adapter.account.fetchPositions("0xYourAddress");

for (const pos of positions) {
  console.log(`Outcome: ${pos.outcomeName} (${pos.outcome})`);
  console.log(`  Shares:         ${pos.shares}`);
  console.log(`  Avg cost:       ${pos.avgCost}`);
  console.log(`  Current price:  ${pos.currentPrice}`);
  console.log(`  Unrealized PnL: ${pos.unrealizedPnl}`);
  console.log(`  Max payout:     ${pos.potentialPayout}`);
}

​
fetchActivity(address)

Returns the last 30 days of trade fills for outcome coins held by the wallet. The response is sorted newest-first. Only fills for HIP-4 outcome coins are included - regular spot trades are filtered out. 
const activity = await adapter.account.fetchActivity("0xYourAddress");

​
Parameters

​
address
string
required
The wallet address to query.

​
Return type

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

​
Example

const activity = await adapter.account.fetchActivity("0xYourAddress");

for (const entry of activity) {
  console.log(
    `${new Date(entry.timestamp).toISOString()} | ` +
    `${entry.side} ${entry.size} @ ${entry.price} | ` +
    `coin: ${entry.outcome}`
  );
}

​
fetchBalance(address)

Returns the raw spot clearinghouse balances for a wallet, including USDH and all outcome tokens. Use this when you need the full picture of what the wallet holds, not just open prediction positions. 
const balances = await adapter.account.fetchBalance("0xYourAddress");

​
Parameters

​
address
string
required
The wallet address to query.

​
Return type

Promise<HLSpotClearinghouseState> - an object with a balances array. Each balance entry contains:
FieldTypeDescription
coinstringToken coin string (e.g. "USDH", "#5160")
tokennumberInternal token index
holdstringAmount currently on hold (in open orders)
totalstringTotal balance including held amount
entryNtlstringTotal entry notional (cost basis)

​
Example

const state = await adapter.account.fetchBalance("0xYourAddress");

for (const bal of state.balances) {
  console.log(`${bal.coin}: total=${bal.total} hold=${bal.hold}`);
  // "USDH: total=250.000000 hold=0.000000"
  // "#5160: total=100.000000 hold=0.000000"
}

​
fetchOpenOrders(address)

Returns the currently resting (unfilled) orders for a wallet. Use the oid field to build cancel requests. 
const orders = await adapter.account.fetchOpenOrders("0xYourAddress");

​
Parameters

​
address
string
required
The wallet address to query.

​
Return type

Promise<HLFrontendOrder[]> - each order contains:
FieldTypeDescription
coinstringCoin string (e.g. "#5160")
side"B" | "A""B" = buy, "A" = sell (ask)
limitPxstringLimit price
szstringRemaining unfilled size
oidnumberOrder ID - use this in cancelOrder
timestampnumberOrder creation time in milliseconds
origSzstringOriginal order size
orderTypestringOrder type label
tifstring | nullTime-in-force

​
Example

const orders = await adapter.account.fetchOpenOrders("0xYourAddress");

for (const order of orders) {
  console.log(
    `${order.coin} ${order.side === "B" ? "buy" : "sell"} ` +
    `${order.sz} @ ${order.limitPx} (oid: ${order.oid})`
  );
}

// Cancel all open orders
import { parseSideCoin } from "@hip4/sdk";

const cancels = orders.map((o) => {
  const parsed = parseSideCoin(o.coin);
  return {
    marketId: parsed ? String(parsed.outcomeId) : o.coin,
    orderId: String(o.oid),
    outcome: o.coin,
  };
});
await adapter.trading.cancelOrder(cancels);

​
subscribePositions(address, cb)

Starts polling the wallet’s positions every 10 seconds and delivers updates to your callback. Each poll makes two API calls - spotClearinghouseState and allMids. Errors during a poll are silently swallowed and the polling continues. There is no WebSocket channel for spot balances on Hyperliquid, so polling is the only mechanism available. 
const unsubscribe = adapter.account.subscribePositions(
  "0xYourAddress",
  (positions) => {
    for (const pos of positions) {
      console.log(pos.outcomeName, pos.shares, pos.unrealizedPnl);
    }
  }
);

// Stop polling when done
unsubscribe();

​
Parameters

​
address
string
required
The wallet address to poll.
​
cb
(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 occurs after the initial 10-second delay, not immediately on subscription. If you need the current positions right away, call fetchPositions() directly first, then subscribe.

​
Example

// Get initial positions immediately, then subscribe for live updates
const initial = await adapter.account.fetchPositions("0xYourAddress");
renderPositions(initial);

const unsubscribe = adapter.account.subscribePositions("0xYourAddress", (positions) => {
  renderPositions(positions);
});

// Clean up when the component unmounts or session ends
window.addEventListener("beforeunload", unsubscribe);