lighter.sdk

Documentation for eth_defi.lighter.sdk Python module.

Authenticated Lighter SDK call helpers.

The official Lighter SDK expects callers to create and pass a short-lived auth token to each authenticated request. This module keeps that SDK optional and provides a small adapter that refreshes the token before expiry and retries a call once after an UnauthorizedException response. The operation receives the token explicitly, so the helper works with any authenticated SDK method and does not need to know its parameter names.

The helper is asynchronous because the official Lighter SDK exposes these operations only as coroutines; it does not introduce asynchronous HTTP into the rest of eth-defi.

Do not wrap a non-idempotent order or withdrawal submission unless the caller can prove that an unauthorised response means the request was not accepted. Use this helper for read-only follow-up calls, such as withdrawal-history polling, where replaying the request is safe.

Authoritative Lighter documentation:

Module Attributes

DEFAULT_LIGHTER_AUTH_TOKEN_TIMEOUT

The Lighter SDK currently defaults auth tokens to ten minutes.

DEFAULT_LIGHTER_AUTH_TOKEN_REFRESH_MARGIN

Refresh a token before its nominal expiry to allow for request latency.

Functions

is_lighter_unauthorized_exception(error)

Return whether an SDK exception indicates an expired or rejected token.

Classes

LighterAuthTokenManager

Manage and retry short-lived auth tokens for asynchronous SDK calls.

Exceptions

LighterAuthTokenError

Raised when an authenticated Lighter SDK token cannot be created.
DEFAULT_LIGHTER_AUTH_TOKEN_TIMEOUT = 600.0

The Lighter SDK currently defaults auth tokens to ten minutes.

DEFAULT_LIGHTER_AUTH_TOKEN_REFRESH_MARGIN = 30.0

Refresh a token before its nominal expiry to allow for request latency.

exception LighterAuthTokenError

Bases: RuntimeError

Raised when an authenticated Lighter SDK token cannot be created.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

is_lighter_unauthorized_exception(error)

Return whether an SDK exception indicates an expired or rejected token.

Lighter SDK releases have exposed the HTTP status as either status or status_code and use UnauthorizedException for the generated error type. Checking these representations keeps this adapter independent of a particular SDK release while avoiding a hard dependency on the optional lighter package.

Parameters

error (BaseException) – Exception raised by an authenticated SDK operation.

Returns

True for a Lighter HTTP 401 or UnauthorizedException.

Return type

bool

class LighterAuthTokenManager

Bases: object

Manage and retry short-lived auth tokens for asynchronous SDK calls.

The manager stores only the current token in memory. token_factory must call the SDK’s token-generation method and return its (token, error) tuple. call passes the token to an arbitrary asynchronous operation, proactively refreshes it before expiry, and retries one rejected token. Token values and SDK error payloads are deliberately excluded from representations and logs.

The token lifetime must match the expiry requested from the SDK. The default is ten minutes, matching the current Lighter SDK default; callers can use a shorter lifetime in tests to exercise rotation.

token_factory: collections.abc.Callable[[], tuple[str | None, object | None]]

Zero-argument SDK callback returning (auth_token, error).

token_lifetime: float

Token lifetime in seconds.

refresh_margin: float

Seconds before expiry at which the current token is refreshed.

clock: collections.abc.Callable[[], float]

Monotonic clock, injectable for deterministic tests.

async call(operation, *, operation_name='Lighter SDK call')

Call an authenticated SDK operation with token refresh and retry.

operation is invoked with the current auth token. Only exceptions recognised by is_lighter_unauthorized_exception() are retried; application errors and transport failures propagate unchanged. A retry warning contains no token, private key or SDK exception payload.

Parameters
Returns

The SDK operation’s result.

Return type

eth_defi.lighter.sdk.T

__init__(token_factory, token_lifetime=600.0, refresh_margin=30.0, clock=<built-in function monotonic>)
Parameters
Return type

None