Package Exports

zklighter-sdk
zklighter-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (zklighter-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Lighter SDK

TypeScript SDK for interacting with the Lighter (zkLighter) API. This SDK provides a complete interface for account management, order creation, transaction signing, and more.

Installation

npm install zklighter-sdk

Requirements

Node.js 18+
TypeScript 5.0+

Dependencies

axios - HTTP client
ethers - Ethereum library for wallet operations
koffi - FFI bindings for native signer libraries

Quick Start

Basic Configuration

import { Configuration, AccountApi } from "zklighter-sdk"

const configuration = new Configuration({
  basePath: "https://mainnet.zklighter.elliot.ai", // or testnet URL
})

const accountApi = new AccountApi(configuration)

Get Account Information

import { AccountApi, Configuration } from "zklighter-sdk"

const configuration = new Configuration({
  basePath: "https://mainnet.zklighter.elliot.ai",
})

const accountApi = new AccountApi(configuration)

// Get account by L1 address
const response = await accountApi.accountsByL1Address("0x...")
const accountIndex = response.data.sub_accounts[0].index

// Get account details
const accountDetails = await accountApi.account(accountIndex)
console.log(accountDetails.data)

Create an Order

import {
  SignerClient,
  Configuration,
  OrderApi,
  TransactionApi,
} from "zklighter-sdk"

const BASE_URL = "https://mainnet.zklighter.elliot.ai"
const API_KEY_PRIVATE_KEY = "your-api-key-private-key"
const API_KEY_INDEX = 0
const ACCOUNT_INDEX = 1

// Initialize the signer client
const client = new SignerClient(
  BASE_URL,
  API_KEY_PRIVATE_KEY,
  API_KEY_INDEX,
  ACCOUNT_INDEX
)

// Get market information
const orderApi = new OrderApi(new Configuration({ basePath: BASE_URL }))
const { data } = await orderApi.orderBooks()
const market = data.order_books.find((m) => m.symbol === "SOL")

// Get current price
const { data: marketData } = await orderApi.orderBookDetails(market.market_id)
const price = marketData.order_book_details[0].last_trade_price

// Get nonce
const txApi = new TransactionApi(new Configuration({ basePath: BASE_URL }))
const { data: nonceData } = await txApi.nextNonce(ACCOUNT_INDEX, API_KEY_INDEX)
const nonce = nonceData.nonce

// Create market order
const [order, tx, errMsg] = await client.create_market_order(
  market.market_id, // market_index
  0, // client_order_index
  4, // base_amount
  price, // avg_execution_price
  false, // is_ask (false = buy, true = sell)
  false, // reduce_only
  nonce,
  API_KEY_INDEX
)

if (errMsg) {
  console.error(`Error: ${errMsg}`)
} else {
  console.log("Order created:", order)
  console.log("Transaction:", tx)
}

// Clean up
await client.close()

API Clients

The SDK provides several API client classes, all auto-generated from the OpenAPI specification:

AccountApi

Account management operations:

account(accountIndex) - Get account details
accountsByL1Address(address) - Get accounts by Ethereum address
accountLimits(accountIndex) - Get account limits
accountMetadata(accountIndex) - Get account metadata
apikeys(accountIndex, apiKeyIndex) - Get API keys
pnl(accountIndex) - Get profit and loss
positionFunding(accountIndex, marketId) - Get position funding
And more...

OrderApi

Order book and trading operations:

orderBooks() - Get all order books
orderBookDetails(marketId) - Get order book details
orderBookOrders(marketId) - Get orders in order book
accountActiveOrders(accountIndex) - Get active orders
accountInactiveOrders(accountIndex) - Get inactive orders
recentTrades(marketId) - Get recent trades
trades(...) - Get trades with filters
And more...

TransactionApi

Transaction operations:

nextNonce(accountIndex, apiKeyIndex) - Get next nonce
sendTx(tx) - Send a transaction
sendTxBatch(txs) - Send multiple transactions
And more...

CandlestickApi

Market data:

candlesticks(marketId, resolution, ...) - Get candlestick data
fundings(marketId) - Get funding rates

Other APIs

BridgeApi - Bridge operations
FundingApi - Funding operations
InfoApi - System information
NotificationApi - Notifications
ReferralApi - Referral program
RootApi - Root endpoints (status, info)
BlockApi - Block information
AnnouncementApi - Announcements

SignerClient

The SignerClient is a high-level client that handles transaction signing and submission. It uses native libraries (via koffi) for cryptographic operations.

Initialization

import { SignerClient } from "zklighter-sdk"

const client = new SignerClient(
  baseUrl, // API base URL
  apiKeyPrivateKey, // API key private key (hex string, with or without 0x)
  apiKeyIndex, // API key index
  accountIndex, // Account index
  {
    max_api_key_index: -1, // Optional: max API key index for nonce management
    private_keys: {}, // Optional: additional private keys for multiple API keys
    nonce_management_type: "optimistic", // or 'pessimistic'
  }
)

Order Operations

// Create limit order
const [order, tx, err] = await client.create_order(
  marketIndex,
  clientOrderIndex,
  baseAmount,
  price,
  isAsk,
  orderType, // SignerClient.ORDER_TYPE_LIMIT
  timeInForce, // SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME
  reduceOnly,
  triggerPrice,
  orderExpiry,
  nonce,
  apiKeyIndex
)

// Create market order
const [order, tx, err] = await client.create_market_order(
  marketIndex,
  clientOrderIndex,
  baseAmount,
  avgExecutionPrice,
  isAsk,
  reduceOnly,
  nonce,
  apiKeyIndex
)

// Create market order with limited slippage
const [order, tx, err] = await client.create_market_order_limited_slippage(
  marketIndex,
  clientOrderIndex,
  baseAmount,
  maxSlippageBps,
  isAsk,
  reduceOnly,
  nonce,
  apiKeyIndex
)

// Cancel order (orderIndex is bigint for large order IDs)
const [tx, err] = await client.cancel_order(
  marketIndex,
  BigInt(orderIndex), // or use 123n literal syntax
  nonce,
  apiKeyIndex
)

// Cancel all orders
const [tx, err] = await client.cancel_all_orders(
  marketIndex,
  cancelAllTif, // SignerClient.CANCEL_ALL_TIF_IMMEDIATE
  nonce,
  apiKeyIndex
)

// Modify order
const [order, tx, err] = await client.modify_order(
  marketIndex,
  orderIndex,
  newPrice,
  newBaseAmount,
  nonce,
  apiKeyIndex
)

Stop Loss and Take Profit Orders

// Create take profit order
const [order, tx, err] = await client.create_tp_order(
  marketIndex,
  clientOrderIndex,
  baseAmount,
  triggerPrice,
  price,
  isAsk,
  reduceOnly,
  nonce,
  apiKeyIndex
)

// Create take profit limit order
const [order, tx, err] = await client.create_tp_limit_order(
  marketIndex,
  clientOrderIndex,
  baseAmount,
  triggerPrice,
  price,
  isAsk,
  reduceOnly,
  nonce,
  apiKeyIndex
)

// Create stop loss order
const [order, tx, err] = await client.create_sl_order(
  marketIndex,
  clientOrderIndex,
  baseAmount,
  triggerPrice,
  isAsk,
  reduceOnly,
  nonce,
  apiKeyIndex
)

// Create stop loss limit order
const [order, tx, err] = await client.create_sl_limit_order(
  marketIndex,
  clientOrderIndex,
  baseAmount,
  triggerPrice,
  price,
  isAsk,
  reduceOnly,
  nonce,
  apiKeyIndex
)

Account Operations

// Withdraw
const [tx, err] = await client.withdraw(amount, nonce, apiKeyIndex)

// Transfer
const [tx, err] = await client.transfer(
  toAccountIndex,
  amount,
  nonce,
  apiKeyIndex
)

// Create sub-account
const [tx, err] = await client.create_sub_account(nonce, apiKeyIndex)

// Update leverage
const [tx, err] = await client.update_leverage(
  marketIndex,
  leverage,
  nonce,
  apiKeyIndex
)

API Key Management

// Change API key
const [tx, err] = await client.change_api_key(ethPrivateKey, newApiPublicKey)

// Create new API key
import { create_api_key } from "zklighter-sdk"

const [privateKey, publicKey, err] = create_api_key("")
if (err) {
  console.error("Error:", err)
} else {
  console.log("Private key:", privateKey)
  console.log("Public key:", publicKey)
}

Authentication

// Create auth token
const [authToken, err] = client.create_auth_token_with_expiry()

// Check client (verify API key)
const err = client.check_client()
if (err) {
  console.error("API key verification failed:", err)
}

Nonce Management

The SignerClient includes automatic nonce management. You can use -1 for nonce and apiKeyIndex parameters to let the client manage them automatically:

// Auto-managed nonce
const [order, tx, err] = await client.create_market_order(
  marketIndex,
  clientOrderIndex,
  baseAmount,
  price,
  isAsk,
  false,
  -1, // nonce: -1 for auto-management
  -1 // apiKeyIndex: -1 for auto-management
)

Constants

Base URLs

The SDK doesn't export base URLs by default, but you can define them in your project:

export const MAINNET_BASE_URL = "https://mainnet.zklighter.elliot.ai"
export const TESTNET_BASE_URL = "https://testnet.zklighter.elliot.ai"

Example scripts in the repository use these constants from examples/scripts/constants.ts.

Order Types

SignerClient.ORDER_TYPE_LIMIT = 0
SignerClient.ORDER_TYPE_MARKET = 1
SignerClient.ORDER_TYPE_STOP_LOSS = 2
SignerClient.ORDER_TYPE_STOP_LOSS_LIMIT = 3
SignerClient.ORDER_TYPE_TAKE_PROFIT = 4
SignerClient.ORDER_TYPE_TAKE_PROFIT_LIMIT = 5
SignerClient.ORDER_TYPE_TWAP = 6

Time in Force

SignerClient.ORDER_TIME_IN_FORCE_IMMEDIATE_OR_CANCEL = 0
SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME = 1
SignerClient.ORDER_TIME_IN_FORCE_POST_ONLY = 2

Transaction Types

SignerClient.TX_TYPE_CHANGE_PUB_KEY = 8
SignerClient.TX_TYPE_CREATE_SUB_ACCOUNT = 9
SignerClient.TX_TYPE_CREATE_PUBLIC_POOL = 10
SignerClient.TX_TYPE_UPDATE_PUBLIC_POOL = 11
SignerClient.TX_TYPE_TRANSFER = 12
SignerClient.TX_TYPE_WITHDRAW = 13
SignerClient.TX_TYPE_CREATE_ORDER = 14
SignerClient.TX_TYPE_CANCEL_ORDER = 15
SignerClient.TX_TYPE_CANCEL_ALL_ORDERS = 16
SignerClient.TX_TYPE_MODIFY_ORDER = 17
SignerClient.TX_TYPE_MINT_SHARES = 18
SignerClient.TX_TYPE_BURN_SHARES = 19
SignerClient.TX_TYPE_UPDATE_LEVERAGE = 20
SignerClient.TX_TYPE_CREATE_GROUP_ORDER = 28

Examples

The SDK includes several example scripts in the examples/scripts/ directory:

check-account.ts - Check account information
create-order.ts - Create a market order
generate-api-key.ts - Generate and register a new API key
get-auth-token.ts - Get authentication token
fast-withdraw.ts - Perform a fast withdrawal
get-info.ts - Get system information
positions-interaction.ts - Position management examples

You can run these examples using the npm scripts defined in package.json:

npm run account
npm run order
npm run key
npm run auth-token
npm run fast-withdraw
npm run info
npm run positions

Error Handling

All API methods return responses in the format:

const { status, data } = await apiClient.someMethod()

The SignerClient methods return tuples:

const [result, tx, error] = await client.someMethod()
// or
const [tx, error] = await client.someMethod()

Always check for errors:

if (error) {
  console.error("Error:", error)
  return
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. All types are exported from the main module:

import {
  Configuration,
  AccountApi,
  OrderApi,
  TransactionApi,
  SignerClient,
  // ... other exports
} from "zklighter-sdk"

Native Libraries

The SDK includes native libraries for cryptographic operations:

signer-amd64.dll (Windows)
signer-amd64.so (Linux)
signer-arm64.dylib (macOS ARM)

These are automatically loaded based on your platform.

Support

For API documentation, see the generated docs in src/docs/ or visit the Lighter API documentation.