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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@andy-liquid-labs/lighter-ts-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for Lighter - signing & hashing of Lighter transactions",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "lighter",
+    "sdk",
+    "trading",
+    "crypto",
+    "signing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elliottech/lighter-ts-sdk"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.55.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.13.3",
+    "js-sha256": "^0.11.1",
+    "reconnecting-websocket": "^4.4.0"
+  }
+}

package/src/api/exchange/change-account-tier.ts

@@ -0,0 +1,38 @@
+import { AxiosInstance, AxiosRequestConfig } from "axios";
+
+export interface ChangeAccountTierRequest {
+  account_index: number;
+  new_tier: string;
+  auth?: string;
+}
+
+export interface ChangeAccountTierResponse {
+  code: number;
+  message?: string;
+}
+
+export async function changeAccountTier(
+  client: AxiosInstance,
+  params: ChangeAccountTierRequest,
+  authorization?: string,
+): Promise<ChangeAccountTierResponse> {
+  const config: AxiosRequestConfig = {
+    headers: {},
+  };
+
+  if (authorization) {
+    config.headers = { Authorization: authorization };
+  }
+
+  return client
+    .post<ChangeAccountTierResponse>(
+      "/api/v1/changeAccountTier",
+      {
+        account_index: params.account_index,
+        new_tier: params.new_tier,
+        ...(params.auth ? { auth: params.auth } : {}),
+      },
+      config,
+    )
+    .then((response) => response.data);
+}

package/src/api/exchange/fastwithdraw.ts

@@ -0,0 +1,38 @@
+import { AxiosInstance, AxiosRequestConfig } from "axios";
+
+export interface FastWithdrawRequest {
+  tx_info: string;
+  to_address: string;
+  auth?: string;
+}
+
+export interface FastWithdrawResponse {
+  code: number;
+  message?: string;
+}
+
+export async function fastWithdraw(
+  client: AxiosInstance,
+  params: FastWithdrawRequest,
+  authorization?: string,
+): Promise<FastWithdrawResponse> {
+  const config: AxiosRequestConfig = {
+    headers: {},
+  };
+
+  if (authorization) {
+    config.headers = { Authorization: authorization };
+  }
+
+  return client
+    .post<FastWithdrawResponse>(
+      "/api/v1/fastwithdraw",
+      {
+        tx_info: params.tx_info,
+        to_address: params.to_address,
+        ...(params.auth ? { auth: params.auth } : {}),
+      },
+      config,
+    )
+    .then((response) => response.data);
+}

package/src/api/exchange/index.ts

@@ -0,0 +1,7 @@
+export * from "./change-account-tier";
+export * from "./fastwithdraw";
+export * from "./notification-ack";
+export * from "./send-tx";
+export * from "./send-tx-batch";
+export * from "./tokens-create";
+export * from "./tokens-revoke";

package/src/api/exchange/notification-ack.ts

@@ -0,0 +1,36 @@
+import { AxiosInstance } from "axios";
+
+export interface NotificationAckRequest {
+  notif_id: string;
+  account_index: number;
+}
+
+export interface NotificationAckResponse {
+  code: number;
+  message?: string;
+}
+
+export async function acknowledgeNotification(
+  client: AxiosInstance,
+  params: NotificationAckRequest,
+  authorization?: string,
+): Promise<NotificationAckResponse> {
+  const queryParams: Record<string, string> = {
+    notif_id: params.notif_id,
+    account_index: params.account_index.toString(),
+  };
+
+  const headers: Record<string, string> = {};
+  if (authorization) {
+    headers["Authorization"] = authorization;
+    headers["auth"] = authorization;
+  }
+
+  return client
+    .post<NotificationAckResponse>(
+      "/api/v1/notification/ack",
+      {},
+      { params: queryParams, headers },
+    )
+    .then((response) => response.data);
+}

package/src/api/exchange/send-tx-batch.ts

