Lighter

A perpetual-futures DEX on a zk rollup, quoted and settled in USDC. The exchange object connects to Lighter perpetuals: placing, modifying and canceling orders and setting leverage are L2 transactions signed with the API key private key, and open/historical order queries use an auth token generated with the same key. Create an API key on Lighter first and note its API key index and the account index.

Names and Configuration

exchange.GetName(): Futures_Lighter (Futures); aliases: zkLighter.

Trading Pairs and Contract Codes

Pair examples: BTC_USDC, ETH_USDC

Only USDC-quoted perpetuals are listed; write the trading pair as BTC_USDC, and the full symbol looks like BTC_USDC.swap; other quote currencies are rejected. Pairs are case-insensitive and returned in upper case.

Lighter lists perpetuals only; contract codes other than swap are rejected.

Exchange-specific IO Commands

The rest of the longer descriptions in the table:

• cross: Lighter sets margin mode and leverage in the same on-chain transaction, which also writes the instrument's current leverage (read from the instrument's setting in the exchange account data; a value set in this run within the last 60 seconds takes precedence; the market's default leverage when neither exists).
• api: By default the auth token generated with the API key private key is attached (the private key and account index must be filled in); with sign set to false (it may also be given directly as the 4th argument) no token is sent, which only works for public GET endpoints. raw is not a request body but a parameter table (a JSON object or a=1&b=2) that replaces params entirely when non-empty; it goes into the query string for GET and a form body for POST. L2 transactions are not signed for the caller.

For the common commands base and currency see exchange.IO.

Common Usage

Set the lifetime of limit orders

            javascript
            
            
function main() {
    // Later limit and conditional orders expire 10 minutes plus 1 hour after they are placed
    // (29 days by default); market orders are not affected
    exchange.IO("expiry", 60 * 60 * 1000)
    var id = exchange.CreateOrder("ETH_USDC.swap", "buy", 2000, 0.01)
    Log("Order ID:", id)
}

Call public endpoints and account endpoints that need the auth token with api

            javascript
            
            
function main() {
    // Public endpoints: false as the 4th argument sends no auth token
    var books = exchange.IO("api", "GET", "/api/v1/orderBooks", {}, false)
    Log("Markets:", books.order_books.length)
    var d = exchange.IO("api", "GET", "/api/v1/orderBookDetails", {market_id: 0}, false)
    Log(d.order_book_details[0].symbol, "last:", d.order_book_details[0].last_trade_price)
    // Account endpoints carry the auth token by default; the account index is in the Info
    // of GetAccount()
    var idx = exchange.GetAccount().Info.account_index
    var params = {account_index: idx, market_id: 0}
    var r = exchange.IO("api", "GET", "/api/v1/accountActiveOrders", params)
    Log("Open orders on market_id 0:", r.orders.length)
}

Function Support

No unsupported standard functions.

Served through a fallback:

• exchange.GetRecords: Native periods are 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w; other periods are synthesized by the docker.

Margin, Account and Simulation

Margin mode: Switch cross/isolated margin per contract with exchange.IO("cross", bool) and set leverage with exchange.SetMarginLevel(). On Lighter both are the same on-chain transaction (UpdateLeverage); every call sends one and always writes both leverage and margin mode, keeping the other one at the instrument's current value: exchange.SetMarginLevel() keeps the current margin mode and exchange.IO("cross", ...) keeps the current leverage. The current values are read from the instrument's setting in the exchange account data (present even without a position); a value set in this run within the last 60 seconds takes precedence (the exchange data lags); without either, the market's default leverage and cross. exchange.SetMarginLevel() also accepts {marginMode: "isolated"} (or cross) in the extra parameters to set the margin mode at the same time. A position's MarginLevel is derived from the initial margin fraction in the exchange's position data.

Position mode: One-way (net) positions only; hedge mode is not supported.

Account: The account index selects the master account or a sub-account; the account and positions are queried by account index, and USDC is the only asset.

Simulation: The Simulate box connects to the Lighter testnet (https://testnet.zklighter.elliot.ai). The API address can also be switched with exchange.SetBase() (or exchange.IO("base", url)): transactions are signed for the testnet when the address contains testnet, otherwise for the mainnet.

Notes