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.

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.

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

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