1. Wallet Tracker

The wallet tracker answers what does this address hold right now?: open perp positions with entry, mark, and liquidation prices, spot balances, resting orders, and a live fill feed that ticks as the address trades. This page introduces three patterns the rest of the series reuses: reading account state, maintaining a live mid-price store, and subscribing to a user-scoped WebSocket channel.

All examples use the info() helper and the key-holding proxy from the series overview.

1. Read account state

You have two options, and the choice is about how much normalization you want. portfolioState is a Uniblock synthetic type: one call returns perps, spot, and account-abstraction mode composed into a single object, with each section isolated so a failure in one doesn’t take down the others.

const portfolio = await info({ type: "portfolioState", user: address });

// {
//   type: "portfolioState",
//   address: "0x...",
//   chainId: 999,
//   perpetuals: { marginSummary, assetPositions, withdrawable, ... } | null,
//   spot: { balances: [...] } | null
// }

Note that perpetuals and spot are nullable. A section that failed upstream comes back null rather than throwing, so guard before you read into it. clearinghouseState and spotClearinghouseState are the native Hyperliquid reads, if you’d rather compose them yourself:

const [perps, spot] = await Promise.all([
  info({ type: "clearinghouseState", user: address }),
  info({ type: "spotClearinghouseState", user: address }),
]);

Either way, the perp payload has the same shape:

{
  "marginSummary": {
    "accountValue": "1250.44",
    "totalNtlPos": "8300.10",
    "totalRawUsd": "1250.44",
    "totalMarginUsed": "415.00"
  },
  "crossMarginSummary": { "...": "same fields" },
  "crossMaintenanceMarginUsed": "83.00",
  "withdrawable": "835.44",
  "assetPositions": [
    {
      "type": "oneWay",
      "position": {
        "coin": "BTC",
        "szi": "0.12",
        "entryPx": "62150.0",
        "positionValue": "7500.00",
        "unrealizedPnl": "42.10",
        "returnOnEquity": "0.0562",
        "liquidationPx": "48120.5",
        "leverage": { "type": "cross", "value": 10 },
        "marginUsed": "750.00"
      }
    }
  ],
  "time": 1753660800000
}

2. Render the positions table

Positions live one level down, under assetPositions[].position. The field that trips people up is szi, which is the signed position size, so its sign is what tells you long from short. There is no side field.

const positions = (perps?.assetPositions ?? []).map(({ position: p }) => ({
  coin: p.coin,
  side: Number(p.szi) > 0 ? "long" : "short",
  size: Math.abs(Number(p.szi)),
  entryPx: Number(p.entryPx),
  // null for a cross-margin position that can't be individually liquidated
  liquidationPx: p.liquidationPx === null ? null : Number(p.liquidationPx),
  leverage: `${p.leverage.value}x ${p.leverage.type}`,
  marginUsed: Number(p.marginUsed),
  unrealizedPnl: Number(p.unrealizedPnl),
}));

liquidationPx is legitimately null for some positions. Cross-margin positions don’t each have their own liquidation price, since the whole account is collateral. Render a dash, not a zero.

Spot balances are flatter:

const balances = (spot?.balances ?? []).map((b) => ({
  coin: b.coin,
  total: Number(b.total),
  available: Number(b.total) - Number(b.hold), // `hold` is locked in resting orders
  entryNtl: Number(b.entryNtl),
}));

3. Show open orders

const orders = await info({ type: "frontendOpenOrders", user: address });

// [{ coin, side, limitPx, sz, oid, timestamp, origSz, cloid? }]

side is "B" for bid (buy) and "A" for ask (sell), Hyperliquid’s convention throughout, in fills as well as orders. sz is what’s left unfilled; origSz is what the order was placed for, so origSz - sz is the filled portion.

Use frontendOpenOrders rather than openOrders unless you have a reason not to. Both return the same resting orders, but frontendOpenOrders adds order-type and trigger metadata, and it’s served by all four providers, whereas openOrders is not served by GoldRush. If your request fails over to GoldRush, frontendOpenOrders keeps working.

4. Keep mid prices live

Positions are only half the picture: unrealizedPnl in the snapshot was true at time, and it drifts the moment the market moves. To keep it live you need a current mark for each coin. There is no allMids WebSocket channel. This is the single most common wrong assumption when building on this stack: the REST type exists, so people look for the matching stream and don’t find one. The working pattern is a hybrid:

Seed and correct from REST allMids on a slow interval (30 seconds is plenty).
Update tick-by-tick from the allFills WebSocket channel, taking each fill’s price as the latest trade price for its coin.

const prices = new Map();

