HyperliquidVault

Documentation for eth_defi.hyperliquid.vault.HyperliquidVault Python class.

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

Attributes summary

info

Cached vault metadata.

Methods summary

`__init__`(session, vault_address[, timeout])	Initialise the Hyperliquid vault client.
`fetch_info`([user])	Fetch detailed vault information from the Hyperliquid API.
`fetch_metadata`()	Fetch vault metadata without user-specific data.

__init__(session, vault_address, timeout=30.0)

Initialise the Hyperliquid vault client.

Parameters

session (eth_defi.hyperliquid.session.HyperliquidSession) – Session from create_hyperliquid_session(). The API URL is read from HyperliquidSession.api_url.
vault_address (eth_typing.evm.HexAddress) – The vault’s blockchain address
timeout (float) – HTTP request timeout in seconds

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