hyperliquid.vault

Documentation for eth_defi.hyperliquid.vault Python module.

Hyperliquid vault data extraction and analysis.

This module provides functionality for extracting historical Hyperliquid vault events and serializing them into Pandas DataFrames for analysis.

API Endpoints

Hyperliquid has two relevant API surfaces for vault data:

Official Info API (https://api.hyperliquid.xyz/info):

  • vaultDetails - Get details for a specific vault (works)

  • userVaultEquities - Get user’s vault positions (works)

  • vaultSummaries - Documented but returns empty array (non-functional)

Stats Data API (https://stats-data.hyperliquid.xyz/Mainnet/vaults):

  • Undocumented internal endpoint that powers the Hyperliquid web UI

  • Returns all vaults (~8,000+) with APR, TVL, and PNL history arrays

  • Uses GET instead of POST - serves pre-aggregated/cached data

  • More comprehensive than the official API but may change without notice

The vaultSummaries endpoint in the official API is documented but non-functional (returns []). For bulk vault listing, use the stats-data endpoint or the bash script at scripts/hyperliquid/fetch-vault-metadata.sh.

For more information about Hyperliquid vaults see:

Functions

estimate_max_withdrawal_commission(...)

Estimate the worst-case vault leader commission for a withdrawal.

fetch_all_vaults([session, stats_url, timeout])

Iterate over all Hyperliquid vaults.

Classes

HyperliquidVault

Client for extracting historical Hyperliquid vault events and data.

PortfolioHistory

Historical portfolio data for a specific time period.

VaultFollower

Represents a follower (depositor) in a Hyperliquid vault.

VaultInfo

Detailed information about a Hyperliquid vault.

VaultSortKey

Supported sort keys for vault listing.

VaultSummary

Summary information for a Hyperliquid vault.
class HyperliquidVault

Bases: object

Client for extracting historical Hyperliquid vault events and data.

This class provides methods to fetch vault information from the Hyperliquid API and serialize the data into Pandas DataFrames for analysis.

Example:

from eth_defi.hyperliquid.session import create_hyperliquid_session, HYPERLIQUID_TESTNET_API_URL
from eth_defi.hyperliquid.vault import HyperliquidVault

# Mainnet
session = create_hyperliquid_session()
vault = HyperliquidVault(
    session=session,
    vault_address="0x1234567890abcdef1234567890abcdef12345678",
)

# Testnet
session = create_hyperliquid_session(api_url=HYPERLIQUID_TESTNET_API_URL)
vault = HyperliquidVault(
    session=session,
    vault_address="0x1234567890abcdef1234567890abcdef12345678",
)
Parameters

  • session – Session from create_hyperliquid_session()

  • vault_address – The vault’s blockchain address

  • timeout – HTTP request timeout in seconds

Initialise the Hyperliquid vault client.

Parameters

  • session – Session from create_hyperliquid_session(). The API URL is read from HyperliquidSession.api_url.

  • vault_address – The vault’s blockchain address

  • timeout – HTTP request timeout in seconds

__init__(session, vault_address, timeout=30.0)

Initialise the Hyperliquid vault client.

Parameters
fetch_info(user=None)

Fetch detailed vault information from the Hyperliquid API.

Makes a request to the vaultDetails endpoint and returns a typed VaultInfo dataclass with all vault metadata.

Note

The maxWithdrawable field in the API response is per-user. You must pass the depositor user address to obtain the real withdrawable amount; without it the API always returns 0.

Example:

from eth_defi.hyperliquid.session import create_hyperliquid_session
from eth_defi.hyperliquid.vault import HyperliquidVault

session = create_hyperliquid_session()
vault = HyperliquidVault(
    session=session,
    vault_address="0x3df9769bbbb335340872f01d8157c779d73c6ed0",
)

info = vault.fetch_info(user="0xYourAddress")
print(f"Vault: {info.name}")
print(f"Leader: {info.leader}")
print(f"Max withdrawable: {info.max_withdrawable}")
Parameters

user (Optional[eth_typing.evm.HexAddress]) – Depositor address. The maxWithdrawable field in the Hyperliquid vaultDetails response is per-user; without this parameter the API always returns 0.

Returns

VaultInfo dataclass with vault details

Raises

requests.HTTPError – If the HTTP request fails

Return type

eth_defi.hyperliquid.vault.VaultInfo

fetch_metadata()

Fetch vault metadata without user-specific data.

Like fetch_info() but does not require a user address. The returned VaultInfo.max_withdrawable will always be 0 because the Hyperliquid API only returns a meaningful value when a depositor address is provided.

Use this for scanning, metrics collection, and other contexts where user-specific withdrawal limits are not needed.

Returns

VaultInfo dataclass (max_withdrawable is always 0)

Return type

eth_defi.hyperliquid.vault.VaultInfo

property info: eth_defi.hyperliquid.vault.VaultInfo

Cached vault metadata.

Fetches vault details on first access and caches the result. Uses fetch_metadata() (no user context), so max_withdrawable is 0. Call fetch_info() with a user address when you need withdrawal limits.

Returns

VaultInfo dataclass with vault details

class PortfolioHistory

Bases: object

Historical portfolio data for a specific time period.

Contains account value history, PNL history, and trading volume for a given period (day, week, month, or allTime).

__init__(period, account_value_history, pnl_history, volume)
Parameters
Return type

None

class VaultFollower

Bases: object

Represents a follower (depositor) in a Hyperliquid vault.

__init__(user, vault_equity, pnl, all_time_pnl, days_following, vault_entry_time, lockup_until=None)
Parameters
Return type

None

class VaultInfo

Bases: object

Detailed information about a Hyperliquid vault.

This dataclass represents the response from the vaultDetails API endpoint, containing comprehensive vault metadata, follower information, and portfolio history.

__init__(name, vault_address, leader, description, followers, portfolio, max_distributable, max_withdrawable, is_closed, allow_deposits, relationship_type, commission_rate=None, leader_fraction=None, leader_commission=None, parent=None)
Parameters
Return type

None

class VaultSortKey

Bases: enum.Enum

Supported sort keys for vault listing.

These correspond to fields available in VaultSummary that provide stable, deterministic ordering.

class VaultSummary

Bases: object

Summary information for a Hyperliquid vault.

Contains both basic vault metadata and performance metrics from the stats-data endpoint.

__init__(name, vault_address, leader, tvl, is_closed, relationship_type, create_time=None, apr=None, pnl_day=None, pnl_week=None, pnl_month=None, pnl_all_time=None)
Parameters
Return type

None

estimate_max_withdrawal_commission(withdrawal_amount, commission_rate)

Estimate the worst-case vault leader commission for a withdrawal.

Hyperliquid vault leaders earn a performance fee (typically 10%) on depositor profits. The fee is deducted at withdrawal time from the portion of the withdrawal that represents profit.

In the worst case — when the entire withdrawal consists of profit — the commission equals commission_rate * withdrawal_amount. In practice the commission is lower because only the profit portion is taxed.

Protocol vaults (HLP and children) have no commission, so commission_rate is None or zero for those.

The withdrawal_amount is always treated as a positive quantity. Hyperliquid withdrawal events store outflows as negative values (see VaultDepositEvent), so callers may pass a negative amount — abs() is applied internally.

Parameters

  • withdrawal_amount (decimal.Decimal) – USDC amount being withdrawn. Negative values are accepted and treated as their absolute value.

  • commission_rate (Optional[Union[decimal.Decimal, float]]) – Leader commission rate as a fraction (e.g. 0.1 or Decimal("0.1") for 10%). Accepts both float (as stored in VaultInfo.commission_rate from the Hyperliquid leaderCommission API field) and Decimal. None for protocol vaults with no fee.

Returns

Worst-case commission in USDC (always non-negative). Returns Decimal(0) when commission_rate is None or zero.

Return type

decimal.Decimal

See https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/vaults

fetch_all_vaults(session=None, stats_url='https://stats-data.hyperliquid.xyz/Mainnet/vaults', timeout=30.0)

Iterate over all Hyperliquid vaults.

This function fetches all vault summaries from the Hyperliquid stats-data API and yields them one by one. It handles API throttling using exponential backoff retry logic.

Note

This uses the undocumented stats-data endpoint (HYPERLIQUID_STATS_URL) instead of the official vaultSummaries endpoint which is documented but non-functional (returns empty array).

Example:

from eth_defi.hyperliquid.session import create_hyperliquid_session
from eth_defi.hyperliquid.vault import fetch_all_vaults, HYPERLIQUID_STATS_TESTNET_URL

# Create a session for API requests
session = create_hyperliquid_session()

# Iterate over all vaults (mainnet)
for vault in fetch_all_vaults(session):
    print(f"Vault: {vault.name}, TVL: ${vault.tvl:,.2f}")

# Use testnet
for vault in fetch_all_vaults(session, stats_url=HYPERLIQUID_STATS_TESTNET_URL):
    print(f"Testnet vault: {vault.name}")

# Filter vaults with high TVL
high_tvl_vaults = [v for v in fetch_all_vaults(session) if v.tvl > 1_000_000]

# Convert to list
all_vaults = list(fetch_all_vaults(session))

# Sort vaults by TVL after fetching
sorted_by_tvl = sorted(fetch_all_vaults(session), key=lambda v: v.tvl, reverse=True)

# Get top 10 vaults by TVL
top_tvl = sorted_by_tvl[:10]
Parameters
Returns

Iterator yielding VaultSummary objects

Raises

requests.HTTPError – If the HTTP request fails after all retries

Return type

Iterator[eth_defi.hyperliquid.vault.VaultSummary]