lighter-ts-sdk 1.0.0

package/docs/WsClient.md

@@ -0,0 +1,275 @@
+# WsClient
+
+The `WsClient` class provides real-time WebSocket connectivity for order book updates, account changes, and other live data from the Lighter Protocol.
+
+## Constructor
+
+```typescript
+new WsClient(config: WsConfig)
+```
+
+### WsConfig
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `url` | `string` | Yes | WebSocket URL (e.g., `wss://mainnet.zklighter.elliot.ai/ws`) |
+| `accountIndex` | `number` | Yes | Your account index |
+| `apiKeyIndex` | `number` | Yes | Your API key index |
+| `privateKey` | `string` | Yes | Your API key private key |
+| `reconnectInterval` | `number` | No | Reconnection interval in ms (default: 5000) |
+| `maxReconnectAttempts` | `number` | No | Maximum reconnection attempts (default: 10) |
+
+## Methods
+
+### connect()
+
+Establishes a WebSocket connection to the Lighter server.
+
+```typescript
+await wsClient.connect();
+```
+
+### disconnect()
+
+Closes the WebSocket connection.
+
+```typescript
+await wsClient.disconnect();
+```
+
+### subscribeOrderBook(marketIndex: number, callback: (data: OrderBookData) => void)
+
+Subscribes to order book updates for a specific market.
+
+**Parameters:**
+- `marketIndex: number` - Market index (0 for ETH/USDC)
+- `callback: (data: OrderBookData) => void` - Callback function for order book updates
+
+**Example:**
+```typescript
+wsClient.subscribeOrderBook(0, (data) => {
+  console.log('ETH/USDC Order Book Update:', data);
+  console.log('Best Bid:', data.bestBid);
+  console.log('Best Ask:', data.bestAsk);
+});
+```
+
+### subscribeAccount(callback: (data: AccountData) => void)
+
+Subscribes to account updates.
+
+**Parameters:**
+- `callback: (data: AccountData) => void` - Callback function for account updates
+
+**Example:**
+```typescript
+wsClient.subscribeAccount((data) => {
+  console.log('Account Update:', data);
+  console.log('Balance:', data.balance);
+  console.log('Positions:', data.positions);
+});
+```
+
+### subscribeTrades(marketIndex: number, callback: (data: TradeData) => void)
+
+Subscribes to trade updates for a specific market.
+
+**Parameters:**
+- `marketIndex: number` - Market index
+- `callback: (data: TradeData) => void` - Callback function for trade updates
+
+**Example:**
+```typescript
+wsClient.subscribeTrades(0, (data) => {
+  console.log('New Trade:', data);
+  console.log('Price:', data.price);
+  console.log('Size:', data.size);
+});
+```
+
+### sendTransaction(txType: number, txInfo: string)
+
+Sends a transaction through the WebSocket connection.
+
+**Parameters:**
+- `txType: number` - Transaction type (use `SignerClient.TX_TYPE_*` constants)
+- `txInfo: string` - Transaction information as JSON string
+
+**Returns:** `Promise<string>` - Transaction hash
+
+**Example:**
+```typescript
+const txHash = await wsClient.sendTransaction(
+  SignerClient.TX_TYPE_CREATE_ORDER,
+  JSON.stringify(orderData)
+);
+console.log('Transaction sent:', txHash);
+```
+
+## Event Handling
+
+The WebSocket client emits events for connection status:
+
+```typescript
+wsClient.on('connected', () => {
+  console.log('WebSocket connected');
+});
+
+wsClient.on('disconnected', () => {
+  console.log('WebSocket disconnected');
+});
+
+wsClient.on('error', (error) => {
+  console.error('WebSocket error:', error);
+});
+
+wsClient.on('reconnecting', (attempt) => {
+  console.log(`Reconnecting... attempt ${attempt}`);
+});
+```
+
+## Types
+
+### OrderBookData
+
+```typescript
+interface OrderBookData {
+  marketIndex: number;
+  bids: PriceLevel[];
+  asks: PriceLevel[];
+  bestBid: string;
+  bestAsk: string;
+  timestamp: number;
+}
+```
+
+### AccountData
+
+```typescript
+interface AccountData {
+  accountIndex: number;
+  balance: string;
+  positions: AccountPosition[];
+  orders: Order[];
+  timestamp: number;
+}
+```
+
+### TradeData
+
+```typescript
+interface TradeData {
+  tradeId: string;
+  marketIndex: number;
+  price: string;
+  size: string;
+  side: 'buy' | 'sell';
+  timestamp: number;
+}
+```
+
+### PriceLevel
+
+```typescript
+interface PriceLevel {
+  price: string;
+  size: string;
+}
+```
+
+## Complete Example
+
+```typescript
+import { WsClient, SignerClient } from '@lighter/typescript-sdk';
+
+async function main() {
+  const wsClient = new WsClient({
+    url: 'wss://mainnet.zklighter.elliot.ai/ws',
+    accountIndex: 123,
+    apiKeyIndex: 0,
+    privateKey: 'your-api-key-private-key',
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+  });
+
+  // Set up event handlers
+  wsClient.on('connected', () => {
+    console.log('WebSocket connected');
+  });
+
+  wsClient.on('disconnected', () => {
+    console.log('WebSocket disconnected');
+  });
+
+  wsClient.on('error', (error) => {
+    console.error('WebSocket error:', error);
+  });
+
+  try {
+    // Connect to WebSocket
+    await wsClient.connect();
+
+    // Subscribe to order book updates
+    wsClient.subscribeOrderBook(0, (data) => {
+      console.log('ETH/USDC Order Book:');
+      console.log(`Best Bid: ${data.bestBid}`);
+      console.log(`Best Ask: ${data.bestAsk}`);
+      console.log(`Bid Depth: ${data.bids.length} levels`);
+      console.log(`Ask Depth: ${data.asks.length} levels`);
+    });
+
+    // Subscribe to account updates
+    wsClient.subscribeAccount((data) => {
+      console.log('Account Update:');
+      console.log(`Balance: ${data.balance} USDC`);
+      console.log(`Positions: ${data.positions.length}`);
+      console.log(`Open Orders: ${data.orders.length}`);
+    });
+
+    // Subscribe to trade updates
+    wsClient.subscribeTrades(0, (data) => {
+      console.log(`New Trade: ${data.size} @ ${data.price} (${data.side})`);
+    });
+
+    // Keep the connection alive
+    await new Promise(() => {}); // Keep running
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    await wsClient.disconnect();
+  }
+}
+
+main().catch(console.error);
+```
+
+## Error Handling
+
+The WebSocket client includes automatic reconnection and error handling:
+
+```typescript
+wsClient.on('error', (error) => {
+  console.error('WebSocket error:', error);
+  // The client will automatically attempt to reconnect
+});
+
+wsClient.on('reconnecting', (attempt) => {
+  console.log(`Reconnection attempt ${attempt}/${wsClient.maxReconnectAttempts}`);
+});
+```
+
+## Best Practices
+
+1. **Always handle connection events** - Monitor connection status
+2. **Use appropriate callbacks** - Keep callback functions lightweight
+3. **Handle errors gracefully** - The client will auto-reconnect, but you should handle errors
+4. **Clean up resources** - Always call `disconnect()` when done
+5. **Monitor performance** - WebSocket connections can generate high-frequency updates
+
+## Limitations
+
+- WebSocket connections are not persistent across browser refreshes
+- Rate limiting may apply to high-frequency subscriptions
+- Some data may be delayed during high network congestion
+- Connection will be lost if the server restarts

