lighter

Lighter.xyz (zklighter)

Lighter is a high-performance ZK-rollup DEX offering perpetual futures and spot trading with sub-second finality. It supports 220+ markets (perpetuals for crypto, stocks, forex, commodities; spot pairs like ETH/USDC). All orders are signed L2 transactions settled on the deployment's L1.

Networks — the user MUST pick one

Lighter runs as two independent deployments. They share the same API shape but have different hosts, accounts, API keys, contracts, markets and quote assets. Credentials from one do not work on the other.

LIGHTER_NETWORK	App	REST base URL	Signing chain ID	L1	Quote
ethereum	https://app.lighter.xyz	https://mainnet.zklighter.elliot.ai	304	Ethereum (1)	USDC
robinhood	https://robinhoodchain.lighter.xyz	https://api.rh.lighter.xyz	466324	Robinhood Chain (4663)	USDG

Testnets: ethereum-testnet (https://testnet.zklighter.elliot.ai) and robinhood-testnet (https://api.rh-testnet.lighter.xyz).

Before the first Lighter call in a session, run lighter_get_network().

• If selected is false, stop and ask the user: "Are you on Lighter (app.lighter.xyz) or Lighter on Robinhood Chain (robinhoodchain.lighter.xyz)?" Do not guess — the wrong choice means wrong markets and failed signatures.
• Then have them set LIGHTER_NETWORK=ethereum or LIGHTER_NETWORK=robinhood (env var or credentials file). Aliases accepted: eth, mainnet, rh, robinhoodchain.
• Every tool errors with a clear message until a network is selected. An explicit LIGHTER_API_URL also counts as a selection and takes precedence.

Network-specific notes:

• Robinhood Chain spot pairs are quoted in USDG (e.g. META/USDG), not USDC. It also lists tokenized stocks (HOOD, SPY, QQQ) and fewer markets overall. Always check lighter_get_markets() rather than assuming a symbol exists.
• Accounts are created by depositing in the respective app. Look up the account index against the selected network — an Ethereum wallet address may have an account on one deployment and not the other.
• Paper trading keeps a separate state file per network.

When to Use Lighter

• Market data — orderbook depth, recent trades, OHLCV candles, funding rates
• Exchange overview — 24h volume, open interest, mark/index prices
• Account queries — positions, balances, active orders, PnL, trade history
• Order management — place limit/market/stop/TP orders, cancel, modify, close-all
• Position management — set leverage, adjust isolated margin
• Fund management — withdraw assets, transfer between perp/spot buckets
• Funding analysis — compare funding rates across Binance, Bybit, Hyperliquid, Lighter

Symbol Convention

• Perp markets use bare tickers: BTC, ETH, SOL, LIT
• Spot markets use quote-qualified pairs: ETH/USDC, LIT/USDC, LINK/USDC
• The / is the discriminator — no --market_type flag needed
• Numeric market_id is also accepted as an escape hatch
• Symbol resolution is automatic with a 5-minute cache

Human-Unit Auto-Scaling

Trading tools accept human-readable prices and amounts (e.g. amount=0.1, price=3200.50). The tools automatically fetch market metadata and scale to integer ticks/lots. Response includes effective_amount and effective_price showing what actually landed after rounding.

Account Setup Flow

Setting up Lighter trading requires two different values from different places:

Step 0: Pick the network

Ask which deployment they trade on and set LIGHTER_NETWORK accordingly (see Networks above). Everything below is per network.

Step 1: Get your Account Index

LIGHTER_ACCOUNT_INDEX is a number (e.g. 12345), not a key.

Ask the user for their Ethereum L1 wallet address (public address, e.g. 0xabc...), then look it up:

lighter_get_account(l1_address="0xabc...")

The response will contain the account index — that's the LIGHTER_ACCOUNT_INDEX.

If no account is found, the user needs to create one first by connecting their wallet and depositing in the app for the selected network (https://app.lighter.xyz or https://robinhoodchain.lighter.xyz).

Step 2: Get API Keys

LIGHTER_PRIVATE_KEY is a hex string — the L2 API private key.

The user generates this on the API keys page of the selected network's app (https://app.lighter.xyz/apikeys or https://robinhoodchain.lighter.xyz/apikeys):

1. Go to the API keys page
2. If using a sub-account, switch to it first
3. Generate a new API key — the private key is shown only once
4. Note the API key index number (this becomes LIGHTER_API_KEY_INDEX)

See the lighter-python setup example for programmatic key generation (requires L1 wallet signature).

Step 3: Configure Credentials

Sanity check before saving:

• LIGHTER_ACCOUNT_INDEX = numeric only (e.g. 12345)
• LIGHTER_PRIVATE_KEY = long hex key string
• LIGHTER_API_KEY_INDEX = small integer key slot (e.g. 4)

Credentials can be set via environment variables OR a credentials file.

Option 1: Environment Variables

LIGHTER_NETWORK=ethereum            # or: robinhood
LIGHTER_PRIVATE_KEY=your_lighter_api_private_key_here
LIGHTER_ACCOUNT_INDEX=your_account_index_here
LIGHTER_API_KEY_INDEX=2

Option 2: Credentials File

~/.lighter/lighter-agent-kit/credentials:

LIGHTER_API_PRIVATE_KEY=...
LIGHTER_ACCOUNT_INDEX=...
LIGHTER_API_KEY_INDEX=...
LIGHTER_NETWORK=robinhood

Environment variables take precedence. Both LIGHTER_PRIVATE_KEY and LIGHTER_API_PRIVATE_KEY are accepted.

Variable	Required	Description
LIGHTER_NETWORK	Yes (unless LIGHTER_API_URL set)	ethereum or robinhood (also ethereum-testnet, robinhood-testnet). No default — the user must choose.
LIGHTER_API_URL	No	Explicit base URL; overrides LIGHTER_NETWORK. LIGHTER_HOST is accepted as an alias.
LIGHTER_PRIVATE_KEY	For trading	Lighter L2 API private key (hex). Not your wallet key.
LIGHTER_ACCOUNT_INDEX	For trading	Your numeric account index on Lighter
LIGHTER_API_KEY_INDEX	No	Which API key slot to use (default 2, range 2-254)

Note: Read-only tools (market data, orderbook, candles, funding rates) work without any keys, but still need LIGHTER_NETWORK. Trading tools require LIGHTER_PRIVATE_KEY and LIGHTER_ACCOUNT_INDEX.

Common Workflows

Check / choose network

lighter_get_network()      # shows selected network, base URL, and the available options

Check Market Info

lighter_get_markets()                        # all markets
lighter_get_markets(filter="perp")           # perps only
lighter_get_markets(market_id=0)             # specific market

Get Orderbook

lighter_get_orderbook(symbol="BTC", limit=20)
lighter_get_orderbook(symbol="ETH/USDC", limit=10)

Get OHLCV Candles

lighter_get_candles(symbol="ETH", resolution="1h", count_back=100)

Check Positions & Balances

lighter_get_account()                        # uses configured account
lighter_get_active_orders(symbol="BTC")
lighter_get_pnl(resolution="1d", count_back=30)

Place Orders (human units, auto-scaled)

# Market buy 0.1 BTC
lighter_create_order(symbol="BTC", side="long", amount=0.1, order_type="market")

# Limit sell 1 ETH at $3200
lighter_create_order(symbol="ETH", side="short", amount=1.0, price=3200, order_type="limit")

# Stop-loss at $2800
lighter_create_order(symbol="ETH", side="short", amount=1.0, price=2800,
                     order_type="stop_loss", trigger_price=2800, reduce_only=true)

Modify / Cancel

lighter_modify_order(symbol="BTC", order_index=12345, amount=0.2, price=61000)
lighter_cancel_order(symbol="BTC", order_index=12345)
lighter_cancel_all_orders()

Close All Positions

# ALWAYS preview first
lighter_close_all_positions(preview=true)
# Then execute after user confirms
lighter_close_all_positions(preview=false)

Leverage & Margin

lighter_set_leverage(symbol="BTC", leverage=10)
lighter_set_leverage(symbol="ETH", leverage=5, margin_mode="isolated")
lighter_adjust_margin(symbol="ETH", amount=100, direction="add")

Withdraw & Transfer

lighter_withdraw(asset="usdc", amount=100)
lighter_transfer_funds(asset="usdc", amount=250, from_route="perp", to_route="spot")

Compare Funding Rates

lighter_get_funding_rates()   # Returns rates from Binance, Bybit, Hyperliquid, Lighter

Paper Trading

Simulate trades against real Lighter order book snapshots — no credentials, no broadcast, no risk. All state is local.

Perp markets only. No spot, no resting limits, no funding accrual. Market orders only (taker fills).

Quick Start

# 1. Create account (once)
lighter_paper_init(collateral=10000, tier="premium")

# 2. Place trades
lighter_paper_order(symbol="BTC", side="long", amount=0.1)
lighter_paper_order(symbol="ETH", side="short", amount=1.0)

# 3. Check status
lighter_paper_status()
lighter_paper_positions()
lighter_paper_health()
lighter_paper_trades(limit=10)

# 4. Reset when done
lighter_paper_reset()

Paper vs Live Caveats

These cause paper-to-live PnL divergence:

1. Maker fills never occur — every fill is charged taker fee
2. No order-impact model — paper orders walk the book but don't move it
3. No latency / partial-fill modeling — fills instantly in full
4. No funding accrual — dominant PnL drag/credit for longer holds
5. Cross-margin only — no isolated margin simulation

Fee Tiers

Tier	Taker bps	Maker bps
standard	0.0	0.0
premium (default)	2.8	0.4
premium_1	2.73	0.39
premium_2	2.66	0.38
premium_3	2.52	0.36
premium_4	2.38	0.34
premium_5	2.24	0.32
premium_6	2.1	0.3
premium_7	1.96	0.28

State file: ~/.lighter/lighter-agent-kit/paper-state.json for ethereum, paper-state-<network>.json for others (override with LIGHTER_PAPER_STATE_PATH env var).

Safety Notes

• lighter_close_all_positions is high-risk. ALWAYS run preview=true first, show the plan to the user, and get explicit confirmation before executing. Never infer intent from vague prompts.
• lighter_withdraw creates a withdrawal request; funds may go through a pending/claim flow.
• Write commands sign and broadcast immediately.
• Private keys are wrapped in SecretValue objects — never attempt to read or display them.

Decision Tree

User Wants	Tool	Key Params
Which deployment am I on / options	lighter_get_network	—
List available markets	lighter_get_markets	filter, market_id
Orderbook snapshot	lighter_get_orderbook	symbol, limit
Recent trade prints	lighter_get_recent_trades	symbol, limit
OHLCV chart data	lighter_get_candles	symbol, resolution, count_back
24h volume/OI/prices	lighter_get_exchange_stats	—
Cross-exchange funding	lighter_get_funding_rates	—
Asset info (decimals, caps)	lighter_get_asset_details	asset_id
Account info/balances	lighter_get_account	account_index
Open orders	lighter_get_active_orders	symbol
Filled/canceled orders	lighter_get_order_history	symbol, limit
Trade history	lighter_get_trade_history	symbol, limit
PnL over time	lighter_get_pnl	resolution, count_back
Place an order	lighter_create_order	symbol, side, amount, price
Cancel one order	lighter_cancel_order	symbol, order_index
Cancel all orders	lighter_cancel_all_orders	—
Modify existing order	lighter_modify_order	symbol, order_index, amount, price
Close all positions	lighter_close_all_positions	preview, slippage
Set leverage	lighter_set_leverage	symbol, leverage, margin_mode
Adjust margin	lighter_adjust_margin	symbol, amount, direction
Withdraw assets	lighter_withdraw	asset, amount, route
Transfer perp/spot	lighter_transfer_funds	asset, amount, from_route, to_route
Paper: create account	lighter_paper_init	collateral, tier
Paper: reset account	lighter_paper_reset	collateral, tier
Paper: account summary	lighter_paper_status	—
Paper: open positions	lighter_paper_positions	symbol
Paper: place trade	lighter_paper_order	symbol, side, amount
Paper: trade history	lighter_paper_trades	symbol, limit
Paper: margin/health	lighter_paper_health	—