@andy-liquid-labs/lighter-ts-sdk 1.0.0

package/src/client/http/client.ts

@@ -0,0 +1,137 @@
+/**
+ * HTTP Client implementation for Lighter API
+ */
+
+import {
+  MinimalHTTPClient,
+  NextNonceResponse,
+  AccountApiKeysResponse,
+  GetAccountResponse,
+  LighterAccount,
+} from './interface';
+
+const CODE_OK = 200;
+
+/**
+ * HTTP Client for Lighter exchange API
+ */
+export class HttpClient implements MinimalHTTPClient {
+  private readonly endpoint: string;
+  private readonly timeout: number;
+
+  constructor(baseUrl: string, timeout: number = 30000) {
+    if (!baseUrl) {
+      throw new Error('Base URL is required');
+    }
+    this.endpoint = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    this.timeout = timeout;
+  }
+
+  /**
+   * Make a GET request to the API
+   */
+  private async get<T>(
+    path: string,
+    params: Record<string, string | number | bigint>
+  ): Promise<T> {
+    const url = new URL(path, this.endpoint);
+    for (const [key, value] of Object.entries(params)) {
+      url.searchParams.set(key, String(value));
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+          Accept: 'application/json',
+        },
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`HTTP ${response.status}: ${text}`);
+      }
+
+      const data = (await response.json()) as T & { code?: number; message?: string };
+
+      // Check result code
+      if (data.code !== undefined && data.code !== CODE_OK) {
+        throw new Error(data.message || `API error: ${data.code}`);
+      }
+
+      return data;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Get the next nonce for an account and API key
+   */
+  async getNextNonce(accountIndex: bigint, apiKeyIndex: number): Promise<bigint> {
+    const result = await this.get<NextNonceResponse>('/api/v1/nextNonce', {
+      account_index: accountIndex,
+      api_key_index: apiKeyIndex,
+    });
+    return BigInt(result.nonce);
+  }
+
+  /**
+   * Get the public key for an account and API key
+   */
+  async getApiKey(accountIndex: bigint, apiKeyIndex: number): Promise<string> {
+    const result = await this.get<AccountApiKeysResponse>('/api/v1/apikeys', {
+      account_index: accountIndex,
+      api_key_index: apiKeyIndex,
+    });
+
+    if (!result.api_keys || result.api_keys.length === 0) {
+      throw new Error('No API keys returned');
+    }
+
+    return result.api_keys[0].public_key;
+  }
+
+  /**
+   * Get account information by L1 address or account index
+   */
+  async getAccount(
+    by: 'l1_address' | 'account_index',
+    value: string
+  ): Promise<LighterAccount[]> {
+    const result = await this.get<GetAccountResponse>('/api/v1/account', {
+      by,
+      value,
+    });
+
+    return result.accounts ?? [];
+  }
+
+  /**
+   * Get account information by L1 address (convenience method)
+   */
+  async getAccountByL1Address(l1Address: string): Promise<LighterAccount[]> {
+    return this.getAccount('l1_address', l1Address);
+  }
+
+  /**
+   * Get account information by account index (convenience method)
+   */
+  async getAccountByIndex(accountIndex: string): Promise<LighterAccount[]> {
+    return this.getAccount('account_index', accountIndex);
+  }
+}
+
+/**
+ * Create a new HTTP client
+ */
+export function newHttpClient(baseUrl: string): MinimalHTTPClient | null {
+  if (!baseUrl) {
+    return null;
+  }
+  return new HttpClient(baseUrl);
+}

package/src/client/http/index.ts

@@ -0,0 +1,6 @@
+/**
+ * HTTP module exports
+ */
+
+export * from './interface';
+export * from './client';

package/src/client/http/interface.ts