@@ -0,0 +1,53 @@
+import { AxiosInstance } from "axios";
+
+export interface SendTransactionBatchFormRequest {
+  tx_types: string;
+  tx_infos: string;
+}
+
+export interface SendTransactionBatchJsonRequest {
+  account_index: number;
+  api_key_index: number;
+  transactions: string[];
+}
+
+export type SendTransactionBatchRequest =
+  | SendTransactionBatchFormRequest
+  | SendTransactionBatchJsonRequest;
+
+export interface TxHashesResponse {
+  hashes?: string[];
+  tx_hash?: string[];
+  code?: number;
+  message?: string;
+  predicted_execution_time_ms?: number;
+}
+
+export async function sendTransactionBatch(
+  client: AxiosInstance,
+  params: SendTransactionBatchRequest,
+): Promise<TxHashesResponse> {
+  if ("tx_types" in params && "tx_infos" in params) {
+    const urlParams = new URLSearchParams();
+    urlParams.append("tx_types", params.tx_types);
+    urlParams.append("tx_infos", params.tx_infos);
+
+    return client
+      .post<TxHashesResponse>("/api/v1/sendTxBatch", urlParams, {
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      })
+      .then((response) => response.data);
+  } else if ("transactions" in params) {
+    return client
+      .post<TxHashesResponse>("/api/v1/sendTxBatch", {
+        account_index: params.account_index,
+        api_key_index: params.api_key_index,
+        transactions: params.transactions,
+      })
+      .then((response) => response.data);
+  }
+
+  throw new Error(
+    "Invalid batch params: must provide either (tx_types, tx_infos) or (transactions)",
+  );
+}

package/src/api/exchange/send-tx.ts

@@ -0,0 +1,105 @@
+import { AxiosInstance } from "axios";
+
+export interface SendTransactionRequest {
+  account_index: number;
+  api_key_index: number;
+  transaction: string;
+  price_protection?: boolean;
+}
+
+export interface SendTxFormRequest {
+  tx_type: number;
+  tx_info: string;
+  price_protection?: boolean;
+}
+
+export interface SendTxWithIndicesRequest {
+  tx_type: number;
+  tx_info: string;
+  account_index: number;
+  api_key_index: number;
+  price_protection?: boolean;
+}
+
+export interface TxHashResponse {
+  hash?: string;
+  tx_hash?: string;
+  code?: number;
+  message?: string;
+  predicted_execution_time_ms?: number;
+}
+
+export async function sendTransaction(
+  client: AxiosInstance,
+  params: SendTransactionRequest,
+): Promise<TxHashResponse> {
+  return client
+    .post<TxHashResponse>("/api/v1/sendTx", {
+      account_index: params.account_index,
+      api_key_index: params.api_key_index,
+      transaction: params.transaction,
+      ...(params.price_protection !== undefined
+        ? { price_protection: params.price_protection }
+        : {}),
+    })
+    .then((response) => response.data);
+}
+
+export async function sendTx(
+  client: AxiosInstance,
+  params: SendTxFormRequest,
+): Promise<TxHashResponse> {
+  const urlParams = new URLSearchParams();
+  urlParams.append("tx_type", params.tx_type.toString());
+  urlParams.append("tx_info", params.tx_info);
+  urlParams.append(
+    "price_protection",
+    params.price_protection !== false ? "true" : "false",
+  );
+
+  return client
+    .post<TxHashResponse>("/api/v1/sendTx", urlParams, {
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    })
+    .then((response) => response.data);
+}
+
+export async function sendTxWithIndices(
+  client: AxiosInstance,
+  params: SendTxWithIndicesRequest,
+): Promise<TxHashResponse> {
+  const urlParams = new URLSearchParams();
+  urlParams.append("tx_type", params.tx_type.toString());
+  urlParams.append("tx_info", params.tx_info);
+  urlParams.append("account_index", params.account_index.toString());
+  urlParams.append("api_key_index", params.api_key_index.toString());
+  urlParams.append(
+    "price_protection",
+    params.price_protection !== false ? "true" : "false",
+  );
+
+  return client
+    .post<TxHashResponse>("/api/v1/sendTx", urlParams, {
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    })
+    .then((response) => response.data);
+}
+
+export async function sendTxJson(
+  client: AxiosInstance,
+  params: SendTxWithIndicesRequest,
+): Promise<TxHashResponse> {
+  const payload = {
+    tx_type: params.tx_type,
+    tx_info: params.tx_info,
+    account_index: params.account_index,
+    api_key_index: params.api_key_index,
+    price_protection: params.price_protection !== false,
+  };
+
+  return client
+    .post<TxHashResponse>("/api/v1/sendTx", payload, {
+      headers: { "Content-Type": "application/json" },
+    })
+    .then((response) => response.data);
+}

package/src/api/exchange/tokens-create.ts

