lighter-sdk-client 0.2.11

package/README.md

@@ -0,0 +1,574 @@
+# Lighter SDK Client
+
+Unofficial TypeScript/JavaScript SDK client for the Lighter protocol - a high-performance decentralized exchange built on zkSync.
+
+[![npm version](https://img.shields.io/npm/v/lighter-sdk-client.svg)](https://www.npmjs.com/package/lighter-sdk-client)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+## Features
+
+- 🔄 **Full API Coverage** - Complete access to public, private, and exchange endpoints
+- 🔐 **WASM Signing** - Built-in transaction signing with WebAssembly support
+- 🌉 **L1 Bridge Integration** - Direct integration with L1 bridging functionality
+- 📡 **WebSocket Support** - Real-time market data and account updates
+- 🎯 **TypeScript First** - Full type safety and IntelliSense support
+- ⚡ **High Performance** - Optimized for speed with minimal dependencies
+
+## Installation
+
+```bash
+pnpm add lighter-sdk-client
+```
+
+## Quick Start
+
+### Public API (InfoClient)
+
+Access public market data without authentication:
+
+```typescript
+import { InfoClient } from 'lighter-sdk-client';
+
+const client = new InfoClient({
+  baseURL: 'https://mainnet.zklighter.elliot.ai'
+});
+
+// Get account information
+const account = await client.getAccountInfo({ 
+  by: 'index', 
+  value: '0' 
+});
+
+// Get order books
+const orderBooks = await client.getOrderBooks();
+
+// Get asset details
+const allAssets = await client.getAssetDetails();
+const specificAsset = await client.getAssetDetails({ asset_index: 0 });
+
+// Get recent trades
+const trades = await client.getRecentTrades({
+  market_id: 1,
+  limit: 50
+});
+
+// Get candlestick data
+const candles = await client.getCandlesticks({
+  market_id: 1,
+  resolution: '1h',
+  start_timestamp: Math.floor(Date.now() / 1000) - 86400,
+  end_timestamp: Math.floor(Date.now() / 1000)
+});
+
+// Get withdrawal delay
+const withdrawalDelay = await client.getWithdrawalDelay();
+
+// Get root status
+const rootStatus = await client.getRootStatus();
+```
+
+### Exchange Operations (ExchangeClient)
+
+Send transactions and manage orders:
+
+```typescript
+import { ExchangeClient } from 'lighter-sdk-client';
+
+const client = new ExchangeClient({
+  baseURL: 'https://mainnet.zklighter.elliot.ai'
+});
+
+// Send a transaction
+const result = await client.sendTransaction({
+  account_index: 0,
+  api_key_index: 0,
+  transaction: '0x...'
+});
+
+// Send a batch of transactions
+const batchResult = await client.sendTransactionBatch({
+  account_index: 0,
+  api_key_index: 0,
+  transactions: ['0x...', '0x...']
+});
+
+// Change account tier
+const tierResult = await client.changeAccountTier({
+  account_index: 0,
+  new_tier: 'premium'
+}, 'auth-token');
+
+// Fast withdraw
+const withdrawResult = await client.fastWithdraw({
+  tx_info: '0x...',
+  to_address: '0x...'
+}, 'auth-token');
+
+// Create API token
+const newToken = await client.createToken({
+  name: 'My API Token',
+  account_index: 0,
+  expiry: Math.floor(Date.now() / 1000) + 86400 * 30, // 30 days
+  sub_account_access: true,
+  scopes: 'read.*'
+}, 'auth-token');
+
+// Revoke API token
+const revokeResult = await client.revokeToken({
+  token_id: 123,
+  account_index: 0
+}, 'auth-token');
+
+// Generate L1 sign message for changing public key
+const signMessage = await client.generateChangePubKeyL1SignMessage(
+  '0xabcdef...', // pubKeyHex
+  1, // nonce
+  0, // accountIndex
+  0  // newApiKeyIndex
+);
+console.log('Sign this message:', signMessage);
+```
+
+### Private API (InfoPrivateClient)
+
+Access authenticated account data with automatic WASM signing:
+
+```typescript
+import { InfoPrivateClient, WasmSigner } from 'lighter-sdk-client';
+
+// Initialize WASM signer
+const wasmSigner = new WasmSigner({
+  wasmPath: './public/wasm/lighter-signer.wasm',
+  wasmExecPath: './public/wasm/lighter-wasm-exec.js'
+});
+
+// Create private client - authentication is handled automatically
+const client = new InfoPrivateClient({
+  baseURL: 'https://mainnet.zklighter.elliot.ai',
+  wasmSigning: wasmSigner
+});
+
+// Get active orders
+const activeOrders = await client.getAccountActiveOrders({
+  account_index: 0,
+  market_id: 1
+});
+
+// Get inactive orders with pagination
+const inactiveOrders = await client.getAccountInactiveOrders({
+  account_index: 0,
+  limit: 50,
+  market_id: 1
+});
+
+// Get account limits and tier info
+const limits = await client.getAccountLimits({
+  account_index: 0
+});
+
+// Get L1 metadata
+const l1Metadata = await client.getL1Metadata({
+  l1_address: '0x...'
+});
+
+// Get API tokens for account
+const tokens = await client.getTokens({
+  account_index: 0
+});
+
+// Get deposit history
+const deposits = await client.getDepositHistory({
+  account_index: 0,
+  l1_address: '0x...',
+  filter: 'pending'
+});
+
+// Get withdrawal history
+const withdrawals = await client.getWithdrawHistory({
+  account_index: 0,
+  l1_address: '0x...',
+  filter: 'completed'
+});
+
+// Get fast withdraw information
+const fastWithdrawInfo = await client.getFastWithdrawInfo({
+  account_index: 0
+});
+
+// Get transfer fee information
+const transferFeeInfo = await client.getTransferFeeInfo({
+  account_index: 0,
+  to_account_index: 1
+});
+
+// Get transfer history
+const transfers = await client.getTransferHistory({
+  account_index: 0,
+  cursor: 'optional-cursor-for-pagination'
+});
+
+// Get liquidation history
+const liquidations = await client.getLiquidations({
+  account_index: 0,
+  limit: 50,
+  market_id: 1
+});
+
+// Get profit and loss data
+const pnl = await client.getPnL({
+  by: 'account_index',
+  value: '0',
+  resolution: '1d',
+  start_timestamp: Math.floor(Date.now() / 1000) - 86400 * 30,
+  end_timestamp: Math.floor(Date.now() / 1000),
+  count_back: 30
+});
+
+// Get position funding history
+const funding = await client.getPositionFunding({
+  account_index: 0,
+  limit: 50,
+  market_id: 1,
+  side: 'long'
+});
+
+// Get public pools metadata
+const pools = await client.getPublicPools({
+  filter: 'all',
+  limit: 10,
+  index: 0
+});
+
+// Get referral points
+const referralPoints = await client.getReferralPoints({
+  account_index: 0
+});
+
+// Get trades for account or market
+const trades = await client.getTrades({
+  sort_by: 'timestamp',
+  limit: 50,
+  account_index: 0,
+  market_id: 1,
+  sort_dir: 'desc'
+});
+
+// Export data
+const exportData = await client.getExport({
+  type: 'trade',
+  account_index: 0,
+  market_id: 1
+});
+console.log('Download URL:', exportData.data_url);
+```
+
+### L1 Bridge Operations
+
+Deposit and withdraw assets:
+
+```typescript
+import { L1BridgeClient } from 'lighter-sdk-client';
+import { arbitrum } from 'viem/chains';
+
+const bridgeClient = new L1BridgeClient({
+  chain: arbitrum,
+  l1RpcUrl: 'https://arb1.arbitrum.io/rpc',
+  privateKey: '0x...',
+  bridgeContractAddress: '0x...',
+  usdcAddress: '0x...'
+});
+
+// Deposit USDC from L1 to L2
+const result = await bridgeClient.depositUSDC({
+  amount: '100.00',
+  lighterAccountIndex: 0
+});
+
+console.log('Transaction hash:', result.transactionHash);
+console.log('Amount deposited:', result.amountDeposited);
+```
+
+### WebSocket Client
+
+Subscribe to real-time updates:
+
+```typescript
+import { WsClient } from 'lighter-sdk-client';
+
+const wsClient = new WsClient({
+  url: 'wss://mainnet.zklighter.elliot.ai/stream',
+  reconnectInterval: 5000,
+  maxReconnectAttempts: 5
+});
+
+await wsClient.connect();
+
+// Subscribe to order book updates
+wsClient.subscribeOrderBook({
+  market_id: 1,
+  onUpdate: (data) => {
+    console.log('Order book update:', data);
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+  }
+});
+
+// Subscribe to trade updates
+wsClient.subscribeTrades({
+  market_id: 1,
+  onUpdate: (data) => {
+    console.log('New trade:', data);
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+  }
+});
+
+// Subscribe to account updates (requires authentication)
+wsClient.subscribeAccountMarket({
+  market_id: 1,
+  account_index: 0,
+  auth_token: 'your-auth-token',
+  onUpdate: (data) => {
+    console.log('Account update:', data);
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+  }
+});
+
+// Disconnect when done
+await wsClient.disconnect();
+```
+
+## API Reference
+
+### InfoClient
+
+Public API client for market data and account information. No authentication required.
+
+#### Methods
+
+**Account Methods**
+- `getAccountInfo(params)` - Get account information by index or L2 address
+- `getAccountByL1Address(params)` - Get account information associated with an L1 address
+
+**API Keys & Announcements**
+- `getApiKeys(params)` - Get API keys for an account
+- `getAnnouncements()` - Get system announcements
+
+**Market Data**
+- `getAssetDetails(params?)` - Get asset details for a specific asset or all assets (symbol, decimals, limits, pricing)
+- `getCandlesticks(params)` - Get candlestick data with specified resolution and time range
+- `getFundings(params)` - Get funding history for a market
+- `getExchangeStats()` - Get exchange-wide statistics including volume and fees
+- `getFundingRates()` - Get current funding rates for all markets
+
+**Order Books**
+- `getOrderBooks()` - Get list of all order books with configurations
+- `getOrderBookDetails(params)` - Get detailed information about a specific order book
+- `getOrderBookOrders(params)` - Get bids and asks in an order book
+
+**Trades**
+- `getRecentTrades(params)` - Get recent trades for a market
+- `getTrades(params, authorization?)` - Get trades with optional filtering and authentication
+
+**Transactions**
+- `getTransaction(params)` - Get a specific transaction by hash
+- `getTransactions(params?)` - Get transactions with optional filtering
+- `getTransactionFromL1TxHash(params)` - Get L2 transaction from L1 transaction hash
+
+**Utilities**
+- `getNextNonce(params)` - Get the next nonce for an account
+- `getFastBridgeInfo()` - Get fast bridge configuration and status
+- `getWithdrawalDelay()` - Get withdrawal delay in seconds
+- `getRootStatus()` - Get root status information including network status and timestamp
+
+### ExchangeClient
+
+Client for sending transactions and managing exchange operations.
+
+#### Methods
+
+**Transaction Submission**
+- `sendTransaction(params)` - Send a signed transaction to the exchange
+- `sendTx(params)` - Send transaction with form data format
+- `sendTxWithIndices(params)` - Send transaction with account and API key indices
+- `sendTxJson(params)` - Send transaction with JSON payload format
+- `sendTransactionBatch(params)` - Send multiple transactions in a single batch for better efficiency
+
+**Account Management**
+- `changeAccountTier(params, authorization?)` - Change account tier (requires authorization)
+- `fastWithdraw(params, authorization?)` - Fast withdraw funds (requires authorization)
+
+**API Tokens**
+- `createToken(params, authorization?)` - Create API token with specified permissions and expiry
+- `revokeToken(params, authorization?)` - Revoke an existing API token
+- `generateChangePubKeyL1SignMessage(pubKeyHex, nonce, accountIndex, newApiKeyIndex)` - Generate L1 sign message for changing public key
+
+**Notifications**
+- `acknowledgeNotification(params)` - Acknowledge receipt of a notification
+
+### InfoPrivateClient
+
+Client for authenticated/private endpoints. Authentication is handled automatically via WasmSigner.
+
+#### Methods
+
+**Account Orders**
+- `getAccountActiveOrders(params)` - Get active orders for an account in a specific market
+- `getAccountInactiveOrders(params)` - Get inactive orders with pagination support
+
+**Account Information**
+- `getAccountLimits(params)` - Get account limits including max LLP percentage, user tier, and pool creation permissions
+- `getAccountMetadata(params)` - Get account metadata by index or L1 address
+- `getL1Metadata(params)` - Get L1 metadata for an address including referral information
+- `getTokens(params)` - Get API tokens for an account with details including name, expiry, scopes, and status
+
+**Transaction History**
+- `getDepositHistory(params)` - Get deposit history with status and timestamps
+- `getWithdrawHistory(params)` - Get withdrawal history with status and timestamps
+- `getFastWithdrawInfo(params)` - Get fast withdraw limits and account information
+- `getTransferFeeInfo(params)` - Get transfer fee information between accounts
+- `getTransferHistory(params)` - Get transfer history with pagination support
+- `getLiquidations(params)` - Get liquidation history with pagination support
+
+**Analytics**
+- `getPnL(params)` - Get profit and loss data with customizable resolution and time range
+- `getPositionFunding(params)` - Get position funding history with pagination support
+
+**Liquidity Pools**
+- `getPublicPools(params?)` - Get public pool information including TVL, APY, and share details
+
+**Referral System**
+- `getReferralPoints(params)` - Get referral points data including user points and referral list
+
+**Trading**
+- `getTrades(params)` - Get trades for an account or market with sorting and filtering options
+
+**Data Export**
+- `getExport(params)` - Export data (funding or trade data) for downloading
+
+### L1BridgeClient
+
+Client for L1 bridge operations to move assets between Layer 1 and Layer 2.
+
+#### Methods
+
+**Bridge Operations**
+- `depositUSDC(params)` - Deposit USDC from L1 to L2 Lighter account
+
+**Balance & Allowance**
+- `checkUSDCBalance()` - Check USDC balance on L1
+- `checkAllowance()` - Check current USDC allowance for bridge contract
+- `approveUSDC(amount)` - Approve USDC spending for bridge contract
+
+### WsClient
+
+WebSocket client for real-time market data and account updates.
+
+#### Methods
+
+**Connection Management**
+- `connect()` - Establish WebSocket connection to server
+- `disconnect()` - Close WebSocket connection and cleanup subscriptions
+- `unsubscribe(subscriptionId)` - Unsubscribe from a specific subscription
+
+**Market Data Subscriptions**
+- `subscribeOrderBook(params)` - Subscribe to real-time order book updates for a market
+- `subscribeTrades(params)` - Subscribe to real-time trade updates for a market
+- `subscribeMarketStats(params)` - Subscribe to market statistics updates
+
+**Account Subscriptions** (requires authentication)
+- `subscribeAccountMarket(params)` - Subscribe to account updates for a specific market
+- `subscribeAccountOrders(params)` - Subscribe to account order updates for a specific market
+- `subscribeAccountAllOrders(params)` - Subscribe to all order updates across all markets
+- `subscribeAccountAllPositions(params)` - Subscribe to all position updates across all markets
+- `subscribeAccountAllTrades(params)` - Subscribe to all trade updates across all markets
+- `subscribeAccountAll(params)` - Subscribe to all account updates (orders, positions, trades)
+
+**System Subscriptions**
+- `subscribeNotifications(params)` - Subscribe to system notifications
+- `subscribeTransactions(params)` - Subscribe to transaction updates
+- `subscribeHeight(params)` - Subscribe to block height updates
+
+## Configuration
+
+### Base URLs
+
+- **Mainnet**: `https://mainnet.zklighter.elliot.ai`
+- **WebSocket**: `wss://mainnet.zklighter.elliot.ai/stream`
+
+### WASM Signing Setup
+
+For transaction signing, you need to include the WASM files (please copy them from the `lighter-sdk-client` package to your `./public` directory):
+
+```typescript
+import { WasmSigner } from 'lighter-sdk-client';
+
+const wasmSigning = new WasmSigner({
+  wasmPath: './public/wasm/lighter-signer.wasm',
+  wasmExecPath: './public/wasm/lighter-wasm-exec.js'
+});
+```
+
+The WASM files should be placed in your public directory and served statically.
+
+## Dependencies
+
+- `axios` - HTTP client for API requests
+- `viem` - Ethereum library for L1 bridge operations
+- `wagmi` - React hooks for Ethereum (peer dependency)
+- `@tanstack/react-query` - Data fetching library (peer dependency)
+
+## Development
+
+### Build
+
+```bash
+pnpm build
+```
+
+### Project Structure
+
+```
+src/
+├── api/              # API endpoint implementations
+│   ├── exchange/     # Exchange/transaction endpoints
+│   ├── info/         # Public info endpoints
+│   └── info-private/ # Private/authenticated endpoints
+├── client/           # Client classes
+│   ├── exchange-client.ts
+│   ├── info-client.ts
+│   ├── info-private-client.ts
+│   ├── l1-bridge-client.ts
+│   └── ws-client.ts
+├── signing/          # Transaction signing utilities
+│   └── wasm-signer.ts
+└── types/            # TypeScript type definitions
+    ├── api.ts
+    ├── config.ts
+    ├── ws.ts
+    └── index.ts
+```
+
+## License
+
+ISC
+
+## Disclaimer
+
+This is an unofficial SDK client for the Lighter protocol. Use at your own risk. Always verify transactions before signing.
+
+## Links
+
+- [Lighter Protocol](https://lighter.xyz)
+- [Documentation](https://docs.lighter.xyz)
+
+## Support
+
+For issues and questions:
+- Create an issue on GitHub
+- Join the Lighter community Discord
+- Check the official documentation

package/dist/api/exchange/change-account-tier.cjs

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkF24JA2OVcjs = require('../../chunk-F24JA2OV.cjs');
+
+
+exports.changeAccountTier = _chunkF24JA2OVcjs.changeAccountTier;

package/dist/api/exchange/change-account-tier.d.cts

@@ -0,0 +1,14 @@
+import { AxiosInstance } from 'axios';
+
+interface ChangeAccountTierRequest {
+    account_index: number;
+    new_tier: string;
+    auth?: string;
+}
+interface ChangeAccountTierResponse {
+    code: number;
+    message?: string;
+}
+declare function changeAccountTier(client: AxiosInstance, params: ChangeAccountTierRequest, authorization?: string): Promise<ChangeAccountTierResponse>;
+
+export { type ChangeAccountTierRequest, type ChangeAccountTierResponse, changeAccountTier };

package/dist/api/exchange/change-account-tier.d.ts

@@ -0,0 +1,14 @@
+import { AxiosInstance } from 'axios';
+
+interface ChangeAccountTierRequest {
+    account_index: number;
+    new_tier: string;
+    auth?: string;
+}
+interface ChangeAccountTierResponse {
+    code: number;
+    message?: string;
+}
+declare function changeAccountTier(client: AxiosInstance, params: ChangeAccountTierRequest, authorization?: string): Promise<ChangeAccountTierResponse>;
+
+export { type ChangeAccountTierRequest, type ChangeAccountTierResponse, changeAccountTier };

package/dist/api/exchange/change-account-tier.js

@@ -0,0 +1,6 @@
+import {
+  changeAccountTier
+} from "../../chunk-5WEMEUUI.js";
+export {
+  changeAccountTier
+};

package/dist/api/exchange/fastwithdraw.cjs

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunk5JDRAN7Lcjs = require('../../chunk-5JDRAN7L.cjs');
+
+
+exports.fastWithdraw = _chunk5JDRAN7Lcjs.fastWithdraw;

package/dist/api/exchange/fastwithdraw.d.cts

@@ -0,0 +1,14 @@
+import { AxiosInstance } from 'axios';
+
+interface FastWithdrawRequest {
+    tx_info: string;
+    to_address: string;
+    auth?: string;
+}
+interface FastWithdrawResponse {
+    code: number;
+    message?: string;
+}
+declare function fastWithdraw(client: AxiosInstance, params: FastWithdrawRequest, authorization?: string): Promise<FastWithdrawResponse>;
+
+export { type FastWithdrawRequest, type FastWithdrawResponse, fastWithdraw };

package/dist/api/exchange/fastwithdraw.d.ts

@@ -0,0 +1,14 @@
+import { AxiosInstance } from 'axios';
+
+interface FastWithdrawRequest {
+    tx_info: string;
+    to_address: string;
+    auth?: string;
+}
+interface FastWithdrawResponse {
+    code: number;
+    message?: string;
+}
+declare function fastWithdraw(client: AxiosInstance, params: FastWithdrawRequest, authorization?: string): Promise<FastWithdrawResponse>;
+
+export { type FastWithdrawRequest, type FastWithdrawResponse, fastWithdraw };

package/dist/api/exchange/fastwithdraw.js

@@ -0,0 +1,6 @@
+import {
+  fastWithdraw
+} from "../../chunk-SA6CXVP6.js";
+export {
+  fastWithdraw
+};

package/dist/api/exchange/index.cjs

@@ -0,0 +1,37 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});require('../../chunk-6CD3YMMG.cjs');
+
+
+var _chunkZIMFMYT2cjs = require('../../chunk-ZIMFMYT2.cjs');
+
+
+
+
+
+var _chunkRYDJEI67cjs = require('../../chunk-RYDJEI67.cjs');
+
+
+var _chunkZGWYI7Q2cjs = require('../../chunk-ZGWYI7Q2.cjs');
+
+
+var _chunkGYQ6HJQYcjs = require('../../chunk-GYQ6HJQY.cjs');
+
+
+var _chunkF24JA2OVcjs = require('../../chunk-F24JA2OV.cjs');
+
+
+var _chunk5JDRAN7Lcjs = require('../../chunk-5JDRAN7L.cjs');
+
+
+var _chunk3R4OL3TUcjs = require('../../chunk-3R4OL3TU.cjs');
+
+
+
+
+
+
+
+
+
+
+
+exports.acknowledgeNotification = _chunk3R4OL3TUcjs.acknowledgeNotification; exports.changeAccountTier = _chunkF24JA2OVcjs.changeAccountTier; exports.createToken = _chunkZGWYI7Q2cjs.createToken; exports.fastWithdraw = _chunk5JDRAN7Lcjs.fastWithdraw; exports.revokeToken = _chunkGYQ6HJQYcjs.revokeToken; exports.sendTransaction = _chunkRYDJEI67cjs.sendTransaction; exports.sendTransactionBatch = _chunkZIMFMYT2cjs.sendTransactionBatch; exports.sendTx = _chunkRYDJEI67cjs.sendTx; exports.sendTxJson = _chunkRYDJEI67cjs.sendTxJson; exports.sendTxWithIndices = _chunkRYDJEI67cjs.sendTxWithIndices;