// Seed from REST, and re-seed slowly to correct any drift.
async function seedPrices() {
  const mids = await info({ type: "allMids" }); // { "BTC": "62150.0", "ETH": "2410.5", ... }
  for (const [coin, px] of Object.entries(mids)) prices.set(coin, Number(px));
}
await seedPrices();
setInterval(seedPrices, 30_000);

// Update from the live trade stream.
ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "allFills" } }));

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel !== "allFills") return;
  for (const [, fill] of msg.fills) {
    if (fill?.coin && fill.px) prices.set(fill.coin, Number(fill.px));
  }
});

Two things to note about that subscription, both covered in full in the next section: allFills needs no parameters (it’s the whole venue), and its payload arrives as [address, fill] tuples, which is why the loop destructures past the address.

allFills is a busy stream, with thousands of events a minute at peak. Don’t re-render on every message. Batch price updates and flush on a timer (250ms works well) so a busy market doesn’t pin your UI thread.

With a live price map, unrealized PnL becomes a derivation rather than a fetch:

function liveUnrealizedPnl(positions) {
  return positions.reduce((sum, p) => {
    const mid = prices.get(p.coin);
    // Fall back to the snapshot value until the first price for that coin arrives.
    if (mid === undefined) return sum + Number(p.unrealizedPnl);
    return sum + Number(p.szi) * (mid - Number(p.entryPx));
  }, 0);
}

Because szi is signed, that one expression is correct for both directions: a short has negative szi, so a falling price yields a positive product.

5. Stream this wallet’s fills

Finally, subscribe to the address’s own fills for a live activity feed.

ws.send(
  JSON.stringify({
    method: "subscribe",
    subscription: { type: "userFills", addresses: [address] },
  }),
);

userFills takes addresses: string[], not user: string. This diverges from Hyperliquid’s native WebSocket contract, and it fails quietly: send the native { type: "userFills", user: "0x..." } form and the subscription is accepted but never delivers anything. The same applies to orderUpdates. If a user-scoped stream is silent, check this first.

The payload diverges too. Fills arrive as [address, fill] tuples under a fills key, not in Hyperliquid’s native { data: { user, fills } } envelope:

{
  "channel": "userFills",
  "fills": [
    [
      "0xabc...",
      {
        "coin": "BTC",
        "px": "62180.0",
        "sz": "0.02",
        "side": "B",
        "time": 1753660812345,
        "startPosition": "0.10",
        "dir": "Open Long",
        "closedPnl": "0.0",
        "hash": "0x...",
        "oid": 88123456,
        "fee": "0.37",
        "tid": 445566778899
      }
    ]
  ]
}

Because allFills and userFills share that envelope, one parser handles both:

function parseFillTuples(msg) {
  if (!Array.isArray(msg.fills)) return [];
  return msg.fills.filter(([address, fill]) => typeof address === "string" && fill?.coin);
}

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel !== "userFills") return;
  for (const [, fill] of parseFillTuples(msg)) {
    feed.unshift({
      coin: fill.coin,
      side: fill.side === "B" ? "buy" : "sell",
      px: Number(fill.px),
      sz: Number(fill.sz),
      // Human-readable already: "Open Long", "Close Short", "Long > Short", …
      dir: fill.dir,
      pnl: Number(fill.closedPnl),
      time: fill.time,
    });
  }
});

The dir field is worth surfacing directly in the feed. It is a pre-formatted description of what the fill did to the position, which saves you inferring it from startPosition and szi.

Subscriptions are matched for unsubscribe by their exact body. Send { method: "unsubscribe", subscription: { type: "userFills", addresses: [address] } } with the identical addresses array you subscribed with, or the subscription (and its per-minute billing) stays open. When a user switches wallets, unsubscribe the old address before subscribing the new one.

Reconnecting

The stream will drop. Handle it with exponential backoff, and re-send every active subscription on reconnect, because the server keeps no state across connections:

let retry = 0;

function connect() {
  const ws = new WebSocket("ws://localhost:8787/ws");

  ws.on("open", () => {
    retry = 0;
    for (const sub of activeSubscriptions) {
      ws.send(JSON.stringify({ method: "subscribe", subscription: sub }));
    }
  });

  ws.on("close", () => {
    setTimeout(connect, Math.min(15_000, 500 * 2 ** retry++));
  });

  return ws;
}

The wallet tracker shows the present. Next, PnL analytics reconstructs the past from fill history.

Quickstart

Guides

Hyperliquid API

1. Read account state

2. Render the positions table

3. Show open orders

4. Keep mid prices live

5. Stream this wallet’s fills

Reconnecting

Next

​1. Read account state

​2. Render the positions table

​3. Show open orders

​4. Keep mid prices live

​5. Stream this wallet’s fills

​Reconnecting

​Next

1. Read account state

2. Render the positions table

3. Show open orders

4. Keep mid prices live

5. Stream this wallet’s fills

Reconnecting

Next