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:

Module Attributes

HYPERLIQUID_API_URL

Hyperliquid mainnet API URL

HYPERLIQUID_TESTNET_API_URL

Hyperliquid testnet API URL

HYPERLIQUID_STATS_URL

Hyperliquid stats-data API URL for vault listing (mainnet).

HYPERLIQUID_STATS_TESTNET_URL

Hyperliquid stats-data API URL for vault listing (testnet)

Functions

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.
HYPERLIQUID_API_URL = 'https://api.hyperliquid.xyz'

Hyperliquid mainnet API URL

HYPERLIQUID_TESTNET_API_URL = 'https://api.hyperliquid-testnet.xyz'

Hyperliquid testnet API URL

HYPERLIQUID_STATS_URL = 'https://stats-data.hyperliquid.xyz/Mainnet/vaults'

Hyperliquid stats-data API URL for vault listing (mainnet). This is an undocumented internal endpoint that powers the Hyperliquid web UI. It must be used instead of the official vaultSummaries endpoint which is documented but non-functional (returns empty array). This endpoint returns all vaults (~8,000+) with APR, TVL, and PNL history via GET request. See: https://app.hyperliquid.xyz/vaults

HYPERLIQUID_STATS_TESTNET_URL = 'https://stats-data.hyperliquid-testnet.xyz/Mainnet/vaults'

Hyperliquid stats-data API URL for vault listing (testnet)

class VaultFollower

Bases: object

Represents a follower (depositor) in a Hyperliquid vault.

user: eth_typing.evm.HexAddress

Follower’s wallet address

vault_equity: decimal.Decimal

Current equity in the vault (USD)

pnl: decimal.Decimal

Profit/loss since entry

all_time_pnl: decimal.Decimal

All-time profit/loss

days_following: int

Number of days following this vault

vault_entry_time: int

Timestamp when user entered the vault (milliseconds)

lockup_until: int | None

Timestamp when lockup period ends (milliseconds), if applicable

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

None

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).

period: str

Time period identifier (day, week, month, allTime)

account_value_history: list[tuple[datetime.datetime, decimal.Decimal]]

Account value history as list of (timestamp, value) tuples

pnl_history: list[tuple[datetime.datetime, decimal.Decimal]]

PNL history as list of (timestamp, pnl) tuples

volume: decimal.Decimal

Trading volume for the period (USD)

__init__(period, account_value_history, pnl_history, volume)
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.

name: str

Vault display name

vault_address: eth_typing.evm.HexAddress

Vault’s blockchain address

leader: eth_typing.evm.HexAddress

Vault manager/operator address

description: str

Vault description text

followers: list[eth_defi.hyperliquid.vault.VaultFollower]

List of vault followers (depositors)

portfolio: dict[str, eth_defi.hyperliquid.vault.PortfolioHistory]

Portfolio history by time period

max_distributable: decimal.Decimal

Maximum distributable amount (USD)

max_withdrawable: decimal.Decimal

Maximum withdrawable amount (USD)

is_closed: bool

Whether vault is closed for deposits

allow_deposits: bool

Whether vault allows deposits

relationship_type: str

Vault relationship type (normal, child, parent)

commission_rate: float | None

Commission rate for the vault leader (as decimal, e.g., 0.1 = 10%)

parent: Optional[eth_typing.evm.HexAddress]

Parent vault address if this is a child vault

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

None

class VaultSummary

Bases: object

Summary information for a Hyperliquid vault.

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

name: str

Vault display name

vault_address: eth_typing.evm.HexAddress

Vault’s blockchain address

leader: eth_typing.evm.HexAddress

Vault manager/operator address

tvl: decimal.Decimal

Total Value Locked (USD)

is_closed: bool

Whether deposits are closed

relationship_type: str

Vault relationship type (normal, child, parent)

create_time: datetime.datetime | None

Vault creation timestamp

apr: float | None

Annual Percentage Rate (as decimal, e.g., 0.15 = 15%)

pnl_day: list[str] | None

PNL history for daily period (list of decimal strings)

pnl_week: list[str] | None

PNL history for weekly period (list of decimal strings)

pnl_month: list[str] | None

PNL history for monthly period (list of decimal strings)

pnl_all_time: list[str] | None

PNL history for all-time period (list of decimal strings)

__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

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
from eth_defi.hyperliquid.vault import HyperliquidVault, HYPERLIQUID_API_URL

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

# Initialize for mainnet
vault = HyperliquidVault(
    session=session,
    vault_address="0x1234567890abcdef1234567890abcdef12345678",
)

# Or for testnet
vault = HyperliquidVault(
    session=session,
    vault_address="0x1234567890abcdef1234567890abcdef12345678",
    server_url=HYPERLIQUID_TESTNET_API_URL,
)
Parameters

  • session – HTTP session with retry logic from create_hyperliquid_session()

  • vault_address – The vault’s blockchain address

  • server_url – Hyperliquid API URL (defaults to mainnet)

  • timeout – HTTP request timeout in seconds

Initialize the Hyperliquid vault client.

Parameters

  • session – HTTP session with retry logic. Use create_hyperliquid_session() to create one.

  • vault_address – The vault’s blockchain address

  • server_url – Hyperliquid API URL. Use HYPERLIQUID_API_URL for mainnet or HYPERLIQUID_TESTNET_API_URL for testnet.

  • timeout – HTTP request timeout in seconds

__init__(session, vault_address, server_url='https://api.hyperliquid.xyz', timeout=30.0)

Initialize the Hyperliquid vault client.

Parameters

  • session (requests.sessions.Session) – HTTP session with retry logic. Use create_hyperliquid_session() to create one.

  • vault_address (eth_typing.evm.HexAddress) – The vault’s blockchain address

  • server_url (str) – Hyperliquid API URL. Use HYPERLIQUID_API_URL for mainnet or HYPERLIQUID_TESTNET_API_URL for testnet.

  • timeout (float) – HTTP request timeout in seconds

fetch_info()

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.

Use info property for cached access.

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()
print(f"Vault: {info.name}")
print(f"Leader: {info.leader}")
print(f"Followers: {len(info.followers)}")
Returns

VaultInfo dataclass with vault details

Raises

requests.HTTPError – If the HTTP request fails

Return type

eth_defi.hyperliquid.vault.VaultInfo

property info: eth_defi.hyperliquid.vault.VaultInfo

Cached vault information.

Fetches vault details on first access and caches the result. Use fetch_info() to force a fresh fetch.

Returns

VaultInfo dataclass with vault details

class VaultSortKey

Bases: enum.Enum

Supported sort keys for vault listing.

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

VAULT_ADDRESS = 'vault_address'

Sort by vault address (hex string, stable and unique)

NAME = 'name'

Sort by vault name (alphabetical)

TVL = 'tvl'

Sort by TVL (Total Value Locked)

APR = 'apr'

Sort by APR (Annual Percentage Rate)

CREATE_TIME = 'create_time'

Sort by creation time

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

  • session (requests.sessions.Session | None) – A requests Session configured for Hyperliquid API. Use eth_defi.hyperliquid.session.create_hyperliquid_session() to create one. If None, a default session will be created.

  • stats_url (str) – Hyperliquid stats-data API URL. Use HYPERLIQUID_STATS_URL for mainnet or HYPERLIQUID_STATS_TESTNET_URL for testnet.

  • timeout (float) – HTTP request timeout in seconds

Returns

Iterator yielding VaultSummary objects

Raises

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

Return type

Iterator[eth_defi.hyperliquid.vault.VaultSummary]