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 — LLP account index

No authentication required.

For more information about Lighter:

• Lighter

• Lighter API docs

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.

class LighterPoolDetail

Bases: object

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

Includes share price history and daily returns from pool_info.

__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

class LighterPoolSummary

Bases: object

Summary information for a Lighter pool from the bulk listing.

From /api/v1/publicPoolsMetadata.

__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

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 to identify the LLP pool.

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]

fetch_system_config(session, timeout=30.0)

Fetch Lighter system configuration.

Returns system config including the LLP account index.

Parameters

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

• timeout (float) – HTTP request timeout.

Returns

System config dict with key field liquidity_pool_index.

Return type

dict[str, Any]

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