Hyperliquid Vault Deposits, Withdrawals, and On-Chain Tax Tracking

Hyperliquid vaults are one of the cleaner ways to deploy capital into a managed perp strategy — you deposit USDC, receive vault equity shares, and your balance accrues or declines in real time as the vault's positions move. What the documentation glosses over is the bridging mechanics under the hood, the exact sequence of on-chain events that tax software needs to see, and where the data actually lives when you go to reconcile at year-end. This article covers all three, based on running production vault integrations for multiple client accounts.

Depositing: The Bridge Is Not a Transfer

Hyperliquid runs on its own L1. When you deposit USDC from Arbitrum — which is the canonical path — you are not sending tokens to a contract on Arbitrum that holds them for you. You are burning USDC on Arbitrum and minting an equivalent credit on the Hyperliquid L1. The bridge is canonical and one-way in the sense that the L1 credit is the native unit; Arbitrum USDC is just the on-ramp.

The practical steps:

• Connect your wallet on app.hyperliquid.xyz and hit Deposit.
• Approve the USDC spend on Arbitrum (EIP-2612 permit is supported — one fewer transaction if your wallet signs it).
• The bridge contract on Arbitrum emits a Deposit event. Finality on the Hyperliquid side typically lands within 5–15 seconds, though the bridge has a 7-day dispute window that matters for large institutional flows.
• Your Hyperliquid account balance updates immediately after L1 finalization.

From that credited USDC you then make a separate vault deposit — an L1-native transaction moving funds from your spot balance into vault equity. This is a distinct on-chain event and matters enormously for tax purposes: the Arbitrum bridge event is one taxable transaction, the vault entry is another.

Withdrawing: Two-Stage, Mind the Queue

Withdrawals reverse the flow but with an important asymmetry: vault withdrawals are subject to the vault's withdrawal queue and lock-up, which is set per vault by the vault leader. Many public vaults enforce a 1–4 day processing window. Do not assume immediate liquidity.

Once the vault releases your equity back to your spot balance, you initiate an L1 withdrawal to Arbitrum. Hyperliquid charges a flat $1 USDC fee for bridge withdrawals (as of mid-2025 — verify on-chain if this matters for your cost basis). Funds typically arrive on Arbitrum within 15 minutes but can take up to a few hours under load.

For accounting purposes, the vault exit and the bridge withdrawal are again two distinct events. The vault exit crystallizes your gain or loss relative to your entry NAV. The bridge withdrawal is a disposal of the L1 credit and acquisition of Arbitrum USDC — generally treated as a like-kind movement, but your jurisdiction may vary.

Where the On-Chain Data Lives

Hyperliquid exposes all L1 state through a public REST API at https://api.hyperliquid.xyz/info. The two endpoints you need:

User fills and funding history:

POST /info
{ "type": "userFills", "user": "0xYourAddress" }

Vault deposit/withdrawal history:

POST /info
{ "type": "userVaultEquities", "user": "0xYourAddress" }

The userVaultEquities response gives you a snapshot of current equity by vault, not a history. For historical vault flow, poll portfolioHistory or scrape userFunding and cross-reference timestamps against your vault entry/exit records. There is no native "vault transaction history" endpoint — you reconstruct it from balance deltas sampled over time or by indexing L1 block data directly.

For Arbitrum-side events, query the bridge contract (0x2Df1c51E09aECF9A5B8E8f6c7f1a5e7A0d3B9c2 — confirm the current address in Hyperliquid's official docs before using) via standard eth_getLogs against Arbitrum RPC. Filter for Deposit(address,uint256) and Withdrawal(address,uint256) events with your address as the indexed argument.

Feeding Data into Koinly

Koinly does not have a native Hyperliquid integration as of mid-2025. The practical workflow:

1. Export fills and funding payments from the Info API for the tax year.
2. Map each fill to a Koinly Trade row (buy/sell + fee).
3. Map funding payments to Income (positive) or Cost (negative) rows.
4. Map vault deposits and withdrawals to Transfer rows between Hyperliquid and a virtual "vault" wallet — this preserves cost basis correctly rather than triggering phantom disposals.
5. Map Arbitrum bridge events as transfers between your Arbitrum wallet and your Hyperliquid wallet.

The most common mistake is importing only the Arbitrum bridge transactions from an EVM scanner and missing the L1 vault activity entirely. Your Arbiscan history shows the on-ramp and off-ramp — the entire trading PnL and funding history lives only in Hyperliquid's L1 and is invisible to EVM indexers.

Writing a Custom Reconciler

If you are running meaningful volume — multiple vaults, high fill frequency, or programmatic strategies — the manual CSV approach breaks quickly. A minimal Python reconciler hits the Info API nightly, stores fills and funding into a local Postgres table with (address, timestamp, type, amount, fee) schema, and computes running cost basis using FIFO or weighted average depending on jurisdiction. You can emit a Koinly-compatible CSV at any point, or wire it directly into your accounting system.

The funding rate component is the piece most reconcilers get wrong. On Hyperliquid, funding is settled every hour to your account balance as a direct USDC credit or debit. It is not embedded in the fill price. If your reconciler treats position PnL as the only taxable event, you are understating income (when you are long in a positive funding environment) or overclaiming losses.

---

If you want a production-grade vault integration or a custom reconciler built for your Hyperliquid operation, reach out to TierZero — we have shipped these end-to-end and can scope what your setup actually requires.