Hyperliquid L1 Vault Contract Architecture for Prop-Trading Funds

Hyperliquid L1 vault contract architecture sits at the intersection of on-chain settlement guarantees and the performance demands of a real prop desk. Unlike EVM vaults where you write a Solidity contract and plug into an external perp venue, Hyperliquid's vault system is a first-class primitive baked into the L1 itself — meaning the settlement logic, margin accounting, and depositor economics are enforced at the consensus layer, not by a smart contract you can audit and fork.

If you're running a fund with external LPs or splitting a strategy across internal traders, the choice between a native vault and a sub-account tree is not cosmetic. It changes your liquidation exposure, your fee surface, and your ability to upgrade the strategy without migrating capital.

How the Vault Primitive Works On-Chain

A Hyperliquid vault is a first-class account type registered on the L1. When a depositor sends USDC to a vault address, the L1 records the deposit in that vault's equity ledger — the share price is computed as (totalEquity / totalShares) at deposit time. This is not a token minting operation in the EVM sense; there is no ERC-20 being issued. The accounting lives in L1 state.

The leader account is the designated address that controls trading inside the vault. Only the leader can submit orders against the vault's margin. From the settlement perspective, the vault's open positions are attributed to the vault account, not to the leader's personal cross-margined book. This is critical: the leader can blow up the vault without touching their own collateral, and vice versa.

Withdrawals go through a lockup window (currently 1 day for non-system vaults) enforced at the consensus level. During that window the vault's unrealized PnL is marked to the index price, and the departing depositor's share is computed on that mark — not on fill prices. If a large position is open, a redemption can materially move the effective price for remaining depositors. Model this before you open the vault to external capital.

Margin Accounting and the Cross-Margin Boundary

Each vault account runs cross-margin across all its open perp positions. There is no isolated-margin mode for vault accounts in the current architecture. This means a long BTC position and a short ETH position share the same margin pool, and the liquidation engine looks at the aggregate portfolio health rather than individual position health.

The maintenance margin requirement is calculated as:

MMR = Σ (|notional_i| × mmr_rate_i)

where mmr_rate_i is the per-asset rate published by Hyperliquid's risk engine (typically 0.4% to 2% depending on asset and tier). A vault's liquidation trigger is when accountValue < MMR. At that point the L1's liquidation engine begins reducing positions — starting with the largest contributors to margin consumption — until the account is healthy or fully liquidated.

The key operational implication: if you run a delta-neutral strategy inside a vault and your hedge legs are on a correlated but non-identical asset, the margin engine sees the gross notional of both legs, not the net. A $5M long BTC / $4.8M short ETH strategy carries the margin footprint of $9.8M notional, not $200k. Size your vault's initial capital accordingly.

HIP-1 Token Layer and Vault Interaction

HIP-1 is Hyperliquid's native token standard, analogous to ERC-20 but settled on the L1. The relevant surface for vault operators is that HIP-1 tokens can be deposited as collateral into a spot account on the L1, and spot balances feed into the vault's USDC-equivalent equity via the oracle price of those tokens.

In practice, most prop vaults operate in pure USDC terms and never touch HIP-1 tokens directly. But if your strategy involves holding a spot position in a HIP-1 token alongside a perp hedge, the interaction is worth understanding. The spot position sits in the vault's spot sub-ledger, is valued at oracle (not mid-market), and contributes to the vault's total equity for share-price computation. A fast oracle move in the underlying can reprice the vault's equity before your perp hedge catches up — this is a basis risk you need to budget for.

For desks building infrastructure around this, the Hyperliquid API exposes vault equity and position state via the /info endpoint with type: vaultDetails. The response includes per-depositor share data, the leader address, and the full position snapshot. There is no on-chain ABI to parse — settlement is L1-native and the canonical data source is the node's state, not an event log.

Sub-Account Structure vs. Vault: The Real Trade-Off

Sub-accounts on Hyperliquid are cheaper to operate and have zero lockup on withdrawals. The main limitations: a sub-account cannot receive external deposits from arbitrary addresses, and each sub-account's margin is isolated from the master account's. If you're running an internal multi-strategy desk where all capital is controlled by one operator and no external LPs need to deposit, sub-accounts give you clean strategy isolation without the depositor mechanics overhead.

Vaults make sense when:

• External LPs deposit capital and need trustless share accounting with on-chain equity attribution.
• You want leader accountability — the leader address can be a multisig, and the vault structure makes it unambiguous which address controls trading.
• Redemption lockups align with your strategy horizon — a short-duration MM strategy where depositors might pull during a drawdown creates adverse selection; the lockup window mitigates this somewhat.

Sub-accounts make sense when:

• The fund is a single operator running multiple uncorrelated strategies internally.
• You need to toggle strategies on and off quickly without a withdrawal cycle.
• Margin segregation by strategy (not by LP) is the priority.

For a desk that needs both — external LPs and multi-strategy isolation — the current answer is to run one vault per strategy tier, not to nest sub-accounts inside a vault. The L1 does not support sub-vaults.

Practical Deployment Checklist

Before you allocate real capital to a vault structure, validate these items against the live API — parameters change with network upgrades:

• Vault creation fee: currently 100 USDC, burned on creation.
• Leader commission cap: the leader can set a take rate up to 50% of profits. Set this in the creation transaction; changing it requires migrating the vault.
• Lockup period: 1 day for user-created vaults. This is a hard L1 rule, not a parameter you control.
• Position limits: vaults share the same per-asset open-interest caps as regular accounts. If the asset is near its OI cap you will receive partial fills or rejections — your execution layer needs to handle this.
• Oracle staleness: the L1 uses a median of external feeds. In low-liquidity assets the oracle can lag spot by several seconds. If your strategy depends on tight oracle tracking, test this explicitly before deploying.

If you need a custom settlement layer on top — for example, streaming PnL to off-chain LP accounts or integrating the vault equity into a risk system — the canonical integration point is the /info endpoint polled at 500ms intervals, or a WebSocket subscription to { "method": "subscribe", "subscription": { "type": "userEvents", "user": "<vault_address>" } }. There is no event-log equivalent to EVM logs; your indexer needs to reconstruct state from the streaming feed.

For firms that want this built and battle-tested rather than assembled from docs, TierZero's Hyperliquid trading infrastructure services cover the full stack — from vault deployment through execution bots and real-time dashboards with kill-switch controls.

---

If you're designing a vault structure for a prop desk or an external-LP fund on Hyperliquid, get in touch — we scope these engagements quickly and can tell you within a call whether a vault, a sub-account tree, or a hybrid makes sense for your capital structure.