@lifi/perps-types 17.0.0 → 18.1.0

package/src/account.ts

@@ -1,4 +1,5 @@
 import type { Asset, AssetDisplay } from './asset.js'
+import type { DecimalString } from './decimal.js'
 import type {
   ActionType,
   ActivityType,
@@ -23,9 +24,9 @@ import type { Address, ProviderId } from './primitives.js'
  */
 export interface FeeTier {
   /** Decimal fraction charged to maker fills, represented as a string. */
-  maker: string
+  maker: DecimalString
   /** Decimal fraction charged to taker fills, represented as a string. */
-  taker: string
+  taker: DecimalString
 }
 
 /**
@@ -38,22 +39,22 @@ export interface Position {
   market: PerpsMarketDisplay
   side: PositionSide
   /** Position quantity in base-asset units. */
-  size: string
+  size: DecimalString
   /** Average entry price in quote-asset units. */
-  entryPrice: string
+  entryPrice: DecimalString
   /** Current provider mark price in quote-asset units. */
-  markPrice: string
+  markPrice: DecimalString
   /** Estimated liquidation price in quote-asset units. */
-  liquidationPrice: string
+  liquidationPrice: DecimalString
   /** Unrealized PnL in quote-currency units. */
-  unrealizedPnl: string
+  unrealizedPnl: DecimalString
   /**
    * Funding this position accrued since it opened, in quote-currency units.
    * Positive means the account received funding and negative means the account
    * paid it, matching {@link FundingActivity} amounts. Every venue resets the
    * value when the position returns to flat.
    */
-  accruedFunding: string
+  accruedFunding: DecimalString
   /** Position leverage as a numeric multiple. */
   leverage: number
   /**
@@ -62,12 +63,12 @@ export interface Position {
    * Hyperliquid isolated `marginUsed` includes the unrealized PnL of the
    * position; Lighter `allocated_margin` excludes it.
    */
-  marginUsed: string
+  marginUsed: DecimalString
   /**
    * Exact initial margin the venue currently requires for this position.
    * Unlike `leverage`, this decimal string is safe for risk calculations.
    */
-  initialMarginRequirement: string
+  initialMarginRequirement: DecimalString
   marginMode: MarginMode
 }
 
