lighter.daily_metrics

Documentation for eth_defi.lighter.daily_metrics Python module.

Lighter daily pool metrics with DuckDB storage.

This module provides a daily pipeline for scanning Lighter pool metrics and storing them in a DuckDB database.

The pipeline:

1. Bulk-fetches all pools from /api/v1/publicPoolsMetadata

2. Filters by TVL and open status

3. Fetches per-pool share price history via /api/v1/account

4. Stores daily prices and metadata in DuckDB

Example:

from eth_defi.lighter.session import create_lighter_session
from eth_defi.lighter.daily_metrics import run_daily_scan

session = create_lighter_session()
db = run_daily_scan(session, min_tvl=1_000, max_pools=100)
print(f"Stored metrics for {db.get_pool_count()} pools")
db.close()

Functions

fetch_and_store_pool(session, db, summary[, ...])	Fetch a single pool's details and store metrics in the database.
run_daily_scan(session[, db_path, min_tvl, ...])	Run the daily Lighter pool metrics scan.

Classes

LighterDailyMetricsDatabase

DuckDB database for storing Lighter pool daily metrics.

class LighterDailyMetricsDatabase

Bases: object

DuckDB database for storing Lighter pool daily metrics.

Stores two tables:

• pool_metadata: Pool information (name, description, fees, TVL, etc.)

• pool_daily_prices: Daily share price time series with returns

Parameters

path – Path to the DuckDB database file.

__init__(path)

Parameters

path (pathlib.Path) –

close()

Close database connection.

get_all_daily_prices()

Retrieve all daily price data.

Returns

DataFrame with columns: account_index, date, share_price, tvl, daily_return, annual_percentage_yield.

Return type

pandas.DataFrame

get_all_pool_metadata()

Retrieve all pool metadata ordered by TVL.

Returns

DataFrame with pool metadata.

Return type

pandas.DataFrame

get_pool_count()

Get number of pools with daily price data.

Returns

Count of unique pools.

Return type

int

get_pool_daily_price_count(account_index)

Get number of daily price records for a specific pool.

Parameters

account_index (int) – Pool account index.

Returns

Count of daily price records.

Return type

int

get_pool_daily_prices(account_index)

Get daily prices for a specific pool.

Parameters

account_index (int) – Pool account index.

Returns

DataFrame with daily price data for the pool.

Return type

pandas.DataFrame

get_pool_last_date(account_index)

Get the latest date with price data for a pool.

Parameters

account_index (int) – Pool account index.

Returns

Latest date or None if no data.

Return type

Optional[datetime.date]

get_vault_count()

Get number of pools with daily price data.

Alias for get_pool_count() to unify the interface across Hyperliquid, GRVT, and Lighter scanners.

Returns

Count of unique pools.

Return type

int

save()

Force checkpoint to disk.

upsert_daily_prices(rows, cutoff_date=None)

Bulk upsert daily price rows for a pool.

Parameters

• rows (list[tuple]) – List of tuples: (account_index, date, share_price, tvl, daily_return, annual_percentage_yield, written_at).

• cutoff_date (Optional[datetime.date]) – If provided, only store rows up to this date (inclusive). Used for incremental scanning / testing.

upsert_pool_metadata(account_index, name, description=None, l1_address=None, is_llp=False, status=0, operator_fee=None, total_asset_value=None, annual_percentage_yield=None, sharpe_ratio=None, created_at=None)

Insert or update pool metadata.

Parameters

• account_index (int) – Pool account index (primary key).

• name (str) – Pool display name.

• description (Optional[str]) – Pool description text.

• l1_address (Optional[str]) – L1 Ethereum address.

• is_llp (bool) – Whether this is the LLP protocol pool.

• status (int) – Pool status code from the API (0 = active).

• operator_fee (Optional[float]) – Operator fee percentage.

• total_asset_value (Optional[float]) – Total value locked in USDC.

• annual_percentage_yield (Optional[float]) – Current APY.

• sharpe_ratio (Optional[float]) – Risk-adjusted return metric.

• created_at (Optional[datetime.datetime]) – Pool creation timestamp.

fetch_and_store_pool(session, db, summary, cutoff_date=None, timeout=30.0)

Fetch a single pool’s details and store metrics in the database.

Parameters

• session (eth_defi.lighter.session.LighterSession) – HTTP session with rate limiting.

• db (eth_defi.lighter.daily_metrics.LighterDailyMetricsDatabase) – The metrics database to write into.

• summary (eth_defi.lighter.vault.LighterPoolSummary) – Pool summary from the bulk listing.

• cutoff_date (Optional[datetime.date]) – If provided, only store price data up to this date.

• timeout (float) – HTTP request timeout.

Returns

True if the pool was successfully processed.

Return type

bool

run_daily_scan(session, db_path=PosixPath('/home/runner/.tradingstrategy/vaults/lighter-pools.duckdb'), min_tvl=1000, max_pools=200, max_workers=16, cutoff_date=None, timeout=30.0, pool_indices=None)

Run the daily Lighter pool metrics scan.

1. Bulk-fetches all pools from publicPoolsMetadata

2. Filters by TVL and pool limit (or by explicit index list)

3. Fetches per-pool details and share price history in parallel

4. Stores everything in DuckDB

Parameters

• session (eth_defi.lighter.session.LighterSession) – HTTP session with rate limiting.

• db_path (pathlib.Path) – Path to the DuckDB database file.

• min_tvl (float) – Minimum TVL in USDC to include a pool. Ignored when pool_indices is provided.

• max_pools (int) – Maximum number of pools to process (sorted by TVL descending). Ignored when pool_indices is provided.

• max_workers (int) – Number of parallel workers for fetching pool details.

• cutoff_date (Optional[datetime.date]) – If provided, only store price data up to this date. Used for incremental scanning / testing.

• timeout (float) – HTTP request timeout.

• pool_indices (Optional[list[int]]) – If provided, only scan these specific pool account indices. Overrides min_tvl and max_pools filters.

Returns

The metrics database instance.

Return type

eth_defi.lighter.daily_metrics.LighterDailyMetricsDatabase