@@ -0,0 +1,89 @@
+/**
+ * Minimal HTTP Client interface for Lighter API
+ */
+
+export interface MinimalHTTPClient {
+  /**
+   * Get the next nonce for an account and API key
+   */
+  getNextNonce(accountIndex: bigint, apiKeyIndex: number): Promise<bigint>;
+
+  /**
+   * Get the public key for an account and API key
+   */
+  getApiKey(accountIndex: bigint, apiKeyIndex: number): Promise<string>;
+
+  /**
+   * Get account information by L1 address or account index
+   */
+  getAccount(by: 'l1_address' | 'account_index', value: string): Promise<LighterAccount[]>;
+}
+
+/**
+ * HTTP response types
+ */
+export interface ResultCode {
+  code: number;
+  message?: string;
+}
+
+export interface NextNonceResponse extends ResultCode {
+  nonce: number;
+}
+
+export interface ApiKey {
+  account_index: number;
+  api_key_index: number;
+  nonce: number;
+  public_key: string;
+}
+
+export interface AccountApiKeysResponse extends ResultCode {
+  api_keys: ApiKey[];
+}
+
+export interface LighterAsset {
+  symbol: string;
+  asset_id: number;
+  balance: string;
+  locked_balance: string;
+}
+
+export interface LighterPosition {
+  // Add position fields as needed
+}
+
+export interface LighterShare {
+  // Add share fields as needed
+}
+
+export interface LighterAccount {
+  code: number;
+  account_type: number;
+  index: number;
+  l1_address: string;
+  cancel_all_time: number;
+  total_order_count: number;
+  total_isolated_order_count: number;
+  pending_order_count: number;
+  available_balance: string;
+  status: number;
+  collateral: string;
+  transaction_time: number;
+  account_index: number;
+  name: string;
+  description: string;
+  can_invite: boolean;
+  referral_points_percentage: string;
+  positions: LighterPosition[];
+  assets: LighterAsset[];
+  total_asset_value: string;
+  cross_asset_value: string;
+  shares: LighterShare[];
+}
+
+export interface GetAccountResponse extends ResultCode {
+  total?: number;
+  accounts?: LighterAccount[];
+}
+

package/src/client/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Client module exports
+ */
+
+export * from "./http";
+export * from "./txClient";
+export * from "./clientManager";
+export * from "./info-client";
+export * from "./info-private-client";
+export * from "./exchange-client";
+export * from "./ws-client";

package/src/client/info-client.ts

