Lighter

Lighter is a decentralized central-limit-order-book exchange for spot and perpetual futures. The venue settles through an Ethereum zero-knowledge rollup, while matching and sequencing run off-chain.

The NautilusTrader Lighter adapter is implemented by the nautilus-lighter crate. It provides Rust data and execution clients, typed REST and WebSocket models, and an in-tree L2 transaction signer for the venue's Schnorr / ECgFp5 signing flow.

Overview

The adapter consists of the following main components:

• LighterRawHttpClient: low-level REST client for the public and account endpoints.
• LighterHttpClient: domain client which parses instruments, trades, books, orders, and account state into Nautilus model types.
• LighterWebSocketClient: reconnecting WebSocket client for public market and private account streams.
• LighterDataClient: Nautilus data client for instruments, trades, quotes, and L2 MBP books.
• LighterExecutionClient: Nautilus execution client for account streams, order submission, modification, cancellation, and reconciliation reports.
• LighterDataClientFactory and LighterExecutionClientFactory: live-node factory wiring.

The Python surface is intentionally narrow. The Python extension exposes configuration, environment selection, factory classes, and integrator revocation; data and execution clients are consumed through the Rust trait surface.

Examples

The adapter includes Python v2 and Rust live-node examples. The Python examples live in python/examples/lighter/ and default to a dry build: they build the node, register the tester, and exit unless --run is passed.

cd python
.venv/bin/python examples/lighter/data_tester.py --lighter-environment testnet
.venv/bin/python examples/lighter/exec_tester.py --lighter-environment testnet

Pass --run to connect to Lighter. The execution tester remains in dry_run mode unless --live-orders is also passed.

cd python
.venv/bin/python examples/lighter/data_tester.py \
    --lighter-environment mainnet \
    --instrument BTC-PERP.LIGHTER \
    --run
.venv/bin/python examples/lighter/exec_tester.py \
    --lighter-environment mainnet \
    --instrument DOGE-PERP.LIGHTER \
    --run

Rust examples live under crates/adapters/lighter/examples/ and run immediately:

cargo run --example lighter-data-tester --package nautilus-lighter --features examples
cargo run --example lighter-exec-tester --package nautilus-lighter --features examples

:::warning Examples can connect to live venues. Execution examples with live order flow enabled can submit orders when pointed at a funded mainnet account. Review the selected instrument, quantity, and environment before running them. :::

Product support

Limitations

The current adapter scope is deliberately narrower than the venue's full transaction surface:

• Grouped order lists, OCO/OTO groups, bracket orders, TWAP, trailing stops, and iceberg display size are not implemented.
• Native batch submit and native batch cancel are wired for independent order operations only. Batch submit sends independent L2CreateOrder txs in one sendTxBatch, and batch cancel signs independent L2CancelOrder txs in one sendTxBatch. Both are capped at 15 txs per batch.
• Grouped venue orders remain out of scope: batch submit does not use CreateGroupedOrders and does not provide atomic OCO/OTO or bracket grouping.
• CancelAllOrders uses cached open orders for the requested instrument. The adapter does not use Lighter's native account-wide cancel-all transaction because it can affect unrelated markets.
• Spot trading supports market and limit orders. Conditional stop-loss and take-profit orders are limited to perpetual markets.
• Account state and position reports come from private WebSocket streams. query_account and position status generation replay the latest cached stream state.
• Unscoped order reconciliation is bounded to configured or observed active markets to avoid a full venue-wide fan-out under the standard REST quota.
• Historical trade requests require credentials for master accounts and sub-accounts.

Symbology

Lighter identifies markets by numeric market_index values. The adapter bootstraps the mapping from GET /api/v1/orderBookDetails, then converts the raw venue symbol into a Nautilus InstrumentId.

The suffix disambiguates spot and perpetual listings that share the same venue symbol. Outbound requests strip the suffix and use the cached market_index.

Environments

Use LighterEnvironment::Mainnet or LighterEnvironment::Testnet in data and execution configuration. URL overrides are available for private gateways or local test fixtures.

Integrator attribution

Submitted create and modify order transactions carry the NautilusTrader integrator account index in Lighter's L2TxAttributes. This helps us gauge real usage of the integration and prioritize ongoing maintenance. Maker and taker integrator fees are set to zero, so attribution adds no trading cost.

Lighter requires an ApproveIntegrator approval before these attributes can be attached to orders. During startup, the execution client submits the required zero-fee approval for the configured L2 account.

Revoking the approval

