@lifi/perps-types 0.2.0-alpha.0 → 1.0.1

package/src/market.ts

@@ -0,0 +1,137 @@
+import type { Asset } from './asset.js'
+
+/** @public */
+export interface FundingInfo {
+  rate: string
+  nextFundingTime: number
+}
+
+/** @public */
+export interface BaseMarket {
+  providerId: string
+  /** Opaque provider market id; referenced elsewhere as `marketId`. */
+  id: string
+  /** References a {@link ProviderCategory} by id. */
+  categoryId: string
+  baseAsset: Asset
+  quoteAsset: Asset
+  szDecimals: number
+  /**
+   * Maximum decimal places the venue accepts for order prices on this market.
+   * Some venues impose further constraints on top of this budget (e.g. a
+   * significant-figure cap), so always format prices through the provider's
+   * `formatOrderPrice` rather than applying this field directly.
+   */
+  priceDecimals?: number
+}
+
+/** @public */
+export interface PerpsMarket extends BaseMarket {
+  maxLeverage: number
+  onlyIsolated: boolean
+  /**
+   * Venue maintenance margin rate for this market as a fraction (e.g. `0.012`
+   * = 1.2%). Feeds client-side liquidation-price estimates via the provider's
+   * `estimateLiquidationPrice`.
+   */
+  maintenanceMarginRate?: number
+}
+
+/** @public */
+export interface SpotMarket extends BaseMarket {}
+
+/** @public */
+export type Market = PerpsMarket | SpotMarket
+
+/** @public */
+export type MarketDisplay = Pick<
+  BaseMarket,
+  'providerId' | 'id' | 'categoryId' | 'baseAsset' | 'quoteAsset'
+>
+
+/**
+ * Minimal market reference for write-action params: identifies a market by
+ * its opaque `marketId` within a `categoryId`. Embeds no Assets — write
+ * params reference by id, not value.
+ * @public
+ */
+export interface MarketRef {
+  marketId: string
+  categoryId: string
+}
+
+/** @public */
+export interface MarketsResponse {
+  markets: Market[]
+}
+
+/**
+ * Live per-market data for the `/prices` endpoint. `price` is the mid;
+ * `markPrice`, `prevDayPrice` and `volume24h` apply to every market type,
+ * while `openInterest` and `funding` are perp-only and absent for spot.
+ * @public
+ */
+export interface MarketPrice {
+  marketId: string
+  price: string
+  markPrice: string
+  prevDayPrice?: string
+  volume24h?: string
+  openInterest?: string
+  funding?: FundingInfo
+}
+
+/** @public */
+export interface PricesResponse {
+  prices: MarketPrice[]
+}
+
+/** @public */
+export interface Candle {
+  t: number
+  o: string
+  h: string
+  l: string
+  c: string
+  v: string
+}
+
+/** @public */
+export interface OhlcvResponse {
+  provider: string
+  marketId: string
+  interval: string
+  candles: Candle[]
+}
+
+/** @public */
+export type OhlcvInterval =
+  | '1m'
+  | '3m'
+  | '5m'
+  | '15m'
+  | '30m'
+  | '1h'
+  | '2h'
+  | '4h'
+  | '8h'
+  | '12h'
+  | '1d'
+  | '3d'
+  | '1w'
+  | '1M'
+
+/** @public */
+export interface OrderbookLevel {
+  price: string
+  size: string
+}
+
+/** @public */
+export interface OrderbookResponse {
+  provider: string
+  marketId: string
+  bids: OrderbookLevel[]
+  asks: OrderbookLevel[]
+  timestamp: number
+}

package/src/meta.ts

@@ -0,0 +1,38 @@
+/**
+ * A single platform-level advisory shown to all users, independent of any
+ * provider or market.
+ * @public
+ */
+export interface Notice {
+  /** Unix epoch milliseconds. */
+  timestamp: number
+  title: string
+  message: string
+  /** Optional URL the notice links to; rendered as a hyperlink when present. */
+  link?: string
+}
+
+/**
+ * Read-only platform metadata served by `GET /v1/perps/meta`.
+ * @public
+ */
+export interface Meta {
+  version: string
+  notices: Notice[]
+}
+
+/**
+ * Current Terms-of-Service and this address's acceptance, served by
+ * `GET /v1/perps/meta/terms?address=`.
+ * @public
+ */
+export interface TermsAcceptanceStatus {
+  /** Backend-owned version identifier for the current terms. */
+  termsVersion: string
+  /** Full current terms-of-service text. */
+  content: string
+  /** Whether the queried address has accepted {@link TermsAcceptanceStatus.termsVersion}. */
+  accepted: boolean
+  /** Unix epoch milliseconds the address accepted; absent when not accepted. */
+  acceptedAt?: number
+}

