hyperliquid.combined_analysis

Documentation for eth_defi.hyperliquid.combined_analysis Python module.

Combined position and deposit analysis for Hyperliquid vaults.

This module provides functionality to combine position PnL data with deposit/withdrawal data to create a comprehensive view of vault performance including:

  • Cumulative account value over time

  • Net capital flows (deposits minus withdrawals)

  • Trading PnL separated from capital movements

  • Internal share price calculation (similar to ERC-4626 vaults)

The share price mechanism works as follows:

  • total_assets tracks the account value (NAV) at each point in time

  • total_supply tracks the number of shares outstanding

  • share_price is calculated as total_assets / total_supply

  • When a deposit occurs, new shares are minted: shares_minted = deposit_amount / share_price

  • When a withdrawal occurs, shares are burned: shares_burned = withdrawal_amount / share_price

  • Share price starts at 1.00 at vault inception

Example:

from datetime import datetime, timedelta
from eth_defi.hyperliquid.session import create_hyperliquid_session
from eth_defi.hyperliquid.position import fetch_vault_fills, reconstruct_position_history
from eth_defi.hyperliquid.position_analysis import create_account_dataframe
from eth_defi.hyperliquid.deposit import fetch_vault_deposits, create_deposit_dataframe
from eth_defi.hyperliquid.combined_analysis import analyse_positions_and_deposits

session = create_hyperliquid_session()
vault_address = "0x3df9769bbbb335340872f01d8157c779d73c6ed0"
start_time = datetime.now() - timedelta(days=30)

# Fetch position data
fills = fetch_vault_fills(session, vault_address, start_time=start_time)
events = reconstruct_position_history(fills)
position_df = create_account_dataframe(events)

# Fetch deposit data
deposit_events = fetch_vault_deposits(session, vault_address, start_time=start_time)
deposit_df = create_deposit_dataframe(list(deposit_events))

# Combine for comprehensive analysis
combined_df = analyse_positions_and_deposits(position_df, deposit_df)

print(f"Final account value: ${combined_df['cumulative_account_value'].iloc[-1]:,.2f}")
print(f"Share price: ${combined_df['share_price'].iloc[-1]:.4f}")
print(f"Total supply: {combined_df['total_supply'].iloc[-1]:,.2f}")

Functions

analyse_positions_and_deposits(position_df, ...)

Combine position and deposit DataFrames into a unified timeline.

get_combined_summary(combined_df)

Generate a summary of combined position and deposit analysis.
analyse_positions_and_deposits(position_df, deposit_df, initial_balance=0.0)

Combine position and deposit DataFrames into a unified timeline.

This function merges trading activity (positions/PnL) with capital flows (deposits/withdrawals) to create a comprehensive view of vault performance.

The resulting DataFrame contains:

  • pnl_update: Change in realised PnL at this timestamp (from trading)

  • netflow_update: Change in capital at this timestamp (deposits positive, withdrawals negative)

  • cumulative_pnl: Running total of realised trading PnL

  • cumulative_netflow: Running total of capital flows (deposits - withdrawals)

  • cumulative_account_value: Total account value (initial_balance + netflow + pnl)

  • total_assets: Alias for cumulative_account_value (NAV)

  • total_supply: Number of shares outstanding

  • share_price: Share price calculated as total_assets / total_supply

The share price calculation follows ERC-4626 vault mechanics:

  • Share price starts at 1.00 when the first deposit occurs

  • When deposits occur, new shares are minted at the current share price

  • When withdrawals occur, shares are burned at the current share price

  • PnL changes affect total_assets but not total_supply, thus changing share price

The DataFrame is indexed by timestamp and sorted chronologically, combining events from both position changes and deposit/withdrawal activity.

Example:

from eth_defi.hyperliquid.combined_analysis import analyse_positions_and_deposits

# Assuming position_df and deposit_df are already created
combined = analyse_positions_and_deposits(position_df, deposit_df, initial_balance=1000.0)

# Get final values
final_pnl = combined["cumulative_pnl"].iloc[-1]
final_netflow = combined["cumulative_netflow"].iloc[-1]
final_value = combined["cumulative_account_value"].iloc[-1]
final_share_price = combined["share_price"].iloc[-1]

print(f"Trading PnL: ${final_pnl:,.2f}")
print(f"Net capital flow: ${final_netflow:,.2f}")
print(f"Account value: ${final_value:,.2f}")
print(f"Share price: ${final_share_price:.4f}")
Parameters
Returns

DataFrame with unified timeline containing PnL, capital flow, and share price metrics.

Return type

pandas.DataFrame

get_combined_summary(combined_df)

Generate a summary of combined position and deposit analysis.

Parameters

combined_df (pandas.DataFrame) – DataFrame from analyse_positions_and_deposits()

Returns

Dict with summary statistics including share price metrics

Return type

dict