On this page

Hyperliquid account & orders

Per-wallet Hyperliquid state, by address. All are part of the /v1/hyperliquid/info/* passthrough family: public (require only the read scope), take ?user=<0x address> (lowercased server-side), do not require the wallet to belong to your org, and return the raw HL Info payload under native.

These power the PM Profile Positions / Orders / History / Trades tabs without the client touching Hyperliquid directly.

Endpoint	HL Info type	What it is
`GET /v1/hyperliquid/info/clearinghouse-state`	`clearinghouseState`	Open positions + margin + account value. Optional `?dex=` for a HIP-3 / builder dex's margin pool (names via `info/perp-dexs`)
`GET /v1/hyperliquid/info/spot-clearinghouse-state`	`spotClearinghouseState`	Per-coin spot balances (`coin`, `total`, `hold`, `entryNtl`) — powers a Balances tab
`GET /v1/hyperliquid/info/open-orders`	`frontendOpenOrders`	Current resting (placed) orders. Optional `?dex=` for a HIP-3 / builder dex order book (incl. its TP/SL triggers) — omit for main perp
`GET /v1/hyperliquid/info/historical-orders`	`historicalOrders`	Recent order lifecycle (filled / canceled / triggered). No `?dex=` — HL returns orders across every dex (main perp + HIP-3 mixed) in one batch
`GET /v1/hyperliquid/info/user-fills`	`userFills`	Recent fills (trade history) — carries the liquidation marker

Requests

bashcurl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/hyperliquid/info/open-orders?user=0xabc…"
 
curl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/hyperliquid/info/historical-orders?user=0xabc…"
 
curl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/hyperliquid/info/user-fills?user=0xabc…"

Each returns { "native": <raw HL payload>, "meta": { provider, fetchedAt, source } }.

Manual close vs. automatic liquidation

To tell whether a position was closed by the user or force-liquidated, use user-fills — not historical-orders. A liquidation is a system action, not a user-placed order, so it does not reliably appear in the order history; but every fill carries HL's liquidation marker:

jsonc// /v1/hyperliquid/info/user-fills → native[]
{
  "coin": "xyz:SPCX",
  "dir": "Close Short",          // position direction of the fill
  "closedPnl": "-70.07",
  "liquidation": {                // ← non-null ⇒ AUTOMATIC liquidation
    "liquidatedUser": "0x77b1…",
    "markPx": "218.92",
    "method": "market"
  }
}

liquidation != null → the close was a forced liquidation (maintenance margin breach). method distinguishes the mechanism (market, backstop, …).
liquidation == null → a normal, user-initiated fill.

Sourcing, freshness & limits

open-orders and user-fills are served from the self-hosted Hyperliquid node (no upstream rate-limit cost) and short-TTL cached. user-fills covers roughly the last ~14 days network-wide; for deeper history use the official HL API.
historical-orders is proxied to the official HL API and cached; HL returns only the most recent batch (~2000), so this is near-term history, not lifetime.
user-fills is the trade-fill stream (what executed). historical-orders is the order lifecycle (includes unfilled / canceled). They are not the same — pick by tab.

For the org-scoped (your bound wallets) fill feed instead of an arbitrary address, use /v1/me/fills. For cross-provider positions + USD value in one call, see Portfolio.

Edit this page on GitHubLast updated yesterday

Hyperliquid account & orders#

Requests#

Manual close vs. automatic liquidation#

Sourcing, freshness & limits#

Hyperliquid account & orders

Requests

Manual close vs. automatic liquidation

Sourcing, freshness & limits