@lifi/perps-types 3.3.2 → 4.0.1

package/src/action.ts

@@ -14,13 +14,22 @@ import type { Address, Hex } from './primitives.js'
 import type { PerpsTypedData } from './typedData.js'
 import type { VoteParams } from './vote.js'
 
-/** @public */
+/**
+ * Unsigned EIP-712 action step containing typed data for client signing.
+ *
+ * @public
+ */
 export interface Eip712ActionStep {
   action: ActionType
   typedData: PerpsTypedData
 }
 
-/** @public */
+/**
+ * Unsigned WASM-blob action step containing provider-specific signing
+ * parameters for the client.
+ *
+ * @public
+ */
 export interface WasmBlobActionStep {
   action: ActionType
   wasmSignParams: Record<string, unknown>
@@ -37,12 +46,18 @@ export interface EvmCall {
   chainId: number
   to: Address
   functionName: string
+  /** Function arguments supplied to the contract call in declaration order. */
   args: readonly unknown[]
   /** Human-readable ABI signatures, e.g. `'function approve(address,uint256) returns (bool)'`, fed to viem `parseAbi`. */
   abi: readonly string[]
 }
 
-/** @public */
+/**
+ * Unsigned EVM transaction action step. `txParams` describes the call that the
+ * client encodes and submits.
+ *
+ * @public
+ */
 export interface EvmTxActionStep {
   action: ActionType
   txParams: EvmCall
@@ -78,12 +93,20 @@ export interface HmacActionStep {
  * @public
  */
 export interface CreateDepositAddressSessionMarker {
+  /** Source network for the provider deposit address. */
   network: 'ethereum'
+  /** Deposit asset symbol; currently constrained to USDC. */
   symbol: 'USDC'
+  /** Provider wallet destination policy; currently constrained to margin. */
   depositDestination: { wallet: 'margin' }
 }
 
-/** @public */
+/**
+ * Client-only session action step, with a provider session request marker or
+ * an empty session payload for actions that do not need one.
+ *
+ * @public
+ */
 export type SessionActionStep =
   | {
       action: Exclude<ActionType, ActionType.CREATE_DEPOSIT_ADDRESS>
@@ -94,17 +117,26 @@ export type SessionActionStep =
       session: CreateDepositAddressSessionMarker
     }
 
-/** @public */
+/**
+ * Unsigned SIWE action step containing the backend-issued login challenge.
+ *
+ * @public
+ */
 export interface SiweActionStep {
   action: ActionType
   siwe: {
+    /** Backend identifier for the SIWE challenge. */
     challengeId: string
     /** The backend-built ERC-4361 challenge the wallet must `personal_sign`. */
     message: string
   }
 }
 
-/** @public */
+/**
+ * Union of all unsigned action-step encodings produced by `createAction`.
+ *
+ * @public
+ */
 export type ActionStep =
   | Eip712ActionStep
   | WasmBlobActionStep
@@ -113,14 +145,22 @@ export type ActionStep =
   | SessionActionStep
   | SiweActionStep
 
-/** @public */
+/**
+ * Signed EIP-712 action step ready for backend execution.
+ *
+ * @public
+ */
 export interface Eip712SignedActionStep {
   action: ActionType
   typedData: PerpsTypedData
   signature: Hex
 }
 
-/** @public */
+/**
+ * Signed WASM-blob action step, including provider wire transaction details.
+ *
+ * @public
+ */
 export interface WasmBlobSignedActionStep {
   action: ActionType
   wasmSignParams: Record<string, unknown>
@@ -131,14 +171,22 @@ export interface WasmBlobSignedActionStep {
   }
 }
 
-/** @public */
+/**
+ * Signed EVM transaction action step with the submitted transaction hash.
+ *
+ * @public
+ */
 export interface EvmTxSignedActionStep {
   action: ActionType
   txParams: EvmCall
   txHash: string
 }
 
-/** @public */
+/**
+ * HMAC-authenticated venue request ready for backend execution.
+ *
+ * @public
+ */
 export interface HmacSignedActionStep {
   action: ActionType
   request: HmacActionStep['request']
@@ -154,14 +202,22 @@ export interface HmacSignedActionStep {
   }
 }
 
-/** @public */
+/**
+ * Signed SIWE login action step.
+ *
+ * @public
+ */
 export interface SiweSignedActionStep {
   action: ActionType
   siwe: SiweActionStep['siwe']
   signature: Hex
 }
 
-/** @public */
+/**
+ * Union of all signed action-step encodings accepted by `executeAction`.
+ *
+ * @public
+ */
 export type SignedActionStep =
   | Eip712SignedActionStep
   | WasmBlobSignedActionStep
@@ -169,7 +225,12 @@ export type SignedActionStep =
   | HmacSignedActionStep
   | SiweSignedActionStep
 
-/** @public */
+/**
+ * Per-action execution result. Success arms may include a provider order id;
+ * failure arms carry a message and optional structured error code.
+ *
+ * @public
+ */
 export type ActionResult =
   | {
       action: ActionType
@@ -184,13 +245,27 @@ export type ActionResult =
       errorCode?: PerpsErrorCode
     }
 
-/** @public */
+/**
+ * Trigger prices used to configure take-profit or stop-loss behavior.
+ * Prices are decimal strings in the market's quote currency.
+ *
+ * @public
+ */
 export interface TriggerOrderInput {
   triggerPrice: string
   limitPrice?: string
+  /**
+   * Base-asset size the trigger closes. Omitted covers the entire position,
+   * tracking later size changes; set, it is a fixed partial amount.
+   */
+  size?: string
 }
 
-/** @public */
+/**
+ * Mutable fields for an existing order, identified by venue order id.
+ *
+ * @public
+ */
 export interface ModifyOrderInput {
   id: string
   price?: string
@@ -199,7 +274,12 @@ export interface ModifyOrderInput {
   limitPrice?: string
 }
 
-/** @public */
+/**
+ * Normalized order returned by a provider, including lifecycle and trigger
+ * metadata. Quantities and prices are decimal strings.
+ *
+ * @public
+ */
 export interface Order {
   orderId: string
   market: MarketDisplay
@@ -223,7 +303,11 @@ export interface Order {
   updatedAt: string
 }
 
-/** @public */
+/**
+ * Parameters for placing a regular order on a market.
+ *
+ * @public
+ */
 export interface PlaceOrderParams {
   market: MarketRef
   side: OrderSide
@@ -240,7 +324,11 @@ export interface PlaceOrderParams {
   stopLoss?: TriggerOrderInput
 }
 
-/** @public */
+/**
+ * Parameters for placing a take-profit or stop-loss trigger order.
+ *
+ * @public
+ */
 export interface PlaceTriggerOrderParams {
   market: MarketRef
   side: OrderSide
@@ -248,7 +336,11 @@ export interface PlaceTriggerOrderParams {
   stopLoss?: TriggerOrderInput
 }
 
-/** @public */
+/**
+ * Parameters for cancelling one or more venue orders.
+ *
+ * @public
+ */
 export interface CancelOrderParams {
   /** Venue order ids. Venues whose ids are scoped per market (e.g. Lighter's
    * `order_index`) also accept the composite `"<market_id>:<order_id>"`. */
@@ -257,12 +349,20 @@ export interface CancelOrderParams {
   assetId?: string
 }
 
-/** @public */
+/**
+ * Parameters for applying one or more modifications to existing orders.
+ *
+ * @public
+ */
 export interface ModifyOrderParams {
   modifications: ModifyOrderInput[]
 }
 
-/** @public */
+/**
+ * Parameters for changing leverage on a market.
+ *
+ * @public
+ */
 export interface UpdateLeverageParams {
   market: MarketRef
   leverage: number
@@ -270,14 +370,23 @@ export interface UpdateLeverageParams {
   marginMode?: MarginMode
 }
 
-/** @public */
+/**
+ * Parameters for adding or removing margin from a market position.
+ * `amount` is a decimal string in the venue's collateral units.
+ *
+ * @public
+ */
 export interface UpdatePositionMarginParams {
   market: MarketRef
   action: 'add' | 'remove'
   amount: string
 }
 
-/** @public */
+/**
+ * Parameters for enabling or disabling an asset as cross-margin collateral.
+ *
+ * @public
+ */
 export interface UpdateAssetCollateralParams {
   /** Provider-native spot asset id (matches `Asset.id`), keyed per asset — not per market. */
   assetId: string
@@ -285,13 +394,21 @@ export interface UpdateAssetCollateralParams {
   enabled: boolean
 }
 
-/** @public */
+/**
+ * Parameters for withdrawing a decimal-string amount to an EVM address.
+ *
+ * @public
+ */
 export interface WithdrawalParams {
   destination: Address
   amount: string
 }
 
-/** @public */
+/**
+ * Parameters for depositing a token from an EVM source chain.
+ *
+ * @public
+ */
 export interface DepositParams {
   /** Amount of the token to deposit (human-readable, e.g. "100.5"). */
   amount: string
@@ -301,23 +418,40 @@ export interface DepositParams {
   chainId: number
 }
 
-/** @public */
+/**
+ * Parameters for approving an account agent, including an optional TTL in
+ * milliseconds.
+ *
+ * @public
+ */
 export interface ApproveAgentParams {
   agentAddress: string
   agentTtlMs?: number
 }
 
-/** @public */
+/**
+ * Parameters for selecting a provider account mode by its wire value.
+ *
+ * @public
+ */
 export interface AccountModeParams {
   mode: string
 }
 
-/** @public */
+/**
+ * Parameters for selecting a provider account tier by its wire value.
+ *
+ * @public
+ */
 export interface AccountTypeParams {
   tier: string
 }
 
-/** @public */
+/**
+ * Parameters for moving an asset between provider DEX accounts.
+ *
+ * @public
+ */
 export interface SendAssetParams {
   /** Canonical `Asset.id` of the asset being moved (for Hyperliquid spot
    * assets, the token index as a string) — never a display symbol. */
@@ -327,7 +461,12 @@ export interface SendAssetParams {
   amount: string
 }
 
-/** @public */
+/**
+ * Parameters for cancelling all orders immediately or through a scheduled
+ * cancellation instruction.
+ *
+ * @public
+ */
 export interface CancelAllOrdersParams {
   /** 0=immediate (cancel GTC), 1=scheduled, 2=abort scheduled */
   timeInForce: number
@@ -335,7 +474,11 @@ export interface CancelAllOrdersParams {
   timestampMs?: number
 }
 
-/** @public */
+/**
+ * Parameters for registering a provider API key in a specific slot.
+ *
+ * @public
+ */
 export interface RegisterApiKeyParams {
   /** The API key slot index to register (0-255). Reusing a fixed slot overwrites the old key. */
   apiKeyIndex: number
@@ -348,7 +491,11 @@ export interface RegisterApiKeyParams {
   knownPublicKey?: string
 }
 
-/** @public */
+/**
+ * Parameters for approving a Lighter read-only token and its scope/expiry.
+ *
+ * @public
+ */
 export interface ApproveReadOnlyTokenParams {
   accountIndex: number
   /** Absolute unix-seconds expiry. Lighter requires lifetime between 1 day and 10 years. */
@@ -356,7 +503,12 @@ export interface ApproveReadOnlyTokenParams {
   scope: 'single' | 'all'
 }
 
-/** @public */
+/**
+ * Mapping from each {@link ActionType} to its action-specific parameter shape.
+ * `Record<string, never>` marks actions whose params object must be empty.
+ *
+ * @public
+ */
 export interface ActionParamsMap {
   [ActionType.APPROVE_AGENT]: ApproveAgentParams
   [ActionType.APPROVE_BUILDER_FEE]: Record<string, never>
@@ -385,7 +537,11 @@ export interface ActionParamsMap {
   [ActionType.META_ACCEPT_TERMS]: AcceptTermsParams
 }
 
-/** @public */
+/**
+ * Discriminated request sent to create unsigned steps for one action.
+ *
+ * @public
+ */
 export type CreateActionRequest = {
   [K in ActionType]: {
     provider: string
@@ -396,12 +552,20 @@ export type CreateActionRequest = {
   }
 }[ActionType]
 
-/** @public */
+/**
+ * Response containing the unsigned steps created for an action request.
+ *
+ * @public
+ */
 export interface CreateActionResponse {
   actions: ActionStep[]
 }
 
-/** @public */
+/**
+ * Discriminated request sent to execute signed steps for one action.
+ *
+ * @public
+ */
 export type ExecuteActionRequest = {
   [K in ActionType]: {
     provider: string
@@ -412,7 +576,11 @@ export type ExecuteActionRequest = {
   }
 }[ActionType]
 
-/** @public */
+/**
+ * Response containing per-action execution results.
+ *
+ * @public
+ */
 export interface ExecuteActionResponse {
   results: ActionResult[]
 }

package/src/asset.ts

@@ -56,15 +56,12 @@ export interface DepositAsset {
   address: Address
   /** ERC-20 decimals, used to scale deposit amounts. */
   decimals: number
-  /** Display ticker for UI labels; same semantics as {@link Asset.displaySymbol}. */
   displaySymbol: string
-  /** Token logo for UI; same semantics as {@link Asset.logoURI}. */
   logoURI: string
-  /** Optional longer display name; same semantics as {@link Asset.displayName}. */
   displayName?: string
 }
 
-/** @public */
+/** Response containing the provider's normalized asset registry. @public */
 export interface AssetsResponse {
   assets: Asset[]
 }

package/src/enums.ts

@@ -1,4 +1,8 @@
-/** @public */
+/**
+ * Numeric error codes returned by the perps API.
+ *
+ * @public
+ */
 export enum PerpsErrorCode {
   // Base errors (2000-2009)
   DefaultError = 2000,
@@ -36,13 +40,13 @@ export enum PerpsErrorCode {
   RouteNotFound = 2060,
 }
 
-/** @public */
+/** Side of an order or execution, using provider wire values. @public */
 export enum OrderSide {
   BUY = 'BUY',
   SELL = 'SELL',
 }
 
-/** @public */
+/** Supported regular and trigger order kinds, using provider wire values. @public */
 export enum OrderType {
   MARKET = 'MARKET',
   LIMIT = 'LIMIT',
@@ -53,19 +57,29 @@ export enum OrderType {
   TRIGGER_ONLY = 'TRIGGER_ONLY',
 }
 
-/** @public */
+/** Direction of an open position. @public */
 export enum PositionSide {
   LONG = 'LONG',
   SHORT = 'SHORT',
 }
 
-/** @public */
+/** Margin allocation mode for a position. @public */
 export enum MarginMode {
   ISOLATED = 'ISOLATED',
   CROSS = 'CROSS',
 }
 
-/** @public */
+/** Per-market support for changing an open position's dedicated margin. @public */
+export enum PositionMarginAdjustment {
+  /** The venue does not expose individual position margin. */
+  NONE = 'NONE',
+  /** Margin can be added but cannot be removed. */
+  ADD_ONLY = 'ADD_ONLY',
+  /** Margin can be added and removed. */
+  ADD_AND_REMOVE = 'ADD_AND_REMOVE',
+}
+
+/** Provider order time-in-force policies. @public */
 export enum TimeInForce {
   GTC = 'GTC',
   IOC = 'IOC',
@@ -73,7 +87,7 @@ export enum TimeInForce {
   GTT = 'GTT',
 }
 
-/** @public */
+/** Lifecycle status of a provider order. @public */
 export enum OrderStatus {
   PENDING = 'PENDING',
   OPEN = 'OPEN',
@@ -85,7 +99,7 @@ export enum OrderStatus {
   TRIGGERED = 'TRIGGERED',
 }
 
-/** @public */
+/** Lifecycle status of an execution/fill. @public */
 export enum FillStatus {
   FILLED = 'FILLED',
   PARTIALLY_FILLED = 'PARTIALLY_FILLED',
@@ -93,13 +107,18 @@ export enum FillStatus {
   REJECTED = 'REJECTED',
 }
 
-/** @public */
+/** Whether a fill supplied maker or taker liquidity. @public */
 export enum LiquidityRole {
   MAKER = 'maker',
   TAKER = 'taker',
 }
 
-/** @public */
+/**
+ * Action identifiers used in setup, create-action, and execute-action
+ * requests. Values are the backend wire strings.
+ *
+ * @public
+ */
 export enum ActionType {
   APPROVE_AGENT = 'approveAgent',
   APPROVE_BUILDER_FEE = 'approveBuilderFee',
@@ -131,26 +150,26 @@ export enum ActionType {
   META_ACCEPT_TERMS = 'metaAcceptTerms',
 }
 
-/** @public */
+/** Price relation that activates a trigger order. @public */
 export enum TriggerCondition {
   ABOVE = 'ABOVE',
   BELOW = 'BELOW',
 }
 
-/** @public */
+/** Take-profit or stop-loss trigger order classification. @public */
 export enum TriggerOrderType {
   TAKE_PROFIT = 'TAKE_PROFIT',
   STOP_LOSS = 'STOP_LOSS',
 }
 
-/** @public */
+/** Lifecycle status of a trigger order. @public */
 export enum TriggerOrderStatus {
   WAITING = 'WAITING',
   TRIGGERED = 'TRIGGERED',
   CANCELLED = 'CANCELLED',
 }
 
-/** @public */
+/** Account activity record categories. @public */
 export enum ActivityType {
   DEPOSIT = 'DEPOSIT',
   WITHDRAWAL = 'WITHDRAWAL',
@@ -159,7 +178,7 @@ export enum ActivityType {
   TRANSFER = 'TRANSFER',
 }
 
-/** @public */
+/** Human-readable classification of how a fill changed a position. @public */
 export enum FillClassification {
   OPENED_LONG = 'Opened Long',
   OPENED_SHORT = 'Opened Short',
@@ -175,24 +194,24 @@ export enum FillClassification {
   SPOT_SELL = 'Spot Sell',
 }
 
-/** @public */
+/** Classification emitted for a liquidation activity. @public */
 export enum LiquidationClassification {
   LIQUIDATED = 'Liquidated',
 }
 
-/** @public */
+/** Classification emitted for a funding activity. @public */
 export enum FundingClassification {
   FUNDING = 'Funding',
 }
 
-/** @public */
+/** Classification emitted for an inbound, outbound, or internal transfer. @public */
 export enum TransferClassification {
   DEPOSIT = 'Deposit',
   WITHDRAWAL = 'Withdrawal',
   TRANSFER = 'Transfer',
 }
 
-/** @public */
+/** Union of classifications emitted by all activity record categories. @public */
 export type ActivityClassification =
   | FillClassification
   | LiquidationClassification
@@ -213,7 +232,12 @@ export enum PerpsSigner {
   SDK = 'SDK',
 }
 
-/** @public */
+/**
+ * Signing mechanisms supported by action steps. Values are serialized in
+ * provider metadata and action responses.
+ *
+ * @public
+ */
 export enum SigningMethod {
   EIP712 = 'eip712',
   WASM_BLOB = 'wasmBlob',

package/src/errors.ts

@@ -1,6 +1,11 @@
 import type { PerpsErrorCode } from './enums.js'
 
-/** @public */
+/**
+ * Structured perps API error payload. `code` is the stable classification;
+ * `tool` identifies the backend tool when the provider supplies one.
+ *
+ * @public
+ */
 export interface PerpsErrorBody {
   code: PerpsErrorCode
   tool?: string