Use revocation as cleanup when leaving the adapter. It sends the same ApproveIntegrator tx with approval_expiry = 0 and every max fee set to zero; the next execution-client startup records a fresh zero-fee approval.

export LIGHTER_API_KEY_INDEX=0
export LIGHTER_API_SECRET=REPLACE_ME
export LIGHTER_ACCOUNT_INDEX=123456
cargo run -p nautilus-lighter --bin lighter-integrator-revoke           # mainnet
cargo run -p nautilus-lighter --bin lighter-integrator-revoke testnet   # testnet

Script source: crates/adapters/lighter/bin/integrator_revoke.rs.

# Python (PyO3 binding) - reads the same env vars as the Rust bin
from nautilus_trader.core.nautilus_pyo3 import revoke_lighter_integrator
from nautilus_trader.core.nautilus_pyo3 import LighterEnvironment

await revoke_lighter_integrator()                            # mainnet (default)
await revoke_lighter_integrator(LighterEnvironment.TESTNET)  # testnet

The Rust script prints a summary of the action and pauses for an Enter keypress before signing or sending; abort with Ctrl+C before that point if anything in the summary looks wrong. The Python binding does not prompt: review the active env vars yourself before calling.

Data subscriptions

Only BookType::L2_MBP is accepted for book-delta and depth10 subscriptions. Other book types return an error before subscribing.

The WebSocket order book initializes only from subscribed/order_book. If an update/order_book arrives before that snapshot, the adapter drops it and waits for the real snapshot because incremental updates do not contain the full visible book.

Bar subscriptions use the venue's candle/{market_id}/{resolution} WebSocket channel. Lighter batches in-progress updates for the open bar every ~500 ms; the adapter emits a Nautilus Bar only when the candle start timestamp advances, so consumers see one event per closed period. The in-progress cache is cleared on reconnect and on unsubscribe.

The stream supports 1m, 5m, 15m, 30m, 1h, 4h, 12h, and 1d. 1w is REST-only via request_bars; subscribing to a 1-WEEK bar type returns an error.

Instrument status subscriptions replay the latest cached orderBookDetails status when available and otherwise fetch a REST snapshot. Lighter does not expose a WebSocket status-change stream.

Funding-rate subscriptions use market_stats.current_funding_rate, which is Lighter's estimate for the upcoming payment. Historical funding-rate requests use /api/v1/fundings at 1h resolution and map settled rows to FundingRateUpdate with interval=60. The REST direction field controls the sign: long stays positive because longs pay shorts, while short is mapped negative because shorts pay longs. The adapter does not use account-specific positionFunding payloads for public funding history.

Trade subscriptions use the public WebSocket trade stream. Historical trade requests use /api/v1/trades; live mainnet testing shows that endpoint rejects unauthenticated requests. The data client mints a Lighter auth token for this request when credentials are available. Without credentials, the data client logs a warning and rejects the request.

Unsupported data requests

request_quotes is not implemented. Lighter exposes best bid and offer data through the WebSocket ticker stream, but the REST endpoints available to the adapter do not provide a timestamped quote snapshot or quote history that can map safely to QuoteTick.

request_book_depth is not implemented. The documented REST book endpoints do not provide a venue event timestamp for OrderBookDepth10.ts_event; use subscribe_book_depth10 for live depth10 snapshots or request_book_snapshot for a REST OrderBook snapshot.

Orders capability

Order identification

Lighter uses a numeric venue order index and a caller-supplied client_order_index. The adapter derives the Lighter client_order_index from the Nautilus ClientOrderId and keeps a local map so private WebSocket reports can recover the original client order ID.

Query paths can use either the Nautilus client order ID or the numeric venue order ID when the required mapping is available.

Order types

Conditional order types are available for perpetual markets only. Spot conditional orders are denied locally because Lighter rejects them at the venue. Conditional order types must include a trigger_price. STOP_MARKET and MARKET_IF_TOUCHED are denied upfront if the trigger is missing, and all conditional types are denied if the trigger truncates to 0 ticks at the instrument's price precision.

Lighter's market-style orders require a worst-acceptable price field on the wire. The adapter derives it automatically: MARKET orders read the cached far-side QuoteTick (ask for buys, bid for sells); STOP_MARKET and MARKET_IF_TOUCHED use the order's trigger_price. The base is widened by market_order_slippage_bps (default 50 bps = 0.5%), rounded conservatively at the instrument's price precision (ceil for buys, floor for sells). A MARKET order submitted before the strategy has subscribed to quotes is denied with a clear error. Override per order via SubmitOrder.params["market_order_slippage_bps"].

