lighter.api

Documentation for eth_defi.lighter.api Python module.

Lighter API helpers for manual trading workflows.

This module follows the same api.py / session.py split as other exchange-style integrations in eth_defi. It wraps the optional lighter-python SDK for scripts and manual integration tests. It covers account polling, API-key registration, small trade sizing and simple market-order round trips.

Authoritative documentation:

Lighter API keys: https://apidocs.lighter.xyz/docs/api-keys
Deposits and withdrawals: https://apidocs.lighter.xyz/docs/deposits-transfers-and-withdrawals

Functions

`ceil_decimal`(value, step)	Round a decimal up to the next step.
`fetch_lighter_account`(lighter, account_index)	Fetch a Lighter account by index.
`get_eth_position`(account[, market_index])	Read a signed ETH position size from a Lighter account response.
`get_lighter_available_balance`(account)	Read the available USDC balance from a Lighter account response.
`get_lighter_collateral`(account)	Read the total USDC collateral from a Lighter account response.
`import_lighter`()	Import the optional Lighter SDK with an actionable error.
`register_lighter_api_key`(lighter, web3, ...)	Generate and register a Lighter API key through a Safe.
`resolve_eth_trade_amounts`(lighter[, ...])	Resolve Lighter ETH market minimums and choose manual-test sizes.
`sdk_pubkey_to_bytes`(public_key)	Convert a Lighter SDK public-key string to on-chain bytes.
`trade_eth_roundtrip`(lighter, account_index, ...)	Open and close an ETH long on Lighter.
`unwrap_lighter_account`(account)	Unwrap a Lighter account API response.
`wait_for_eth_position`(lighter, ...[, timeout])	Wait until the ETH position matches a predicate.
`wait_for_lighter_account`(lighter, safe_address)	Wait until Lighter API exposes an account for an L1 owner.
`wait_for_lighter_collateral`(lighter, ...[, ...])	Wait until the Lighter account shows deposited collateral.
`withdraw_from_lighter`(lighter, ...)	Request a secure USDC withdrawal from Lighter.

Classes

LighterTradeAmounts

USDC and ETH sizes used by a Lighter manual trade.

class LighterTradeAmounts

Bases: object

USDC and ETH sizes used by a Lighter manual trade.

Parameters

deposit_usdc – Suggested USDC deposit amount.
position_usdc – Effective ETH long notional in USDC.
base_amount – Lighter integer base amount for the ETH market order.
max_buy_price – Worst acceptable buy price in Lighter integer price units.
min_quote_amount – ETH market minimum quote amount, as reported by Lighter.
min_base_amount – ETH market minimum base amount, as reported by Lighter.

__init__(deposit_usdc, position_usdc, base_amount, max_buy_price, min_quote_amount, min_base_amount)

Parameters

deposit_usdc (decimal.Decimal) –
position_usdc (decimal.Decimal) –
base_amount (int) –
max_buy_price (int) –
min_quote_amount (decimal.Decimal) –
min_base_amount (decimal.Decimal) –

Return type

None

ceil_decimal(value, step)

Round a decimal up to the next step.

Parameters

value (decimal.Decimal) – Value to round.
step (decimal.Decimal) – Rounding step.

Returns

Rounded value.

Return type

decimal.Decimal

async fetch_lighter_account(lighter, account_index)

Fetch a Lighter account by index.

Parameters

lighter (Any) – Imported Lighter SDK module.
account_index (int) – Lighter account index.

Returns

Detailed account model.

Return type

Any

get_eth_position(account, market_index=0)

Read a signed ETH position size from a Lighter account response.

Parameters

account (Any) – Lighter detailed account model.
market_index (int) – Lighter market index.

Returns

Signed ETH position amount.

Return type

decimal.Decimal

get_lighter_available_balance(account)

Read the available USDC balance from a Lighter account response.

Parameters: account (Any) – Lighter account response.
Returns: Available USDC collateral.
Return type: decimal.Decimal

get_lighter_collateral(account)

Read the total USDC collateral from a Lighter account response.

Parameters: account (Any) – Lighter account response.
Returns: Total USDC collateral.
Return type: decimal.Decimal

