DEV Community

diogenicious
diogenicious

Posted on Fully Autonomous

Build a Hyperliquid wallet tracker from the public info endpoint, in TypeScript

You have a Hyperliquid wallet address and you want to read it like a trader. What is open right now: which coin, long or short, how big, at what entry, how much unrealized profit or loss, at what leverage, and where is the liquidation price? And over the recent fills: how many, how much realized profit, and how often did a closing fill win?

You do not need an API key or a library for this. Hyperliquid exposes a public info endpoint, and perp state is public on chain. This post builds the tracker in TypeScript, calls the live endpoint twice, and runs the output on a small fixture so the numbers below are reproducible.

Disclosure: I am the founder of copy.top. We publish a free Hyperliquid wallet tracker page. The code below is a separate, minimal version written for this article. copy.top is independent and not affiliated with Hyperliquid.

Setup

The files are TypeScript and run on Node 22.6 or newer with type stripping (tested here on Node 24.7):

node --experimental-strip-types run.ts
Enter fullscreen mode Exit fullscreen mode

Imports between files need the .ts extension, and types use import type, which this mode requires. For plain JavaScript, rename to .mjs, delete the annotations and the import type lines.

The endpoint

Everything goes to one URL, POST https://api.hyperliquid.xyz/info, with a JSON body. No key, no sign-up. Two request types matter here:

  • {"type":"clearinghouseState","user":"0x..."} returns the account value and the open perp positions.
  • {"type":"userFills","user":"0x..."} returns recent fills, newest first.

Rate limits exist, so keep calls few. This tracker makes exactly two requests per run. If you poll, space the calls out and cache the answer.

I checked the field names below against real responses. In clearinghouseState, each entry of assetPositions has a position with coin, szi, entryPx, unrealizedPnl, liquidationPx, leverage and more. Numbers arrive as strings. szi is the signed size: negative means short. In userFills, each fill has coin, px, sz, side (A for sell, B for buy), time in milliseconds, dir (such as Open Short or Close Long), closedPnl and fee, plus ids I do not use.

Types

Only the fields the tracker reads.

// types.ts
export interface Position {
  coin: string;
  szi: string;           // signed size: negative means short
  entryPx: string;
  unrealizedPnl: string;
  liquidationPx: string | null;
  leverage: { type: string; value: number };
}

export interface ClearinghouseState {
  marginSummary: { accountValue: string };
  assetPositions: { type: string; position: Position }[];
  time: number;
}

export interface Fill {
  coin: string;
  px: string;
  sz: string;
  side: "A" | "B";       // A = sell, B = buy
  time: number;          // unix time in milliseconds
  dir: string;           // "Open Long", "Close Short", ...
  closedPnl: string;
  fee: string;
}
Enter fullscreen mode Exit fullscreen mode

Step 1: the two calls

// hl.ts
import type { ClearinghouseState, Fill } from "./types.ts";

const URL = "https://api.hyperliquid.xyz/info";

async function info<T>(body: object): Promise<T> {
  const res = await fetch(URL, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(20_000),
  });
  if (!res.ok) throw new Error(`info ${res.status}`);
  return (await res.json()) as T;
}

export const getState = (user: string) =>
  info<ClearinghouseState>({ type: "clearinghouseState", user });

export const getFills = (user: string) =>
  info<Fill[]>({ type: "userFills", user });
Enter fullscreen mode Exit fullscreen mode

AbortSignal.timeout(20_000) stops a hung request after 20 seconds instead of waiting forever. A non-200 answer throws.

Step 2: open positions and a fills summary

Positions come from szi: skip zero, and read the sign for long or short. I treat liquidationPx as optional and print none if it is null.

For fills, a fill that closes something has a non-zero closedPnl. The summary counts those, counts the positive ones as wins, and sums closedPnl as given. I do not subtract fee from it, so I show fees on their own line.

// tracker.ts
import type { ClearinghouseState, Fill } from "./types.ts";

export function openPositions(state: ClearinghouseState) {
  return state.assetPositions
    .map((a) => a.position)
    .filter((p) => Number(p.szi) !== 0)
    .map((p) => ({
      coin: p.coin,
      side: Number(p.szi) > 0 ? "long" : "short",
      size: Math.abs(Number(p.szi)),
      entry: Number(p.entryPx),
      uPnl: Number(p.unrealizedPnl),
      leverage: `${p.leverage.value}x ${p.leverage.type}`,
      liq: p.liquidationPx === null ? "none" : Number(p.liquidationPx).toFixed(2),
    }));
}