package/docs/types/Account.md

@@ -0,0 +1,67 @@
+# Account
+
+Account information returned by the `AccountApi.getAccount()` method.
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `index` | `string` | Account index |
+| `l1_address` | `string` | Ethereum L1 address |
+| `l2_address` | `string` | Lighter L2 address |
+| `sub_accounts` | `SubAccount[]` | Sub-accounts associated with this account |
+| `positions` | `AccountPosition[]` | Current positions |
+| `trades` | `Trade[]` | Recent trades |
+
+## Example
+
+```typescript
+import { AccountApi } from '@lighter/typescript-sdk';
+
+const accountApi = new AccountApi(client);
+const account = await accountApi.getAccount({ by: 'index', value: '123' });
+
+console.log('Account Index:', account.index);
+console.log('L1 Address:', account.l1_address);
+console.log('L2 Address:', account.l2_address);
+console.log('Positions:', account.positions.length);
+console.log('Recent Trades:', account.trades.length);
+```
+
+## Related Types
+
+### SubAccount
+
+```typescript
+interface SubAccount {
+  index: string;
+  l1_address: string;
+  l2_address: string;
+}
+```
+
+### AccountPosition
+
+```typescript
+interface AccountPosition {
+  market_id: number;
+  side: 'long' | 'short';
+  size: string;
+  entry_price: string;
+  mark_price: string;
+  pnl: string;
+}
+```
+
+### Trade
+
+```typescript
+interface Trade {
+  trade_id: string;
+  market_index: number;
+  price: string;
+  size: string;
+  timestamp: string;
+  side: 'buy' | 'sell';
+}
+```