import_lighter()

Import the optional Lighter SDK with an actionable error.

Returns: Imported lighter module.
Return type: Any

async register_lighter_api_key(lighter, web3, safe, hot_wallet, account_index, api_key_index)

Generate and register a Lighter API key through a Safe.

Parameters

lighter (Any) – Imported Lighter SDK module.
web3 (web3.main.Web3) – Web3 connection.
safe (safe_eth.safe.safe.Safe) – Safe that owns the Lighter account.
hot_wallet (eth_defi.hotwallet.HotWallet) – 1-of-1 Safe owner.
account_index (int) – Lighter account index.
api_key_index (int) – Lighter API-key slot.

Returns

SDK API private key.

Return type

str

async resolve_eth_trade_amounts(lighter, deposit_usdc=None, position_usdc=None)

Resolve Lighter ETH market minimums and choose manual-test sizes.

Parameters

lighter (Any) – Imported Lighter SDK module.
deposit_usdc (Optional[decimal.Decimal]) – Optional explicit deposit amount.
position_usdc (Optional[decimal.Decimal]) – Optional explicit position notional.

Returns

Trade amount configuration.

Return type

eth_defi.lighter.api.LighterTradeAmounts

sdk_pubkey_to_bytes(public_key)

Convert a Lighter SDK public-key string to on-chain bytes.

Parameters: public_key (str) – SDK public-key string, 0x plus 40 bytes.
Returns: Raw public-key bytes for changePubKey.
Return type: bytes

async trade_eth_roundtrip(lighter, account_index, api_private_key, api_key_index, amounts)

Open and close an ETH long on Lighter.

Parameters

lighter (Any) – Imported Lighter SDK module.
account_index (int) – Lighter account index.
api_private_key (str) – SDK API private key.
api_key_index (int) – Lighter API-key slot.
amounts (eth_defi.lighter.api.LighterTradeAmounts) – Trade sizing information.

Return type

None

unwrap_lighter_account(account)

Unwrap a Lighter account API response.

Parameters: account (Any) – Lighter account response. The SDK returns either a DetailedAccounts wrapper with an accounts list or the account object itself.
Returns: The first account object, or None if the response is empty.
Return type: Optional[Any]

async wait_for_eth_position(lighter, account_index, predicate, description, timeout=300)

Wait until the ETH position matches a predicate.

Parameters

lighter (Any) – Imported Lighter SDK module.
account_index (int) – Lighter account index.
predicate (Callable[[decimal.Decimal], bool]) – Function receiving the signed position.
description (str) – Human-readable wait target.
timeout (int) – Maximum wait in seconds.

Returns

Matching position.

Return type

decimal.Decimal

async wait_for_lighter_account(lighter, safe_address, timeout=900)

Wait until Lighter API exposes an account for an L1 owner.

Parameters

lighter (Any) – Imported Lighter SDK module.
safe_address (str) – L1 owner address, usually the Lagoon Safe.
timeout (int) – Maximum wait in seconds.

Returns

Lighter account index.

Return type

int

async wait_for_lighter_collateral(lighter, account_index, expected_usdc, timeout=900)

Wait until the Lighter account shows deposited collateral.

L1 deposits are asynchronous. The Ethereum transaction can be mined before Lighter’s API reflects the credited USDC balance, so callers must wait before registering a trading key and opening a position.

Parameters

lighter (Any) – Imported Lighter SDK module.
account_index (int) – Lighter account index.
expected_usdc (decimal.Decimal) – Expected deposited USDC amount.
timeout (int) – Maximum wait in seconds.

Returns

Observed collateral.

Return type

decimal.Decimal

async withdraw_from_lighter(lighter, account_index, api_private_key, api_key_index, withdraw_usdc)

Request a secure USDC withdrawal from Lighter.

Parameters

lighter (Any) – Imported Lighter SDK module.
account_index (int) – Lighter account index.
api_private_key (str) – SDK API private key.
api_key_index (int) – Lighter API-key slot.
withdraw_usdc (decimal.Decimal) – Human-readable USDC withdrawal amount.

Return type

None