Reading state

The gate is write-only. Read the vault's trading state from Hyperliquid's public info API directly, addressing the vault's address (the vault is the Hyperliquid account; the agent only signs). Response shapes are documented by Hyperliquid — these are the same calls their own frontend makes:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"clearinghouseState","user":"0xVAULT"}'

Useful types: clearinghouseState (positions, margin), openOrders / frontendOpenOrders, userFills, historicalOrders, spotClearinghouseState (spot balances), activeAssetData (per-market leverage/mode — builder coins are addressed by full name, e.g. "xyz:GOLD").

The per-dex scoping trap

clearinghouseState, openOrders, and frontendOpenOrders return the native dex only by default. Positions and orders on builder dexes are invisible unless you pass the dex name:

-d '{"type":"openOrders","user":"0xVAULT","dex":"xyz"}'

Query the native dex plus every builder dex you trade and merge. (Fills via userFills and historicalOrders are account-wide — no dex parameter needed.)

Polling etiquette

The public API and RPC rate-limit per IP (roughly 100 requests/minute) and answer with 503s when hammered — CORS preflights included, which can poison browser connection pools for minutes. Poll modestly, back off on failure, and prefer the WebSocket streams for anything real-time. See Hyperliquid's rate limits for the exact budgets.