package/src/primitives.ts

@@ -0,0 +1,5 @@
+/** @public */
+export type Address = `0x${string}`
+
+/** @public */
+export type Hex = `0x${string}`

package/src/providers.ts

@@ -1,122 +1,75 @@
+import type { Asset } from './asset.js'
 import type { ActionType, PerpsSigner, SigningMethod } from './enums.js'
+import type { OhlcvInterval } from './market.js'
 
-export interface ActionDescriptor {
-  type: ActionType
-  signers: PerpsSigner[]
-  /**
-   * How the SDK must sign this specific action. Most actions match the
-   * provider's dominant pattern (Hyperliquid: EIP712, Lighter: WASM_BLOB),
-   * but on-chain bridge actions like DEPOSIT are EVM_TX regardless of
-   * provider — the SDK dispatches by this field rather than by
-   * `Provider.signingMethod`.
-   */
-  signingMethod: SigningMethod
-}
-
-/**
- * One selectable value on a `Param` whose `values` are enumerated.
- *
- * `value` is the opaque per-provider identifier the SDK passes back to the
- * backend in the corresponding action params (e.g. the string assigned to
- * `mode` for `ACCOUNT_MODE`, or `tier` for `ACCOUNT_TYPE`).
- * `label` is the user-facing string the widget renders.
- */
+/** @public */
 export interface ParamOption {
   value: string
   label: string
 }
 
-/**
- * A single parameter the widget must collect from the user before
- * dispatching an action.
- *
- * `name` is the wire key the widget passes through to `execute()` — for the
- * existing `ACCOUNT_MODE` action that's `'mode'`, for `ACCOUNT_TYPE` it's
- * `'tier'`, etc. The widget builds the action's params object as
- * `{ [param.name]: <selected value> }` straight from the descriptor at
- * dispatch time; there is no per-ActionType translation layer.
- *
- * `type` describes the primitive shape of the value. Currently only
- * `'string'` is admitted — numeric / boolean primitives are deferred until
- * a real descriptor needs them.
- *
- * `values` is present iff the parameter has a fixed enumeration of
- * admissible values (e.g. Hyperliquid abstraction modes, Lighter account
- * tiers). When absent the widget renders a free-form input appropriate to
- * the primitive `type`.
- *
- * `default` flags the suggested choice when `values` is provided. Must be
- * one of the entries in `values` if specified; consumers should fall back
- * to "no selection" when absent and let the user pick.
- *
- * `readOnly: true` means the widget must render the control disabled —
- * typically used when the provider exposes the current value but does not
- * allow the user to change it from this surface (e.g. Lighter account
- * mode, which is set during onboarding and immutable thereafter).
- */
+/** @public */
 export interface Param {
+  /** Wire key for the action params object: `{ [param.name]: value }`. */
   name: string
   type: 'string'
+  /** Present iff the parameter has a fixed enumeration of admissible values. */
   values?: ParamOption[]
   default?: ParamOption
   readOnly?: boolean
 }
 
 /**
- * Self-documenting descriptor for an account-level action the user may
- * (setup) or must (options) interact with. Extends `ActionDescriptor`
- * because each descriptor resolves to exactly one action the SDK
- * dispatches when the user proceeds; the additional fields are the
- * presentation and parameter-collection metadata the widget needs to
- * render the action without hardcoded per-ActionType branches.
- *
- * `params` is the list of parameters the widget must collect from the
- * user (zero-or-more); each entry tells the widget the wire key, the
- * primitive type, optional enumeration of admissible values, and
- * optional default. See `Param` for the field-level semantics.
- *
- * Categorisation of a descriptor as "setup" vs "options" is carried by
- * which array on `Provider` it appears in (`Provider.setup` vs
- * `Provider.options`), NOT by a field on the descriptor — by design.
- * `ProviderSetup` and `ProviderOption` are type aliases for this same
- * shape with no additional fields.
+ * A single provider action. The same shape backs `Provider.setup`,
+ * `Provider.options`, and `Provider.actions` — categorisation lives in which
+ * array it sits in, not in the type. The core three fields are always present;
+ * the rest are presentation/ordering hints provided per-action in the
+ * provider's hardcoded metadata.
+ * @public
  */