package/docs/types/ApiKeyPair.md

@@ -0,0 +1,33 @@
+# ApiKeyPair
+
+Structure representing a generated API key pair.
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `privateKey` | `string` | The private key for the API key |
+| `publicKey` | `string` | The public key for the API key |
+
+## Example
+
+```typescript
+import { SignerClient } from '@lighter/typescript-sdk';
+
+const client = new SignerClient(config);
+await client.initialize();
+await client.ensureWasmClient();
+
+const apiKeyPair = await client.generateAPIKey();
+if (apiKeyPair) {
+  console.log('Private Key:', apiKeyPair.privateKey);
+  console.log('Public Key:', apiKeyPair.publicKey);
+}
+```
+
+## Notes
+
+- The `privateKey` should be kept secure and not shared
+- The `publicKey` can be used for verification purposes
+- Both keys are returned as hexadecimal strings
+- The `generateAPIKey()` method returns `null` if generation fails

package/docs/types/CreateOrderParams.md

@@ -0,0 +1,47 @@
+# CreateOrderParams
+
+Parameters for creating a limit order using the `SignerClient.createOrder()` method.
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `marketIndex` | `number` | Yes | Market index (0 for ETH/USDC) |
+| `clientOrderIndex` | `number` | Yes | Unique client order index |
+| `baseAmount` | `number` | Yes | Base amount in smallest unit |
+| `price` | `number` | Yes | Order price in smallest unit |
+| `isAsk` | `boolean` | Yes | True for sell orders, false for buy orders |
+| `orderType` | `number` | Yes | Order type (use `SignerClient.ORDER_TYPE_LIMIT`) |
+| `timeInForce` | `number` | Yes | Time in force (use `SignerClient.ORDER_TIME_IN_FORCE_*`) |
+| `reduceOnly` | `boolean` | Yes | Whether this is a reduce-only order |
+| `triggerPrice` | `number` | Yes | Trigger price for conditional orders |
+| `orderExpiry` | `number` | Yes | Order expiry timestamp |
+
+## Example
+
+```typescript
+import { SignerClient } from '@lighter/typescript-sdk';
+
+const orderParams: CreateOrderParams = {
+  marketIndex: 0, // ETH/USDC
+  clientOrderIndex: Date.now(),
+  baseAmount: 1000000, // 1 ETH in smallest unit
+  price: 300000000, // $3000 in smallest unit
+  isAsk: true, // Sell order
+  orderType: SignerClient.ORDER_TYPE_LIMIT,
+  timeInForce: SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
+  reduceOnly: false,
+  triggerPrice: SignerClient.NIL_TRIGGER_PRICE,
+  orderExpiry: SignerClient.DEFAULT_28_DAY_ORDER_EXPIRY
+};
+
+const [tx, txHash, err] = await client.createOrder(orderParams);
+```
+
+## Notes
+
+- `baseAmount` and `price` are in the smallest units (e.g., wei for ETH, micro-USDC for USDC)
+- `clientOrderIndex` should be unique per client to avoid conflicts
+- `triggerPrice` is used for conditional orders (stop loss, take profit)
+- `orderExpiry` can be set to `SignerClient.DEFAULT_28_DAY_ORDER_EXPIRY` for 28-day expiry
+- Use `SignerClient.NIL_TRIGGER_PRICE` for regular limit orders

package/docs/types/MarketOrderParams.md

