src/markets/types.ts

/** Thrown when an `orderBooks` / `orderBookDetails` payload cannot be trusted as a whole. */
export class LighterMetaError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'LighterMetaError';
  }
}

/**
 * One market from `GET /api/v1/orderBookDetails`, decoded. Numbers on the wire are strings; the raw
 * string of every price/size field is kept next to the parsed number where the grid matters.
 */
export interface LighterMarket {
  /** `symbol` as the exchange knows it: `ETH`, `SNDK`, `ETH/USDG`. */
  symbol: string;
  /** `market_id` here, `market_index` in orders and positions - the same number. Never hard-code it: RH and mainnet differ. */
  marketId: number;
  /** `market_type`; only `'perp'` markets are decoded by default. */
  marketType: string;
  /**
   * `status`; trade only `'active'`. Other values were not observed live (knowledge base:
   * instances-and-api.md §2.2).
   */
  status: string;
  /** `supported_size_decimals`: lot = 10^-n. */
  sizeDecimals: number;
  /** `supported_price_decimals`: tick = 10^-m. */
  priceDecimals: number;
  /** `min_base_amount` in base units (lot minimum, code 21706). 0 = none reported. */
  minBaseAmount: number;
  /** Raw `min_base_amount` string (`"0.0100"`) for exact checks. */
  minBaseAmountRaw: string;
  /** `min_quote_amount` in USD ($10 on RH). 0 = none reported. */
  minQuoteUsd: number;
  /** Raw `min_quote_amount` string (`"10.000000"`). */
  minQuoteUsdRaw: string;
  /** `mark_price`: the mid for planning; margin, liquidation and code 21734 are computed from it. */
  markPrice: number;
  /** Raw `mark_price` string. */
  markPriceRaw: string;
  /** `last_trade_price`; jumps on thin markets, do not use as a mid. */
  lastTradePrice: number;
  /** `min_initial_margin_fraction` raw (hundredths of a percent, `1000` = 10%). */
  minInitialMarginFraction: number;
  /** `default_initial_margin_fraction` raw (hundredths of a percent, `5000` = 50% = 2x). */
  defaultInitialMarginFraction: number;
  /** `floor(10000 / min_initial_margin_fraction)`, at least 1. */
  maxLeverage: number;
  /** True for USDG-quoted duplicates of a base market (`ETH/USDG`). */
  isUsdgDuplicate: boolean;
}

/** One row of `GET /api/v1/orderBooks` (flat market list). Only `symbol` and `market_id` are required. */
export interface LighterOrderBookRow {
  symbol: string;
  marketId: number;
  status: string;
  marketType: string;
  isUsdgDuplicate: boolean;
  /** Everything else the row carried, untouched (fees, decimals, minimums when present). */
  raw: Record<string, unknown>;
}