Contingent orders

Order options

Adapter order params

Time in force

For MARKET, STOP_MARKET, and MARKET_IF_TOUCHED, the adapter maps the wire time-in-force to Lighter ImmediateOrCancel because the venue rejects market-style orders sent as GoodTillTime. Plain MARKET orders set OrderExpiry = 0. Conditional market orders (STOP_MARKET and MARKET_IF_TOUCHED) keep a positive OrderExpiry so the trigger can rest, and the wire ImmediateOrCancel applies only after the trigger fires. Nautilus IOC cannot be represented for conditional market orders, so the adapter denies it locally with a clear error. Conditional limit orders (STOP_LIMIT and LIMIT_IF_TOUCHED) can use Nautilus IOC: the trigger rests with a positive OrderExpiry, and the child limit order uses Lighter ImmediateOrCancel after the trigger fires.

When no explicit GTD expiry is supplied, limit-style GTC, DAY, and GTD orders default to the current time plus 28 days. Conditional GTC, DAY, and limit-style IOC orders use the same default expiry. The venue rejects -1 as an invalid expiry for these TIFs. Live testing has also shown that very short GTD expiries can be rejected by the sequencer with 21711 invalid expiry; use a venue-accepted expiry horizon for live GTD tests.

Execution instructions

Use post_only on limit-style orders. The adapter does not synthesize maker-only market orders. Live mainnet testing confirms reduce_only=true for closing perpetual positions. Invalid reduce-only opens can be dropped by Lighter without a venue order report; the adapter reconciles them as INFLIGHT_TIMEOUT rather than a venue-supplied rejection reason.

Advanced order features

Order operations

The native venue CancelAllOrders transaction is account-wide. The adapter deliberately cancels cached open orders per instrument to avoid touching unrelated markets.

SubmitOrderList and BatchCancelOrders use sendTxBatch for independent operations. They do not create grouped venue orders, do not provide atomic OCO/OTO or bracket semantics, and do not use account-wide CancelAllOrders for scoped cancels.

The sendTxBatch response exposes one top-level API code and a tx_hash list; it does not expose per-order API rejection fields. A successful batch response queues the signed transactions, then private account streams report the final per-order submit, cancel, fill, and reject outcomes.

UpdateLeverage is exposed as LighterExecutionClient::update_leverage(instrument_id, initial_margin_fraction, margin_mode). The initial_margin_fraction is in venue ticks (1e-4 fraction): 500 is 5% initial margin (20x leverage), 1000 is 10% (10x), and so on.

UpdateLeverage has no oracle test vectors in this repo; the body field order is pinned against the cgo header from the upstream signer, and the wire format was verified by submitting a signed tx to Lighter mainnet that the sequencer accepted.

Order querying and reconciliation

Account and position management

Authenticated execution clients subscribe to these private streams:

• account_all_orders: order status reports.
• account_all_trades: fill reports.
• account_all_positions: position snapshots.
• account_all_assets: account balance and margin snapshots.

The execution client requires credentials before connecting because private account streams and nonce refresh are mandatory. A client can be constructed without credentials, but live execution will not connect until private_key, account_index, and api_key_index resolve.

Perpetual positions are reported in netting mode: one position per market. Spot balances arrive through account asset state rather than position reports. Each account_all_positions frame is treated as a complete venue snapshot. If a new frame omits a previously cached market, the adapter emits a flat position report for that instrument; an empty positions map clears all cached perpetual positions and emits a flat report for each.

Liquidation and ADL handling

Funding rates

Perpetual market_stats frames emit MarkPriceUpdate, IndexPriceUpdate, and FundingRateUpdate events. Spot spot_market_stats frames emit IndexPriceUpdate events.

Historical funding-rate requests use the public /api/v1/fundings endpoint and emit FundingRateUpdate responses for settled hourly rows.

Account tiers

Lighter assigns each account a tier that governs latency, rate limits, and fees. Standard is the zero-fee default; the higher tiers are opt-in on the venue and trade fees for lower latency and higher throughput. The execution client detects the tier on connect (via GET /api/v1/account) and logs it in blue, including the raw account_type code for any tier this adapter does not yet recognize. Detection is informational only: the adapter never raises rate limits on its own, because the higher venue limits require registering the caller IP with Lighter, so a higher tier does not by itself guarantee the higher limit is active for your connection.

