Your first request

Start with reads: they’re the safe place to learn the info endpoint. They pay no fee and change nothing. They also give you what every order depends on: a market’s position in meta, its szDecimals, and its book’s price levels.

Three reads, step by step

Step 1: list the perpetual markets

curl -s -X POST https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"meta"}'

Abridged from the docs’ example; live values differ, so read them from the API:

{
  "universe": [
    { "name": "BTC", "szDecimals": 5, "maxLeverage": 50 },
    { "name": "ETH", "szDecimals": 4, "maxLeverage": 50 },
    { "name": "HPOS", "szDecimals": 0, "maxLeverage": 3, "onlyIsolated": true }
  ]
}

Field	Meaning
position in universe	The asset id orders use. BTC, first in the list, is asset 0 on mainnet.
name	The coin string that info requests and WebSocket subscriptions use.
szDecimals	Decimals a size may have; also caps price decimals, see precision.
maxLeverage	The leverage ceiling. Some entries also carry isDelisted, onlyIsolated or marginMode.

The full response also carries marginTables. {"type":"metaAndAssetCtxs"} adds a second array, in the same order, with each market’s markPx, oraclePx, funding, openInterest, dayNtlVlm and more. Add "dex":"<name>" to either request to list a builder-deployed HIP-3 perp dex instead of the first one.

Step 2: read an order book

curl -s -X POST https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"l2Book","coin":"BTC"}'

The docs’ example response:

{
  "coin": "BTC",
  "time": 1754450974231,
  "levels": [
    [
      { "px": "113377.0", "sz": "7.6699", "n": 17 },
      { "px": "113376.0", "sz": "4.13714", "n": 8 }
    ],
    [
      { "px": "113397.0", "sz": "0.11543", "n": 3 }
    ]
  ]
}

levels holds bids, then asks, each from the best price:

Field	Meaning
px	Price of the level
sz	Total size resting there, in units of the coin
n	Number of orders at the level

nSigFigs (2, 3, 4 or 5) aggregates levels to fewer significant figures; mantissa (1, 2 or 5) is allowed only with nSigFigs of 5.

Other coin strings: @107 for HYPE spot on mainnet, dex:COIN for HIP-3, #<number> for an outcome side.

Step 3: read an account

ADDR=0x0000000000000000000000000000000000000000   # replace with the account to inspect
curl -s -X POST https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d "{\"type\":\"clearinghouseState\",\"user\":\"$ADDR\"}"

The docs’ example, with one isolated ETH position:

{
  "assetPositions": [
    {
      "position": {
        "coin": "ETH",
        "szi": "0.0335",
        "entryPx": "2986.3",
        "leverage": { "type": "isolated", "value": 20, "rawUsd": "-95.059824" },
        "liquidationPx": "2866.26936529",
        "marginUsed": "4.967826",
        "positionValue": "100.02765",
        "unrealizedPnl": "-0.0134"
      },
      "type": "oneWay"
    }
  ],
  "marginSummary": {
    "accountValue": "13109.482328",
    "totalMarginUsed": "4.967826",
    "totalNtlPos": "100.02765",
    "totalRawUsd": "13009.454678"
  },
  "withdrawable": "13104.514502",
  "time": 1708622398623
}

The docs’ example also carries cumFunding, maxLeverage, returnOnEquity, crossMarginSummary and crossMaintenanceMarginUsed. The notation:

Field	Meaning
szi	Signed size: positive long, negative short
Ntl	Notional: price times size, in USD
Px	A price
withdrawable	What can leave the account now
time	Snapshot time, in milliseconds

The same three reads in TypeScript

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

async function info<T>(body: object): Promise<T> {
  const res = await fetch(INFO, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const text = await res.text(); // a 422 arrives as plain text, not JSON
  if (!res.ok) throw new Error(`${res.status}: ${text}`);
  return JSON.parse(text) as T;
}

type Meta = { universe: { name: string; szDecimals: number; maxLeverage: number }[] };
type Level = { px: string; sz: string; n: number };
type Book = { coin: string; time: number; levels: [Level[], Level[]] };
type Account = { withdrawable: string; assetPositions: { position: { coin: string; szi: string } }[] };

const meta = await info<Meta>({ type: "meta" });
const asset = meta.universe.findIndex((m) => m.name === "BTC"); // the asset id orders use
console.log(asset, meta.universe[asset].szDecimals);

const book = await info<Book>({ type: "l2Book", coin: "BTC" });
const [bids, asks] = book.levels;
console.log(bids[0].px, asks[0].px); // best bid and best ask, as strings

const account = await info<Account>({
  type: "clearinghouseState",
  user: "0x0000000000000000000000000000000000000000", // the account to inspect
});
console.log(account.withdrawable, account.assetPositions.length);

Every number is a string: keep it one or parse it into a decimal type, never a float (see precision).

The numbers

Request	Rate-limit weight	Notes
l2Book	2	At most 20 levels per side
clearinghouseState	2	One perp dex per request; dex defaults to the first
meta	20	Changes rarely: cache it
metaAndAssetCtxs	20	Live contexts; for frequent updates use the WebSocket

One IP’s weights share a budget of 1200 per minute. Time-range requests return at most 500 elements; page by passing the last timestamp returned as the next startTime.

Reading your own account

Put your address in step 3 to read your account with no key or login; HyperCore positions, orders and fills are public for any address. Read liquidationPx, the protocol’s own figure, rather than recomputing it.

When a read comes back empty or unexpected

• An API wallet’s address returns an empty result: it only signs for the account.
• Under unified account or portfolio margin, the spot and perps trading balance is in spotClearinghouseState, not clearinghouseState (account modes).
• Outcome positions are spot balances: read spotClearinghouseState.
• App names can differ: BTC/USDC in the app is UBTC/USDC on HyperCore (the docs’ example).
• An unparseable body returns HTTP 422 as plain text beginning Failed to deserialize; hence the helper reads text first.
• Testnet is https://api.hyperliquid-testnet.xyz, with different asset ids, token indices and dex lists.

For every coin string and asset id, see Asset ids and naming. For the same data as a stream, see WebSocket.