Skip to main content
Prerequisites: Trading on Hyperliquid for order semantics and funding the account, Strategies for the general agent model.

​
Overview

All Scalar Field activity on Hyperliquid — chat trades and every strategy agent — settles into one exchange account per user (your EVM wallet address). The exchange only knows the account’s net position per coin. Agent isolation is implemented on the platform side as a ledger:
  • Each agent has its own cash balance and its own position book with signed quantities (negative = short).
  • The sum of all agents’ claims on a symbol, plus any manual residual (positions you hold outside of agents), must equal what the exchange actually holds. Reconciliation verifies this continuously.
  • Agent NAV = cash + sum(qty x mark price). Because quantities are signed, a short position contributes negative market value.
Two things live only at the account level, not per agent:
  • Margin and liquidation price. The exchange computes margin_used and liq_price on the net account position. Agents do not carry their own margin model — an agent’s NAV tracks entry/exit prices, fees, and funding, not free collateral.
  • Collateral buckets. USDC sits in perps, spot, and HIP-3 builder-dex balances on the account. Agent cash is a bookkeeping ledger over that shared collateral, not a segregated wallet.

​
Signed Fill Accounting

Every fill (agent order, reconciled external fill, or attributed liquidation) moves an agent’s book with sign-aware transitions: Cash moves with the fill: buys debit qty x price (plus fees), sells credit qty x price (minus fees). Fees always debit cash. Opening a short therefore credits cash while market value goes negative — NAV is unchanged at the moment of the fill, then tracks PnL.

​
Funding

Hyperliquid settles funding hourly on every open perp position, crediting or debiting the account’s USDC. Since the exchange settles at the account level, the platform mirrors each settlement onto the agents that held the position.

​
Attribution across agents

Funding is attributed per coin, pro-rata by signed quantity, using the account’s actual funding ledger (the userFunding events Hyperliquid records for each settlement):
Because the per-unit rate is derived from the real settlement, agents holding the same coin in the same direction split the payment exactly in proportion to their size, shorts receive the opposite sign of longs automatically, and the manual residual’s share is never charged to any agent. If no ledger event is available for an hour (e.g. the account position was netted flat while an agent still held a claim), the platform falls back to the published hourly funding rate: per_unit = -funding_rate x close price (longs pay when the rate is positive).

​
Watermarks within an agent

Each agent position carries a funding watermark — the timestamp through which funding has been applied:
  • Hours are applied strictly after the watermark, then the watermark advances. A 2-minute settlement lag is left so an in-flight settlement is never half-counted.
  • Opening a position from flat, or flipping direction, resets the watermark to now — an agent never pays funding for hours it did not hold.
  • Accrual looks back at most 168 hours (7 days); older unapplied hours are dropped rather than back-charged.
Applied funding lands in the agent’s cash (and therefore its NAV) and accumulates in the position’s funding_paid counter. Each application emits a FUNDING_ACCRUED event in strategy.activity().

​
When accrual runs

Accrual is lazy — nothing runs on a timer inside the agent. It triggers whenever the ledger is about to be read or changed: Trigger points: every strategy.state(), before every fill is applied, before a liquidation is attributed (funding is settled up to the liquidation timestamp first), and on unfreeze. If no hour boundary has passed since the watermark, the call is a no-op.

​
Exchange Liquidation

There are two different things called “liquidation”:
  • strategy.liquidate() — a voluntary flatten: the agent submits closing orders through the normal execution path.
  • Exchange (forced) liquidation — Hyperliquid force-closes part or all of the account’s net position when margin runs out. This section covers the forced case.

​
Detection

Forced closes happen outside any agent’s order flow, so they surface as a divergence during reconciliation: the exchange’s net quantity no longer matches the sum of agent claims. On Hyperliquid, any divergence beyond a 1e-6 quantity epsilon (in either direction — forced closes can hit longs or shorts) triggers a scan of the account’s recent fills for entries carrying Hyperliquid’s liquidation marker, looking back up to 72 hours.

​
Attribution across agents

Each liquidation fill is split among the agents holding the liquidated direction, plus the manual residual:
The share is capped at the agent’s own quantity, and the manual residual absorbs its proportion — agents are never assigned more than they held, and never pay for positions they did not claim.

​
Application within an agent

For each attributed share, in order:
  1. Funding is settled first, up to the liquidation timestamp, at the pre-liquidation quantity.
  2. The share is applied as a sign-correct close at the actual liquidation price: a liquidated long realizes share x (liq_px - avg_px) and credits share x liq_px to cash; a liquidated short realizes share x (avg_px - liq_px) and debits the buyback cost. The agent’s proportion of the liquidation fee is deducted from cash.
  3. The close is recorded and the agent is paused with reason account_liquidated so it does not keep trading against a book that just changed underneath it.

​
What you see

Attribution is idempotent: each exchange fill is applied to an agent at most once, so repeated reconciliations never double-count.

​
Parameters

​
HIP-3 Builder Dexs

Hyperliquid’s HIP-3 builder-deployed perp dexs (symbols H:<dex>:<coin>, e.g. H:xyz:AAPL) hold their own USDC collateral in separate clearinghouses on the same account:
  • Account values aggregate them. venue.account(account="HYPERLIQUID") reports account_value, margin_used, and portfolio_value summed across the main dex and every HIP-3 dex, with per-dex USDC balance rows tagged with a dex key.
  • Agent ledgers are symbol-keyed, so HIP-3 positions flow through the same signed-fill, funding, and liquidation-attribution paths as main-dex perps — the dex only determines which collateral bucket backs the position at the exchange.
  • Moving USDC between the spot, main perps, and HIP-3 buckets is a transfer on the account (done from the portfolio page), not an agent operation.

​
Related