lighter.vault

Documentation for eth_defi.lighter.vault Python module.

Lighter pool data extraction and analysis.

This module provides functionality for extracting Lighter pool data via public endpoints:

• Pool listing via /api/v1/publicPoolsMetadata — bulk fetch all pools with TVL, APY, Sharpe ratio, and operator fee

• Pool details (share price history, daily returns, positions) via /api/v1/account — per-pool detailed data

• System config via /api/v1/systemConfig — reported LLP account index

No authentication required.

For more information about Lighter:

• Lighter

• Lighter API docs

Module Attributes

LIGHTER_LLP_NAME	Display-name fallback for the canonical protocol liquidity pool.
LIGHTER_LLP_DESCRIPTION	Description fallback for the same protocol-operated insurance pool.

Functions

fetch_all_pools(session[, timeout, page_size])	Fetch all Lighter public pools.
fetch_pool_detail(session, account_index[, ...])	Fetch detailed pool data including share price history.
fetch_pool_total_shares_history(session, ...)	Fetch historical total shares from the PnL endpoint.
fetch_system_config(session[, timeout])	Fetch Lighter system configuration.
pool_detail_to_daily_dataframe(detail[, ...])	Convert pool detail share prices into a daily DataFrame.

Classes

LighterPoolDetail	Detailed pool information from the /api/v1/account endpoint.
LighterPoolSummary	Summary information for a Lighter pool from the bulk listing.

LIGHTER_LLP_NAME = 'Lighter Liquidity Provider (LLP)'

Display-name fallback for the canonical protocol liquidity pool. The Robinhood deployment currently returns an empty API name for this account.

LIGHTER_LLP_DESCRIPTION = 'Protocol-operated liquidity and insurance pool that provides market-making liquidity and handles liquidations on Lighter.'

Description fallback for the same protocol-operated insurance pool.

class LighterPoolSummary

Bases: object

Summary information for a Lighter pool from the bulk listing.

From /api/v1/publicPoolsMetadata.

account_index: int

Pool account index (int64 primary identifier)

name: str

Pool display name (e.g. “ETH 3x long”)

l1_address: str

Operator address from the API’s legacy l1_address field

annual_percentage_yield: float

Annual percentage yield

sharpe_ratio: Optional[float]

Risk-adjusted return metric

operator_fee: float

Operator fee percentage (e.g. 10.0 = 10%)

total_asset_value: float

Total asset value (TVL) in the deployment’s collateral currency

total_shares: int

Total shares outstanding

status: int

Pool status code (0 = active)

account_type: int

Account type code (2 = pool)

master_account_index: int

Master account index (operator’s main account)

created_at: Optional[datetime.datetime]

Creation timestamp

is_llp: bool

Whether this is the LLP (Lighter Liquidity Pool) protocol pool

__init__(account_index, name, l1_address, annual_percentage_yield, sharpe_ratio, operator_fee, total_asset_value, total_shares, status, account_type, master_account_index, created_at, is_llp=False)

Parameters

• account_index (int) –

• name (str) –

• l1_address (str) –

• annual_percentage_yield (float) –

• sharpe_ratio (Optional[float]) –

• operator_fee (float) –

• total_asset_value (float) –

• total_shares (int) –

• status (int) –

• account_type (int) –

• master_account_index (int) –

• created_at (Optional[datetime.datetime]) –

• is_llp (bool) –

Return type

None

class LighterPoolDetail

Bases: object

Detailed pool information from the /api/v1/account endpoint.

Includes share price history and daily returns from pool_info.

account_index: int

Pool account index

name: str

Pool display name

description: str

Pool description text

total_asset_value: float

Total asset value in the deployment’s collateral currency

operator_fee: float

Operator fee percentage (e.g. 10.0 = 10%)

annual_percentage_yield: float

Annual percentage yield

sharpe_ratio: Optional[float]

Sharpe ratio

share_prices: list[tuple[int, float]]

Historical share prices as (timestamp_seconds, share_price) tuples

