hyperliquid.deposit

Documentation for eth_defi.hyperliquid.deposit Python module.

Hyperliquid vault deposit and redemption history analysis.

This module provides functionality for fetching and analysing historical deposit and redemption (withdrawal) events for Hyperliquid vaults.

The Hyperliquid API provides the userNonFundingLedgerUpdates endpoint which returns all ledger updates excluding funding payments. This includes vault-specific events:

  • vaultDeposit - User deposits into a vault

  • vaultWithdraw - User withdraws from a vault

  • vaultCreate - Vault creation event

  • vaultDistribution - Distribution event (e.g., profit sharing)

  • vaultLeaderCommission - Commission paid to vault leader

API Endpoints Used

  • userNonFundingLedgerUpdates - Paginated ledger history with time range support

Example:

from datetime import datetime, timedelta
from eth_defi.hyperliquid.session import create_hyperliquid_session
from eth_defi.hyperliquid.deposit import (
    fetch_vault_deposits,
    create_deposit_dataframe,
)

session = create_hyperliquid_session()
vault_address = "0x3df9769bbbb335340872f01d8157c779d73c6ed0"

# Fetch deposit/withdrawal history for the last 30 days
start_time = datetime.now() - timedelta(days=30)
events = list(fetch_vault_deposits(session, vault_address, start_time=start_time))

# Convert to DataFrame for analysis
df = create_deposit_dataframe(events)
print(f"Total deposits: ${df[df['event_type'] == 'vault_deposit']['usdc'].sum():,.2f}")

See Also

Functions

aggregate_daily_flows(events)

Aggregate vault events into daily deposit/withdrawal flow metrics.

create_deposit_dataframe(events)

Create a DataFrame from vault deposit/withdrawal events.

fetch_vault_deposits(session, vault_address)

Fetch all deposit and withdrawal events for a vault.

get_deposit_summary(events)

Generate a summary of vault deposit/withdrawal activity.

Classes

RawLedgerUpdate

Parsed ledger update data from Hyperliquid API.

VaultDepositEvent

Represents a vault deposit, withdrawal, or related event.

VaultEventType

Type of vault deposit/withdrawal event.
class RawLedgerUpdate

Bases: object

Parsed ledger update data from Hyperliquid API.

This is an intermediate representation of raw API ledger data with proper typing.

__init__(timestamp_ms, hash, delta)
Parameters
Return type

None

classmethod from_api_response(data)

Parse a ledger update from API response data.

Parameters

data (dict) – Raw ledger update dict from API

Returns

Parsed RawLedgerUpdate object

Return type

eth_defi.hyperliquid.deposit.RawLedgerUpdate

property timestamp: datetime.datetime

Convert millisecond timestamp to datetime.

class VaultDepositEvent

Bases: object

Represents a vault deposit, withdrawal, or related event.

This dataclass captures vault-related ledger events from the userNonFundingLedgerUpdates API endpoint.

__init__(event_type, vault_address, user_address, usdc, timestamp, hash=None, requested_usd=None, commission=None, closing_cost=None, basis=None, net_withdrawn_usd=None)
Parameters
Return type

None

class VaultEventType

Bases: enum.Enum

Type of vault deposit/withdrawal event.

aggregate_daily_flows(events)

Aggregate vault events into daily deposit/withdrawal flow metrics.

Groups events by calendar date and computes:

  • Number of deposit events

  • Number of withdrawal events

  • Total USD deposited (positive)

  • Total USD withdrawn (positive, absolute value)

Only vault_deposit and vault_withdraw events are counted. Other event types (vault_create, vault_distribution, vault_leader_commission) are excluded.

Parameters

events (list[eth_defi.hyperliquid.deposit.VaultDepositEvent]) – List of vault events from fetch_vault_deposits().

Returns

Dict mapping date to (deposit_count, withdrawal_count, deposit_usd, withdrawal_usd).

Return type

dict[datetime.date, tuple[int, int, float, float]]

create_deposit_dataframe(events)

Create a DataFrame from vault deposit/withdrawal events.

Creates a time-indexed DataFrame where each row represents a vault event (deposit, withdrawal, distribution, etc.).

Example:

from eth_defi.hyperliquid.deposit import fetch_vault_deposits, create_deposit_dataframe

events = list(fetch_vault_deposits(session, vault_address))
df = create_deposit_dataframe(events)

# Calculate net flows
total_deposits = df[df["event_type"] == "vault_deposit"]["usdc"].sum()
total_withdrawals = df[df["event_type"] == "vault_withdraw"]["usdc"].abs().sum()
net_flow = total_deposits - total_withdrawals
Parameters

events (list[eth_defi.hyperliquid.deposit.VaultDepositEvent]) – List of vault events from fetch_vault_deposits()

Returns

DataFrame with timestamp index and columns for event details

Return type

pandas.DataFrame

fetch_vault_deposits(session, vault_address, start_time=None, end_time=None, timeout=30.0)

Fetch all deposit and withdrawal events for a vault.

Fetches ledger updates from the Hyperliquid API using the userNonFundingLedgerUpdates endpoint and filters for vault-related events (deposits, withdrawals, distributions, etc.).

The events are yielded in chronological order (oldest first).

Example:

from datetime import datetime, timedelta
from eth_defi.hyperliquid.session import create_hyperliquid_session
from eth_defi.hyperliquid.deposit import fetch_vault_deposits

session = create_hyperliquid_session()
vault = "0x3df9769bbbb335340872f01d8157c779d73c6ed0"

# Fetch last 7 days of deposits/withdrawals
events = list(
    fetch_vault_deposits(
        session,
        vault,
        start_time=datetime.now() - timedelta(days=7),
    )
)
print(f"Fetched {len(events)} vault events")
Parameters
Returns

Iterator of vault events sorted by timestamp ascending (oldest first)

Raises

requests.HTTPError – If the HTTP request fails after retries

Return type

Iterator[eth_defi.hyperliquid.deposit.VaultDepositEvent]

get_deposit_summary(events)

Generate a summary of vault deposit/withdrawal activity.

Parameters

events (list[eth_defi.hyperliquid.deposit.VaultDepositEvent]) – List of vault events from fetch_vault_deposits()

Returns

Dict with summary statistics

Return type

dict