@@ -0,0 +1,50 @@
+import { AxiosInstance, AxiosRequestConfig } from "axios";
+
+export interface TokensCreateRequest {
+  name: string;
+  account_index: number;
+  expiry: number;
+  sub_account_access: boolean;
+  scopes?: string;
+}
+
+export interface TokensCreateResponse {
+  code: number;
+  message?: string;
+  token_id: number;
+  api_token: string;
+  name: string;
+  account_index: number;
+  expiry: number;
+  sub_account_access: boolean;
+  revoked: boolean;
+  scopes: string;
+}
+
+export async function createToken(
+  client: AxiosInstance,
+  params: TokensCreateRequest,
+  authorization?: string,
+): Promise<TokensCreateResponse> {
+  const config: AxiosRequestConfig = {
+    headers: {},
+  };
+
+  if (authorization) {
+    config.headers = { Authorization: authorization };
+  }
+
+  return client
+    .post<TokensCreateResponse>(
+      "/api/v1/tokens/create",
+      {
+        name: params.name,
+        account_index: params.account_index,
+        expiry: params.expiry,
+        sub_account_access: params.sub_account_access,
+        ...(params.scopes ? { scopes: params.scopes } : { scopes: "read.*" }),
+      },
+      config,
+    )
+    .then((response) => response.data);
+}

package/src/api/exchange/tokens-revoke.ts

@@ -0,0 +1,38 @@
+import { AxiosInstance, AxiosRequestConfig } from "axios";
+
+export interface TokensRevokeRequest {
+  token_id: number;
+  account_index: number;
+}
+
+export interface TokensRevokeResponse {
+  code: number;
+  message?: string;
+  token_id: number;
+  revoked: boolean;
+}
+
+export async function revokeToken(
+  client: AxiosInstance,
+  params: TokensRevokeRequest,
+  authorization?: string,
+): Promise<TokensRevokeResponse> {
+  const config: AxiosRequestConfig = {
+    headers: {},
+  };
+
+  if (authorization) {
+    config.headers = { Authorization: authorization };
+  }
+
+  return client
+    .post<TokensRevokeResponse>(
+      "/api/v1/tokens/revoke",
+      {
+        token_id: params.token_id,
+        account_index: params.account_index,
+      },
+      config,
+    )
+    .then((response) => response.data);
+}

package/src/api/index.ts

@@ -0,0 +1,3 @@
+export * from "./info";
+export * from "./info-private";
+export * from "./exchange";

package/src/api/info/account-by-l1-address.ts

@@ -0,0 +1,23 @@
+import { AxiosInstance } from "axios";
+
+export interface AccountByL1AddressRequest {
+  l1_address: string;
+}
+
+export interface AccountAccountByL1AddressResponse {
+  code: number;
+  message?: string;
+  account_index: number;
+  l1_address: string;
+}
+
+export async function getAccountByL1Address(
+  client: AxiosInstance,
+  params: AccountByL1AddressRequest,
+): Promise<AccountAccountByL1AddressResponse> {
+  return client
+    .get<AccountAccountByL1AddressResponse>("/api/v1/accountByL1Address", {
+      params: params,
+    })
+    .then((response) => response.data);
+}

package/src/api/info/account.ts

@@ -0,0 +1,80 @@
+import { AxiosInstance } from "axios";
+
+export interface AccountRequest {
+  by: "index" | "l1_address";
+  value: string;
+}
+
+export interface AccountPosition {
+  market_id: number;
+  symbol: string;
+  initial_margin_fraction: string;
+  open_order_count: number;
+  pending_order_count: number;
+  position_tied_order_count: number;
+  sign: number;
+  position: string;
+  avg_entry_price: string;
+  position_value: string;
+  unrealized_pnl: string;
+  realized_pnl: string;
+  liquidation_price: string;
+  margin_mode: number;
+  allocated_margin: string;
+}
+
+export interface AccountAsset {
+  symbol: string;
+  asset_id: number;
+  balance: string;
+  locked_balance: string;
+}
+
+export interface AccountShare {
+  public_pool_index: number;
+  shares_amount: number;
+  entry_usdc: string;
+}
+
+export interface AccountInfo {
+  code: number;
+  message?: string;
+  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;
+  account_index: number;
+  name: string;
+  description: string;
+  can_invite: boolean;
+  referral_points_percentage: string;
+  positions: AccountPosition[];
+  assets: AccountAsset[];
+  total_asset_value: string;
+  cross_asset_value: string;
+  shares: AccountShare[];
+}
+
+export interface AccountResponse {
+  code: number;
+  message?: string;
+  total: number;
+  accounts: AccountInfo[];
+}
+
+export async function getAccountInfo(
+  client: AxiosInstance,
+  params: AccountRequest,
+): Promise<AccountResponse> {
+  return client
+    .get<AccountResponse>("/api/v1/account", {
+      params: params,
+    })
+    .then((response) => response.data);
+}