@@ -0,0 +1,36 @@
+# MarketOrderParams
+
+Parameters for creating a market order using the `SignerClient.createMarketOrder()` method.
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `marketIndex` | `number` | Yes | Market index (0 for ETH/USDC) |
+| `clientOrderIndex` | `number` | Yes | Unique client order index |
+| `baseAmount` | `number` | Yes | Base amount in smallest unit |
+| `avgExecutionPrice` | `number` | Yes | Maximum average execution price |
+| `isAsk` | `boolean` | Yes | True for sell orders, false for buy orders |
+
+## Example
+
+```typescript
+import { SignerClient } from '@lighter/typescript-sdk';
+
+const marketOrderParams: MarketOrderParams = {
+  marketIndex: 0, // ETH/USDC
+  clientOrderIndex: Date.now(),
+  baseAmount: 1000000, // 1 ETH in smallest unit
+  avgExecutionPrice: 300000000, // Max $3000 average price
+  isAsk: true // Sell order
+};
+
+const [tx, txHash, err] = await client.createMarketOrder(marketOrderParams);
+```
+
+## Notes
+
+- `baseAmount` is in the smallest units (e.g., wei for ETH)
+- `avgExecutionPrice` acts as a price limit to prevent excessive slippage
+- Market orders are executed immediately at the best available price
+- Use `avgExecutionPrice` to set a maximum price you're willing to pay/receive

package/docs/types/SignerConfig.md

@@ -0,0 +1,40 @@
+# SignerConfig
+
+Configuration object for the `SignerClient` class.
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `url` | `string` | Yes | The Lighter API URL (e.g., `https://mainnet.zklighter.elliot.ai`) |
+| `privateKey` | `string` | Yes | Your API key private key |
+| `accountIndex` | `number` | Yes | Your account index |
+| `apiKeyIndex` | `number` | Yes | Your API key index |
+| `signerServerUrl` | `string` | No | URL of the signer server (alternative to WASM) |
+| `wasmConfig` | `WasmSignerConfig` | No | Configuration for WASM signer |
+
+## Example
+
+```typescript
+import { SignerClient } from '@lighter/typescript-sdk';
+
+const config: SignerConfig = {
+  url: 'https://mainnet.zklighter.elliot.ai',
+  privateKey: '0x1234567890abcdef...',
+  accountIndex: 123,
+  apiKeyIndex: 0,
+  wasmConfig: {
+    wasmPath: 'wasm/lighter-signer.wasm',
+    wasmExecPath: 'wasm/wasm_exec.js' // optional
+  }
+};
+
+const client = new SignerClient(config);
+```
+
+## Notes
+
+- Either `signerServerUrl` or `wasmConfig` must be provided
+- The `privateKey` should be your API key private key, not your Ethereum private key
+- The `accountIndex` and `apiKeyIndex` can be obtained from the system setup process
+- The `wasmPath` should point to the compiled WASM binary file

package/docs/types/WasmSignerConfig.md

@@ -0,0 +1,30 @@
+# WasmSignerConfig
+
+Configuration object for the WASM signer client.
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `wasmPath` | `string` | Yes | Path to the WASM binary file |
+| `wasmExecPath` | `string` | No | Path to wasm_exec.js runtime (optional) |
+
+## Example
+
+```typescript
+import { WasmSignerClient } from '@lighter/typescript-sdk';
+
+const config: WasmSignerConfig = {
+  wasmPath: 'wasm/lighter-signer.wasm',
+  wasmExecPath: 'wasm/wasm_exec.js' // optional, will auto-detect if not provided
+};
+
+const wasmClient = new WasmSignerClient(config);
+```
+
+## Notes
+
+- The `wasmPath` should point to the compiled WASM binary file
+- The `wasmExecPath` is optional and will be auto-detected if not provided
+- For Node.js environments, the runtime will look for wasm_exec.js in common locations
+- For browser environments, the runtime will look for wasm_exec.js in the same directory as the WASM file

package/examples/README.md