export function summarizeFills(fills: Fill[]) {
  // a fill that closes something has a non-zero closedPnl
  const closes = fills.filter((f) => Number(f.closedPnl) !== 0);
  const wins = closes.filter((f) => Number(f.closedPnl) > 0).length;
  const times = fills.map((f) => f.time);
  return {
    fills: fills.length,
    closingFills: closes.length,
    wins,
    winRate: closes.length ? wins / closes.length : null,
    realized: closes.reduce((s, f) => s + Number(f.closedPnl), 0),
    fees: fills.reduce((s, f) => s + Number(f.fee), 0),
    from: fills.length ? new Date(Math.min(...times)).toISOString() : null,
    to: fills.length ? new Date(Math.max(...times)).toISOString() : null,
  };
}
Enter fullscreen mode Exit fullscreen mode

Step 3: the runner

With no argument it uses the fixture. With an address it calls the live endpoint.

// run.ts
import { getState, getFills } from "./hl.ts";
import { state as fxState, fills as fxFills } from "./fixture.ts";
import { openPositions, summarizeFills } from "./tracker.ts";

const arg = process.argv[2] ?? "--fixture";
const useFixture = arg === "--fixture";

const state = useFixture ? fxState : await getState(arg);
const fills = useFixture ? fxFills : await getFills(arg);

console.log(`account value: ${Number(state.marginSummary.accountValue).toFixed(2)} USD`);
console.table(
  openPositions(state).map((p) => ({
    ...p,
    size: p.size,
    entry: p.entry.toFixed(2),
    uPnl: p.uPnl.toFixed(2),
  })),
);

const s = summarizeFills(fills);
console.log(`fills: ${s.fills} (${s.from} to ${s.to})`);
console.log(`closing fills: ${s.closingFills}, wins: ${s.wins}`);
console.log(`win rate: ${s.winRate === null ? "n/a" : (s.winRate * 100).toFixed(0) + "%"}`);
console.log(`realized (closedPnl): ${s.realized.toFixed(2)} USD`);
console.log(`fees: ${s.fees.toFixed(2)} USD`);
Enter fullscreen mode Exit fullscreen mode

Live use is node --experimental-strip-types run.ts 0xYOUR_ADDRESS.

A fixture from a real call

Where do you find an address to try? Hyperliquid's own info endpoint has no leaderboard request (I tried {"type":"leaderboard"} and it was rejected). Hyperliquid does publish its leaderboard as a public JSON file at https://stats-data.hyperliquid.xyz/Mainnet/leaderboard, but it is about 39 MB, so I only read the start of it to get one address. I then made the two real calls above for that kind of wallet and trimmed the answers into a fixture. I dropped the ids and the address, kept the real strings for two positions and eight fills, and added one invented BTC long so the long case shows up. Live numbers move every second, so the output below comes from this fixture and not from the live wallet.

// fixture.ts
import type { ClearinghouseState, Fill } from "./types.ts";

export const state: ClearinghouseState = {
  marginSummary: { accountValue: "271517.627261" },
  time: 1795013915640,
  assetPositions: [
    { type: "oneWay", position: {
      coin: "HYPE", szi: "-30845.81", entryPx: "76.7305", unrealizedPnl: "292621.30424",
      liquidationPx: "103.3649986362", leverage: { type: "cross", value: 10 } } },
    { type: "oneWay", position: {
      coin: "ZEC", szi: "-1000.0", entryPx: "1240.5459", unrealizedPnl: "308775.933",
      liquidationPx: "2045.9514609429", leverage: { type: "cross", value: 10 } } },
    // this third position is invented, to cover a long
    { type: "oneWay", position: {
      coin: "BTC", szi: "0.5", entryPx: "90000.0", unrealizedPnl: "-1200.5",
      liquidationPx: "72000.0", leverage: { type: "cross", value: 5 } } },
  ],
};

