@lifi/perps-types 0.1.1-alpha.2 → 0.1.1-alpha.22

package/src/account.ts

@@ -1,6 +1,9 @@
 import type { Address } from './typedData.js'
+import type { AssetDisplay } from './asset.js'
 import type {
-  HistoryItemStatus,
+  ActivityType,
+  FillClassification,
+  FillStatus,
   MarginMode,
   OrderSide,
   OrderType,
@@ -13,9 +16,7 @@ export interface FeeTier {
 }
 
 export interface Position {
-  symbol: string
-  assetId: number
-  dex: string
+  asset: AssetDisplay
   side: PositionSide
   size: string
   entryPrice: string
@@ -29,15 +30,14 @@ export interface Position {
 
 export interface OpenOrder {
   id: string
-  symbol: string
-  assetId: number
-  dex: string
+  asset: AssetDisplay
   side: OrderSide
   type: OrderType
   size: string
   price: string
   filledSize: string
   reduceOnly: boolean
+  label?: string
   createdAt: string
 }
 
@@ -47,30 +47,52 @@ export interface Balance {
 }
 
 export interface AccountResponse {
-  dex: string
+  provider: string
   address: Address
-  balances: Balance[]
+  balances: Record<string, Balance[]>
   marginUsed: string
   unrealizedPnl: string
   feeTier: FeeTier
+  config: Record<string, unknown>
+}
+
+export interface TriggerOrder {
+  id: string
+  asset: AssetDisplay
+  type: OrderType
+  size: string
+  triggerPrice: string
+  limitPrice?: string
+  label?: string
+  createdAt: string
+}
+
+export interface PositionsResponse {
+  provider: string
   positions: Position[]
+  pagination: Pagination
+}
+
+export interface OrdersResponse {
+  provider: string
   openOrders: OpenOrder[]
-  config: Record<string, unknown>
+  triggerOrders: TriggerOrder[]
+  pagination: Pagination
 }
 
-export interface HistoryItem {
+export interface Fill {
   id: string
-  symbol: string
-  assetId: number
-  dex: string
+  asset: AssetDisplay
   side: OrderSide
   type: OrderType
   size: string
   price: string
-  status: HistoryItemStatus
+  status: FillStatus
   filledSize?: string
   fee?: string
   realizedPnl?: string | null
+  startPosition?: string
+  classification: FillClassification
   createdAt: string
 }
 
@@ -81,8 +103,62 @@ export interface Pagination {
   nextUrl?: string
 }
 
-export interface HistoryResponse {
-  dex: string
-  items: HistoryItem[]
+export interface FillsResponse {
+  provider: string
+  items: Fill[]
+  pagination: Pagination
+}
+
+// ---------------------------------------------------------------------------
+// Activities
+// ---------------------------------------------------------------------------
+
+export interface BaseActivity {
+  id: string
+  provider: string
+  timestamp: string
+}
+
+export interface DepositActivity extends BaseActivity {
+  type: ActivityType.DEPOSIT
+  amount: string
+}
+
+export interface WithdrawalActivity extends BaseActivity {
+  type: ActivityType.WITHDRAWAL
+  amount: string
+  fee: string
+}
+
+export interface LiquidatedPosition {
+  asset: AssetDisplay
+  size: string
+}
+
+export interface LiquidationActivity extends BaseActivity {
+  type: ActivityType.LIQUIDATION
+  liquidatedNotionalPosition: string
+  accountValue: string
+  leverageType: string
+  liquidatedPositions: LiquidatedPosition[]
+}
+
+export interface FundingActivity extends BaseActivity {
+  type: ActivityType.FUNDING
+  asset: AssetDisplay
+  amount: string
+  positionSize: string
+  fundingRate: string
+}
+
+export type ActivityItem =
+  | DepositActivity
+  | WithdrawalActivity
+  | LiquidationActivity
+  | FundingActivity
+
+export interface ActivitiesResponse {
+  provider: string
+  items: ActivityItem[]
   pagination: Pagination
 }

package/src/action.ts

@@ -0,0 +1,246 @@
+import type { OrderType } from './enums.js'
+import {
+  type ActionType,
+  type OrderSide,
+  type OrderStatus,
+  type TimeInForce,
+  type TriggerCondition,
+} from './enums.js'
+import type { Address, Hex, PerpsTypedData } from './typedData.js'
+import type { AssetIdentity, AssetDisplay } from './asset.js'
+
+// ---------------------------------------------------------------------------
+// Action step types (create → sign → execute flow)
+//
+// Union by structural shape — the SDK knows which variant to expect based
+// on the provider's `signingMethod` from the /providers response.
+//
+//   Eip712    – Hyperliquid and future EVM dexes (EIP-712 typed data + ECDSA sig)
+//   WasmBlob  – Lighter and zk-rollup dexes (WASM signer → {txType, txInfo, txHash})
+//   EvmTx     – plain EVM transaction (reserved for future use)
+// ---------------------------------------------------------------------------
+
+export interface Eip712ActionStep {
+  action: ActionType
+  typedData: PerpsTypedData
+}
+
+export interface WasmBlobActionStep {
+  action: ActionType
+  wasmSignParams: Record<string, unknown>
+}
+
+export interface EvmTxActionStep {
+  action: ActionType
+  txParams: Record<string, unknown>
+}
+
+export type ActionStep = Eip712ActionStep | WasmBlobActionStep | EvmTxActionStep
+
+export interface Eip712SignedActionStep {
+  action: ActionType
+  typedData: PerpsTypedData
+  signature: Hex
+}
+
+export interface WasmBlobSignedActionStep {
+  action: ActionType
+  wasmSignParams: Record<string, unknown>
+  signedTx: {
+    txType: number
+    txInfo: string
+    txHash: string
+  }
+}
+
+export interface EvmTxSignedActionStep {
+  action: ActionType
+  txParams: Record<string, unknown>
+  txHash: string
+}
+
+export type SignedActionStep =
+  | Eip712SignedActionStep
+  | WasmBlobSignedActionStep
+  | EvmTxSignedActionStep
+
+export interface ActionResult {
+  action: ActionType
+  success: boolean
+  orderId?: string
+  error?: string
+}
+
+// ---------------------------------------------------------------------------
+// Shared data types
+// ---------------------------------------------------------------------------
+
+export interface TriggerOrderInput {
+  triggerPrice: string
+  limitPrice?: string
+}
+
+export interface ModifyOrderInput {
+  id: string
+  price?: string
+  size?: string
+  triggerPrice?: string
+  limitPrice?: string
+}
+
+export interface Order {
+  orderId: string
+  asset: AssetDisplay
+  side: OrderSide
+  type: OrderType
+  price?: string
+  originalSize: string
+  remainingSize: string
+  filledSize: string
+  timeInForce?: TimeInForce
+  expiresAt?: string
+  reduceOnly?: boolean
+  isTrigger?: boolean
+  triggerPrice?: string
+  triggerCondition?: TriggerCondition
+  status: OrderStatus
+  averagePrice?: string
+  createdAt: string
+  updatedAt: string
+}
+
+// ---------------------------------------------------------------------------
+// Per-action param types
+// ---------------------------------------------------------------------------
+
+export interface PlaceOrderParams {
+  asset: AssetIdentity
+  side: OrderSide
+  type?: OrderType
+  size: string
+  price?: string
+  leverage?: number
+  reduceOnly?: boolean
+  timeInForce?: TimeInForce
+  expiresAt?: string
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
+export interface PlaceTriggerOrderParams {
+  asset: AssetIdentity
+  side: OrderSide
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
+export interface CancelOrderParams {
+  ids: string[]
+}
+
+export interface ModifyOrderParams {
+  modifications: ModifyOrderInput[]
+}
+
+export interface UpdateLeverageParams {
+  asset: AssetIdentity
+  leverage: number
+}
+
+export interface UpdatePositionMarginParams {
+  asset: AssetIdentity
+  action: 'add' | 'remove'
+  amount: string
+}
+
+export interface WithdrawalParams {
+  destination: Address
+  amount: string
+}
+
+export interface DepositParams {
+  /** Amount of the token to deposit (human-readable, e.g. "100.5"). */
+  amount: string
+  /** ERC-20 token address on the source chain. */
+  tokenAddress: Address
+  /** Chain ID of the source chain (e.g. 1 for Ethereum, 42161 for Arbitrum). */
+  chainId: number
+}
+
+export interface ApproveAgentParams {
+  agentAddress: string
+  agentTtlMs?: number
+}
+
+export interface SetAbstractionParams {
+  abstraction?: string
+}
+
+export interface SendAssetParams {
+  collateral: string
+  sourceDex: string
+  destinationDex: string
+  amount: string
+}
+
+// ---------------------------------------------------------------------------
+// ActionParamsMap — compile-time type resolution for SDK
+// ---------------------------------------------------------------------------
+
+export interface CancelAllOrdersParams {
+  /** 0=immediate (cancel GTC), 1=scheduled, 2=abort scheduled */
+  timeInForce: number
+  /** Unix timestamp in milliseconds (required for scheduled cancels) */
+  timestampMs?: number
+}
+
+export interface RegisterApiKeyParams {
+  /** The API key slot index to register (0-255). Reusing a fixed slot overwrites the old key. */
+  apiKeyIndex: number
+}
+
+export interface ActionParamsMap {
+  [ActionType.APPROVE_AGENT]: ApproveAgentParams
+  [ActionType.APPROVE_BUILDER_FEE]: Record<string, never>
+  [ActionType.USER_SET_ABSTRACTION]: SetAbstractionParams
+  [ActionType.AGENT_SET_ABSTRACTION]: SetAbstractionParams
+  [ActionType.SEND_ASSET]: SendAssetParams
+  [ActionType.WITHDRAWAL]: WithdrawalParams
+  [ActionType.PLACE_ORDER]: PlaceOrderParams
+  [ActionType.PLACE_TRIGGER_ORDER]: PlaceTriggerOrderParams
+  [ActionType.CANCEL_ORDER]: CancelOrderParams
+  [ActionType.CANCEL_ALL_ORDERS]: CancelAllOrdersParams
+  [ActionType.MODIFY_ORDER]: ModifyOrderParams
+  [ActionType.UPDATE_LEVERAGE]: UpdateLeverageParams
+  [ActionType.UPDATE_POSITION_MARGIN]: UpdatePositionMarginParams
+  [ActionType.REGISTER_API_KEY]: RegisterApiKeyParams
+  [ActionType.DEPOSIT]: DepositParams
+}
+
+// ---------------------------------------------------------------------------
+// Request / Response types
+// ---------------------------------------------------------------------------
+
+export interface CreateActionRequest {
+  provider: string
+  address: Address
+  signerAddress?: Address
+  action: ActionType
+  params: ActionParamsMap[ActionType]
+}
+
+export interface CreateActionResponse {
+  actions: ActionStep[]
+}
+
+export interface ExecuteActionRequest {
+  provider: string
+  address: Address
+  signerAddress?: Address
+  action: ActionType
+  actions: SignedActionStep[]
+}
+
+export interface ExecuteActionResponse {
+  results: ActionResult[]
+}

package/src/asset.ts

@@ -0,0 +1,88 @@
+export interface FundingInfo {
+  rate: string
+  nextFundingTime: number
+}
+
+export interface AssetIdentity {
+  assetId: string // provider's canonical identity: "BTC", "xyz:PURR", "@142"
+  market: string // market category from /providers.markets: "hyperliquid", "xyz", "spot"
+}
+
+export interface Asset extends AssetIdentity {
+  displaySymbol: string // UI base name: "BTC", "PURR"; spot keeps full pair: "PURR/USDC"
+  displayQuote: string | null // quote asset for perps: "USDC", "USDH"; null for spot
+  displayName?: string // future: "Bitcoin", "Ethereum"
+  logoURI: string
+  szDecimals: number
+  maxLeverage: number
+  onlyIsolated: boolean
+  isMarginCollateral?: boolean
+  funding: FundingInfo
+  openInterest?: string
+  volume24h?: string
+  prevDayPrice?: string
+  markPrice: string
+}
+
+export type AssetDisplay = Pick<
+  Asset,
+  'assetId' | 'market' | 'displaySymbol' | 'displayQuote'
+>
+
+export interface AssetPrice {
+  assetId: string
+  price: string
+}
+
+export interface AssetsResponse {
+  assets: Asset[]
+}
+
+export interface PricesResponse {
+  prices: AssetPrice[]
+}
+
+export interface Candle {
+  t: number
+  o: string
+  h: string
+  l: string
+  c: string
+  v: string
+}
+
+export interface OhlcvResponse {
+  provider: string
+  assetId: string
+  interval: string
+  candles: Candle[]
+}
+
+export type OhlcvInterval =
+  | '1m'
+  | '3m'
+  | '5m'
+  | '15m'
+  | '30m'
+  | '1h'
+  | '2h'
+  | '4h'
+  | '8h'
+  | '12h'
+  | '1d'
+  | '3d'
+  | '1w'
+  | '1M'
+
+export interface OrderbookLevel {
+  price: string
+  size: string
+}
+
+export interface OrderbookResponse {
+  provider: string
+  assetId: string
+  bids: OrderbookLevel[]
+  asks: OrderbookLevel[]
+  timestamp: number
+}

package/src/enums.ts

@@ -5,6 +5,7 @@ export enum PerpsErrorCode {
   ValidationError = 2002,
   TimeoutError = 2003,
   ThirdPartyError = 2004,
+  SDKError = 2005,
 
   // Auth errors (2010-2019)
   SignatureInvalid = 2010,
@@ -38,6 +39,11 @@ export enum OrderSide {
 export enum OrderType {
   MARKET = 'MARKET',
   LIMIT = 'LIMIT',
+  STOP_MARKET = 'STOP_MARKET',
+  STOP_LIMIT = 'STOP_LIMIT',
+  TAKE_PROFIT_MARKET = 'TAKE_PROFIT_MARKET',
+  TAKE_PROFIT_LIMIT = 'TAKE_PROFIT_LIMIT',
+  TRIGGER_ONLY = 'TRIGGER_ONLY',
 }
 
 export enum PositionSide {
@@ -68,18 +74,29 @@ export enum OrderStatus {
   TRIGGERED = 'TRIGGERED',
 }
 
-export enum HistoryItemStatus {
+export enum FillStatus {
   FILLED = 'FILLED',
   PARTIALLY_FILLED = 'PARTIALLY_FILLED',
   CANCELLED = 'CANCELLED',
   REJECTED = 'REJECTED',
 }
 
-export enum OrderActionType {
-  UPDATE_LEVERAGE = 'updateLeverage',
+export enum ActionType {
+  APPROVE_AGENT = 'approveAgent',
+  APPROVE_BUILDER_FEE = 'approveBuilderFee',
+  USER_SET_ABSTRACTION = 'userSetAbstraction',
+  AGENT_SET_ABSTRACTION = 'agentSetAbstraction',
+  SEND_ASSET = 'sendAsset',
+  WITHDRAWAL = 'withdrawal',
   PLACE_ORDER = 'placeOrder',
   PLACE_TRIGGER_ORDER = 'placeTriggerOrder',
   CANCEL_ORDER = 'cancelOrder',
+  CANCEL_ALL_ORDERS = 'cancelAllOrders',
+  MODIFY_ORDER = 'modifyOrder',
+  UPDATE_LEVERAGE = 'updateLeverage',
+  UPDATE_POSITION_MARGIN = 'updatePositionMargin',
+  REGISTER_API_KEY = 'registerApiKey',
+  DEPOSIT = 'deposit',
 }
 
 export enum TriggerCondition {
@@ -97,3 +114,55 @@ export enum TriggerOrderStatus {
   TRIGGERED = 'TRIGGERED',
   CANCELLED = 'CANCELLED',
 }
+
+export enum ActivityType {
+  DEPOSIT = 'DEPOSIT',
+  WITHDRAWAL = 'WITHDRAWAL',
+  LIQUIDATION = 'LIQUIDATION',
+  FUNDING = 'FUNDING',
+}
+
+export enum FillClassification {
+  OPENED_LONG = 'Opened Long',
+  OPENED_SHORT = 'Opened Short',
+  INCREASED_LONG = 'Increased Long',
+  INCREASED_SHORT = 'Increased Short',
+  REDUCED_LONG = 'Reduced Long',
+  REDUCED_SHORT = 'Reduced Short',
+  CLOSED_LONG = 'Closed Long',
+  CLOSED_SHORT = 'Closed Short',
+  SWITCHED_LONG = 'Switched Long',
+  SWITCHED_SHORT = 'Switched Short',
+  SPOT_BUY = 'Spot Buy',
+  SPOT_SELL = 'Spot Sell',
+}
+
+export enum LiquidationClassification {
+  LIQUIDATED = 'Liquidated',
+}
+
+export enum FundingClassification {
+  FUNDING = 'Funding',
+}
+
+export enum TransferClassification {
+  DEPOSIT = 'Deposit',
+  WITHDRAWAL = 'Withdrawal',
+}
+
+export type ActivityClassification =
+  | FillClassification
+  | LiquidationClassification
+  | FundingClassification
+  | TransferClassification
+
+export enum PerpsSigner {
+  USER = 'USER',
+  AGENT = 'AGENT',
+}
+
+export enum SigningMethod {
+  EIP712 = 'eip712',
+  WASM_BLOB = 'wasmBlob',
+  EVM_TX = 'evmTx',
+}

package/src/index.ts

@@ -1,9 +1,8 @@
 export * from './typedData.js'
 export * from './enums.js'
-export * from './market.js'
-export * from './authorization.js'
+export * from './providers.js'
+export * from './asset.js'
+export * from './action.js'
 export * from './account.js'
-export * from './trading.js'
-export * from './withdrawal.js'
 export * from './errors.js'
 export * from './subscriptions.js'

package/src/providers/hyperliquid/assetId.ts

@@ -1,26 +1,32 @@
+/** Spot asset IDs use the @pairIndex format (e.g. "@230"). */
+export const assetIsSpot = (assetId: string): boolean => assetId.startsWith('@')
+
 /**
- * Calculate the asset ID for a given DEX index and asset index.
+ * Calculate the asset ID for a given provider index and asset index.
  *
- * Main DEX (dex = ''): assetId = indexInDex
- * HIP-3 DEXes (dex = 'xyz'): assetId = 100_000 + perpDexIndex * 10_000 + indexInDex
+ * Main provider (provider = ''): assetId = indexInProvider
+ * HIP-3 providers (provider = 'xyz'): assetId = 100_000 + perpDexIndex * 10_000 + indexInProvider
  */
 export const calculateAssetId = (
-  dexIndex: number,
-  indexInDex: number
+  providerIndex: number,
+  indexInProvider: number
 ): number => {
-  if (dexIndex === 0) {
-    return indexInDex
+  if (providerIndex === 0) {
+    return indexInProvider
   }
-  return 100_000 + dexIndex * 10_000 + indexInDex
+  return 100_000 + providerIndex * 10_000 + indexInProvider
 }
 
 /**
- * Get the DEX index from the given list of dex names.
+ * Get the provider index from the given list of provider names.
  */
-export const getDexIndex = (dex: string, dexNames: string[]): number => {
-  const index = dexNames.indexOf(dex)
+export const getProviderIndex = (
+  provider: string,
+  providerNames: string[]
+): number => {
+  const index = providerNames.indexOf(provider)
   if (index === -1) {
-    throw new Error(`Unknown sub-dex: ${dex}`)
+    throw new Error(`Unknown sub-provider: ${provider}`)
   }
   return index
 }