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

Module Attributes

MAX_UPDATES_PER_REQUEST

Maximum ledger updates returned per API request

Functions

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.
MAX_UPDATES_PER_REQUEST = 2000

Maximum ledger updates returned per API request

class VaultEventType

Bases: enum.Enum

Type of vault deposit/withdrawal event.

vault_create = 'vault_create'

Initial vault creation

vault_deposit = 'vault_deposit'

Deposit into the vault

vault_withdraw = 'vault_withdraw'

Withdrawal from the vault

vault_distribution = 'vault_distribution'

Distribution event (e.g., profit sharing)

vault_leader_commission = 'vault_leader_commission'

Commission paid to vault leader

class VaultDepositEvent

Bases: object

Represents a vault deposit, withdrawal, or related event.

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

event_type: eth_defi.hyperliquid.deposit.VaultEventType

Type of event

vault_address: eth_typing.evm.HexAddress

Vault address

user_address: Optional[eth_typing.evm.HexAddress]

User address (for withdrawals and commissions)

usdc: decimal.Decimal

USDC amount (positive for deposits/inflows, negative for withdrawals/outflows)

timestamp: datetime.datetime

Event timestamp

hash: str | None

Transaction hash

requested_usd: decimal.Decimal | None

Requested USD amount (for withdrawals)

commission: decimal.Decimal | None

Commission amount (for withdrawals)

closing_cost: decimal.Decimal | None

Closing cost (for withdrawals)

basis: decimal.Decimal | None

Basis amount (for withdrawals)

net_withdrawn_usd: decimal.Decimal | None

Net withdrawn USD (for withdrawals)

__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 RawLedgerUpdate

Bases: object

Parsed ledger update data from Hyperliquid API.

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

timestamp_ms: int

Timestamp in milliseconds

hash: str | None

Transaction hash

delta: dict

Delta type and data

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.

__init__(timestamp_ms, hash, delta)
Parameters

  • timestamp_ms (int) –

  • hash (str | None) –

  • delta (dict) –

Return type

None

fetch_vault_deposits(session, vault_address, start_time=None, end_time=None, server_url='https://api.hyperliquid.xyz', 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

  • session (requests.sessions.Session) – HTTP session with retry logic from create_hyperliquid_session()

  • vault_address (eth_typing.evm.HexAddress) – Vault address to fetch events for

  • start_time (datetime.datetime | None) – Start of time range (inclusive). Defaults to 30 days ago.

  • end_time (datetime.datetime | None) – End of time range (inclusive). Defaults to current time.

  • server_url (str) – Hyperliquid API URL

  • timeout (float) – HTTP request timeout in seconds

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]

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

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