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

package/dist/types/utils/fetchDetailedAccount.d.ts

@@ -1,11 +1,12 @@
 import type { Address } from 'viem';
-import type { LtDetailedAccount } from '../types/index.js';
+import type { LtAccount } from '../types/index.js';
 import type { LighterApiClient } from './apiClient.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 declare const fetchDetailedAccount: (client: LighterApiClient, address: Address) => Promise<LtDetailedAccount>;
+export declare const fetchDetailedAccount: (client: LighterApiClient, address: Address) => Promise<LtAccount>;
 //# sourceMappingURL=fetchDetailedAccount.d.ts.map

package/dist/types/utils/fetchDetailedAccount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetchDetailedAccount.d.ts","sourceRoot":"","sources":["../../../src/utils/fetchDetailedAccount.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,gBAAgB,EACxB,SAAS,OAAO,KACf,OAAO,CAAC,iBAAiB,CA6B3B,CAAA"}
+{"version":3,"file":"fetchDetailedAccount.d.ts","sourceRoot":"","sources":["../../../src/utils/fetchDetailedAccount.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,mBAAmB,CAAA;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGtD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,gBAAgB,EACxB,SAAS,OAAO,KACf,OAAO,CAAC,SAAS,CAkCnB,CAAA"}

package/dist/types/utils/lighterErrorCode.d.ts

@@ -0,0 +1,7 @@
+import { PerpsErrorCode } from '@lifi/perps-types';
+/**
+ * Maps a Lighter body error `code` to the `PerpsErrorCode` it names. Returns
+ * `undefined` for every other code so the status-driven layer decides.
+ */
+export declare const lighterErrorCodeFromBody: (code: number | undefined) => PerpsErrorCode | undefined;
+//# sourceMappingURL=lighterErrorCode.d.ts.map

package/dist/types/utils/lighterErrorCode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lighterErrorCode.d.ts","sourceRoot":"","sources":["../../../src/utils/lighterErrorCode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAsBlD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GACnC,MAAM,MAAM,GAAG,SAAS,KACvB,cAAc,GAAG,SACiD,CAAA"}

package/dist/types/utils/ohlcvInterval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ohlcvInterval.d.ts","sourceRoot":"","sources":["../../../src/utils/ohlcvInterval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAsBtD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,aAAa,KAAG,MAUrD,CAAA"}
+{"version":3,"file":"ohlcvInterval.d.ts","sourceRoot":"","sources":["../../../src/utils/ohlcvInterval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAqBtD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,aAAa,KAAG,MAUrD,CAAA"}

package/dist/types/utils/wireList.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare const wireList: <T>(value: T[] | null | undefined) => T[];
+//# sourceMappingURL=wireList.d.ts.map

package/dist/types/utils/wireList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wireList.d.ts","sourceRoot":"","sources":["../../../src/utils/wireList.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,KAAG,CAAC,EAAiB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-lighter",
-  "version": "20.0.0",
+  "version": "22.0.0",
   "description": "Lighter provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -44,10 +44,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^12.0.1"
+    "@lifi/perps-types": "^12.1.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^12.0.0"
+    "@lifi/perps-sdk": "^12.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/LighterProvider.ts

@@ -4,6 +4,7 @@ import {
   getAssetRegistry,
   getMarketRegistry,
   getProviders,
+  isActiveOrderStatus,
   localStorageAdapter,
   PerpsError,
   type PerpsProviderPlugin,
@@ -66,6 +67,7 @@ import {
   DEFAULT_TRADES_LIMIT,
   LIGHTER_ALL_MARKETS_WILDCARD,
   LIGHTER_BASE_FEE_TIER,
+  LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX,
   LIGHTER_FEE_TICK_SCALE,
   LIGHTER_HISTORY_PAGE_SIZE,
   LIGHTER_MAINNET_DEPLOYMENT,
@@ -86,15 +88,22 @@ import {
   lighterSignActions,
 } from './signers/signActions.js'
 import type {
+  LtAccount,
   LtAccountLimits,
+  LtAccountOrdersResponse,
+  LtDepositHistoryItem,
   LtDepositHistoryResponse,
-  LtDetailedAccount,
   LtDetailedAccountPosition,
+  LtLiquidation,
   LtLiquidationsResponse,
+  LtOrder,
   LtOrdersResponse,
+  LtPositionFunding,
   LtPositionFundingsResponse,
   LtTradesResponse,
+  LtTransfer,
   LtTransferHistoryResponse,
+  LtWithdrawHistoryItem,
   LtWithdrawHistoryResponse,
 } from './types/index.js'
 import { LT_MARGIN_MODE_CROSS, LT_MARGIN_MODE_ISOLATED } from './types/index.js'
@@ -132,6 +141,7 @@ import {
   fetchRegisteredApiKey,
   normalizeLighterPublicKey,
 } from './utils/registeredApiKey.js'
+import { wireList } from './utils/wireList.js'
 
 const ZERO_FEE_TIER = { maker: '0', taker: '0' }
 
@@ -158,6 +168,13 @@ const orderCountFor = (p: LtDetailedAccountPosition): number =>
  */
 const TX_HASH_PATTERN = /^[0-9a-f]{80}$/
 
+/**
+ * Lighter's `client_order_index` is an int64 and `accountOrders` takes it as a
+ * decimal string, so a prefixed id's suffix goes to the venue verbatim rather
+ * than through a lossy JS number.
+ */
+const CLIENT_ORDER_INDEX_PATTERN = /^\d+$/
+
 const INACTIVE_ORDERS_LOOKUP_LIMIT = 100
 
 /** Activity surfaces whose rows name a market, so they need the market registry. */
@@ -560,19 +577,35 @@ export const createLighterProvider = (
       account_index: accountIndex,
     })
 
-  const fetchActiveOrdersForMarket = (
+  const fetchActiveOrders = async (
     client: LighterApiClient,
     authToken: string,
     accountIndex: number,
     marketId: number
-  ): Promise<LtOrdersResponse> =>
-    client.getAuthed<LtOrdersResponse>(
+  ): Promise<LtOrdersResponse & { orders: LtOrder[] }> => {
+    const response = await client.getAuthed<LtOrdersResponse>(
       '/api/v1/accountActiveOrders',
       authToken,
       { account_index: accountIndex, market_id: marketId }
     )
+    return { ...response, orders: wireList(response.orders) }
+  }
 
-  const deriveOrderBearingMarketIds = (account: LtDetailedAccount): number[] =>
+  const fetchOrdersByClientOrderIndex = async (
+    client: LighterApiClient,
+    authToken: string,
+    accountIndex: number,
+    clientOrderIndex: string
+  ): Promise<LtOrder[]> => {
+    const response = await client.getAuthed<LtAccountOrdersResponse>(
+      '/api/v1/accountOrders',
+      authToken,
+      { account_index: accountIndex, client_order_indexes: clientOrderIndex }
+    )
+    return wireList(response.orders)
+  }
+
+  const deriveOrderBearingMarketIds = (account: LtAccount): number[] =>
     account.positions
       .filter((p) => orderCountFor(p) > 0)
       .map((p) => p.market_id)
@@ -585,11 +618,15 @@ export const createLighterProvider = (
     requested: ActivityType[] | undefined,
     inputCursor: LighterActivityCursor | undefined
   ): Promise<{
-    deposits: LtDepositHistoryResponse
-    withdraws: LtWithdrawHistoryResponse
-    fundings: LtPositionFundingsResponse
-    liquidations: LtLiquidationsResponse
-    transfers: LtTransferHistoryResponse
+    deposits: LtDepositHistoryResponse & { deposits: LtDepositHistoryItem[] }
+    withdraws: LtWithdrawHistoryResponse & {
+      withdraws: LtWithdrawHistoryItem[]
+    }
+    fundings: LtPositionFundingsResponse & {
+      position_fundings: LtPositionFunding[]
+    }
+    liquidations: LtLiquidationsResponse & { liquidations: LtLiquidation[] }
+    transfers: LtTransferHistoryResponse & { transfers: LtTransfer[] }
   }> => {
     const wantsType = (t: ActivityType): boolean =>
       requested === undefined || requested.includes(t)
@@ -643,7 +680,6 @@ export const createLighterProvider = (
               token,
               {
                 account_index: accountIndex,
-                market_id: LIGHTER_ALL_MARKETS_WILDCARD,
                 limit: LIGHTER_HISTORY_PAGE_SIZE,
                 ...cursorParam('fundings'),
               }
@@ -670,7 +706,30 @@ export const createLighterProvider = (
           : Promise.resolve(empty({ code: 0, transfers: [] })),
       ])
 
-    return { deposits, withdraws, fundings, liquidations, transfers }
+    return {
+      deposits: {
+        ...deposits,
+        deposits: wireList<LtDepositHistoryItem>(deposits.deposits),
+      },
+      withdraws: {
+        ...withdraws,
+        withdraws: wireList<LtWithdrawHistoryItem>(withdraws.withdraws),
+      },
+      fundings: {
+        ...fundings,
+        position_fundings: wireList<LtPositionFunding>(
+          fundings.position_fundings
+        ),
+      },
+      liquidations: {
+        ...liquidations,
+        liquidations: wireList<LtLiquidation>(liquidations.liquidations),
+      },
+      transfers: {
+        ...transfers,
+        transfers: wireList<LtTransfer>(transfers.transfers),
+      },
+    }
   }
 
   const resolveAccountExists = async (
@@ -924,7 +983,7 @@ export const createLighterProvider = (
       if (params.market.categoryId === LIGHTER_SPOT_CATEGORY_ID) {
         return undefined
       }
-      let account: LtDetailedAccount
+      let account: LtAccount
       try {
         account = await fetchDetailedAccount(apiClient(opts), params.address)
       } catch (err) {
@@ -982,21 +1041,17 @@ export const createLighterProvider = (
         registry.sync(),
       ])
 
-      const marketIds =
+      const marketId =
         params.marketId === undefined
-          ? deriveOrderBearingMarketIds(account)
-          : [Number(registry.require(params.marketId).id)]
+          ? LIGHTER_ALL_MARKETS_WILDCARD
+          : Number(registry.require(params.marketId).id)
 
-      const responses = await retryOnRevoked(opts, params.address, token, (t) =>
-        Promise.all(
-          marketIds.map((id) =>
-            fetchActiveOrdersForMarket(client, t, account.index, id)
-          )
-        )
+      const response = await retryOnRevoked(opts, params.address, token, (t) =>
+        fetchActiveOrders(client, t, account.index, marketId)
       )
 
       const { openOrders, triggerOrders } = classifyAndMapOrders(
-        responses.flatMap((r) => r.orders),
+        response.orders,
         (marketIndex) => registry.require(String(marketIndex))
       )
 
@@ -1030,9 +1085,7 @@ export const createLighterProvider = (
           : [Number(registry.require(params.marketId).id)]
       const responses = await retryOnRevoked(opts, params.address, token, (t) =>
         Promise.all(
-          marketIds.map((id) =>
-            fetchActiveOrdersForMarket(client, t, account.index, id)
-          )
+          marketIds.map((id) => fetchActiveOrders(client, t, account.index, id))
         )
       )
 
@@ -1052,6 +1105,14 @@ export const createLighterProvider = (
       return twaps
     },
 
+    /**
+     * Resolves either reference Lighter hands out for an order: a bare
+     * `order_index` — the value `Order.orderId` carries, as streamed by
+     * `orderUpdates` / `fills` — or a `client_order_index` prefixed with
+     * {@link LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX}, which a signed placement
+     * step returns and which resolves before the venue has assigned an
+     * `order_index`.
+     */
     async getOrder(
       params: ProviderGetOrderParams,
       opts?: SDKRequestOptions
@@ -1073,41 +1134,75 @@ export const createLighterProvider = (
         registry.sync(),
       ])
 
-      // Native `order_index` route only. The cross-provider `Order.orderId`
-      // for Lighter is `String(order_index)` — see `mapOrder`. A tx-hash route
-      // would require mapping the caller's executeAction tx hash → wasm nonce
-      // → matching order, which the LI.FI backend did via its `UserAction`
-      // table; the SDK has no equivalent persistence, so we refuse rather
-      // than mis-resolve.
+      const notFound = (): PerpsError =>
+        new PerpsError(
+          PerpsErrorCode.OrderNotFound,
+          `Lighter order ${params.id} not found for ${params.address}`
+        )
+      const detail = (order: LtOrder): Order =>
+        mapOrderDetail(order, registry.require(String(order.market_index)))
+
+      // A tx-hash route would require mapping the caller's executeAction tx
+      // hash → wasm nonce → matching order, which the LI.FI backend did via
+      // its `UserAction` table; the SDK has no equivalent persistence, so we
+      // refuse rather than mis-resolve.
       if (TX_HASH_PATTERN.test(params.id)) {
         throw new PerpsError(
           PerpsErrorCode.OrderNotFound,
           `Lighter order id "${params.id}" looks like a tx hash. The SDK ` +
-            `resolves orders by Lighter \`order_index\` only — surface the orderId ` +
-            `from the orderUpdates / fills WS stream and pass it here.`
+            `resolves orders by Lighter \`order_index\` or by a ` +
+            `\`${LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX}<index>\` id — surface the ` +
+            `orderId from the orderUpdates / fills WS stream, or the ` +
+            `clientOrderIndex from the signed placement step, and pass it here.`
         )
       }
-      const predicate: (o: { order_index: number }) => boolean = (o) =>
-        String(o.order_index) === params.id
 
-      const marketIds = deriveOrderBearingMarketIds(account)
-      const activeResponses = await retryOnRevoked(
-        opts,
-        params.address,
-        token,
-        (t) =>
-          Promise.all(
-            marketIds.map((id) =>
-              fetchActiveOrdersForMarket(client, t, account.index, id)
-            )
+      if (params.id.startsWith(LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX)) {
+        const clientOrderIndex = params.id.slice(
+          LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX.length
+        )
+        if (!CLIENT_ORDER_INDEX_PATTERN.test(clientOrderIndex)) {
+          throw new PerpsError(
+            PerpsErrorCode.SDKError,
+            `Lighter order id "${params.id}" names a client order index, but ` +
+              `"${clientOrderIndex}" is not a decimal integer.`
           )
-      )
-
-      for (const response of activeResponses) {
-        const hit = response.orders.find(predicate as (o: unknown) => boolean)
-        if (hit !== undefined) {
-          return mapOrderDetail(hit, registry.require(String(hit.market_index)))
         }
+        const orders = await retryOnRevoked(opts, params.address, token, (t) =>
+          fetchOrdersByClientOrderIndex(
+            client,
+            t,
+            account.index,
+            clientOrderIndex
+          )
+        )
+        // `accountOrders` reaches active and inactive rows alike, so a reused
+        // client order index can match more than one row. Prefer the live one.
+        const matches = orders
+          .filter((o) => String(o.client_order_index) === clientOrderIndex)
+          .map(detail)
+        const hit =
+          matches.find((o) => isActiveOrderStatus(o.status)) ?? matches[0]
+        if (hit === undefined) {
+          throw notFound()
+        }
+        return hit
+      }
+
+      const byOrderIndex = (o: LtOrder): boolean =>
+        String(o.order_index) === params.id
+
+      const active = await retryOnRevoked(opts, params.address, token, (t) =>
+        fetchActiveOrders(
+          client,
+          t,
+          account.index,
+          LIGHTER_ALL_MARKETS_WILDCARD
+        )
+      )
+      const activeHit = active.orders.find(byOrderIndex)
+      if (activeHit !== undefined) {
+        return detail(activeHit)
       }
 
       const inactive = await retryOnRevoked(opts, params.address, token, (t) =>
@@ -1117,15 +1212,11 @@ export const createLighterProvider = (
           limit: INACTIVE_ORDERS_LOOKUP_LIMIT,
         })
       )
-      const hit = inactive.orders.find(predicate as (o: unknown) => boolean)
-      if (hit !== undefined) {
-        return mapOrderDetail(hit, registry.require(String(hit.market_index)))
+      const inactiveHit = wireList(inactive.orders).find(byOrderIndex)
+      if (inactiveHit === undefined) {
+        throw notFound()
       }
-
-      throw new PerpsError(
-        PerpsErrorCode.OrderNotFound,
-        `Lighter order ${params.id} not found for ${params.address}`
-      )
+      return detail(inactiveHit)
     },
 
     async getFills(
@@ -1170,7 +1261,7 @@ export const createLighterProvider = (
       // drops only its own row instead of rejecting the whole page. The
       // registry warns once per unresolved id. A delisted market still
       // resolves, so its rows stay.
-      const items = response.trades.flatMap((t): Fill[] => {
+      const items = wireList(response.trades).flatMap((t): Fill[] => {
         const market = registry.get(String(t.market_id))
         if (market === undefined) {
           return []
@@ -1297,7 +1388,7 @@ export const createLighterProvider = (
           }
           const price = toBigOrNull(l.trade.price)
           const size = toBigOrNull(l.trade.size)
-          const marginMode = l.info.positions.find(
+          const marginMode = wireList(l.info.positions).find(
             (p) => p.market_id === l.market_id
           )?.margin_mode
           // Lighter reports the margin mode as an integer, so the venue

package/src/constants.ts

@@ -204,13 +204,26 @@ export const LIGHTER_BASE_FEE_TIER: FeeTier = { maker: '0', taker: '0' }
 
 /**
  * Wildcard `market_id` accepted by Lighter's per-market account endpoints to
- * indicate "every market". Used on `accountInactiveOrders`, `positionFunding`,
- * `liquidations`.
+ * indicate "every market". Used on `accountActiveOrders`,
+ * `accountInactiveOrders` and `liquidations`. It is also the venue's own
+ * documented default for `accountActiveOrders.market_id`.
  *
  * @internal
  */
 export const LIGHTER_ALL_MARKETS_WILDCARD = 255
 
+/**
+ * Prefix that marks a `getOrder` id as a Lighter `client_order_index` rather
+ * than an `order_index`. Compose the id as
+ * `` `${LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX}${clientOrderIndex}` `` from the
+ * `clientOrderIndex` a signed placement step returns. Both references are
+ * decimal integers, so without the prefix `getOrder` could resolve one as the
+ * other and return an unrelated order.
+ *
+ * @public
+ */
+export const LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX = 'client_order_index:'
+
 /**
  * Lighter caps `limit` at 100 on positionFunding/liquidations endpoints.
  *

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   DEFAULT_LIGHTER_EXPLORER_TX_BASE_URL,
   DEFAULT_LIGHTER_REST_URL,
   DEFAULT_LIGHTER_WS_URL,
+  LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX,
   LIGHTER_COLLATERAL_ASSETS,
   LIGHTER_MAINNET_DEPLOYMENT,
   LIGHTER_MAINNET_SIGNER_CHAIN_ID,

package/src/signers/LighterReadOnlyTokenManager.ts

@@ -218,9 +218,12 @@ const isLighterReadOnlyToken = (
   >
   // Accept a record that carries no `tokenId`: rejecting one would discard a
   // usable token and force an unnecessary replacement.
+  // A token carrying a line break cannot go in the `Authorization` header, so
+  // reject the record and let the manager create a replacement.
   return (
     typeof token === 'string' &&
     token.length > 0 &&
+    !/[\r\n]/.test(token) &&
     typeof expiry === 'number' &&
     Number.isFinite(expiry) &&
     (scope === 'single' || scope === 'all') &&

package/src/signers/signActions.ts

@@ -230,13 +230,30 @@ async function signStandardWasmAction(
     apiKeyIndex: apiKey.apiKeyIndex,
     accountIndex: apiKey.accountIndex,
   })
+  const clientOrderIndex = clientOrderIndexOf(step.wasmSignParams)
   return {
     action: step.action,
     wasmSignParams: step.wasmSignParams,
     signedTx,
+    ...(clientOrderIndex === undefined ? {} : { clientOrderIndex }),
   }
 }
 
+/**
+ * Project the signed order's `client_order_index` so the caller can resolve it
+ * through `getOrder` before the venue assigns an `order_index`. Only the
+ * order-placing actions carry one, and the value is read back off the params
+ * that were signed rather than generated a second time.
+ */
+function clientOrderIndexOf(
+  wasmSignParams: Record<string, unknown>
+): string | undefined {
+  const value = wasmSignParams.client_order_index
+  return typeof value === 'number' && Number.isInteger(value)
+    ? String(value)
+    : undefined
+}
+
 /**
  * REGISTER_API_KEY flow:
  *   1. Look up the user's Lighter accountIndex (Lighter REST).
@@ -484,11 +501,11 @@ async function executeTokenAuthMutation(
     }
   }
 
-  const { path, params } = buildTokenAuthMutationRequest(step, authToken)
+  const { path, params } = buildTokenAuthMutationRequest(step)
   const { status, data } = await deps.apiClient.postForm<{
     code?: number
     message?: string
-  }>(path, params)
+  }>(path, authToken, params)
 
   const code = data?.code
   const referralAlreadyApplied =
@@ -533,14 +550,14 @@ async function readAppliedReferralCode(
 }
 
 /**
- * Map a token-authenticated mutation step to its Lighter endpoint and
- * form body, mirroring the backend's request contract. The auth token is the
- * `auth` field; the remaining fields come from `wasmSignParams`.
+ * Map a token-authenticated mutation step to its Lighter endpoint and form
+ * body. The fields come from `wasmSignParams`; the auth token travels in the
+ * `Authorization` header, not the body.
  */
-function buildTokenAuthMutationRequest(
-  step: WasmBlobActionStep,
-  authToken: string
-): { path: string; params: ApiParams } {
+function buildTokenAuthMutationRequest(step: WasmBlobActionStep): {
+  path: string
+  params: ApiParams
+} {
   const kind = step.wasmSignParams.kind
   if (kind === 'changeAccountTier') {
     const { account_index, new_tier } = step.wasmSignParams as {
@@ -555,7 +572,7 @@ function buildTokenAuthMutationRequest(
     }
     return {
       path: '/api/v1/changeAccountTier',
-      params: { auth: authToken, account_index, new_tier },
+      params: { account_index, new_tier },
     }
   }
   if (kind === 'referralUse') {
@@ -572,7 +589,7 @@ function buildTokenAuthMutationRequest(
     }
     return {
       path: '/api/v1/referral/use',
-      params: { auth: authToken, l1_address, referral_code, x },
+      params: { l1_address, referral_code, x },
     }
   }
   throw new PerpsError(

package/src/types/account.ts

@@ -1,5 +1,6 @@
 // Account / balance shapes returned by Lighter's `/api/v1/account` and
 // `/api/v1/accountLimits` endpoints.
+// Lighter serializes an empty list as JSON `null`, so list members are nullable.
 
 /**
  * Per-market position row returned by Lighter's account endpoints.
@@ -35,6 +36,8 @@ export type LtAccountPosition = {
   margin_mode: number
   allocated_margin: string
   total_discount: string
+  /** Lighter bit flags recording which margin settings the account set itself. */
+  margin_set_flag?: number
 }
 
 /**
@@ -126,8 +129,8 @@ export interface LtDetailedAccount {
   account_index: number
   name: string
   description: string
-  positions: LtDetailedAccountPosition[]
-  assets: LtAccountAsset[]
+  positions: LtDetailedAccountPosition[] | null
+  assets: LtAccountAsset[] | null
   total_asset_value: string
   cross_asset_value: string
   /** Initial margin locked by cross positions; isolated positions carry
@@ -136,6 +139,17 @@ export interface LtDetailedAccount {
   approved_integrators?: LtApprovedIntegrator[]
 }
 
+/**
+ * A detailed account whose wire lists `fetchDetailedAccount` has normalized to
+ * real arrays. Every SDK read of an account works on this shape.
+ *
+ * @public
+ */
+export type LtAccount = LtDetailedAccount & {
+  positions: LtDetailedAccountPosition[]
+  assets: LtAccountAsset[]
+}
+
 /**
  * Response envelope for a detailed-account lookup. `code` is Lighter's
  * endpoint result code and `total` is the number of account rows returned.
@@ -145,7 +159,7 @@ export interface LtDetailedAccount {
 export interface LtDetailedAccountsResponse {
   code: number
   total: number
-  accounts: LtDetailedAccount[]
+  accounts: LtDetailedAccount[] | null
 }
 
 /**