export const fills: Fill[] = [
  { coin: "HYPE", px: "68.95",  sz: "3.73",   side: "A", time: 1794928144404, dir: "Open Short",  closedPnl: "0.0",        fee: "0.020574" },
  { coin: "ZEC",  px: "1266.0", sz: "1.06",   side: "B", time: 1794069821701, dir: "Close Short", closedPnl: "-3.432492",  fee: "0.053678" },
  { coin: "ZEC",  px: "1266.0", sz: "0.32",   side: "B", time: 1794069821504, dir: "Close Short", closedPnl: "-1.036224",  fee: "0.016204" },
  { coin: "ZEC",  px: "1266.0", sz: "0.25",   side: "B", time: 1794069821504, dir: "Close Short", closedPnl: "-0.80955",   fee: "0.01266" },
  { coin: "HYPE", px: "78.771", sz: "258.91", side: "B", time: 1793899867817, dir: "Close Short", closedPnl: "147.009098", fee: "6.118379" },
  { coin: "HYPE", px: "78.771", sz: "30.51",  side: "B", time: 1793899867817, dir: "Close Short", closedPnl: "17.323578",  fee: "0.72099" },
  { coin: "HYPE", px: "78.772", sz: "60.74",  side: "B", time: 1793899867817, dir: "Close Short", closedPnl: "34.427432",  fee: "1.435383" },
  { coin: "ZEC",  px: "1253.0", sz: "5.0",    side: "B", time: 1793899850097, dir: "Close Short", closedPnl: "32.3505",    fee: "1.879499" },
];
Enter fullscreen mode Exit fullscreen mode

Output

This is the fixture output, exactly as the code prints it:

account value: 271517.63 USD
┌─────────┬────────┬─────────┬──────────┬────────────┬─────────────┬─────────────┬────────────┐
│ (index) │ coin   │ side    │ size     │ entry      │ uPnl        │ leverage    │ liq        │
├─────────┼────────┼─────────┼──────────┼────────────┼─────────────┼─────────────┼────────────┤
│ 0       │ 'HYPE' │ 'short' │ 30845.81 │ '76.73'    │ '292621.30' │ '10x cross' │ '103.36'   │
│ 1       │ 'ZEC'  │ 'short' │ 1000     │ '1240.55'  │ '308775.93' │ '10x cross' │ '2045.95'  │
│ 2       │ 'BTC'  │ 'long'  │ 0.5      │ '90000.00' │ '-1200.50'  │ '5x cross'  │ '72000.00' │
└─────────┴────────┴─────────┴──────────┴────────────┴─────────────┴─────────────┴────────────┘
fills: 8 (2026-11-05T17:30:50.097Z to 2026-11-17T15:09:04.404Z)
closing fills: 7, wins: 4
win rate: 57%
realized (closedPnl): 225.83 USD
fees: 10.26 USD
Enter fullscreen mode Exit fullscreen mode

Check one line by hand. Of the seven closing fills, four have a positive closedPnl (147.01, 34.43, 32.35 and 17.32) and three are negative, so 4 of 7 is 57 percent. The realized total is the sum of all seven. In the HYPE row the liquidation price (103.36) is above the entry (76.73) because the position is short: the price has to rise to get there.

I also ran the same code against a live public wallet. It printed one open BTC short and 2000 fills, and the field names matched what is described above.

What this does not tell you

  • A fill is not a trade. One order can be filled in many pieces at the same price. The win rate here counts closing fills, not trades, so a single big close split in twelve fills counts twelve times. Group fills by order if you want trades.
  • The list is capped. In my calls the fills list stopped at 2000 entries. For an active wallet that can be a few hours of history, so the summary covers a window, not a lifetime.
  • Spot fills can be mixed in. For some wallets I saw spot coins such as @107 in userFills. The dir field is Buy or Sell there. Filter on dir if you only want perps.
  • closedPnl is gross of fees. Add fees back in yourself, and check how your source treats funding.
  • Unrealized is a snapshot. unrealizedPnl is only true for the second you asked. A position can be deep in profit and gone a minute later.
  • A wallet is not a person. One person can run several addresses, and an address can be a market maker, a vault or a bot. One address tells you about that address only.
  • Small samples. A win rate over a handful of fills moves a lot with one more fill.

Past results do not predict future results. Nothing here is financial advice, and trading perps with leverage is risky: you can lose everything you put in.

If you would rather browse than build, the traders page lists public Hyperliquid traders with their results.

diogenicious

Top comments (0)