src/history/types.ts

// Shapes of Hyperliquid history responses used by this module. They mirror
// the raw POST /info JSON (and @nktkas/hyperliquid types): numbers such as
// px, sz, closedPnl and fee arrive as decimal STRINGS.

/** `'B'` = buy / bid, `'A'` = sell / ask. */
export type FillSide = 'B' | 'A';

/** Position direction of a round trip or a closed position. */
export type PositionSide = 'LONG' | 'SHORT';

/**
 * Minimal fill shape accepted by the pure helpers, so fills from other sources
 * (a WebSocket feed, a local journal) can be analysed too.
 */
export interface FillLike {
  /** Perp: `BTC`. HIP-3: `xyz:TSLA`. Spot: `@107` or `PURR/USDC`. */
  coin: string;
  px: string;
  /** Unsigned size. */
  sz: string;
  side: FillSide;
  /** Unix ms. */
  time: number;
  /** `Open Long`, `Close Short`, liquidation dirs (contain `Liquidat`), `Settlement`, spot `Buy`/`Sell`... */
  dir: string;
  closedPnl: string;
  /** Signed position of this coin BEFORE the fill; the source of truth for position trajectory. */
  startPosition?: string;
  fee?: string;
  feeToken?: string;
  /** All partial fills of one order share the oid. */
  oid?: number | null;
  /** Unique trade id; the dedup key. */
  tid?: number | null;
  hash?: string;
  /** true = taker (crossed the spread), false = maker. */
  crossed?: boolean;
  /** Fee paid to ANY builder, not necessarily yours. */
  builderFee?: string;
  twapId?: number | null;
}

/** A fill as returned by `userFills` / `userFillsByTime` / `userTwapSliceFills`. */
export interface HlFill extends FillLike {
  startPosition: string;
  hash: string;
  oid: number;
  crossed: boolean;
  fee: string;
  feeToken: string;
  tid: number;
}

/** A candle as returned by `candleSnapshot`. Prices and volume are strings. */
export interface HlCandle {
  /** Bar OPEN time, ms. The close `c` belongs to `t + interval`, not to `t`. */
  t: number;
  /** Bar close time, ms. */
  T: number;
  /** Coin. */
  s: string;
  /** Interval. */
  i: string;
  o: string;
  h: string;
  l: string;
  c: string;
  v: string;
  /** Number of trades. */
  n: number;
}

/** Inclusive time window in unix ms. */
export interface TimeWindow {
  startTime: number;
  endTime: number;
}