-export interface ProviderActionDescriptor extends ActionDescriptor {
-  /** User-facing row title rendered in the setup / options modal. */
-  title: string
-  /** User-facing description rendered in the setup / options modal. */
-  description: string
-  /** Parameters the widget must collect before dispatching the action. */
-  params: Param[]
+export interface ProviderAction {
+  type: ActionType
+  signers: PerpsSigner[]
+  signingMethod: SigningMethod
+  /**
+   * Human label. Drives the card heading in the setup/options modals, and may
+   * also front an in-flight trading action ("{title} is working…").
+   */
+  title?: string
+  description?: string
+  /** UI form fields the widget renders to collect input for this action. */
+  params?: Param[]
+  /**
+   * Ascending order in which the user satisfies setup steps. Cloud-init
+   * convention: 10, 20, 30, … with 99 reserved for "always last"; the gaps
+   * leave room to insert steps later without renumbering. Lower runs first;
+   * a step may depend on every lower-sequenced step already being satisfied.
+   */
+  sequence?: number
 }
 
 /**
- * A descriptor that gates trading: the user MUST satisfy every entry on
- * `Provider.setup` before they can place orders with this provider. The
- * widget renders these in `<SetupModal />`, which auto-pops mid-session
- * whenever setup becomes unsatisfied (e.g. Hyperliquid agent expiry).
- *
- * Type alias for `ProviderActionDescriptor` — no additional fields. The
- * setup-vs-options distinction is the array, not a flag on the item.
- */
-export type ProviderSetup = ProviderActionDescriptor
-
-/**
- * A post-setup descriptor the user MAY interact with to tune provider
- * behaviour (e.g. switching Hyperliquid abstraction modes, switching
- * Lighter account tier). The widget renders these in `<OptionsModal />`
- * behind a cog icon; they never gate trading.
- *
- * Type alias for `ProviderActionDescriptor` — no additional fields. The
- * setup-vs-options distinction is the array, not a flag on the item.
+ * Provider-attached advisory shown against a market. Provider-agnostic: the
+ * producer decides when to emit one (e.g. an HL HIP-3 sub-dex risk warning).
+ * @public
  */
-export type ProviderOption = ProviderActionDescriptor
+export interface TradeNotice {
+  /** Maps to the widget's panel styling: `warn` → warning, `info` → info. */
+  level: 'info' | 'warn'
+  /** Plaintext; any URL is rendered as text, not a hyperlink. */
+  message: string
+}
 
-export interface ProviderMarketInfo {
+/** @public */
+export interface ProviderCategory {
   id: string
-  quoteAsset: string | null
+  logoURI?: string
+  /** `null` for the "spot" category — no single fixed quote. */
+  quoteAsset: Asset | null
+  tradeNotice?: TradeNotice
 }
 
+/** @public */
 export interface Provider {
   key: string
   name: string
@@ -124,30 +77,46 @@ export interface Provider {
   signingMethod: SigningMethod
   /** When false, the provider is announced but not yet selectable in clients. */
   active: boolean
+  setup: ProviderAction[]
+  options: ProviderAction[]
+  actions: ProviderAction[]
+  categories: ProviderCategory[]
+  wsUrl?: string
+  /** Absent means no minimum advertised. */
+  minDepositUsd?: number
   /**
-   * Mandatory account-setup descriptors. The user MUST satisfy every
-   * entry before trading. The widget renders these in `<SetupModal />`,
-   * which auto-pops whenever setup becomes unsatisfied. An empty array
-   * is valid and indicates the provider has no setup gates.
+   * Minimum order notional value in USD. Feeds the SDK's `validateMargin`
+   * `minMarginUsd` parameter. Absent means no minimum advertised.
    */
-  setup: ProviderSetup[]
+  minOrderValueUsd?: number
   /**
-   * Optional post-setup descriptors the user may tune (account mode,
-   * fee tier, etc.). Rendered in `<OptionsModal />` behind the cog icon;
-   * never gates trading. An empty array is valid.
+   * Minimum order notional value in USD for reduce-only orders, when the
+   * provider applies a lower floor than `minOrderValueUsd`. Absent means
+   * reduce-only orders use the same floor as `minOrderValueUsd`.
    */
-  options: ProviderOption[]
-  actions: ActionDescriptor[]
-  markets: ProviderMarketInfo[]
-  wsUrl?: string
+  minReduceOrderValueUsd?: number
+  /** Minimum withdrawal notional in USD. Absent means no minimum advertised. */
+  minWithdrawalUsd?: number
+  /** Flat deposit fee in USD the provider charges. Absent means no fee advertised. */
+  depositFeeUsd?: number
+  /** Flat withdrawal fee in USD the provider charges. Absent means no fee advertised. */
+  withdrawalFeeUsd?: number
   /**
-   * Minimum deposit amount in USD that the provider's deposit path will
-   * accept. Absent means no minimum is advertised — clients should not
-   * gate the deposit UX on a value they don't have.
+   * Aggregate up-votes for this provider. Populated only for inactive
+   * providers (those gathering demand before launch); absent once `active`.
    */
-  minDepositUsd?: number
+  upVotes?: number
+  /** Aggregate down-votes. Populated only for inactive providers; see {@link upVotes}. */
+  downVotes?: number
+  /**
+   * Candle intervals this provider supports for OHLCV/chart requests, in
+   * ascending order. Drives the client's chart interval selector. Empty for
+   * providers that expose no candle data.
+   */
+  supportedIntervals: OhlcvInterval[]
 }
 
+/** @public */
 export interface ProvidersResponse {
   providers: Provider[]
 }

package/src/quote.ts

@@ -0,0 +1,49 @@
+import type { FeeTier } from './account.js'
+import type { FundingInfo } from './market.js'
+
+/** @public */
+export type QuoteSide = 'buy' | 'sell'
+
+/** @public */
+export type TradeType = 'perps' | 'spot'
+
+/**
+ * One-shot fill estimate for a market order of `sizeUsd` notional on a single
+ * venue: the VWAP fill walked from the orderbook, the price impact versus the
+ * mark, the base-tier taker fee, and (for perps) the current funding rate.
+ *
+ * `priceImpactBps` is signed-magnitude basis points (1 bps = 0.01%) of the
+ * VWAP fill's deviation from `markPrice` — always non-negative, since a buy
+ * fills above mark and a sell below.
+ * @public
+ */
+export interface Quote {
+  provider: string
+  /** Human `displaySymbol` the quote was resolved against, e.g. `"BTC"`. */
+  symbol: string
+  /** Opaque resolved `Market.id`. */
+  marketId: string
+  type: TradeType
+  side: QuoteSide
+  /** Input notional in USD. */
+  sizeUsd: string
+  /** Base amount the book filled for `sizeUsd` (or the most obtainable when the book is too thin). */
+  baseSize: string
+  markPrice: string
+  /** Volume-weighted average fill price from the book walk. */
+  expectedFillPrice: string
+  /** VWAP deviation from `markPrice` in basis points; non-negative. */
+  priceImpactBps: string
+  /** Base maker/taker fee fractions (not bps) for the public tier. */
+  feeTier: FeeTier
+  /** Always `true` in v1 — quotes use the public base tier, never a per-account tier. */
+  isDefaultFeeTier: boolean
+  /** Taker fee on the filled notional in USD: `filledNotional * feeTier.taker`. */
+  feeUsd: string
+  /** Current funding for perps; `null` for spot. */
+  funding: FundingInfo | null
+  /** `true` when the book could not fill the full `sizeUsd` — `baseSize`/fill reflect the best obtainable. */
+  insufficientLiquidity: boolean
+  /** Unix milliseconds the quote was produced. */
+  timestamp: number
+}

package/src/subscriptions.ts

@@ -1,44 +1,62 @@
-import type { Address } from './typedData.js'
-import type { Candle, OhlcvInterval, OrderbookResponse } from './asset.js'
-import type { Fill, Position } from './account.js'
-import type { Order } from './action.js'
-
-// --- Channels the user can subscribe to ---
+import type {
+  Balance,
+  Fill,
+  OpenOrder,
+  Position,
+  TriggerOrder,
+} from './account.js'
+import type { Candle, OhlcvInterval, OrderbookResponse } from './market.js'
+import type { Address } from './primitives.js'
 
+/** @public */
 export type PricesSubscription = { channel: 'prices'; dex: string }
+/** @public */
 export type OrderbookSubscription = {
   channel: 'orderbook'
   dex: string
-  assetId: string
+  marketId: string
   depth?: number
+  /**
+   * Desired price granularity of streamed levels, in quote currency (e.g.
+   * `10` buckets a BTC book into $10-wide levels). Providers that aggregate
+   * the book server-side honour it best-effort; providers that stream the
+   * full book ignore it. `undefined` requests full precision.
+   */
+  priceStep?: number
 }
+/** @public */
 export type CandleSubscription = {
   channel: 'candle'
   dex: string
-  assetId: string
+  marketId: string
   interval: OhlcvInterval
 }
+/** @public */
 export type OrderUpdatesSubscription = {
   channel: 'orderUpdates'
   dex: string
   address: Address
 }
+/** @public */
 export type FillsSubscription = {
   channel: 'fills'
   dex: string
   address: Address
 }
+/** @public */
 export type PositionsSubscription = {
   channel: 'positions'
   dex: string
   address: Address
 }
+/** @public */
 export type SpotBalancesSubscription = {
   channel: 'spotBalances'
   dex: string
   address: Address
 }
 
+/** @public */
 export type Subscription =
   | PricesSubscription
   | OrderbookSubscription
@@ -48,22 +66,48 @@ export type Subscription =
   | PositionsSubscription
   | SpotBalancesSubscription
 
-// --- Events emitted to listeners ---
-
-export interface SpotBalance {
-  coin: string
-  total: string
-  hold: string
-}
-
+/** @public */
 export type PricesEvent = { channel: 'prices'; data: Record<string, string> }
+/** @public */
 export type OrderbookEvent = { channel: 'orderbook'; data: OrderbookResponse }
+/** @public */
 export type CandleEvent = { channel: 'candle'; data: Candle }
-export type OrderUpdatesEvent = { channel: 'orderUpdates'; data: Order[] }
+/** @public */
+export type OrderUpdatesEvent = {
+  channel: 'orderUpdates'
+  data: {
+    /** Upserts — active orders, non-trigger. */
+    openOrders: OpenOrder[]
+    /** Upserts — active orders with trigger semantics (TP/SL). */
+    triggerOrders: TriggerOrder[]
+    /**
+     * orderIds whose status just transitioned to terminal (filled, cancelled,
+     * rejected, expired). Consumers should evict these from both buckets.
+     */
+    terminated: string[]
+  }
+}
+/** @public */
 export type FillsEvent = { channel: 'fills'; data: Fill[] }
+/**
+ * Positions stream frame. `data` is always the full set of currently open
+ * positions for the subscribed address, never a partial update: zero-size
+ * entries never appear, and a close is observed as the market's absence from
+ * the next frame. Consumers replace their state; they must not merge.
+ * @public
+ */
 export type PositionsEvent = { channel: 'positions'; data: Position[] }
-export type SpotBalancesEvent = { channel: 'spotBalances'; data: SpotBalance[] }
+/**
+ * Spot holdings as typed {@link Balance}s, each carrying the venue-locked
+ * portion (`locked` = reserved against open orders; `available = units − locked`).
+ * @public
+ */
+export type SpotBalancesEvent = {
+  channel: 'spotBalances'
+  data: (Balance & { locked: string })[]
+}
 
+/** @public */
 export type SubscriptionEvent =
   | PricesEvent
   | OrderbookEvent

package/src/typedData.ts

@@ -1,23 +1,32 @@
-import type { Address, Hex, TypedDataDomain, TypedDataParameter } from 'viem'
-import type { HlPrimaryType } from './providers/hyperliquid/types.js'
+import type { Address, Hex } from './primitives.js'
 
-/**
- * All known EIP-712 primaryType values across supported providers.
- * Extend this union when adding a new EIP-712 provider.
- */
-export type PerpsPrimaryType = HlPrimaryType
+/** @public */
+export interface TypedDataDomain {
+  name?: string
+  version?: string
+  chainId?: number
+  verifyingContract?: Address
+  salt?: Hex
+}
+
+/** @public */
+export interface TypedDataParameter {
+  name: string
+  type: string
+}
 
+/** @public */
+export type PerpsPrimaryType = string
+
+/** @public */
 export type PerpsTypedData = {
   domain: TypedDataDomain
   types: Record<string, readonly TypedDataParameter[]>
   primaryType: PerpsPrimaryType
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   message: Record<string, any>
 }
 
+/** @public */
 export type PerpsSignedTypedData = PerpsTypedData & {
   signature: Hex
 }
-
-// Re-export viem primitives used across perps types
-export type { Address, Hex, TypedDataDomain, TypedDataParameter }