daily_returns: list[tuple[int, float]]

Historical daily returns as (timestamp_seconds, daily_return) tuples

total_shares: int

Total shares outstanding

operator_shares: int

Operator’s shares

__init__(account_index, name, description, total_asset_value, operator_fee, annual_percentage_yield, sharpe_ratio, share_prices, daily_returns, total_shares, operator_shares)

Parameters

• account_index (int) –

• name (str) –

• description (str) –

• total_asset_value (float) –

• operator_fee (float) –

• annual_percentage_yield (float) –

• sharpe_ratio (Optional[float]) –

• share_prices (list[tuple[int, float]]) –

• daily_returns (list[tuple[int, float]]) –

• total_shares (int) –

• operator_shares (int) –

Return type

None

fetch_system_config(session, timeout=30.0)

Fetch Lighter system configuration.

Returns system config including the deployment’s reported LLP account index. Deployment configuration may override a stale reported value.

Parameters

• session (eth_defi.lighter.session.LighterSession) – HTTP session.

• timeout (float) – HTTP request timeout.

Returns

System config dict with reported liquidity_pool_index field.

Return type

dict[str, Any]

fetch_all_pools(session, timeout=30.0, page_size=100)

Fetch all Lighter public pools.

Uses /api/v1/publicPoolsMetadata with pagination. Also fetches system config and applies any deployment-specific LLP account override to identify the canonical pool exactly.

Parameters

• session (eth_defi.lighter.session.LighterSession) – HTTP session.

• timeout (float) – HTTP request timeout.

• page_size (int) – Number of pools per page (max 100).

Returns

List of LighterPoolSummary objects.

Return type

list[eth_defi.lighter.vault.LighterPoolSummary]

fetch_pool_detail(session, account_index, timeout=30.0)

Fetch detailed pool data including share price history.

Uses /api/v1/account?by=index&value={account_index}. The response includes pool_info with share_prices and daily_returns arrays for pool accounts.

Parameters

• session (eth_defi.lighter.session.LighterSession) – HTTP session.

• account_index (int) – Pool account index.

• timeout (float) – HTTP request timeout.

Returns

LighterPoolDetail with share price history.

Return type

eth_defi.lighter.vault.LighterPoolDetail

fetch_pool_total_shares_history(session, account_index, start_timestamp=None, timeout=30.0)

Fetch historical total shares from the PnL endpoint.

Uses /api/v1/pnl at daily resolution to get pool_total_shares at each timestamp. This is the only endpoint that provides full history for all pool types (including user pools).

The returned shares can be combined with share prices to compute historical TVL: tvl = pool_total_shares * share_price.

Parameters

• session (eth_defi.lighter.session.LighterSession) – HTTP session.

• account_index (int) – Pool account index.

• start_timestamp (Optional[int]) – Unix timestamp for the start of the range. Defaults to Jan 1 2025.

• timeout (float) – HTTP request timeout.

Returns

Mapping of {date: pool_total_shares}.

Return type

dict[datetime.date, int]

pool_detail_to_daily_dataframe(detail, total_shares_by_date=None)

Convert pool detail share prices into a daily DataFrame.

Takes the share price history from the /api/v1/account endpoint and produces a DataFrame indexed by date with share_price, daily_return, and tvl columns.

Historical TVL is computed as pool_total_shares * share_price when total_shares_by_date is provided (from fetch_pool_total_shares_history()). Without it, TVL defaults to 0.

The share price array from the API contains daily entries with unix timestamps. We convert to dates and compute daily returns via pct_change().

Parameters

• detail (eth_defi.lighter.vault.LighterPoolDetail) – Pool detail with share_prices array.

• total_shares_by_date (Optional[dict[datetime.date, int]]) – Mapping of {date: pool_total_shares} from the PnL endpoint. Used to compute historical TVL.

Returns

DataFrame indexed by date with share_price, daily_return, and tvl columns. Empty if insufficient data.

Return type

pandas.DataFrame