@@ -0,0 +1,171 @@
+# Lighter TypeScript SDK Examples
+
+This directory contains comprehensive examples demonstrating how to use the Lighter TypeScript SDK.
+
+## Setup Instructions
+
+### Testnet Setup
+1. Go to https://testnet.app.lighter.xyz/ and connect a wallet to receive $500
+2. Run `system_setup.ts` with the correct ETH Private key configured
+   - Set an API key index which is not 0, so you won't override the one used by [app.lighter.xyz](https://app.lighter.xyz/)
+   - This will require you to enter your Ethereum private key
+   - The ETH private key will only be used in the TypeScript SDK to sign a message
+   - The ETH private key is not required in order to trade on the platform
+   - The ETH private key is not passed to the WASM binary
+   - Copy the output of the script and post it into `create_cancel_order.ts`
+   - The output should look like:
+```
+BASE_URL = 'https://testnet.zklighter.elliot.ai'
+API_KEY_PRIVATE_KEY = '0xea5d2eca5be67eca056752eaf27b173518b8a5550117c09d2b58c7ea7d306cc4426f913ccf27ab19'
+ACCOUNT_INDEX = 595
+API_KEY_INDEX = 1
+```
+3. Start trading using:
+   - `create_cancel_order.ts` has an example which creates an order on testnet & cancels it
+   - You'll need to set up both your account index, API key index & API Key private key
+
+### Mainnet Setup
+1. Deposit money on Lighter to create an account first
+2. Change the URL to `mainnet.zklighter.elliot.ai`
+3. Repeat setup steps
+
+## Examples Overview
+
+### Basic Trading Examples
+
+#### [Create Market Order](create_market_order.ts)
+Demonstrates how to create a market order using the WASM signer.
+
+```bash
+npx ts-node examples/create_market_order.ts
+```
+
+#### [Create & Cancel Orders](create_cancel_order.ts)
+Shows how to create limit orders and cancel them.
+
+```bash
+npx ts-node examples/create_cancel_order.ts
+```
+
+#### [Create Market Order with Max Slippage](create_market_order_max_slippage.ts)
+Example of creating market orders with price protection.
+
+```bash
+npx ts-node examples/create_market_order_max_slippage.ts
+```
+
+#### [Create Stop Loss & Take Profit Orders](create_sl_tp.ts)
+Demonstrates advanced order types with trigger prices.
+
+```bash
+npx ts-node examples/create_sl_tp.ts
+```
+
+### Account Management Examples
+
+#### [System Setup](system_setup.ts)
+Complete setup process for creating API keys and configuring accounts.
+
+```bash
+npx ts-node examples/system_setup.ts
+```
+
+#### [Transfer & Update Leverage](transfer_update_leverage.ts)
+Shows how to transfer USDC between accounts and update leverage settings.
+
+```bash
+npx ts-node examples/transfer_update_leverage.ts
+```
+
+#### [Create Orders with Multiple Keys](create_with_multiple_keys.ts)
+Demonstrates using multiple API keys for trading.
+
+```bash
+npx ts-node examples/create_with_multiple_keys.ts
+```
+
+### API Information Examples
+
+#### [Get Information](get_info.ts)
+Comprehensive example showing all available API endpoints.
+
+```bash
+npx ts-node examples/get_info.ts
+```
+
+### WebSocket Examples
+
+#### [WebSocket Sync](ws.ts)
+Real-time order book and account synchronization.
+
+```bash
+npx ts-node examples/ws.ts
+```
+
+#### [WebSocket Async](ws_async.ts)
+Asynchronous WebSocket connection handling.
+
+```bash
+npx ts-node examples/ws_async.ts
+```
+
+#### [WebSocket Send Transaction](ws_send_tx.ts)
+Sending transactions through WebSocket connection.
+
+```bash
+npx ts-node examples/ws_send_tx.ts
+```
+
+#### [WebSocket Send Batch Transaction](ws_send_batch_tx.ts)
+Sending multiple transactions in a batch via WebSocket.
+
+```bash
+npx ts-node examples/ws_send_batch_tx.ts
+```
+
+### Advanced Examples
+
+#### [Send Transaction Batch](send_tx_batch.ts)
+Batch transaction processing for improved efficiency.
+
+```bash
+npx ts-node examples/send_tx_batch.ts
+```
+
+## Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+BASE_URL=https://mainnet.zklighter.elliot.ai
+PRIVATE_KEY=your-api-key-private-key
+ACCOUNT_INDEX=123
+API_KEY_INDEX=0
+ETH_PRIVATE_KEY=your-ethereum-private-key
+```
+
+## Running Examples
+
+All examples can be run using:
+
+```bash
+npx ts-node examples/[example-name].ts
+```
+
+Make sure you have:
+1. Installed dependencies: `npm install`
+2. Set up your `.env` file with correct credentials
+3. Built the WASM signer (if using signer examples)
+
+## Error Handling
+
+All examples include proper error handling and will display helpful error messages if something goes wrong. Common issues include:
+
+- Invalid API credentials
+- Insufficient balance
+- Invalid order parameters
+- Network connectivity issues
+
+## Support
+
+For questions about the examples or the SDK, please visit our [documentation](https://docs.lighter.xyz) or join our [Discord community](https://discord.gg/lighter).