Premium latency, fees, and sendTx throughput scale with staked LIT, and the schedule can change; see the Lighter docs for the current figures. To actually use a higher tier's limits, register the caller IP with Lighter and set the quota explicitly (see Rate limiting).

Rate limiting

Lighter applies rate limits to both IP address and L1 address. The execution client detects the account tier on connect and logs it (see Account tiers), but it does not raise limits automatically. By default both clients use the conservative standard-account quotas. To use a higher tier's throughput, register the caller IP with Lighter and set the quota explicitly in the client config:

• rest_quota_per_min: REST read-bucket quota in requests per minute. Unset keeps 60 req/min. Available on both the data and execution clients.
• sendtx_quota_per_min: transaction quota in requests per minute, metered in a bucket separate from reads. Unset keeps it at the standard 60 req/min, independent of rest_quota_per_min. Execution client only.

The venue meters transactions per account across both transports in one bucket. The execution client enforces sendtx_quota_per_min with a single shared limiter across both paths it submits on: the WebSocket sendTx path (single order submit, cancel, modify, leverage) and the HTTP sendTx / sendTxBatch endpoints (native batch submit/cancel and the startup integrator approval). Their combined rate therefore stays under the one venue limit.

Premium volume quota is a separate venue constraint for L2CreateOrder, L2CancelAllOrders, L2ModifyOrder, and L2CreateGroupedOrders. The adapter does not inspect remaining quota; use venue account tools if a strategy depends on premium or plus limits.

Connection management

The WebSocket client sends heartbeats every 30 seconds and reconnects with exponential backoff from 250 milliseconds up to 30 seconds. Private account subscriptions use Lighter auth tokens with an 8-hour maximum TTL; the adapter refreshes tokens 15 minutes before expiry and resubscribes account channels.

On execution reconnect, the adapter refreshes the nonce baseline through GET /api/v1/nextNonce before it resumes signed transaction dispatch.

LighterExecutionClient::connect() waits up to 30 seconds for every account stream (account_all_orders, account_all_trades, account_all_positions, account_all_assets) to deliver its first frame before returning. Lighter has no REST endpoint for account or position state, so the WebSocket frames are the only ground truth: returning earlier would let strategies race the venue's initial state and find the venue order id lookup table or position cache empty. The gate clears any prior-session position and account caches at the start of each connect attempt so a reconnect cycle observes the new session's frames, not stale data. By contrast, transparent WebSocket reconnects do not re-enter connect(): they keep cached positions until the next account_all_positions frame, then apply the same complete-snapshot replacement rules.

API credentials

Lighter signing requires all three credential values:

• Account index: numeric Lighter account identifier.
• API key index: numeric API key slot, 0..=254. Indices 0..=3 are reserved for Lighter desktop/mobile clients.
• API private key: 40-byte hex private key, with or without a 0x prefix.

Config values take precedence. When config fields are omitted, the adapter reads environment variables based on the selected environment.

Execution rejects incomplete credentials. The data client can run without credentials for public streams and public REST endpoints; authenticated data requests such as request_trades use the same values when all three are available.

Configuration

Data client configuration options

Execution client configuration options

Configuration example

use nautilus_lighter::{
    common::enums::LighterEnvironment,
    config::{LighterDataClientConfig, LighterExecClientConfig},
};

let data_config = LighterDataClientConfig {
    environment: LighterEnvironment::Testnet,
    ..Default::default()
};

let exec_config = LighterExecClientConfig::builder()
    .trader_id(trader_id)
    .account_id(account_id)
    .environment(LighterEnvironment::Testnet)
    .active_markets(vec![0])
    .build();

The execution config above resolves credentials from the matching testnet environment variables. Set account_index, api_key_index, and private_key directly to override environment lookup. Set active_markets to the venue market IDs that should be checked for open orders during cold-start reconciliation.

Official documentation

• Trading and signing: https://apidocs.lighter.xyz/docs/trading
• API keys: https://apidocs.lighter.xyz/docs/api-keys
• Rate limits: https://apidocs.lighter.xyz/docs/rate-limits
• Volume quota: https://apidocs.lighter.xyz/docs/volume-quota-program
• Data structures, constants, and errors: https://apidocs.lighter.xyz/docs/data-structures-constants-and-errors
• REST OpenAPI: https://raw.githubusercontent.com/elliottech/lighter-python/main/openapi.json
• WebSocket reference: https://apidocs.lighter.xyz/docs/websocket-reference

Contributing

:::info For additional features or to contribute to the Lighter adapter, please see our contributing guide. :::