@lifi/perps-sdk-provider-lighter 17.0.1 → 17.2.0

package/src/constants.ts

@@ -183,6 +183,16 @@ export const DEFAULT_TRADES_LIMIT = 50
  */
 export const LIGHTER_FEE_TICK_SCALE = 1_000_000
 
+/**
+ * Scale of the integer `initial_margin_fraction` values Lighter publishes on
+ * trade rows and order-book details: the integer is a percent times 100, so
+ * `500` is 5.00% and `200` is 2.00%. Account positions publish the same
+ * fraction as a plain percent string ("5.00") instead.
+ *
+ * @internal
+ */
+export const LIGHTER_IMF_PERCENT_SCALE = 100
+
 /**
  * Lighter's public base fee tier (Standard Account): 0% maker / 0% taker on all
  * perps markets. Per-account Premium tiers exist but require auth to resolve;

package/src/signers/LighterKeyStore.ts

@@ -4,10 +4,7 @@ import type { Address } from 'viem'
 import { LIGHTER_PROVIDER_KEY } from '../constants.js'
 
 // The private key here is a Lighter custom keypair — generated via WASM
-// GenerateAPIKey — not an Ethereum private key. The storage key is namespaced
-// by the resolved provider instance key so two Lighter instances sharing a
-// storage adapter (e.g. `lighter` and `lighter-rh`) never clobber each other's
-// API key.
+// GenerateAPIKey — not an Ethereum private key.
 
 const STORAGE_PREFIX = 'lifi-perps-lighter-key'
 
@@ -19,6 +16,12 @@ const STORAGE_PREFIX = 'lifi-perps-lighter-key'
  * @public
  */
 export interface LighterApiKey {
+  /**
+   * Lighter instance the record belongs to. A record read by any other
+   * instance is discarded, so its key material never signs on a chain that
+   * does not hold it.
+   */
+  providerKey: LighterProviderKey
   /** Lighter account index, looked up once via accountsByL1Address. */
   accountIndex: number
   /** API key slot (0-255), as named by the backend registration payload. */
@@ -29,28 +32,37 @@ export interface LighterApiKey {
   apiKeyPublicKey: string
 }
 
-const isLighterApiKey = (value: unknown): value is LighterApiKey => {
-  if (typeof value !== 'object' || value === null) {
-    return false
+const isLighterApiKeyOf =
+  (owner: LighterProviderKey) =>
+  (value: unknown): value is LighterApiKey => {
+    if (typeof value !== 'object' || value === null) {
+      return false
+    }
+    const {
+      providerKey,
+      accountIndex,
+      apiKeyIndex,
+      apiKeyPrivateKey,
+      apiKeyPublicKey,
+    } = value as Record<string, unknown>
+    return (
+      providerKey === owner &&
+      typeof accountIndex === 'number' &&
+      Number.isFinite(accountIndex) &&
+      typeof apiKeyIndex === 'number' &&
+      Number.isFinite(apiKeyIndex) &&
+      typeof apiKeyPrivateKey === 'string' &&
+      apiKeyPrivateKey.length > 0 &&
+      typeof apiKeyPublicKey === 'string' &&
+      apiKeyPublicKey.length > 0
+    )
   }
-  const { accountIndex, apiKeyIndex, apiKeyPrivateKey, apiKeyPublicKey } =
-    value as Record<string, unknown>
-  return (
-    typeof accountIndex === 'number' &&
-    Number.isFinite(accountIndex) &&
-    typeof apiKeyIndex === 'number' &&
-    Number.isFinite(apiKeyIndex) &&
-    typeof apiKeyPrivateKey === 'string' &&
-    apiKeyPrivateKey.length > 0 &&
-    typeof apiKeyPublicKey === 'string' &&
-    apiKeyPublicKey.length > 0
-  )
-}
 
 /**
  * Storage-backed cache for Lighter API keys. Records are namespaced by L1
- * address and provider instance so multiple Lighter deployments can share one
- * {@link StorageAdapter} without collisions.
+ * address and provider instance, and each record names its own instance, so
+ * multiple Lighter deployments can share one {@link StorageAdapter} and no
+ * instance ever reads another instance's key material.
  *
  * @public
  */
@@ -82,8 +94,8 @@ export class LighterKeyStore {
     this.providerKey = providerKey
   }
 
-  // The default instance keeps the legacy, un-namespaced key so existing
-  // `lighter` users are not orphaned; only additional instances get a segment.
+  // The default instance keeps the legacy, un-namespaced slot name; only
+  // additional instances get a segment.
   private storageKey(address: Address): string {
     const lower = address.toLowerCase()
     return this.providerKey === LIGHTER_PROVIDER_KEY
@@ -101,7 +113,11 @@ export class LighterKeyStore {
     if (cached) {
       return cached
     }
-    const parsed = await readValidatedRecord(this.storage, key, isLighterApiKey)
+    const parsed = await readValidatedRecord(
+      this.storage,
+      key,
+      isLighterApiKeyOf(this.providerKey)
+    )
     if (!parsed) {
       return null
     }
@@ -111,12 +127,17 @@ export class LighterKeyStore {
 
   /**
    * Persist an API key for an L1 address, replacing any existing record under
-   * that provider namespace.
+   * that provider namespace. The store stamps the record with its own instance
+   * key, so callers never name the instance themselves.
    */
-  async set(address: Address, value: LighterApiKey): Promise<void> {
+  async set(
+    address: Address,
+    value: Omit<LighterApiKey, 'providerKey'>
+  ): Promise<void> {
     const key = this.storageKey(address)
-    this.cache.set(key, value)
-    await this.storage.set(key, JSON.stringify(value))
+    const record: LighterApiKey = { ...value, providerKey: this.providerKey }
+    this.cache.set(key, record)
+    await this.storage.set(key, JSON.stringify(record))
   }
 
   /**

package/src/signers/LighterReadOnlyTokenManager.ts

@@ -17,7 +17,7 @@ import { DEFAULT_LIGHTER_REST_URL, LIGHTER_PROVIDER_KEY } from '../constants.js'
  * Default token name persisted alongside Lighter's `tokens/create` row.
  * Lighter requires a non-empty `name` form field; the literal here is what
  * surfaces in Lighter's UI listing under `app.lighter.xyz/read-only-tokens`.
- * @public
+ * @internal
  */
 export const DEFAULT_READ_ONLY_TOKEN_NAME = 'LI.FI Perps'
 
@@ -26,7 +26,7 @@ export const DEFAULT_READ_ONLY_TOKEN_NAME = 'LI.FI Perps'
  * Lighter's opaque `ro:{accountIndex}:{scope}:{expiry}:{rand}` bearer; the
  * SDK never parses it — `expiry`/`scope`/`accountIndex` are create-time inputs
  * we keep alongside so consumers can render expiry UX without re-fetching.
- * @public
+ * @internal
  */
 export interface LighterReadOnlyToken {
   /** Opaque bearer string — never parse client-side. */
@@ -37,19 +37,27 @@ export interface LighterReadOnlyToken {
   scope: 'single' | 'all'
   /** Lighter L2 account index the token authorises. */
   accountIndex: number
+  /**
+   * Lighter's monotonic registry row id. Optional: a record persisted without
+   * it stays valid, and the cleanup pass then identifies its row by the
+   * bearer string instead.
+   */
+  tokenId?: number
 }
 
 /**
- * Lighter `POST /api/v1/tokens/create` response shape (subset). Lighter's
- * OpenAPI documents additional fields (`token_id`, `name`, `revoked`, etc.)
- * we don't need client-side.
- * @public
+ * Lighter `POST /api/v1/tokens/create` response shape — the subset of
+ * Lighter's `RespPostApiToken` the SDK consumes. Lighter documents further
+ * fields (`name`, `revoked`, `sub_account_access`) the SDK does not need.
+ * @internal
  */
 export interface LighterCreateTokenResponse {
   api_token: string
   account_index: number
   expiry: number
   scopes: string
+  /** Monotonic registry row id Lighter assigns to the new row. */
+  token_id: number
 }
 
 /**
@@ -57,7 +65,7 @@ export interface LighterCreateTokenResponse {
  * endpoint. Returning a parsed {@link LighterCreateTokenResponse} keeps the
  * create code free of fetch/multipart plumbing and lets tests drop a fixture
  * in without spinning a mock server.
- * @public
+ * @internal
  */
 export type LighterTokenFetcher = (params: {
   url: string
@@ -69,12 +77,76 @@ export type LighterTokenFetcher = (params: {
   scopes: string
 }) => Promise<LighterCreateTokenResponse>
 
+/**
+ * One row of Lighter's read-only token registry, matching Lighter's
+ * `ApiToken`. `name` carries the label supplied at create time, which is how
+ * the SDK recognises a row it owns.
+ * @internal
+ */
+export interface LighterApiToken {
+  token_id: number
+  api_token: string
+  name: string
+  account_index: number
+  expiry: number
+  sub_account_access: boolean
+  revoked: boolean
+  scopes: string
+}
+
+/**
+ * Lighter `GET /api/v1/tokens` response shape, matching `RespGetApiTokens`.
+ * @internal
+ */
+export interface LighterListTokensResponse {
+  code: number
+  message?: string
+  api_tokens: LighterApiToken[]
+}
+
+/**
+ * Lighter `POST /api/v1/tokens/revoke` response shape, matching Lighter's
+ * `RespRevokeApiToken`.
+ * @internal
+ */
+export interface LighterRevokeTokenResponse {
+  code: number
+  message?: string
+  token_id: number
+  revoked: boolean
+}
+
+/**
+ * Function injected for the HTTP boundary against Lighter's
+ * `GET /api/v1/tokens` endpoint. Injected for the same reason as
+ * {@link LighterTokenFetcher}: a unit spec supplies a registry fixture
+ * without a mock server.
+ * @internal
+ */
+export type LighterTokenListFetcher = (params: {
+  url: string
+  authorization: string
+  accountIndex: number
+}) => Promise<LighterListTokensResponse>
+
+/**
+ * Function injected for the HTTP boundary against Lighter's
+ * `POST /api/v1/tokens/revoke` endpoint.
+ * @internal
+ */
+export type LighterTokenRevokeFetcher = (params: {
+  url: string
+  authorization: string
+  tokenId: number
+  accountIndex: number
+}) => Promise<LighterRevokeTokenResponse>
+
 /**
  * Dependencies and overrides for {@link LighterReadOnlyTokenManager}.
  * Storage and token-fetching defaults target the browser's local storage and
  * Lighter's mainnet REST API.
  *
- * @public
+ * @internal
  */
 export interface LighterReadOnlyTokenManagerOptions {
   storage?: StorageAdapter
@@ -89,6 +161,10 @@ export interface LighterReadOnlyTokenManagerOptions {
   lighterApiUrl?: string
   /** Override the multipart POST. Defaults to a `fetch`-based implementation. */
   fetcher?: LighterTokenFetcher
+  /** Override the registry list GET. Defaults to a `fetch`-based implementation. */
+  listFetcher?: LighterTokenListFetcher
+  /** Override the revoke POST. Defaults to a `fetch`-based implementation. */
+  revokeFetcher?: LighterTokenRevokeFetcher
   /** Clock injection for testing expiry logic. Defaults to `Date.now`. */
   now?: () => number
 }
@@ -97,7 +173,7 @@ export interface LighterReadOnlyTokenManagerOptions {
  * Input to the read-only-token approval flow. Extends the shared approval
  * parameters with the L1 address whose wallet authorizes token creation.
  *
- * @public
+ * @internal
  */
 export interface ApproveReadOnlyTokenInputs extends ApproveReadOnlyTokenParams {
   /** L1 wallet address that signs the create message. */
@@ -108,7 +184,7 @@ export interface ApproveReadOnlyTokenInputs extends ApproveReadOnlyTokenParams {
  * Result of approving or creating a Lighter read-only token. `config` is the
  * account-state projection callers can persist alongside the token.
  *
- * @public
+ * @internal
  */
 export interface ApproveReadOnlyTokenResult {
   token: LighterReadOnlyToken
@@ -131,10 +207,12 @@ const isLighterReadOnlyToken = (
   if (typeof value !== 'object' || value === null) {
     return false
   }
-  const { token, expiry, scope, accountIndex } = value as Record<
+  const { token, expiry, scope, accountIndex, tokenId } = value as Record<
     string,
     unknown
   >
+  // Accept a record that carries no `tokenId`: rejecting one would discard a
+  // usable token and force an unnecessary replacement.
   return (
     typeof token === 'string' &&
     token.length > 0 &&
@@ -142,10 +220,19 @@ const isLighterReadOnlyToken = (
     Number.isFinite(expiry) &&
     (scope === 'single' || scope === 'all') &&
     typeof accountIndex === 'number' &&
-    Number.isFinite(accountIndex)
+    Number.isFinite(accountIndex) &&
+    (tokenId === undefined ||
+      (typeof tokenId === 'number' && Number.isFinite(tokenId)))
   )
 }
 
+const isLiveRow = (
+  row: LighterApiToken,
+  live: LighterReadOnlyToken | undefined
+): boolean =>
+  live !== undefined &&
+  (row.token_id === live.tokenId || row.api_token === live.token)
+
 /**
  * Manage the per-account Lighter read-only token alongside the existing
  * `(L1 address, account index)`-scoped storage adapter pattern. Takes an
@@ -163,13 +250,15 @@ const isLighterReadOnlyToken = (
  * a fully compromised page — a same-origin script can still drive this manager
  * to decrypt. Blast radius is limited to reads: the token cannot sign orders
  * or move funds.
- * @public
+ * @internal
  */
 export class LighterReadOnlyTokenManager {
   private readonly storage: StorageAdapter
   private readonly providerKey: LighterProviderKey
   private readonly lighterApiUrl: string
   private readonly fetcher: LighterTokenFetcher
+  private readonly listFetcher: LighterTokenListFetcher
+  private readonly revokeFetcher: LighterTokenRevokeFetcher
   private readonly now: () => number
   private readonly cache = new Map<string, LighterReadOnlyToken>()
 
@@ -178,6 +267,9 @@ export class LighterReadOnlyTokenManager {
     this.providerKey = options.providerKey ?? LIGHTER_PROVIDER_KEY
     this.lighterApiUrl = options.lighterApiUrl ?? DEFAULT_LIGHTER_REST_URL
     this.fetcher = options.fetcher ?? defaultLighterTokenFetcher
+    this.listFetcher = options.listFetcher ?? defaultLighterTokenListFetcher
+    this.revokeFetcher =
+      options.revokeFetcher ?? defaultLighterTokenRevokeFetcher
     this.now = options.now ?? (() => Date.now())
   }
 
@@ -189,6 +281,19 @@ export class LighterReadOnlyTokenManager {
     return token.expiry * 1000 <= this.now()
   }
 
+  /** Stored record for the pair, whether or not it is past its `expiry`. */
+  private async readStoredToken(
+    address: Address,
+    accountIndex: number
+  ): Promise<LighterReadOnlyToken | undefined> {
+    const key = this.storageKey(address, accountIndex)
+    return (
+      this.cache.get(key) ??
+      (await readValidatedRecord(this.storage, key, isLighterReadOnlyToken)) ??
+      undefined
+    )
+  }
+
   /**
    * Return the stored token for the `(address, accountIndex)` pair, or
    * `undefined` if absent or past its `expiry`. Never surfaces an expired
@@ -226,10 +331,7 @@ export class LighterReadOnlyTokenManager {
     accountIndex: number,
     thresholdDays = 30
   ): Promise<boolean> {
-    const key = this.storageKey(address, accountIndex)
-    const token =
-      this.cache.get(key) ??
-      (await readValidatedRecord(this.storage, key, isLighterReadOnlyToken))
+    const token = await this.readStoredToken(address, accountIndex)
     if (!token) {
       return false
     }
@@ -272,6 +374,9 @@ export class LighterReadOnlyTokenManager {
    * and persists the returned `ro:` bearer alongside its
    * `expiry`/`scope`/`accountIndex`.
    *
+   * Before the create call, the flow revokes this SDK's own stale registry
+   * rows. That pass is best-effort: a failure is logged and the create runs.
+   *
    * `authorization` MUST be a **standard** Lighter auth token — one created by
    * the account's API key (`createAuthToken` / the WASM signer), NOT an L1
    * wallet signature. Lighter authenticates the create request with that token
@@ -295,6 +400,8 @@ export class LighterReadOnlyTokenManager {
   ): Promise<ApproveReadOnlyTokenResult> {
     const { address, accountIndex, expirySeconds, scope } = inputs
 
+    await this.revokeStaleOwnTokens(authorization, address, accountIndex)
+
     const response = await this.fetcher({
       url: `${this.lighterApiUrl}/api/v1/tokens/create`,
       authorization,
@@ -313,6 +420,12 @@ export class LighterReadOnlyTokenManager {
       // `get()` looks up by, else a divergent echo orphans the token and re-creates every read.
       scope,
       accountIndex,
+      // Lighter declares `token_id` required but the response is unvalidated.
+      // A non-numeric id must degrade to the bearer-string match: persisting it
+      // would fail record validation and re-create the token on every read.
+      tokenId: Number.isFinite(response.token_id)
+        ? response.token_id
+        : undefined,
     }
     await this.set(address, token.accountIndex, token)
 
@@ -327,6 +440,57 @@ export class LighterReadOnlyTokenManager {
       },
     }
   }
+
+  /**
+   * Revoke the registry rows this SDK owns and no longer needs. Lighter's
+   * `tokens/create` appends a row on every call, so without this pass the
+   * user's registry grows on every rotation.
+   */
+  private async revokeStaleOwnTokens(
+    authorization: string,
+    address: Address,
+    accountIndex: number
+  ): Promise<void> {
+    try {
+      const live = await this.readStoredToken(address, accountIndex)
+      const { api_tokens: rows } = await this.listFetcher({
+        url: `${this.lighterApiUrl}/api/v1/tokens`,
+        authorization,
+        accountIndex,
+      })
+      const nowSeconds = Math.floor(this.now() / 1000)
+      const stale = rows
+        // A row is ours only when its name matches the name we create rows
+        // under. Any other name belongs to the user and must survive.
+        .filter((row) => row.name === DEFAULT_READ_ONLY_TOKEN_NAME)
+        .filter((row) => !row.revoked)
+        // Keep the row the local store holds; with no stored record every owned
+        // row is stale, and a peer client's row self-heals via `retryOnRevoked`.
+        .filter((row) => row.expiry <= nowSeconds || !isLiveRow(row, live))
+        .sort((a, b) => a.token_id - b.token_id)
+
+      for (const row of stale) {
+        try {
+          await this.revokeFetcher({
+            url: `${this.lighterApiUrl}/api/v1/tokens/revoke`,
+            authorization,
+            tokenId: row.token_id,
+            accountIndex,
+          })
+        } catch (err) {
+          console.warn(
+            `[lighter] could not revoke stale read-only token ${row.token_id}; continuing.`,
+            err
+          )
+        }
+      }
+    } catch (err) {
+      console.warn(
+        '[lighter] could not clean up stale read-only tokens; creating the new one anyway.',
+        err
+      )
+    }
+  }
 }
 
 /**
@@ -334,7 +498,7 @@ export class LighterReadOnlyTokenManager {
  * `tokens/create` endpoint and returns the parsed response. Throws a
  * {@link PerpsError} with the Lighter-side body when the response is
  * non-2xx.
- * @public
+ * @internal
  */
 export const defaultLighterTokenFetcher: LighterTokenFetcher = async ({
   url,
@@ -368,3 +532,66 @@ export const defaultLighterTokenFetcher: LighterTokenFetcher = async ({
 
   return (await response.json()) as LighterCreateTokenResponse
 }
+
+/**
+ * Default list fetcher: `GET /api/v1/tokens` with `account_index` as a query
+ * parameter. Lighter's OpenAPI defines no request body for this route. Throws
+ * a {@link PerpsError} with the Lighter-side body when the response is
+ * non-2xx.
+ * @internal
+ */
+export const defaultLighterTokenListFetcher: LighterTokenListFetcher = async ({
+  url,
+  authorization,
+  accountIndex,
+}) => {
+  const query = new URLSearchParams({ account_index: String(accountIndex) })
+
+  const response = await fetch(`${url}?${query.toString()}`, {
+    headers: { authorization },
+  })
+
+  if (!response.ok) {
+    const body = await response.text()
+    throw new PerpsError(
+      PerpsErrorCode.ServerError,
+      `Lighter tokens returned ${response.status}: ${body || '<empty>'}`
+    )
+  }
+
+  return (await response.json()) as LighterListTokensResponse
+}
+
+/**
+ * Default revoke fetcher: posts `application/x-www-form-urlencoded` to
+ * Lighter's `tokens/revoke` endpoint, which is the content type Lighter's
+ * OpenAPI declares for that route. Throws a {@link PerpsError} with the
+ * Lighter-side body when the response is non-2xx.
+ * @internal
+ */
+export const defaultLighterTokenRevokeFetcher: LighterTokenRevokeFetcher =
+  async ({ url, authorization, tokenId, accountIndex }) => {
+    const form = new URLSearchParams({
+      token_id: String(tokenId),
+      account_index: String(accountIndex),
+    })
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        authorization,
+        'content-type': 'application/x-www-form-urlencoded',
+      },
+      body: form,
+    })
+
+    if (!response.ok) {
+      const body = await response.text()
+      throw new PerpsError(
+        PerpsErrorCode.ServerError,
+        `Lighter tokens/revoke returned ${response.status}: ${body || '<empty>'}`
+      )
+    }
+
+    return (await response.json()) as LighterRevokeTokenResponse
+  }

package/src/signers/signActions.ts

@@ -64,7 +64,7 @@ export interface LighterSignActionsDeps {
 const TOKEN_AUTH_MUTATION_KINDS = new Set(['changeAccountTier', 'referralUse'])
 
 /**
- * Lifetime of the per-call auth token minted for a token-authenticated venue
+ * Lifetime of the per-call auth token issued for a token-authenticated venue
  * mutation. Minutes, not the read endpoints' hours: it authenticates one POST
  * that completes immediately, so it never lingers usable.
  */
@@ -133,11 +133,19 @@ export const createLighterApiKeyFreshness = (): LighterApiKeyFreshness => {
         checkedAtMs.set(windowKey, Date.now())
         return
       }
-      // A slot carrying no entry leaves nothing to compare against.
-      if (
-        registered !== undefined &&
-        normalizeLighterPublicKey(registered.public_key) !== storedKey
-      ) {
+      // An answered read that names no entry is a verdict, not a gap: the slot
+      // holds no key the stored one can match, so a signature it produces
+      // cannot verify.
+      if (registered === undefined) {
+        throw new PerpsError(
+          PerpsErrorCode.SDKError,
+          `The Lighter API key stored for ${address} is not registered: ` +
+            `account ${apiKey.accountIndex} holds no key in API-key slot ` +
+            `${apiKey.apiKeyIndex}. Run prepareAccount / REGISTER_API_KEY to ` +
+            'register a fresh key.'
+        )
+      }
+      if (normalizeLighterPublicKey(registered.public_key) !== storedKey) {
         throw new PerpsError(
           PerpsErrorCode.SDKError,
           `The Lighter API key stored for ${address} is no longer registered: ` +
@@ -146,7 +154,7 @@ export const createLighterApiKeyFreshness = (): LighterApiKeyFreshness => {
         )
       }
       // Every read the venue answered counts against the window, so a burst
-      // costs one read whatever the verdict. A mismatch throws above, so it
+      // costs one read whatever the verdict. A rejection throws above, so it
       // never records and the next batch reads again.
       checkedAtMs.set(windowKey, Date.now())
     },
@@ -295,13 +303,12 @@ async function signRegisterApiKey(
     l1Signature
   )
 
-  const apiKey: LighterApiKey = {
+  await deps.keyStore.set(address, {
     accountIndex,
     apiKeyIndex,
     apiKeyPrivateKey: keypair.privateKey,
     apiKeyPublicKey: keypair.publicKey,
-  }
-  await deps.keyStore.set(address, apiKey)
+  })
 
   return {
     action: step.action,
@@ -431,7 +438,7 @@ async function signTransfer(
  *
  * Neither endpoint consumes a wasm-signed transaction — both authenticate with
  * a Lighter auth token and enforce their business rules (open positions,
- * pending orders, 24h tier cooldown) server-side. We mint a fresh short-lived
+ * pending orders, 24h tier cooldown) server-side. We create a fresh short-lived
  * token per call (never the stored read-only token, never persisted) and POST
  * the mirror of the backend's form body directly to Lighter, so no auth token
  * ever transits the LI.FI backend. A non-success verdict surfaces Lighter's

package/src/types/fill.ts

@@ -48,6 +48,12 @@ export type LtTrade = {
   // trade rows that predate the field.
   taker_entry_quote_before?: string
   maker_entry_quote_before?: string
+  // Per-counterparty initial-margin-fraction snapshot BEFORE the trade: the
+  // leverage that counterparty had set on the market, as an integer percent on
+  // `LIGHTER_IMF_PERCENT_SCALE` (`500` = 5.00% = 20x). Optional: absent on
+  // older trade rows that predate the field.
+  taker_initial_margin_fraction_before?: number
+  maker_initial_margin_fraction_before?: number
 }
 
 /**

package/src/utils/mapFill.ts

@@ -11,8 +11,12 @@ import {
   OrderType,
 } from '@lifi/perps-types'
 import Big from 'big.js'
-import { LIGHTER_FEE_TICK_SCALE } from '../constants.js'
+import {
+  LIGHTER_FEE_TICK_SCALE,
+  LIGHTER_IMF_PERCENT_SCALE,
+} from '../constants.js'
 import type { LtTrade } from '../types/index.js'
+import { leverageFromImf } from './mapPosition.js'
 
 /**
  * Fee charged on a fill, in the market's quote asset. Lighter publishes the
@@ -35,6 +39,18 @@ const tickToFeeAmount = (
     .div(LIGHTER_FEE_TICK_SCALE)
     .toFixed()
 
+/**
+ * Display leverage the viewer had set on the market when the trade executed.
+ * Lighter reports it as the pre-trade initial margin fraction, an integer
+ * percent on `LIGHTER_IMF_PERCENT_SCALE`: `500` is 5.00%, so 20x. Returns
+ * `undefined` when the row omits the fraction. Lighter declares the fraction a
+ * `StrictInt`, so the scale division is exact and `toFixed()` loses nothing.
+ */
+const leverageFromTradeImf = (imf: number | undefined): number | undefined =>
+  imf === undefined
+    ? undefined
+    : leverageFromImf(new Big(imf).div(LIGHTER_IMF_PERCENT_SCALE).toFixed())
+
 /**
  * Realized PnL on a position-reducing fill, derived from the pre-trade entry
  * basis. Returns `undefined` for opens/increases (nothing closes) or when the
@@ -101,6 +117,9 @@ export const mapFill = (
   const integratorFeeTick = isMaker
     ? trade.integrator_maker_fee
     : trade.integrator_taker_fee
+  const imfBefore = isMaker
+    ? trade.maker_initial_margin_fraction_before
+    : trade.taker_initial_margin_fraction_before
 
   return {
     id: trade.trade_id.toString(),
@@ -124,6 +143,7 @@ export const mapFill = (
             ),
             asset: market.quoteAsset.displaySymbol,
           },
+    leverage: leverageFromTradeImf(imfBefore),
     realizedPnl: deriveRealizedPnl(
       startPosition,
       entryQuoteBefore,