@@ -0,0 +1,383 @@
+import axios, { AxiosInstance } from "axios";
+
+import {
+  AccountAccountByL1AddressResponse,
+  AccountByL1AddressRequest,
+  AccountRequest,
+  AccountResponse,
+  AnnouncementsResponse,
+  ApiKeysRequest,
+  ApiKeysResponse,
+  AssetDetailsRequest,
+  AssetDetailsResponse,
+  CandlesRequest,
+  CandlesResponse,
+  ExchangeStatsResponse,
+  FastBridgeInfoResponse,
+  FundingRatesResponse,
+  FundingsRequest,
+  FundingsResponse,
+  getAccountByL1Address,
+  getAccountInfo,
+  getAnnouncements,
+  getApiKeys,
+  getAssetDetails,
+  getCandlesticks,
+  getExchangeStats,
+  getFastBridgeInfo,
+  getFundingRates,
+  getFundings,
+  getNextNonce,
+  getOrderBookDetails,
+  getOrderBookOrders,
+  getOrderBooks,
+  getRecentTrades,
+  getRootStatus,
+  getTransaction,
+  getTransactionFromL1TxHash,
+  getTransactions,
+  getWithdrawalDelay,
+  NextNonceRequest,
+  NextNonceResponse,
+  OrderBookDetailsRequest,
+  OrderBookDetailsResponse,
+  OrderBookOrdersRequest,
+  OrderBookOrdersResponse,
+  OrderBooksResponse,
+  RecentTradesRequest,
+  RecentTradesResponse,
+  RootStatusResponse,
+  Transaction,
+  TransactionFromL1TxHashRequest,
+  TransactionRequest,
+  TransactionsRequest,
+  TransactionsResponse,
+  WithdrawalDelayResponse,
+} from "../api/info";
+
+export interface InfoClientConfig {
+  baseURL?: string;
+}
+
+/**
+ * InfoClient - Client for public info endpoints
+ *
+ * Provides access to all public API endpoints that don't require authentication.
+ *
+ * @example
+ * ```typescript
+ * const client = new InfoClient({
+ *   baseURL: "https://mainnet.zklighter.elliot.ai"
+ * });
+ *
+ * const account = await client.getAccountInfo({ by: "index", value: "0" });
+ * const orderBooks = await client.getOrderBooks();
+ * ```
+ */
+export class InfoClient {
+  private readonly config: InfoClientConfig;
+  private readonly axiosInstance: AxiosInstance;
+
+  constructor(config?: InfoClientConfig) {
+    this.config = {
+      baseURL: config?.baseURL || "https://mainnet.zklighter.elliot.ai",
+    };
+
+    this.axiosInstance = this.createAxiosInstance();
+  }
+
+  private createAxiosInstance(): AxiosInstance {
+    return axios.create({
+      baseURL: this.config.baseURL,
+    });
+  }
+
+  /**
+   * Get account information by index or L2 address
+   * @param params - Account lookup parameters (by index or L2 address)
+   * @returns Account information including balances and positions
+   * @example
+   * ```typescript
+   * const account = await client.getAccountInfo({ by: "index", value: "0" });
+   * ```
+   */
+  public async getAccountInfo(
+    params: AccountRequest,
+  ): Promise<AccountResponse> {
+    return getAccountInfo(this.axiosInstance, params);
+  }
+
+  /**
+   * Get account information by L1 address
+   * @param params - L1 address lookup parameters
+   * @returns Account information associated with the L1 address
+   * @example
+   * ```typescript
+   * const account = await client.getAccountByL1Address({ l1_address: "0x..." });
+   * ```
+   */
+  public async getAccountByL1Address(
+    params: AccountByL1AddressRequest,
+  ): Promise<AccountAccountByL1AddressResponse> {
+    return getAccountByL1Address(this.axiosInstance, params);
+  }
+
+  /**
+   * Get API keys for an account
+   * @param params - Account index to retrieve API keys for
+   * @returns List of API keys associated with the account
+   * @example
+   * ```typescript
+   * const keys = await client.getApiKeys({ account_index: 0 });
+   * ```
+   */
+  public async getApiKeys(params: ApiKeysRequest): Promise<ApiKeysResponse> {
+    return getApiKeys(this.axiosInstance, params);
+  }
+
+  /**
+   * Get system announcements
+   * @returns List of active announcements
+   * @example
+   * ```typescript
+   * const announcements = await client.getAnnouncements();
+   * ```
+   */
+  public async getAnnouncements(): Promise<AnnouncementsResponse> {
+    return getAnnouncements(this.axiosInstance);
+  }
+
+  /**
+   * Get asset details for a specific asset or all assets
+   * @param params - Optional asset_index to get details for a specific asset
+   * @returns Asset details including symbol, decimals, limits, and pricing information
+   * @example
+   * ```typescript
+   * // Get all assets
+   * const allAssets = await client.getAssetDetails();
+   *
+   * // Get specific asset
+   * const asset = await client.getAssetDetails({ asset_index: 0 });
+   * ```
+   */
+  public async getAssetDetails(
+    params?: AssetDetailsRequest,
+  ): Promise<AssetDetailsResponse> {
+    return getAssetDetails(this.axiosInstance, params);
+  }
+
+  /**
+   * Get candlestick data for a market
+   * @param params - Candlestick query parameters including market_id, resolution, and time range
+   * @returns Array of candlestick data
+   * @example
+   * ```typescript
+   * const candles = await client.getCandlesticks({
+   *   market_id: 1,
+   *   resolution: "1h",
+   *   start_timestamp: 1234567890,
+   *   end_timestamp: 1234567900
+   * });
+   * ```
+   */
+  public async getCandlesticks(
+    params: CandlesRequest,
+  ): Promise<CandlesResponse> {
+    return getCandlesticks(this.axiosInstance, params);
+  }
+
+  /**
+   * Get funding history for a market
+   * @param params - Funding query parameters including market_id and time range
+   * @returns Array of funding data
+   * @example
+   * ```typescript
+   * const fundings = await client.getFundings({
+   *   market_id: 1,
+   *   start_timestamp: 1234567890,
+   *   end_timestamp: 1234567900
+   * });
+   * ```
+   */
+  public async getFundings(params: FundingsRequest): Promise<FundingsResponse> {
+    return getFundings(this.axiosInstance, params);
+  }
+
+  /**
+   * Get exchange statistics
+   * @returns Exchange-wide statistics including volume, fees, and markets
+   * @example
+   * ```typescript
+   * const stats = await client.getExchangeStats();
+   * ```
+   */
+  public async getExchangeStats(): Promise<ExchangeStatsResponse> {
+    return getExchangeStats(this.axiosInstance);
+  }
+
+  /**
+   * Get fast bridge information
+   * @returns Fast bridge configuration and status
+   * @example
+   * ```typescript
+   * const bridgeInfo = await client.getFastBridgeInfo();
+   * ```
+   */
+  public async getFastBridgeInfo(): Promise<FastBridgeInfoResponse> {
+    return getFastBridgeInfo(this.axiosInstance);
+  }
+
+  /**
+   * Get current funding rates for all markets
+   * @returns Funding rates for all markets
+   * @example
+   * ```typescript
+   * const rates = await client.getFundingRates();
+   * ```
+   */
+  public async getFundingRates(): Promise<FundingRatesResponse> {
+    return getFundingRates(this.axiosInstance);
+  }
+
+  /**
+   * Get the next nonce for an account
+   * @param params - Account index to get nonce for
+   * @returns Next nonce value
+   * @example
+   * ```typescript
+   * const nonce = await client.getNextNonce({ account_index: 0 });
+   * ```
+   */
+  public async getNextNonce(
+    params: NextNonceRequest,
+  ): Promise<NextNonceResponse> {
+    return getNextNonce(this.axiosInstance, params);
+  }
+
+  /**
+   * Get all order books
+   * @returns List of all order books with their configurations
+   * @example
+   * ```typescript
+   * const orderBooks = await client.getOrderBooks();
+   * ```
+   */
+  public async getOrderBooks(): Promise<OrderBooksResponse> {
+    return getOrderBooks(this.axiosInstance);
+  }
+
+  /**
+   * Get detailed information about a specific order book
+   * @param params - Optional market_id to get details for a specific market
+   * @returns Order book details including market information
+   * @example
+   * ```typescript
+   * const details = await client.getOrderBookDetails({ market_id: 1 });
+   * ```
+   */
+  public async getOrderBookDetails(
+    params?: OrderBookDetailsRequest,
+  ): Promise<OrderBookDetailsResponse> {
+    return getOrderBookDetails(this.axiosInstance, params);
+  }
+
+  /**
+   * Get orders in an order book
+   * @param params - Market ID and optional depth/limit parameters
+   * @returns Bids and asks in the order book
+   * @example
+   * ```typescript
+   * const orders = await client.getOrderBookOrders({ market_id: 1, limit: 50 });
+   * ```
+   */
+  public async getOrderBookOrders(
+    params: OrderBookOrdersRequest,
+  ): Promise<OrderBookOrdersResponse> {
+    return getOrderBookOrders(this.axiosInstance, params);
+  }
+
+  /**
+   * Get recent trades for a market
+   * @param params - Market ID and optional limit
+   * @returns Recent trades for the market
+   * @example
+   * ```typescript
+   * const trades = await client.getRecentTrades({ market_id: 1, limit: 50 });
+   * ```
+   */
+  public async getRecentTrades(
+    params: RecentTradesRequest,
+  ): Promise<RecentTradesResponse> {
+    return getRecentTrades(this.axiosInstance, params);
+  }
+
+  /**
+   * Get a specific transaction by hash
+   * @param params - Transaction hash to look up
+   * @returns Transaction details
+   * @example
+   * ```typescript
+   * const tx = await client.getTransaction({ tx_hash: "0x..." });
+   * ```
+   */
+  public async getTransaction(
+    params: TransactionRequest,
+  ): Promise<Transaction> {
+    return getTransaction(this.axiosInstance, params);
+  }
+
+  /**
+   * Get transactions with optional filtering
+   * @param params - Optional filter parameters for transaction queries
+   * @returns List of transactions
+   * @example
+   * ```typescript
+   * const txs = await client.getTransactions({ limit: 50 });
+   * ```
+   */
+  public async getTransactions(
+    params?: TransactionsRequest,
+  ): Promise<TransactionsResponse> {
+    return getTransactions(this.axiosInstance, params);
+  }
+
+  /**
+   * Get L2 transaction from L1 transaction hash
+   * @param params - L1 transaction hash
+   * @returns Corresponding L2 transaction
+   * @example
+   * ```typescript
+   * const tx = await client.getTransactionFromL1TxHash({ l1_tx_hash: "0x..." });
+   * ```
+   */
+  public async getTransactionFromL1TxHash(
+    params: TransactionFromL1TxHashRequest,
+  ): Promise<Transaction> {
+    return getTransactionFromL1TxHash(this.axiosInstance, params);
+  }
+
+  /**
+   * Get withdrawal delay in seconds
+   * @returns Withdrawal delay configuration
+   * @example
+   * ```typescript
+   * const delay = await client.getWithdrawalDelay();
+   * console.log(`Withdrawal delay: ${delay.seconds} seconds`);
+   * ```
+   */
+  public async getWithdrawalDelay(): Promise<WithdrawalDelayResponse> {
+    return getWithdrawalDelay(this.axiosInstance);
+  }
+
+  /**
+   * Get root status information
+   * @returns Root status including network status, network_id, and timestamp
+   * @example
+   * ```typescript
+   * const status = await client.getRootStatus();
+   * ```
+   */
+  public async getRootStatus(): Promise<RootStatusResponse> {
+    return getRootStatus(this.axiosInstance);
+  }
+}