@lifi/perps-sdk 6.2.1 → 6.3.0

package/src/types/api.ts

@@ -243,6 +243,16 @@ export interface GetDepositFlowParams {
   address: Address
 }
 
+/**
+ * Parameters for {@link PerpsClient.getWithdrawableBalances}.
+ *
+ * @public
+ */
+export interface GetWithdrawableBalancesParams {
+  provider: string
+  address: Address
+}
+
 /**
  * Result from {@link PerpsClient.checkSetup}.
  *

package/src/types/provider.ts

@@ -33,6 +33,7 @@ import type {
   SDKRequestOptions,
 } from './config.js'
 import type { DepositFlow } from './deposit.js'
+import type { ProviderWithdrawableBalance } from './withdrawal.js'
 
 /**
  * Low-level SDK client: resolved config, the optional end-user wallet, and the
@@ -176,6 +177,15 @@ export interface ProviderGetDepositFlowParams {
   address: Address
 }
 
+/**
+ * Read params for {@link PerpsProviderPlugin.getWithdrawableBalances}.
+ *
+ * @public
+ */
+export interface ProviderGetWithdrawableBalancesParams {
+  address: Address
+}
+
 /**
  * Read params for {@link PerpsProvider.getPositions}.
  *
@@ -377,6 +387,21 @@ export interface PerpsProviderPlugin {
     options?: SDKRequestOptions
   ): Promise<DepositFlow>
 
+  /**
+   * The `(asset, route)` pairs `params.address` currently has something to
+   * withdraw from, keyed by provider-native asset id. Only the venue knows how
+   * its balance payload splits across routes, so the split is owned here; the
+   * per-asset venue minimum is applied by `PerpsClient.getWithdrawableBalances`,
+   * which holds the core asset registry.
+   *
+   * Optional: a provider whose withdrawals are not a per-route selection omits
+   * it, and `PerpsClient.getWithdrawableBalances` then resolves `undefined`.
+   */
+  getWithdrawableBalances?(
+    params: ProviderGetWithdrawableBalancesParams,
+    options?: SDKRequestOptions
+  ): Promise<ProviderWithdrawableBalance[]>
+
   getPositions(
     params: ProviderGetPositionsParams,
     options?: SDKRequestOptions

package/src/types/withdrawal.ts

@@ -0,0 +1,39 @@
+import type { Asset } from '@lifi/perps-types'
+
+/**
+ * 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'
+
+/**
+ * One withdrawable `(asset, route)` selection as the provider reports it, keyed
+ * by provider-native asset id and awaiting the core asset-metadata join.
+ *
+ * @public
+ */
+export interface ProviderWithdrawableBalance {
+  /** Provider-native `Asset.id`; never a display symbol. */
+  assetId: string
+  route: WithdrawalRoute
+  /** Withdrawable amount in the asset's own units. Always greater than zero. */
+  available: string
+}
+
+/**
+ * One withdrawable `(asset, route)` selection a caller can act on: the amount
+ * clears the asset's venue minimum, and `asset` carries the precision and
+ * minimum needed to scale and validate the withdrawal.
+ *
+ * @public
+ */
+export interface WithdrawableBalance {
+  asset: Asset
+  route: WithdrawalRoute
+  /** Withdrawable amount in the asset's own units. */
+  available: string
+}

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '6.2.1'
+export const version = '6.3.0'