lighter.valuation

Documentation for eth_defi.lighter.valuation Python module.

Lighter account valuation.

Calculate the net asset value of a Lighter trading account using the public /api/v1/account endpoint.

Lighter returns account equity directly as total_asset_value. For cross margin accounts this value matches collateral + sum(position.unrealized_pnl) within API rounding. This module preserves both values so downstream callers can use the canonical API NAV while still logging a useful breakdown.

from eth_defi.lighter.session import create_lighter_session
from eth_defi.lighter.valuation import fetch_lighter_total_equity

session = create_lighter_session()
result = fetch_lighter_total_equity(session, account_index=123456)

nav = result.get_total()

Functions

`fetch_lighter_account_by_index`(session, ...)	Fetch a raw Lighter account dict by account index.
`fetch_lighter_total_equity`(session, ...[, ...])	Calculate the total equity of a Lighter trading account.
`parse_lighter_account_equity`(account)	Parse a raw Lighter account dict into `LighterEquity`.

Classes

LighterEquity

Equity breakdown for a Lighter trading account.

class LighterEquity

Bases: object

Equity breakdown for a Lighter trading account.

See fetch_lighter_total_equity().

__init__(account_index, collateral, unrealised_pnl, total_asset_value, available_balance, initial_margin_requirement, maintenance_margin_requirement, position_count)

Parameters

account_index (int) –
collateral (decimal.Decimal) –
unrealised_pnl (decimal.Decimal) –
total_asset_value (decimal.Decimal) –
available_balance (decimal.Decimal) –
initial_margin_requirement (decimal.Decimal) –
maintenance_margin_requirement (decimal.Decimal) –
position_count (int) –

Return type

None

calculate_total_from_parts()

Calculate account NAV from collateral and unrealised PnL.

Returns: collateral + unrealised_pnl in USDC.
Return type: decimal.Decimal

get_total()

Return canonical Lighter account NAV.

Lighter exposes total_asset_value directly, so this method returns the API value instead of recomputing it locally. Use calculate_total_from_parts() for a collateral plus PnL sanity check.

Returns: Account net asset value in USDC.
Return type: decimal.Decimal

fetch_lighter_account_by_index(session, account_index, timeout=30.0)

Fetch a raw Lighter account dict by account index.

Parameters

session (eth_defi.lighter.session.LighterSession) – Lighter HTTP session.
account_index (int) – Lighter account index.
timeout (float) – HTTP request timeout.

Returns

Raw account dict from the first accounts response item.

Raises

ValueError – If the response contains no accounts.

Return type

dict[str, Any]

fetch_lighter_total_equity(session, account_index, timeout=30.0)

Calculate the total equity of a Lighter trading account.

Uses Lighter’s public /api/v1/account?by=index&value={account_index} endpoint. No API key is required. The returned LighterEquity.get_total() value is the canonical total_asset_value reported by Lighter, denominated in USDC.

Authoritative endpoint documentation: https://apidocs.lighter.xyz/reference/account

Parameters

session (eth_defi.lighter.session.LighterSession) – Lighter HTTP session.
account_index (int) – Lighter account index.
timeout (float) – HTTP request timeout.

Returns

LighterEquity with NAV, collateral, unrealised PnL, available balance, margin requirements and position count.

Raises

ValueError – If the API returns no account or malformed decimal fields.

Return type

eth_defi.lighter.valuation.LighterEquity

parse_lighter_account_equity(account)

Parse a raw Lighter account dict into LighterEquity.

The Lighter API uses strings for decimal values. This parser converts them to Decimal and treats missing optional balances as zero.

Parameters: account (dict[str, Any]) – Raw account dict from /api/v1/account.
Returns: Parsed equity breakdown.
Raises: ValueError – If required account fields are missing or malformed.
Return type: eth_defi.lighter.valuation.LighterEquity