@lifi/perps-types 18.0.0 → 18.1.0

package/src/action.ts

@@ -1,4 +1,5 @@
 import type { AcceptTermsParams } from './acceptTerms.js'
+import type { DecimalString } from './decimal.js'
 import type {
   ActionType,
   MarginMode,
@@ -271,13 +272,13 @@ export type ActionResult =
  * @public
  */
 export interface TriggerOrderInput {
-  triggerPrice: string
-  limitPrice?: string
+  triggerPrice: DecimalString
+  limitPrice?: DecimalString
   /**
    * Base-asset size the trigger closes. Omitted covers the entire position,
    * tracking later size changes; set, it is a fixed partial amount.
    */
-  size?: string
+  size?: DecimalString
 }
 
 /**
@@ -287,10 +288,10 @@ export interface TriggerOrderInput {
  */
 export interface ModifyOrderInput {
   id: string
-  price?: string
-  size?: string
-  triggerPrice?: string
-  limitPrice?: string
+  price?: DecimalString
+  size?: DecimalString
+  triggerPrice?: DecimalString
+  limitPrice?: DecimalString
 }
 
 /**
@@ -302,8 +303,8 @@ export interface PlaceOrderParams {
   market: MarketRef
   side: OrderSide
   type?: Exclude<OrderType, OrderType.TWAP>
-  size: string
-  price?: string
+  size: DecimalString
+  price?: DecimalString
   leverage?: number
   /**
    * Hyperliquid: requires `leverage`. Omitted leaves the market's current
@@ -344,7 +345,7 @@ export interface PlaceTwapOrderParams {
   market: MarketRef
   side: OrderSide
   /** Total base-asset size executed across the TWAP's lifetime, as a decimal string. */
-  size: string
+  size: DecimalString
   /** Total execution window in seconds. */
   durationSeconds: number
   reduceOnly?: boolean
@@ -353,9 +354,9 @@ export interface PlaceTwapOrderParams {
   /** Ondo: interval between child orders in seconds. */
   frequencySeconds?: number
   /** Ondo: lowest acceptable child-order price, as a decimal string. */
-  minPrice?: string
+  minPrice?: DecimalString
   /** Ondo: highest acceptable child-order price, as a decimal string. */
-  maxPrice?: string
+  maxPrice?: DecimalString
 }
 
 /**
@@ -417,7 +418,7 @@ export interface UpdateLeverageParams {
 export interface UpdatePositionMarginParams {
   market: MarketRef
   action: 'add' | 'remove'
-  amount: string
+  amount: DecimalString
 }
 
 /**
@@ -449,7 +450,7 @@ export type WithdrawalRoute = 'perps' | 'spot'
  */
 export interface WithdrawalParams {
   destination: Address
-  amount: string
+  amount: DecimalString
   /** Lighter: provider-native `Asset.id` to withdraw. Omitted withdraws the quote asset. */
   assetId?: string
   /** Lighter: balance route to draw from. Omitted is `perps`. */
@@ -469,7 +470,7 @@ export interface WithdrawalParams {
  */
 export interface DepositParams {
   /** Amount of the token to deposit, as an integer string in the token's base units (e.g. "100500000" for 100.5 USDC). */
-  amount: string
+  amount: DecimalString
   /** ERC-20 token address on the source chain. */
   tokenAddress: Address
   /** Chain ID of the source chain (e.g. 1 for Ethereum, 42161 for Arbitrum). */
@@ -534,7 +535,7 @@ export interface SendAssetParams {
   collateral: string
   sourceDex: string
   destinationDex: string
-  amount: string
+  amount: DecimalString
 }
 
 /**

package/src/asset.ts

@@ -1,3 +1,5 @@
+import type { DecimalString } from './decimal.js'
+
 /**
  * Underlying token/registry entry. The base entity of the perps taxonomy:
  * a tradable unit referenced by markets (as base/quote legs) and held by
@@ -32,7 +34,7 @@ export interface Asset {
   /** L1 token contract; the zero address denotes native gas. */
   l1Address?: string
   /** Venue minimum for a single withdrawal, denominated in this asset — not USD. */
-  minWithdrawalAmount?: string
+  minWithdrawalAmount?: DecimalString
 }
 
 /**

package/src/decimal.ts

@@ -0,0 +1,26 @@
+/**
+ * Plain decimal string: optional `-`, digits, optional fraction. No grouping,
+ * exponent, currency sign or whitespace; matches {@link DECIMAL_PATTERN}. Build
+ * it with an SDK `snap*`/`calculate*` helper or a provider, not `.toString()`.
+ *
+ * @public
+ */
+export type DecimalString = string
+
+/**
+ * The single spelling rule for a {@link DecimalString}. It stays byte-identical
+ * to the pattern `lifi-perps-backend` matches every stored decimal against, so
+ * one amount has exactly one spelling in all three repositories.
+ *
+ * @public
+ */
+export const DECIMAL_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/
+
+/**
+ * Narrows an unknown value to a {@link DecimalString}.
+ *
+ * @public
+ */
+export function isDecimalString(value: unknown): value is DecimalString {
+  return typeof value === 'string' && DECIMAL_PATTERN.test(value)
+}

package/src/index.ts

@@ -11,6 +11,7 @@ export * from './acceptTerms.js'
 export * from './account.js'
 export * from './action.js'
 export * from './asset.js'
+export * from './decimal.js'
 export * from './enums.js'
 export * from './errors.js'
 export * from './market.js'

package/src/market.ts

@@ -1,4 +1,5 @@
 import type { Asset } from './asset.js'
+import type { DecimalString } from './decimal.js'
 import type { PositionMarginAdjustment } from './enums.js'
 
 /**
@@ -9,7 +10,7 @@ import type { PositionMarginAdjustment } from './enums.js'
  */
 export interface FundingInfo {
   /** Funding rate as a decimal fraction. */
-  rate: string
+  rate: DecimalString
   /** Next funding timestamp in Unix milliseconds. */
   nextFundingTime: number
 }
@@ -43,14 +44,14 @@ export interface BaseMarket {
    * describe the tick. Format prices through the provider's `formatOrderPrice`
    * rather than applying this field directly.
    */
-  priceIncrement?: string
+  priceIncrement?: DecimalString
   /**
    * Exact size lot as a plain decimal string (e.g. `'0.05'`). Present when the
    * venue's grid is not a power of ten, where `szDecimals` alone cannot
    * describe the lot. Format sizes through the provider's `formatOrderSize`
    * rather than applying this field directly.
    */
-  sizeIncrement?: string
+  sizeIncrement?: DecimalString
 }
 
 /**
@@ -71,11 +72,11 @@ export interface PerpsMarket extends BaseMarket {
    * venue-wide `Provider.minOrderValueUsd`, which is a `number`; parse this
    * string before comparing the two.
    */
-  minOrderValueUsd?: string
+  minOrderValueUsd?: DecimalString
   /** Maximum market-order notional in USD, as a plain decimal string. */
-  maxMarketOrderUsd?: string
+  maxMarketOrderUsd?: DecimalString
   /** Maximum limit-order notional in USD, as a plain decimal string. */
-  maxLimitOrderUsd?: string
+  maxLimitOrderUsd?: DecimalString
   onlyIsolated: boolean
   /** Whether individual position margin can be added and/or removed. */
   positionMarginAdjustment: PositionMarginAdjustment
@@ -150,16 +151,16 @@ export interface MarketContext {
   /** Opaque provider market identifier for this context frame. */
   marketId: string
   /** Current order-book midpoint, as a decimal quote string. */
-  midPrice: string
+  midPrice: DecimalString
   /** Provider mark price, as a decimal quote string. */
-  markPrice: string
-  oraclePrice?: string
-  prevDayPrice?: string
-  priceChange24h?: string
-  volume24h?: string
-  marketCap?: string
+  markPrice: DecimalString
+  oraclePrice?: DecimalString
+  prevDayPrice?: DecimalString
+  priceChange24h?: DecimalString
+  volume24h?: DecimalString
+  marketCap?: DecimalString
   /** Quote-asset open-interest notional as a decimal string. */
-  openInterest?: string
+  openInterest?: DecimalString
   funding?: FundingInfo
 }
 
@@ -176,11 +177,11 @@ export interface PricesResponse {
  */
 export interface Candle {
   t: number
-  o: string
-  h: string
-  l: string
-  c: string
-  v: string
+  o: DecimalString
+  h: DecimalString
+  l: DecimalString
+  c: DecimalString
+  v: DecimalString
 }
 
 /** Response containing candles for one provider market and interval. @public */
@@ -215,8 +216,8 @@ export type OhlcvInterval =
 
 /** One price/size level in an order book; both values are decimal strings. @public */
 export interface OrderbookLevel {
-  price: string
-  size: string
+  price: DecimalString
+  size: DecimalString
 }
 
 /** Snapshot of bids and asks for one market. `timestamp` is Unix milliseconds. @public */
@@ -232,8 +233,8 @@ export interface OrderbookResponse {
 export interface Trade {
   provider: string
   marketId: string
-  price: string
-  size: string
+  price: DecimalString
+  size: DecimalString
   timestamp: number
   side: 'buy' | 'sell'
   id?: string

package/src/portfolioHistory.ts

@@ -1,3 +1,5 @@
+import type { DecimalString } from './decimal.js'
+
 /** Lookback window of a portfolio history read. @public */
 export type PortfolioHistoryRange = '24h' | '7d' | '30d' | 'all'
 
@@ -9,9 +11,9 @@ export type PortfolioHistoryRange = '24h' | '7d' | '30d' | 'all'
 export interface PortfolioHistoryPoint {
   /** Unix milliseconds. */
   timestamp: number
-  accountValue: string
+  accountValue: DecimalString
   /** Cumulative PnL from the start of the requested window. */
-  pnl: string
+  pnl: DecimalString
 }
 
 /**
@@ -22,6 +24,6 @@ export interface PortfolioHistoryPoint {
 export interface PortfolioHistoryResponse {
   range: PortfolioHistoryRange
   points: PortfolioHistoryPoint[]
-  volume?: string
-  totalPnl?: string
+  volume?: DecimalString
+  totalPnl?: DecimalString
 }

package/src/quote.ts

@@ -1,4 +1,5 @@
 import type { FeeTier } from './account.js'
+import type { DecimalString } from './decimal.js'
 import type { FundingInfo } from './market.js'
 
 /** Side of the quoted market order, using lowercase wire values. @public */
@@ -26,20 +27,20 @@ export interface Quote {
   type: TradeType
   side: QuoteSide
   /** Input notional in USD. */
-  sizeUsd: string
+  sizeUsd: DecimalString
   /** Base amount the book filled for `sizeUsd` (or the most obtainable when the book is too thin). */
-  baseSize: string
-  markPrice: string
+  baseSize: DecimalString
+  markPrice: DecimalString
   /** Volume-weighted average fill price from the book walk. */
-  expectedFillPrice: string
+  expectedFillPrice: DecimalString
   /** VWAP deviation from `markPrice` in basis points; non-negative. */
-  priceImpactBps: string
+  priceImpactBps: DecimalString
   /** 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
+  feeUsd: DecimalString
   /** 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. */

package/src/referral.ts

@@ -1,4 +1,5 @@
 import type { Pagination } from './account.js'
+import type { DecimalString } from './decimal.js'
 import type { Address } from './primitives.js'
 import type { PerpsTypedData, TypedDataParameter } from './typedData.js'
 
@@ -71,9 +72,9 @@ export interface OwnedReferralCodeEligibility {
    * Executed notional the address must reach, as a decimal string in the
    * backend's reporting currency. Absent when the backend does not disclose it.
    */
-  requiredNotional?: string
+  requiredNotional?: DecimalString
   /** The address's executed notional so far, in the same units as `requiredNotional`. */
-  currentNotional?: string
+  currentNotional?: DecimalString
 }
 
 /**
@@ -125,7 +126,7 @@ export interface ReferralActivityItem {
    * Executed notional recorded against this attachment, as a decimal string in
    * the backend's reporting currency.
    */
-  notional: string
+  notional: DecimalString
 }
 
 /**

package/src/subscriptions.ts

@@ -6,6 +6,7 @@ import type {
   Order,
   Position,
 } from './account.js'
+import type { DecimalString } from './decimal.js'
 import type {
   Candle,
   MarketContext,
@@ -152,7 +153,7 @@ export type PositionsEvent = { channel: 'positions'; data: Position[] }
  */
 export type SpotBalancesEvent = {
   channel: 'spotBalances'
-  data: (Balance & { locked: string })[]
+  data: (Balance & { locked: DecimalString })[]
 }
 
 /**