hyperliquid.position_analysis

Documentation for eth_defi.hyperliquid.position_analysis Python module.

Position analysis and DataFrame creation for Hyperliquid vault positions.

This module provides functionality to convert position event history into a pandas DataFrame format suitable for analysis and visualization.

Example:

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

session = create_hyperliquid_session()
vault_address = "0x3df9769bbbb335340872f01d8157c779d73c6ed0"

fills = fetch_vault_fills(session, vault_address)
events = reconstruct_position_history(fills)
df = create_account_dataframe(events)

# Calculate total account PnL at each timestamp
pnl_columns = [col for col in df.columns if col.endswith("_pnl")]
df["total_pnl"] = df[pnl_columns].sum(axis=1)

Functions

create_account_dataframe(events)

Create a DataFrame from position events with exposure and PnL columns per market.

create_account_dataframe(events)

Create a DataFrame from position events with exposure and PnL columns per market.

Creates a time-indexed DataFrame where each row represents a point in time when a position event occurred. For each market (coin), the DataFrame contains columns for both long and short directions tracking exposure and cumulative PnL.

Column naming convention: - {coin}_long_exposure: Long position exposure (positive = size * price) - {coin}_long_pnl: Cumulative realized PnL from long positions - {coin}_short_exposure: Short position exposure (positive = abs(size) * price) - {coin}_short_pnl: Cumulative realized PnL from short positions

The total account PnL at any row can be calculated by summing all *_pnl columns.

Parameters

events (Iterable[eth_defi.hyperliquid.position.PositionEvent]) – Iterator of position events from reconstruct_position_history(). Events should be in chronological order.

Returns

DataFrame with timestamp index and columns for each market/direction combination. Exposure represents the notional value (size * price) of open positions. PnL columns contain cumulative realized PnL.

Return type

pandas.core.frame.DataFrame