package/src/api/info/announcement.ts

@@ -0,0 +1,24 @@
+import { AxiosInstance } from "axios";
+
+export interface Announcement {
+  id: number;
+  title: string;
+  content: string;
+  created_at: number;
+  updated_at: number;
+  is_active: boolean;
+}
+
+export interface AnnouncementsResponse {
+  code: number;
+  message?: string;
+  announcements: Announcement[];
+}
+
+export async function getAnnouncements(
+  client: AxiosInstance,
+): Promise<AnnouncementsResponse> {
+  return client
+    .get<AnnouncementsResponse>("/api/v1/announcements")
+    .then((response) => response.data);
+}

package/src/api/info/api-keys.ts

@@ -0,0 +1,32 @@
+import { AxiosInstance } from "axios";
+
+export interface ApiKeysRequest {
+  account_index: number;
+  api_key_index: number;
+}
+
+export interface ApiKey {
+  account_index: number;
+  api_key_index: number;
+  nonce: number;
+  public_key: string;
+  transaction_time: number;
+}
+
+export interface ApiKeysResponse {
+  api_keys: ApiKey[];
+}
+
+export async function getApiKeys(
+  client: AxiosInstance,
+  params: ApiKeysRequest,
+): Promise<ApiKeysResponse> {
+  return client
+    .get<ApiKeysResponse>("/api/v1/apikeys", {
+      params: {
+        account_index: params.account_index,
+        api_key_index: params.api_key_index,
+      },
+    })
+    .then((response) => response.data);
+}

package/src/api/info/asset-details.ts

@@ -0,0 +1,42 @@
+import { AxiosInstance, AxiosRequestConfig } from "axios";
+
+export interface AssetDetailsRequest {
+  asset_id?: number;
+}
+
+export interface AssetDetail {
+  asset_id: number;
+  symbol: string;
+  l1_decimals: number;
+  decimals: number;
+  extension_multiplier: number;
+  min_transfer_amount: number;
+  min_withdrawal_amount: number;
+  margin_mode: number;
+  index_price: number;
+  l1_address: string;
+  tick_size: string;
+}
+
+export interface AssetDetailsResponse {
+  code: number;
+  message?: string;
+  asset_details: AssetDetail[];
+}
+
+export async function getAssetDetails(
+  client: AxiosInstance,
+  params?: AssetDetailsRequest,
+): Promise<AssetDetailsResponse> {
+  const config: AxiosRequestConfig = {
+    params: {
+      ...(params?.asset_id !== undefined
+        ? { asset_id: params.asset_id }
+        : {}),
+    },
+  };
+
+  return client
+    .get<AssetDetailsResponse>("/api/v1/assetDetails", config)
+    .then((response) => response.data);
+}

package/src/api/info/candles.ts

@@ -0,0 +1,31 @@
+import { AxiosInstance } from "axios";
+
+export interface Candlestick {
+  t: number;
+  o: number;
+  h: number;
+  l: number;
+  c: number;
+  v: number;
+}
+
+export interface CandlesRequest {
+  market_id: number;
+  resolution: string;
+  start_timestamp: number;
+  end_timestamp: number;
+  count_back: number;
+}
+
+export interface CandlesResponse {
+  c: Candlestick[];
+}
+
+export async function getCandlesticks(
+  client: AxiosInstance,
+  params: CandlesRequest,
+): Promise<CandlesResponse> {
+  return client
+    .get<CandlesResponse>("/api/v1/candles", { params })
+    .then((response) => response.data);
+}

package/src/api/info/exchange-stats.ts

@@ -0,0 +1,16 @@
+import { AxiosInstance } from "axios";
+
+export interface ExchangeStatsResponse {
+  total_volume_24h: string;
+  total_trades_24h: number;
+  total_orders_24h: number;
+  active_markets: number;
+}
+
+export async function getExchangeStats(
+  client: AxiosInstance,
+): Promise<ExchangeStatsResponse> {
+  return client
+    .get<ExchangeStatsResponse>("/api/v1/exchangeStats")
+    .then((response) => response.data);
+}