@@ -82,10 +83,10 @@ export interface OrderBase {
   status: OrderStatus
   /** Venue text for a REJECTED or CANCELLED order, when the venue gives one. */
   statusReason?: string
-  originalSize: string
-  remainingSize: string
-  filledSize: string
-  averagePrice?: string
+  originalSize: DecimalString
+  remainingSize: DecimalString
+  filledSize: DecimalString
+  averagePrice?: DecimalString
   reduceOnly: boolean
   /** Parent of a placement TP/SL leg or TWAP child; absent on position-level triggers. */
   parentOrderId?: string
@@ -98,7 +99,7 @@ export interface OrderBase {
 /** Market or limit order with a time-in-force policy. */
 export interface RegularOrder extends OrderBase {
   type: OrderType.MARKET | OrderType.LIMIT
-  price?: string
+  price?: DecimalString
   timeInForce: TimeInForce
   expiresAt?: string
 }
@@ -110,9 +111,9 @@ export interface TriggerOrder extends OrderBase {
     | OrderType.STOP_LIMIT
     | OrderType.TAKE_PROFIT_MARKET
     | OrderType.TAKE_PROFIT_LIMIT
-  triggerPrice: string
+  triggerPrice: DecimalString
   triggerCondition: TriggerCondition
-  limitPrice?: string
+  limitPrice?: DecimalString
 }
 
 /** Time-weighted execution parent. */
@@ -135,17 +136,18 @@ export interface Balance {
   /** Which category/venue this balance sits in — references a {@link ProviderCategory}. */
   categoryId: string
   asset: Asset
-  units: string
+  units: DecimalString
   /** USD value the SDK fills from the prices map; consumers render with zero math. */
-  valueUsd: string
+  valueUsd: DecimalString
   /** USD price of one unit. Absent when the provider holds no price for the asset. */
-  price?: string
+  price?: DecimalString
   /**
-   * Part of `units` the venue releases from this category in a category
-   * transfer, as a decimal string from `0` to `units`. Set on each
-   * perps-category collateral row; absent on every other row.
+   * Part of `units` the venue releases from this category, as a decimal
+   * string clamped to `[0, units]`. Every collateral row and every spot row
+   * carries it. It is not the withdrawal ceiling: read
+   * `PerpsClient.getWithdrawableBalances` for that.
    */
-  transferable?: string
+  transferable?: DecimalString
 }
 
 /**
@@ -169,9 +171,9 @@ export interface AccountResponse {
   /** Open positions the snapshot already computed; equals the unfiltered `getPositions` output. */
   positions: Position[]
   /** Margin reserved across the account, represented as a decimal string. */
-  marginUsed: string
+  marginUsed: DecimalString
   /** Unrealized account PnL, represented as a decimal string. */
-  unrealizedPnl: string
+  unrealizedPnl: DecimalString
   feeTier: FeeTier
   config: AccountConfig
 }
@@ -184,13 +186,13 @@ export interface AccountResponse {
  */
 export interface AccountSummary {
   /** Total account portfolio value in USD. */
-  portfolioValue: string
+  portfolioValue: DecimalString
   /** Margin currently available for new orders in USD. */
-  availableMargin: string
+  availableMargin: DecimalString
   /** Margin currently reserved by open positions/orders in USD. */
-  marginUsed: string
+  marginUsed: DecimalString
   /** Aggregate unrealized PnL in USD. */
-  unrealizedPnl: string
+  unrealizedPnl: DecimalString
 }
 
 /**
@@ -207,15 +209,14 @@ export interface AvailableToTrade {
   /** The market's margin asset, which both amounts are denominated in. */
   asset: AssetDisplay
   /** Amount the account can still buy, represented as a decimal string. */
-  buy: string
+  buy: DecimalString
   /** Amount the account can still sell, represented as a decimal string. */
-  sell: string
+  sell: DecimalString
 }
 
 /**
- * The user's complete venue-side settings for one market: the margin mode
- * and display leverage the next order on it will use. A provider returns
- * `undefined` when it cannot read both values.
+ * The user's complete venue-side settings for one perps market: the margin
+ * mode and display leverage the next order on it will use.
  * @public
  */
 export interface MarketSettings {
@@ -251,7 +252,7 @@ export interface OrdersResponse {
  */
 export interface Fee {
   /** Decimal string in `asset`'s units. */
-  amount: string
+  amount: DecimalString
   /**
    * Display symbol the fee is denominated in, resolved by the provider
    * adapter. Falls back to the venue's own asset id when the registry knows no
@@ -276,10 +277,10 @@ export interface Fill {
    * Hyperliquid taker fill, which may be a market or an aggressive limit order).
    */
   type?: OrderType
-  size: string
-  price: string
+  size: DecimalString
+  price: DecimalString
   liquidity: LiquidityRole
-  filledSize?: string
+  filledSize?: DecimalString
   /** Absent when the venue reports no fee for the fill. */
   fee?: Fee
   /**
@@ -300,8 +301,8 @@ export interface Fill {
    * a sentinel value.
    */
   leverage?: number
-  realizedPnl?: string | null
-  startPosition?: string
+  realizedPnl?: DecimalString | null
+  startPosition?: DecimalString
   classification: FillClassification
   createdAt: string
   /** Fully-resolved block-explorer URL for the settling on-chain tx. Absent when
@@ -354,7 +355,7 @@ export interface BaseActivity {
 export interface DepositActivity extends BaseActivity {
   type: ActivityType.DEPOSIT
   asset: Asset
-  amount: string
+  amount: DecimalString
   /**
    * Address the deposited funds came from, as the venue reports it. Absent
    * when the venue's deposit payload names no source address.
@@ -373,7 +374,7 @@ export interface DepositActivity extends BaseActivity {
 export interface WithdrawalActivity extends BaseActivity {
   type: ActivityType.WITHDRAWAL
   asset: Asset
-  amount: string
+  amount: DecimalString
   /** Absent when the venue reports no fee for the withdrawal. */
   fee?: Fee
   /** Fully-resolved block-explorer URL for the on-chain withdrawal tx. */
@@ -388,7 +389,7 @@ export interface WithdrawalActivity extends BaseActivity {
 export interface LiquidatedPosition {
   market: MarketDisplay
   /** Absent when the venue reports no liquidated size for the position. */
-  size?: string
+  size?: DecimalString
 }
 
 /**
@@ -402,9 +403,9 @@ export interface LiquidatedPosition {
 export interface LiquidationActivity extends BaseActivity {
   type: ActivityType.LIQUIDATION
   /** Absent when the venue reports no liquidated notional. */
-  liquidatedNotionalPosition?: string
+  liquidatedNotionalPosition?: DecimalString
   /** Absent when the venue reports no account value at liquidation time. */
-  accountValue?: string
+  accountValue?: DecimalString
   /**
    * Margin mode the liquidated account ran under, in the venue's own
    * vocabulary — typically `cross` or `isolated`, but the venue may report
@@ -432,9 +433,9 @@ export interface FundingActivity extends BaseActivity {
    * Signed, in quote-currency units. Positive means the account received
    * funding; negative means the account paid it.
    */
-  amount: string
-  positionSize: string
-  fundingRate: string
+  amount: DecimalString
+  positionSize: DecimalString
+  fundingRate: DecimalString
 }
 
 // At least one of `counterpartyAccountIndex` / `counterpartyAddress` is always
@@ -451,7 +452,7 @@ export type TransferActivity = BaseActivity & {
   type: ActivityType.TRANSFER
   direction: 'IN' | 'OUT'
   asset: Asset
-  amount: string
+  amount: DecimalString
   /**
    * Every fee the venue charged for the transfer, in the order the venue
    * reports them. A venue may charge several fees for one transfer, each in a
@@ -509,7 +510,7 @@ export type HyperliquidAgent = Record<string, unknown>
 export interface HyperliquidBuilderFeeApproval {
   builderAddress: string
   /** Basis points as a string. */
-  maxFeeRate: string
+  maxFeeRate: DecimalString
   approved: boolean
 }
 
@@ -521,10 +522,10 @@ export interface HyperliquidBuilderFeeApproval {
  */
 export interface HyperliquidMarginSummary {
   /** Total equity: locked margin and unrealized PnL included. */
-  accountValue: string
-  totalNtlPos: string
-  totalRawUsd: string
-  totalMarginUsed: string
+  accountValue: DecimalString
+  totalNtlPos: DecimalString
+  totalRawUsd: DecimalString
+  totalMarginUsed: DecimalString
 }
 
 /**
@@ -539,8 +540,8 @@ export interface HyperliquidDexAccountState {
   marginSummary: HyperliquidMarginSummary
   /** Cross-margin subset of {@link HyperliquidDexAccountState.marginSummary}. */
   crossMarginSummary: HyperliquidMarginSummary
-  crossMaintenanceMarginUsed: string
-  withdrawable: string
+  crossMaintenanceMarginUsed: DecimalString
+  withdrawable: DecimalString
 }
 
 /**
@@ -561,7 +562,7 @@ export interface HyperliquidAccountConfig {
    * `tokenToAvailableAfterMaintenance` list. Unified and portfolio-margin
    * accounts only; other modes derive buying power from `marginSummary`.
    */
-  availableAfterMaintenance?: string
+  availableAfterMaintenance?: DecimalString
 }
 
 /**
@@ -609,16 +610,28 @@ export interface LighterAccountConfig {
    */
   accountType: number
   /**
-   * Lighter `available_balance`: venue buying power for the whole account,
-   * already marked to market. A decimal string in quote-asset units.
+   * Lighter `available_balance`: the withdrawable total, already marked to
+   * market. It is not the buying power: it adds each isolated position's
+   * equity above its initial margin requirement and subtracts the shortfall
+   * below it. A decimal string in quote-asset units.
    */
-  availableBalance: string
+  availableBalance: DecimalString
+  /**
+   * Lighter `cross_asset_value`: cross-margin collateral plus the unrealized
+   * PnL of the cross positions. A decimal string in quote-asset units.
+   */
+  crossAssetValue: DecimalString
+  /**
+   * Lighter `cross_initial_margin_requirement`: the initial margin the cross
+   * positions lock. A decimal string in quote-asset units.
+   */
+  crossInitialMarginRequirement: DecimalString
   /**
    * Lighter `total_asset_value`: perps-route equity, isolated allocations and
    * unrealized PnL included. It excludes the spot-route balances. A decimal
    * string in quote-asset units.
    */
-  totalAssetValue: string
+  totalAssetValue: DecimalString
   /**
    * Lighter `user_tier_name` from `/accountLimits`, in the tier vocabulary
    * `changeAccountTier` accepts. Absent on an unauthenticated read, which
@@ -657,15 +670,15 @@ export interface LighterAccountConfig {
  */
 export interface OndoAccountBalance {
   /** Collateral only: locked margin included, unrealized PnL excluded. */
-  walletBalance: string
-  unrealizedPnl: string
+  walletBalance: DecimalString
+  unrealizedPnl: DecimalString
   /** Total equity. */
-  marginBalance: string
-  usedMargin: string
+  marginBalance: DecimalString
+  usedMargin: DecimalString
   /** Venue buying power. */
-  availableMargin: string
+  availableMargin: DecimalString
   /** Venue withdrawable figure, at or below {@link OndoAccountBalance.availableMargin}. */
-  withdrawableMargin: string
+  withdrawableMargin: DecimalString
 }
 
 /**

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,10 +303,13 @@ export interface PlaceOrderParams {
   market: MarketRef
   side: OrderSide
   type?: Exclude<OrderType, OrderType.TWAP>
-  size: string
-  price?: string
+  size: DecimalString
+  price?: DecimalString
   leverage?: number
-  /** Omitted falls back to the provider's default (currently CROSS). */
+  /**
+   * Hyperliquid: requires `leverage`. Omitted leaves the market's current
+   * margin mode unchanged.
+   */
   marginMode?: MarginMode
   reduceOnly?: boolean
   timeInForce?: TimeInForce
@@ -341,18 +345,18 @@ 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
-  /** Hyperliquid: randomize sub-order timing within the execution window. */
+  /** Hyperliquid: randomize each sub-order size by up to 20 percent. */
   randomize?: boolean
   /** 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
 }
 
 /**
@@ -401,7 +405,7 @@ export interface ModifyOrderParams {
 export interface UpdateLeverageParams {
   market: MarketRef
   leverage: number
-  /** Omitted falls back to the provider's default (currently CROSS). */
+  /** Hyperliquid: omitted is sent as isolated. */
   marginMode?: MarginMode
 }
 
@@ -414,7 +418,7 @@ export interface UpdateLeverageParams {
 export interface UpdatePositionMarginParams {
   market: MarketRef
   action: 'add' | 'remove'
-  amount: string
+  amount: DecimalString
 }
 
 /**
@@ -429,6 +433,16 @@ export interface UpdateAssetCollateralParams {
   enabled: boolean
 }
 
+/**
+ * Which of a venue's two balance routes a withdrawal is drawn from. Lighter's
+ * own vocabulary, carried in the signed tx as `AssetRouteType` (`perps` = 0,
+ * `spot` = 1); an account's mode changes what the two balances mean, never
+ * which route the tx names.
+ *
+ * @public
+ */
+export type WithdrawalRoute = 'perps' | 'spot'
+
 /**
  * Parameters for withdrawing a decimal-string amount to an EVM address.
  *
@@ -436,7 +450,11 @@ export interface UpdateAssetCollateralParams {
  */
 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`. */
+  route?: WithdrawalRoute
   /**
    * The venue-native account identifier, as a string. The provider plugin
    * supplies it; callers omit it. A string because Ondo's 20-digit accountID
@@ -451,8 +469,8 @@ export interface WithdrawalParams {
  * @public
  */
 export interface DepositParams {
-  /** Amount of the token to deposit (human-readable, e.g. "100.5"). */
-  amount: string
+  /** Amount of the token to deposit, as an integer string in the token's base units (e.g. "100500000" for 100.5 USDC). */
+  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). */
@@ -471,17 +489,12 @@ export interface ApproveAgentParams {
 }
 
 /**
- * Parameters for deregistering an account agent.
+ * Parameters for deregistering an account agent. The action takes no
+ * parameters: the backend picks the agent to revoke and the user confirms it.
  *
  * @public
  */
-export interface RevokeAgentParams {
-  address: Address
-  /** The name the venue holds for the agent. HyperCore identifies a named API
-   * wallet by name, not by address, so a revoke that omits the exact stored
-   * name leaves the slot occupied. */
-  name: string
-}
+export type RevokeAgentParams = Record<string, never>
 
 /**
  * Parameters for removing the session agent the SDK signs with, targeted by
@@ -522,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'