hyperliquid.vault_data_export

Documentation for eth_defi.hyperliquid.vault_data_export Python module.

Export Hyperliquid vault data into the ERC-4626 pipeline format.

This module bridges the Hyperliquid-specific DuckDB data into the formats consumed by the existing ERC-4626 vault metrics pipeline:

  • Synthetic VaultRow entries for the VaultDatabase pickle

  • Raw price DataFrames matching the uncleaned Parquet schema, so that Hypercore data goes through the same cleaning pipeline as EVM vaults

  • Merge functions to append Hyperliquid data into existing files

Example:

from pathlib import Path
from eth_defi.hyperliquid.daily_metrics import HyperliquidDailyMetricsDatabase
from eth_defi.hyperliquid.vault_data_export import merge_into_vault_database, merge_into_uncleaned_parquet

db = HyperliquidDailyMetricsDatabase(Path("daily-metrics.duckdb"))

merge_into_vault_database(db, vault_db_path)
merge_into_uncleaned_parquet(db, uncleaned_parquet_path)

db.close()

Module Attributes

LEADER_FRACTION_WARNING_THRESHOLD

If the leader's share of vault capital drops below this threshold, we warn that new deposits may not be accepted because the leader must maintain at least 5% of total vault capital.

Functions

build_raw_prices_dataframe(db)

Build a raw prices DataFrame from the Hyperliquid DuckDB.

create_hyperliquid_vault_row(vault_address, ...)

Create a synthetic VaultRow for a Hyperliquid native vault.

merge_into_uncleaned_parquet(db, parquet_path)

Merge Hyperliquid daily prices into the uncleaned Parquet file.

merge_into_vault_database(db, vault_db_path)

Merge Hyperliquid vault metadata into an existing VaultDatabase pickle.
LEADER_FRACTION_WARNING_THRESHOLD: float = 0.055

If the leader’s share of vault capital drops below this threshold, we warn that new deposits may not be accepted because the leader must maintain at least 5% of total vault capital.

The threshold is set 0.5% above the Hyperliquid minimum (5%) to give an early warning before deposits are actually blocked.

Source: https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/vaults/for-vault-leaders-legacy Verified: 2026-03-09

create_hyperliquid_vault_row(vault_address, name, description, tvl, create_time, follower_count=None, is_closed=False, allow_deposits=True, relationship_type='normal', leader_fraction=None)

Create a synthetic VaultRow for a Hyperliquid native vault.

Builds a VaultRow that matches what calculate_vault_record() expects, using the Hypercore synthetic chain ID.

User-created vaults (relationship_type="normal") use the fixed platform performance fee HYPERLIQUID_VAULT_PERFORMANCE_FEE. Protocol vaults (HLP and its children with relationship_type="parent" or "child") have zero fees.

Parameters

  • vault_address (eth_typing.evm.HexAddress) – Vault hex address (will be lowercased).

  • name (str) – Vault display name.

  • description (str | None) – Vault description text.

  • tvl (float) – Current TVL in USD.

  • create_time (datetime.datetime | None) – Vault creation timestamp.

  • follower_count (int | None) – Number of vault depositors.

  • is_closed (bool) – Whether the vault is closed for new deposits.

  • allow_deposits (bool) – Whether the vault allows deposits. A vault can have is_closed=False but allow_deposits=False.

  • relationship_type (str) – Vault relationship type from the API: "normal" for user-created vaults, "parent" for HLP, "child" for HLP sub-vaults.

  • leader_fraction (float | None) – Leader’s fraction of total vault capital (e.g. 0.10 = 10%). Used for _get_deposit_closed_reason() to warn when close to the Hyperliquid 5% minimum.

Returns

Tuple of (VaultSpec, VaultRow).

Return type

tuple[eth_defi.vault.base.VaultSpec, eth_defi.vault.vaultdb.VaultRow]

build_raw_prices_dataframe(db)

Build a raw prices DataFrame from the Hyperliquid DuckDB.

Produces rows matching the schema of the EVM vault scanner (export()), so Hypercore data can go through the same cleaning pipeline (process_raw_vault_scan_data()) as ERC-4626 vaults.

The output has timestamp as a column (not index), matching the raw uncleaned Parquet format.

Includes per-row deposit_closed_reason (str or None) and deposits_open (str “true”/”false” or None) columns derived from forward-filled is_closed, allow_deposits, and leader_fraction state columns in the DuckDB.

Also exposes Hyperliquid’s raw cumulative account PnL as account_pnl so downstream consumers can compare the website-style account PnL against the cleaned share-price based return series. follower_count and cumulative_volume are exported as scalar historical fields when available.

Parameters

db (eth_defi.hyperliquid.daily_metrics.HyperliquidDailyMetricsDatabase) – The Hyperliquid daily metrics database.

Returns

DataFrame with columns matching the uncleaned Parquet schema.

Return type

pandas.DataFrame

merge_into_vault_database(db, vault_db_path)

Merge Hyperliquid vault metadata into an existing VaultDatabase pickle.

Reads the existing pickle, upserts Hyperliquid VaultRow entries (keyed by VaultSpec), and writes back. Idempotent: running twice produces the same result.

If the pickle file does not exist, creates a new VaultDatabase.

Parameters
Returns

The updated VaultDatabase.

Return type

eth_defi.vault.vaultdb.VaultDatabase

merge_into_uncleaned_parquet(db, parquet_path)

Merge Hyperliquid daily prices into the uncleaned Parquet file.

Writes Hypercore raw data in the same format as the EVM vault scanner, so the standard cleaning pipeline (process_raw_vault_scan_data()) can process all vaults together.

Reads the existing Parquet, removes any prior Hypercore rows (chain == 9999), appends fresh Hyperliquid daily price rows, and writes back. Idempotent: running twice produces the same result.

If the Parquet file does not exist, creates a new one.

Parameters
Returns

The combined DataFrame.

Return type

pandas.DataFrame