@lifi/perps-sdk-provider-lighter 20.0.0 → 22.0.0

package/src/types/activity.ts

@@ -1,5 +1,6 @@
 // Activity history shapes returned by Lighter's REST API
 // (deposits, withdrawals, funding payments, liquidations, transfers).
+// Lighter serializes an empty list as JSON `null`, so list members are nullable.
 
 import type { LtAccountPosition } from './account.js'
 
@@ -27,7 +28,7 @@ export interface LtDepositHistoryItem {
  */
 export interface LtDepositHistoryResponse {
   code: number
-  deposits: LtDepositHistoryItem[]
+  deposits: LtDepositHistoryItem[] | null
   cursor?: string
 }
 
@@ -56,7 +57,7 @@ export interface LtWithdrawHistoryItem {
  */
 export interface LtWithdrawHistoryResponse {
   code: number
-  withdraws: LtWithdrawHistoryItem[]
+  withdraws: LtWithdrawHistoryItem[] | null
   cursor?: string
 }
 
@@ -80,6 +81,8 @@ export interface LtPositionFunding {
   rate: string
   position_size: string
   position_side: string
+  /** Funding-fee discount Lighter applied to `change`, as a decimal string. */
+  discount?: string
 }
 
 /**
@@ -90,7 +93,7 @@ export interface LtPositionFunding {
  */
 export interface LtPositionFundingsResponse {
   code: number
-  position_fundings: LtPositionFunding[]
+  position_fundings: LtPositionFunding[] | null
   next_cursor?: string
 }
 
@@ -142,7 +145,7 @@ export type LtLiquidationPosition = Pick<
  * @public
  */
 export interface LtLiquidationInfo {
-  positions: LtLiquidationPosition[]
+  positions: LtLiquidationPosition[] | null
   risk_info_before: {
     // Lighter's OpenAPI does not require this member, so an account without
     // cross exposure may omit it.
@@ -176,7 +179,7 @@ export interface LtLiquidation {
  */
 export interface LtLiquidationsResponse {
   code: number
-  liquidations: LtLiquidation[]
+  liquidations: LtLiquidation[] | null
   next_cursor?: string
 }
 
@@ -212,6 +215,6 @@ export interface LtTransfer {
  */
 export interface LtTransferHistoryResponse {
   code: number
-  transfers: LtTransfer[]
+  transfers: LtTransfer[] | null
   cursor?: string
 }

package/src/types/fill.ts

@@ -1,4 +1,5 @@
 // Trade (fill) shapes returned by Lighter's `/api/v1/trades` endpoint.
+// Lighter serializes an empty list as JSON `null`, so list members are nullable.
 
 /**
  * Public trade/fill row returned by Lighter's `/api/v1/trades` endpoint.
@@ -54,6 +55,10 @@ export type LtTrade = {
   // older trade rows that predate the field.
   taker_initial_margin_fraction_before?: number
   maker_initial_margin_fraction_before?: number
+  /** Version of the resting ask order the trade matched against. */
+  ask_order_version?: number
+  /** Version of the resting bid order the trade matched against. */
+  bid_order_version?: number
 }
 
 /**
@@ -65,5 +70,5 @@ export type LtTrade = {
 export interface LtTradesResponse {
   code: number
   next_cursor: string
-  trades: LtTrade[]
+  trades: LtTrade[] | null
 }

package/src/types/order.ts

@@ -1,4 +1,5 @@
 // Order shapes returned by Lighter's REST API.
+// Lighter serializes an empty list as JSON `null`, so list members are nullable.
 
 /**
  * Order payload returned by Lighter's REST API. Amounts and prices are decimal
@@ -46,6 +47,8 @@ export type LtOrder = {
   timestamp: number
   created_at: number
   updated_at: number
+  /** Lighter bit flags recording the order's wire options. */
+  order_flags?: number
   /**
    * Unix timestamp in microseconds. Lighter documents no unit, and its public
    * trade rows report this member in microseconds while the sibling
@@ -63,7 +66,20 @@ export type LtOrder = {
 export interface LtOrdersResponse {
   code: number
   next_cursor: string
-  orders: LtOrder[]
+  orders: LtOrder[] | null
+}
+
+/**
+ * Order-lookup response from Lighter's `accountOrders` path. The lookup takes
+ * up to 20 `client_order_indexes` rather than a page, so it carries no cursor.
+ * It reaches the last 10K active orders with no time bound, and the last 1K
+ * inactive orders from the past 24 hours.
+ *
+ * @public
+ */
+export interface LtAccountOrdersResponse {
+  code: number
+  orders: LtOrder[] | null
 }
 
 /**

package/src/utils/apiClient.ts

@@ -9,6 +9,7 @@ import {
   LIGHTER_SUCCESS_CODES,
   LIGHTER_TOKEN_REVOKED_CODE,
 } from '../constants.js'
+import { lighterErrorCodeFromBody } from './lighterErrorCode.js'
 
 /** @internal */
 export type ApiParams = Record<string, string | number | boolean>
@@ -48,6 +49,28 @@ const isLighterAuthRejection = (status: number, data: unknown): boolean =>
 const isLighterTokenRevoked = (data: unknown): boolean =>
   lighterBodyErrorCode(data) === LIGHTER_TOKEN_REVOKED_CODE
 
+/**
+ * A CR or LF in a token would split the request when it reaches a
+ * `fetchImpl` that does not validate header values itself. A blank token
+ * would dispatch an `Authorization` header that carries no credential at
+ * all, which Lighter answers as a generic rejection.
+ */
+const assertHeaderSafe = (authToken: string): string => {
+  if (authToken.trim().length === 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Lighter auth token is blank and cannot go in a header'
+    )
+  }
+  if (/[\r\n]/.test(authToken)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Lighter auth token carries a line break and cannot go in a header'
+    )
+  }
+  return authToken
+}
+
 /** @internal */
 export const LIGHTER_RETRY_DEFAULTS: ResolvedRetryPolicy = {
   enabled: true,
@@ -115,9 +138,17 @@ export interface LighterApiClientOptions {
  *
  * Auth-gated endpoints (accountLimits, accountActiveOrders, deposit/history,
  * withdraw/history, positionFunding, liquidations, transfer/history) take the
- * Lighter read-only token as the `auth` query parameter — NOT as an
- * `Authorization` header. This matches Lighter's OpenAPI spec and lets the
- * same call work browser-direct and from server-side proxies.
+ * Lighter read-only token in the `Authorization` header, which is the only
+ * auth channel Lighter's OpenAPI spec declares. The header makes such a read
+ * CORS-preflighted; both Lighter hosts answer the `OPTIONS` probe with
+ * `Authorization` in `Access-Control-Allow-Headers` and
+ * `Access-Control-Max-Age: 86400`, so a browser sends one preflight per day
+ * per origin.
+ *
+ * The `/api/v1/changeAccountTier` and `/api/v1/referral/use` mutations send
+ * the same header with a fresh per-call token. Their `OPTIONS` response is
+ * not yet probed against a live host, so a browser may reject the preflight
+ * even though the GET paths pass.
  *
  * Lighter signals rate limits through HTTP 429 or HTTP 405. This client never
  * retries such a response. It throws `RateLimitExceeded` and holds all network
@@ -198,29 +229,24 @@ export class LighterApiClient {
     return this.getChecked<T>(path, params)
   }
 
-  /**
-   * Auth-gated GET. The token is appended as the `auth` query parameter (per
-   * Lighter's OpenAPI spec); the `Authorization` header is intentionally NOT
-   * used — Lighter rejects it.
-   */
+  /** Auth-gated GET carrying the Lighter token in the `Authorization` header. */
   async getAuthed<T>(
     path: string,
     authToken: string,
     params: ApiParams = {}
   ): Promise<T> {
-    const { status, data } = await this.getWithStatus<unknown>(path, {
-      ...params,
-      auth: authToken,
+    const { status, data } = await this.sendGet<unknown>(path, params, {
+      Authorization: assertHeaderSafe(authToken),
     })
     if (isLighterTokenRevoked(data)) {
       throw new LighterTokenRevokedError(
-        PerpsErrorCode.ThirdPartyError,
+        PerpsErrorCode.Unauthorized,
         `Lighter reports a revoked auth token for ${path}`
       )
     }
     if (isLighterAuthRejection(status, data)) {
       throw new LighterAuthRejectedError(
-        PerpsErrorCode.ThirdPartyError,
+        PerpsErrorCode.Unauthorized,
         `Lighter rejected the auth token for ${path}`
       )
     }
@@ -236,12 +262,20 @@ export class LighterApiClient {
   async getWithStatus<T>(
     path: string,
     params?: ApiParams
+  ): Promise<{ status: number; data: T }> {
+    return this.sendGet<T>(path, params)
+  }
+
+  private async sendGet<T>(
+    path: string,
+    params?: ApiParams,
+    headers?: Record<string, string>
   ): Promise<{ status: number; data: T }> {
     this.assertRequestAllowed()
     const url = this.buildUrl(path, params)
     const response = await fetchWithRetry(
       url,
-      {},
+      headers === undefined ? {} : { headers },
       {
         policy: this.policy,
         fetchImpl: this.fetchWithHold,
@@ -254,13 +288,15 @@ export class LighterApiClient {
   }
 
   /**
-   * Form-encoded POST to a Lighter mutation endpoint. Single-shot — never
-   * retried, since these are money/state writes whose outcome is unknown on a
-   * transport failure. Surfaces the raw `{status, body}` pair so the caller can
-   * map Lighter's per-endpoint business-rule `code` to a domain error verbatim.
+   * Form-encoded POST to a Lighter mutation endpoint, carrying the Lighter
+   * token in the `Authorization` header. Single-shot — never retried, since
+   * these are money/state writes whose outcome is unknown on a transport
+   * failure. Surfaces the raw `{status, body}` pair so the caller can map
+   * Lighter's per-endpoint business-rule `code` to a domain error verbatim.
    */
   async postForm<T>(
     path: string,
+    authToken: string,
     params: ApiParams
   ): Promise<{ status: number; data: T }> {
     const body = new URLSearchParams()
@@ -269,7 +305,10 @@ export class LighterApiClient {
     }
     const response = await this.fetchWithHold(`${this.baseUrl}${path}`, {
       method: 'POST',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      headers: {
+        'content-type': 'application/x-www-form-urlencoded',
+        Authorization: assertHeaderSafe(authToken),
+      },
       body: body.toString(),
       signal: this.signal,
     })
@@ -279,27 +318,31 @@ export class LighterApiClient {
   }
 
   private async getChecked<T>(path: string, params?: ApiParams): Promise<T> {
-    const { status, data } = await this.getWithStatus<unknown>(path, params)
+    const { status, data } = await this.sendGet<unknown>(path, params)
     this.assertOk(path, status, data)
     return data as T
   }
 
   /**
    * Post-parse validation shared by every checked read: rejects a non-2xx HTTP
-   * status and a 200 body carrying a non-success `code`. Callers that surface a
-   * distinct auth-rejection error must run that check before this one.
+   * status and a 200 body carrying a non-success `code`. A body `code` that
+   * names a nonce, margin, or balance rejection sets the matching
+   * `PerpsErrorCode`; every other rejection is `ThirdPartyError`. Callers that
+   * surface a distinct auth-rejection error must run that check before this one.
    */
   private assertOk(path: string, status: number, data: unknown): void {
+    const errorCode = lighterBodyErrorCode(data)
+    const code =
+      lighterErrorCodeFromBody(errorCode) ?? PerpsErrorCode.ThirdPartyError
     if (status < 200 || status >= 300) {
       throw new PerpsError(
-        PerpsErrorCode.ThirdPartyError,
+        code,
         `Lighter API request failed: ${status} — ${JSON.stringify(data).slice(0, 200)}`
       )
     }
-    const errorCode = lighterBodyErrorCode(data)
     if (errorCode !== undefined) {
       throw new PerpsError(
-        PerpsErrorCode.ThirdPartyError,
+        code,
         `Lighter API error for ${path}: code ${errorCode} — ${JSON.stringify(data).slice(0, 200)}`
       )
     }

package/src/utils/fetchDetailedAccount.ts

@@ -2,22 +2,24 @@ import { PerpsError } from '@lifi/perps-sdk'
 import { PerpsErrorCode } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { LIGHTER_CODE_ACCOUNT_NOT_FOUND } from '../constants.js'
-import type { LtDetailedAccount } from '../types/index.js'
+import type { LtAccount, LtDetailedAccount } from '../types/index.js'
 import type { LighterApiClient } from './apiClient.js'
+import { wireList } from './wireList.js'
 
 /**
  * Look up the Lighter account for an L1 address via `/api/v1/account`,
  * discriminating Lighter's account-not-found body code from generic failures.
+ * The returned account carries real arrays for `positions` and `assets`.
  *
  * @public
  */
 export const fetchDetailedAccount = async (
   client: LighterApiClient,
   address: Address
-): Promise<LtDetailedAccount> => {
+): Promise<LtAccount> => {
   const { status, data } = await client.getWithStatus<{
     code: number
-    accounts?: LtDetailedAccount[]
+    accounts?: LtDetailedAccount[] | null
     message?: string
   }>('/api/v1/account', { by: 'l1_address', value: address })
 
@@ -35,12 +37,17 @@ export const fetchDetailedAccount = async (
     )
   }
 
-  const accounts = data?.accounts
-  if (accounts === undefined || accounts.length === 0) {
+  const accounts = wireList(data?.accounts)
+  const account = accounts[0]
+  if (account === undefined) {
     throw new PerpsError(
       PerpsErrorCode.AccountNotFound,
       `No Lighter account found for address: ${address}`
     )
   }
-  return accounts[0]
+  return {
+    ...account,
+    positions: wireList(account.positions),
+    assets: wireList(account.assets),
+  }
 }

package/src/utils/lighterErrorCode.ts

@@ -0,0 +1,30 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+
+/** Lighter body `code` values that name a rejection a `PerpsErrorCode` describes. */
+const LIGHTER_BODY_ERROR_CODES: ReadonlyMap<number, PerpsErrorCode> = new Map([
+  // invalid nonce
+  [21104, PerpsErrorCode.InvalidNonce],
+  // batch transaction nonce is not increasing
+  [21105, PerpsErrorCode.InvalidNonce],
+  // not enough collateral
+  [21301, PerpsErrorCode.InsufficientBalance],
+  // not enough asset balance
+  [21304, PerpsErrorCode.InsufficientBalance],
+  // not enough asset balance for fee
+  [21305, PerpsErrorCode.InsufficientBalance],
+  // account is below maintenance margin
+  [21507, PerpsErrorCode.InsufficientMargin],
+  // account is below initial margin
+  [21508, PerpsErrorCode.InsufficientMargin],
+  // not enough margin to create the order
+  [21739, PerpsErrorCode.InsufficientMargin],
+])
+
+/**
+ * Maps a Lighter body error `code` to the `PerpsErrorCode` it names. Returns
+ * `undefined` for every other code so the status-driven layer decides.
+ */
+export const lighterErrorCodeFromBody = (
+  code: number | undefined
+): PerpsErrorCode | undefined =>
+  code === undefined ? undefined : LIGHTER_BODY_ERROR_CODES.get(code)

package/src/utils/ohlcvInterval.ts

@@ -6,7 +6,7 @@ import { PerpsErrorCode } from '@lifi/perps-types'
  * Map our `OhlcvInterval` literal to Lighter's `resolution` enum.
  *
  * Lighter exposes only the timeframes listed below. SDK intervals without a
- * direct match (3m, 2h, 8h, 3d, 1M) raise a validation error rather than
+ * direct match (3m, 2h, 8h, 3d, 1w, 1M) raise a validation error rather than
  * silently rounding — the caller picks a supported timeframe.
  */
 const LIGHTER_SUPPORTED_INTERVALS: Partial<Record<OhlcvInterval, string>> = {
@@ -18,7 +18,6 @@ const LIGHTER_SUPPORTED_INTERVALS: Partial<Record<OhlcvInterval, string>> = {
   '4h': '4h',
   '12h': '12h',
   '1d': '1d',
-  '1w': '1w',
 }
 
 /**

package/src/utils/wireList.ts

@@ -0,0 +1,9 @@
+/**
+ * Read a Lighter wire list member. Lighter serializes an empty list as JSON
+ * `null` rather than `[]`, so every list the SDK reads off a REST body passes
+ * through this at the response boundary and every mapper downstream works on a
+ * real array.
+ *
+ * @internal
+ */
+export const wireList = <T>(value: T[] | null | undefined): T[] => value ?? []