@lifi/perps-sdk 4.4.2 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/dist/cjs/client/PerpsClient.d.ts +10 -2
  2. package/dist/cjs/client/PerpsClient.d.ts.map +1 -1
  3. package/dist/cjs/client/PerpsClient.js +14 -0
  4. package/dist/cjs/client/PerpsClient.js.map +1 -1
  5. package/dist/cjs/index.d.ts +10 -6
  6. package/dist/cjs/index.d.ts.map +1 -1
  7. package/dist/cjs/index.js +16 -7
  8. package/dist/cjs/index.js.map +1 -1
  9. package/dist/cjs/registry/marketRegistry.d.ts +2 -1
  10. package/dist/cjs/registry/marketRegistry.d.ts.map +1 -1
  11. package/dist/cjs/registry/marketRegistry.js +24 -1
  12. package/dist/cjs/registry/marketRegistry.js.map +1 -1
  13. package/dist/cjs/services/getGasRecommendation.d.ts +9 -0
  14. package/dist/cjs/services/getGasRecommendation.d.ts.map +1 -0
  15. package/dist/cjs/services/getGasRecommendation.js +10 -0
  16. package/dist/cjs/services/getGasRecommendation.js.map +1 -0
  17. package/dist/cjs/types/api.d.ts +6 -1
  18. package/dist/cjs/types/api.d.ts.map +1 -1
  19. package/dist/cjs/types/deposit.d.ts +25 -0
  20. package/dist/cjs/types/deposit.d.ts.map +1 -0
  21. package/dist/cjs/types/deposit.js +3 -0
  22. package/dist/cjs/types/deposit.js.map +1 -0
  23. package/dist/cjs/types/provider.d.ts +12 -1
  24. package/dist/cjs/types/provider.d.ts.map +1 -1
  25. package/dist/cjs/utils/calculations.d.ts +0 -5
  26. package/dist/cjs/utils/calculations.d.ts.map +1 -1
  27. package/dist/cjs/utils/calculations.js +0 -9
  28. package/dist/cjs/utils/calculations.js.map +1 -1
  29. package/dist/cjs/utils/depositAssets.d.ts +8 -0
  30. package/dist/cjs/utils/depositAssets.d.ts.map +1 -0
  31. package/dist/cjs/utils/depositAssets.js +36 -0
  32. package/dist/cjs/utils/depositAssets.js.map +1 -0
  33. package/dist/cjs/utils/transferMargin.d.ts +7 -0
  34. package/dist/cjs/utils/transferMargin.d.ts.map +1 -0
  35. package/dist/cjs/utils/transferMargin.js +52 -0
  36. package/dist/cjs/utils/transferMargin.js.map +1 -0
  37. package/dist/cjs/version.d.ts +1 -1
  38. package/dist/cjs/version.js +1 -1
  39. package/dist/esm/client/PerpsClient.d.ts +35 -2
  40. package/dist/esm/client/PerpsClient.d.ts.map +1 -1
  41. package/dist/esm/client/PerpsClient.js +39 -0
  42. package/dist/esm/client/PerpsClient.js.map +1 -1
  43. package/dist/esm/index.d.ts +11 -7
  44. package/dist/esm/index.d.ts.map +1 -1
  45. package/dist/esm/index.js +6 -4
  46. package/dist/esm/index.js.map +1 -1
  47. package/dist/esm/registry/marketRegistry.d.ts +9 -1
  48. package/dist/esm/registry/marketRegistry.d.ts.map +1 -1
  49. package/dist/esm/registry/marketRegistry.js +30 -1
  50. package/dist/esm/registry/marketRegistry.js.map +1 -1
  51. package/dist/esm/services/getGasRecommendation.d.ts +31 -0
  52. package/dist/esm/services/getGasRecommendation.d.ts.map +1 -0
  53. package/dist/esm/services/getGasRecommendation.js +22 -0
  54. package/dist/esm/services/getGasRecommendation.js.map +1 -0
  55. package/dist/esm/types/api.d.ts +16 -1
  56. package/dist/esm/types/api.d.ts.map +1 -1
  57. package/dist/esm/types/deposit.d.ts +68 -0
  58. package/dist/esm/types/deposit.d.ts.map +1 -0
  59. package/dist/esm/types/deposit.js +2 -0
  60. package/dist/esm/types/deposit.js.map +1 -0
  61. package/dist/esm/types/provider.d.ts +48 -1
  62. package/dist/esm/types/provider.d.ts.map +1 -1
  63. package/dist/esm/utils/calculations.d.ts +0 -20
  64. package/dist/esm/utils/calculations.d.ts.map +1 -1
  65. package/dist/esm/utils/calculations.js +0 -23
  66. package/dist/esm/utils/calculations.js.map +1 -1
  67. package/dist/esm/utils/depositAssets.d.ts +46 -0
  68. package/dist/esm/utils/depositAssets.d.ts.map +1 -0
  69. package/dist/esm/utils/depositAssets.js +71 -0
  70. package/dist/esm/utils/depositAssets.js.map +1 -0
  71. package/dist/esm/utils/transferMargin.d.ts +24 -0
  72. package/dist/esm/utils/transferMargin.d.ts.map +1 -0
  73. package/dist/esm/utils/transferMargin.js +58 -0
  74. package/dist/esm/utils/transferMargin.js.map +1 -0
  75. package/dist/esm/version.d.ts +1 -1
  76. package/dist/esm/version.js +1 -1
  77. package/dist/types/client/PerpsClient.d.ts +35 -2
  78. package/dist/types/client/PerpsClient.d.ts.map +1 -1
  79. package/dist/types/index.d.ts +11 -7
  80. package/dist/types/index.d.ts.map +1 -1
  81. package/dist/types/registry/marketRegistry.d.ts +9 -1
  82. package/dist/types/registry/marketRegistry.d.ts.map +1 -1
  83. package/dist/types/services/getGasRecommendation.d.ts +31 -0
  84. package/dist/types/services/getGasRecommendation.d.ts.map +1 -0
  85. package/dist/types/types/api.d.ts +16 -1
  86. package/dist/types/types/api.d.ts.map +1 -1
  87. package/dist/types/types/deposit.d.ts +68 -0
  88. package/dist/types/types/deposit.d.ts.map +1 -0
  89. package/dist/types/types/provider.d.ts +48 -1
  90. package/dist/types/types/provider.d.ts.map +1 -1
  91. package/dist/types/utils/calculations.d.ts +0 -20
  92. package/dist/types/utils/calculations.d.ts.map +1 -1
  93. package/dist/types/utils/depositAssets.d.ts +46 -0
  94. package/dist/types/utils/depositAssets.d.ts.map +1 -0
  95. package/dist/types/utils/transferMargin.d.ts +24 -0
  96. package/dist/types/utils/transferMargin.d.ts.map +1 -0
  97. package/dist/types/version.d.ts +1 -1
  98. package/package.json +2 -2
  99. package/src/client/PerpsClient.ts +56 -0
  100. package/src/index.ts +26 -6
  101. package/src/registry/marketRegistry.ts +45 -2
  102. package/src/services/getGasRecommendation.ts +45 -0
  103. package/src/types/api.ts +17 -0
  104. package/src/types/deposit.ts +75 -0
  105. package/src/types/provider.ts +63 -0
  106. package/src/utils/calculations.ts +0 -28
  107. package/src/utils/depositAssets.ts +77 -0
  108. package/src/utils/transferMargin.ts +103 -0
  109. package/src/version.ts +1 -1
  110. package/dist/cjs/utils/depositChain.d.ts +0 -6
  111. package/dist/cjs/utils/depositChain.d.ts.map +0 -1
  112. package/dist/cjs/utils/depositChain.js +0 -14
  113. package/dist/cjs/utils/depositChain.js.map +0 -1
  114. package/dist/esm/utils/depositChain.d.ts +0 -27
  115. package/dist/esm/utils/depositChain.d.ts.map +0 -1
  116. package/dist/esm/utils/depositChain.js +0 -24
  117. package/dist/esm/utils/depositChain.js.map +0 -1
  118. package/dist/types/utils/depositChain.d.ts +0 -27
  119. package/dist/types/utils/depositChain.d.ts.map +0 -1
  120. package/src/utils/depositChain.ts +0 -39
@@ -0,0 +1 @@
1
+ {"version":3,"file":"depositAssets.d.ts","sourceRoot":"","sources":["../../../src/utils/depositAssets.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,oBAI3B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,oBAIjC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,oBAI9B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,oBAI1B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,oBAI5B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,oBAIlC,CAAA"}
@@ -0,0 +1,24 @@
1
+ import { type Position, type PositionMarginConstraints } from '@lifi/perps-types';
2
+ /**
3
+ * Exact inputs for {@link removableIsolatedMargin}.
4
+ *
5
+ * @public
6
+ */
7
+ export interface RemovableIsolatedMarginParams {
8
+ position: Position;
9
+ constraints: PositionMarginConstraints;
10
+ }
11
+ /**
12
+ * Calculate margin that can be removed from an isolated position using the
13
+ * provider's exact retained-margin requirement. Position equity is allocated
14
+ * margin plus unrealized PnL.
15
+ *
16
+ * The result snaps down to the provider's accepted amount increment. Markets
17
+ * that are add-only and cross-margined positions return `'0'`.
18
+ *
19
+ * @throws {PerpsError} `ValidationError` for malformed, non-positive, or
20
+ * inconsistent risk inputs.
21
+ * @public
22
+ */
23
+ export declare function removableIsolatedMargin({ position, constraints, }: RemovableIsolatedMarginParams): string;
24
+ //# sourceMappingURL=transferMargin.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"transferMargin.d.ts","sourceRoot":"","sources":["../../../src/utils/transferMargin.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EAEb,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAA;AAoC1B;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,QAAQ,CAAA;IAClB,WAAW,EAAE,yBAAyB,CAAA;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,QAAQ,EACR,WAAW,GACZ,EAAE,6BAA6B,GAAG,MAAM,CAmCxC"}
@@ -1,3 +1,3 @@
1
1
  export declare const name = "@lifi/perps-sdk";
2
- export declare const version = "4.4.2";
2
+ export declare const version = "6.0.0";
3
3
  //# sourceMappingURL=version.d.ts.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/perps-sdk",
3
- "version": "4.4.2",
3
+ "version": "6.0.0",
4
4
  "description": "LI.FI Perps SDK for perpetuals trading",
5
5
  "homepage": "https://github.com/lifinance/perps-sdk",
6
6
  "bugs": {
@@ -45,7 +45,7 @@
45
45
  "big.js": "^7.0.1",
46
46
  "partysocket": "^1.1.19",
47
47
  "viem": "^2.48.8",
48
- "@lifi/perps-types": "^3.3.1"
48
+ "@lifi/perps-types": "^4.0.0"
49
49
  },
50
50
  "publishConfig": {
51
51
  "access": "public"
@@ -7,7 +7,9 @@ import type {
7
7
  CreateActionResponse,
8
8
  ExecuteActionResponse,
9
9
  MarketRef,
10
+ MarketSettings,
10
11
  Position,
12
+ PositionMarginConstraints,
11
13
  Provider,
12
14
  ProviderAction,
13
15
  SignedActionStep,
@@ -30,6 +32,7 @@ import type {
30
32
  ExecuteProviderSetupParams,
31
33
  ExecuteProviderSetupResult,
32
34
  GetAccountResult,
35
+ GetDepositFlowParams,
33
36
  GetSetupParams,
34
37
  ModifyOrdersParams,
35
38
  PerpsClientOptions,
@@ -40,6 +43,7 @@ import type {
40
43
  WithdrawParams,
41
44
  } from '../types/api.js'
42
45
  import type { PerpsClientSigner, SwitchChainHook } from '../types/config.js'
46
+ import type { DepositFlow } from '../types/deposit.js'
43
47
  import type {
44
48
  ActionSignerContribution,
45
49
  PerpsProvider,
@@ -383,6 +387,41 @@ export class PerpsClient {
383
387
  return { ...response, settings }
384
388
  }
385
389
 
390
+ /**
391
+ * The user's current venue-side settings for a market — the margin mode
392
+ * and leverage the next order on it will use. Resolves `undefined` when
393
+ * the venue exposes no readable setting for the market (or the provider
394
+ * has no such read at all).
395
+ *
396
+ * @throws {PerpsError} When the provider plugin is not registered.
397
+ * @public
398
+ */
399
+ async getMarketSettings(params: {
400
+ provider: string
401
+ address: Address
402
+ market: MarketRef
403
+ }): Promise<MarketSettings | undefined> {
404
+ const plugin = this.requireProvider(params.provider)
405
+ return plugin.getMarketSettings?.({
406
+ address: params.address,
407
+ market: params.market,
408
+ })
409
+ }
410
+
411
+ /**
412
+ * Resolve the exact venue-owned margin requirements for `position`.
413
+ * Returns `undefined` when the position has no individual margin adjustment.
414
+ *
415
+ * @public
416
+ */
417
+ getPositionMarginConstraints(
418
+ position: Position
419
+ ): PositionMarginConstraints | undefined {
420
+ return this.requireProvider(
421
+ position.market.providerId
422
+ ).positionMarginConstraints(position)
423
+ }
424
+
386
425
  /**
387
426
  * Roll an already-fetched {@link AccountResponse} (plus its positions) up
388
427
  * into an {@link AccountSummary}, delegating to the owning provider so the
@@ -412,6 +451,23 @@ export class PerpsClient {
412
451
  return this.requireProvider(provider).accountExists({ address })
413
452
  }
414
453
 
454
+ /**
455
+ * The deposit flow for `params.address` at `params.provider`, delegated to the
456
+ * provider plugin — every deposit decision (the collateral destination, the
457
+ * account-opening pipeline, an outstanding setup gate) is venue-owned.
458
+ *
459
+ * @returns `undefined` when the registered plugin declares no deposit flow.
460
+ * @throws {PerpsError} When the provider plugin is not registered, or the
461
+ * plugin's flow resolution fails.
462
+ * @public
463
+ */
464
+ async getDepositFlow(
465
+ params: GetDepositFlowParams
466
+ ): Promise<DepositFlow | undefined> {
467
+ const plugin = this.requireProvider(params.provider)
468
+ return plugin.getDepositFlow?.({ address: params.address })
469
+ }
470
+
415
471
  /**
416
472
  * Return the unsatisfied entries on `Provider.setup` for this account as a
417
473
  * flat, self-describing list. Trading is gated on `isReady === true`.
package/src/index.ts CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  /**
5
5
  * `@lifi/perps-sdk` — the public entry point. Exports `createPerpsClient` and
6
- * `PerpsClient` (the primary API), the realtime `PerpsWsClient`, the pure
6
+ * `PerpsClient` (the primary API), the WebSocket `PerpsWsClient`, the pure
7
7
  * calculation/parsing/order helpers, and re-exports the shared `@lifi/perps-types`.
8
8
  *
9
9
  * @packageDocumentation
@@ -25,6 +25,7 @@ export {
25
25
  isActiveMarket,
26
26
  MarketRegistry,
27
27
  toMarketDisplay,
28
+ toPerpsMarketDisplay,
28
29
  } from './registry/marketRegistry.js'
29
30
  // Services
30
31
  export type { CreateActionParams } from './services/createAction.js'
@@ -39,6 +40,11 @@ export type { GetAssetsParams } from './services/getAssets.js'
39
40
  export { getAssets } from './services/getAssets.js'
40
41
  export type { GetFillsParams } from './services/getFills.js'
41
42
  export { getFills } from './services/getFills.js'
43
+ export type { GetGasRecommendationParams } from './services/getGasRecommendation.js'
44
+ export {
45
+ getGasRecommendation,
46
+ LIFI_API_URL,
47
+ } from './services/getGasRecommendation.js'
42
48
  export type { GetMarketParams } from './services/getMarket.js'
43
49
  export { getMarket } from './services/getMarket.js'
44
50
  export type { GetMarketsParams } from './services/getMarkets.js'
@@ -93,6 +99,7 @@ export type {
93
99
  BuildProviderSetupParams,
94
100
  CancelOrdersParams,
95
101
  GetAccountResult,
102
+ GetDepositFlowParams,
96
103
  GetSetupParams,
97
104
  ModifyOrdersParams,
98
105
  PerpsClientOptions,
@@ -113,6 +120,13 @@ export type {
113
120
  SDKRequestOptions,
114
121
  SwitchChainHook,
115
122
  } from './types/config.js'
123
+ export type {
124
+ DeclaredDepositAsset,
125
+ DepositFlow,
126
+ DepositFlowFirstDepositPipeline,
127
+ DepositFlowLifiSwap,
128
+ DepositFlowSetupRequired,
129
+ } from './types/deposit.js'
116
130
  export type {
117
131
  ActionSignerContribution,
118
132
  LiquidationEstimateParams,
@@ -122,7 +136,9 @@ export type {
122
136
  ProviderAccountExistsParams,
123
137
  ProviderGetAccountParams,
124
138
  ProviderGetActivityParams,
139
+ ProviderGetDepositFlowParams,
125
140
  ProviderGetFillsParams,
141
+ ProviderGetMarketSettingsParams,
126
142
  ProviderGetOrderParams,
127
143
  ProviderGetOrdersParams,
128
144
  ProviderGetPositionsParams,
@@ -151,14 +167,16 @@ export {
151
167
  liquidationDistancePercent,
152
168
  percentFromPrice,
153
169
  priceFromPercent,
154
- removableMargin,
155
170
  walkOrderbook,
156
171
  } from './utils/calculations.js'
157
- export type { DepositProviderKey } from './utils/depositChain.js'
158
172
  export {
159
- LIFI_DEPOSIT_CHAIN_BY_PROVIDER,
160
- lifiDepositChainForProvider,
161
- } from './utils/depositChain.js'
173
+ ETHEREUM_NATIVE_GAS,
174
+ ETHEREUM_USDC,
175
+ HYPERLIQUID_USDC,
176
+ LIGHTER_USDC,
177
+ ROBINHOOD_NATIVE_GAS,
178
+ ROBINHOOD_USDG,
179
+ } from './utils/depositAssets.js'
162
180
  export {
163
181
  ExplorerChainId,
164
182
  explorerTxUrl,
@@ -205,6 +223,8 @@ export {
205
223
  signTypedData,
206
224
  signTypedDataWithSigner,
207
225
  } from './utils/signTypedData.js'
226
+ export type { RemovableIsolatedMarginParams } from './utils/transferMargin.js'
227
+ export { removableIsolatedMargin } from './utils/transferMargin.js'
208
228
  export { fromBaseUnits, fromBaseUnitsNumber } from './utils/units.js'
209
229
  export { validateMargin } from './utils/validation.js'
210
230
  // Version
@@ -1,5 +1,10 @@
1
- import type { Market, MarketDisplay, MarketsResponse } from '@lifi/perps-types'
2
- import { PerpsErrorCode } from '@lifi/perps-types'
1
+ import type {
2
+ Market,
3
+ MarketDisplay,
4
+ MarketsResponse,
5
+ PerpsMarketDisplay,
6
+ } from '@lifi/perps-types'
7
+ import { PerpsErrorCode, PositionMarginAdjustment } from '@lifi/perps-types'
3
8
  import { PerpsError } from '../errors/PerpsError.js'
4
9
  import { buildUrl, request } from '../transport/request.js'
5
10
  import type { PerpsSDKClient } from '../types/provider.js'
@@ -127,3 +132,41 @@ export const toMarketDisplay = (market: Market): MarketDisplay => ({
127
132
  quoteAsset: market.quoteAsset,
128
133
  ...(market.isDelisted === undefined ? {} : { isDelisted: market.isDelisted }),
129
134
  })
135
+
136
+ /**
137
+ * Project a perpetual {@link Market} to the identity embedded on a
138
+ * {@link Position}, preserving its individual-margin capability.
139
+ *
140
+ * @throws {PerpsError} `ValidationError` when passed a spot market.
141
+ * @public
142
+ */
143
+ export const toPerpsMarketDisplay = (market: Market): PerpsMarketDisplay => {
144
+ if (!('positionMarginAdjustment' in market)) {
145
+ throw new PerpsError(
146
+ PerpsErrorCode.ValidationError,
147
+ `Market '${market.id}' is not a perpetual market.`
148
+ )
149
+ }
150
+ const capability = market.positionMarginAdjustment
151
+ if (
152
+ capability !== PositionMarginAdjustment.NONE &&
153
+ capability !== PositionMarginAdjustment.ADD_ONLY &&
154
+ capability !== PositionMarginAdjustment.ADD_AND_REMOVE
155
+ ) {
156
+ throw new PerpsError(
157
+ PerpsErrorCode.ValidationError,
158
+ `Market '${market.id}' is not a perpetual market.`
159
+ )
160
+ }
161
+ return {
162
+ providerId: market.providerId,
163
+ id: market.id,
164
+ categoryId: market.categoryId,
165
+ baseAsset: market.baseAsset,
166
+ quoteAsset: market.quoteAsset,
167
+ ...(market.isDelisted === undefined
168
+ ? {}
169
+ : { isDelisted: market.isDelisted }),
170
+ positionMarginAdjustment: capability,
171
+ }
172
+ }
@@ -0,0 +1,45 @@
1
+ import type { GasRecommendationResponse } from '@lifi/types'
2
+ import { request } from '../transport/request.js'
3
+ import type { SDKRequestOptions } from '../types/config.js'
4
+ import type { PerpsSDKClient } from '../types/provider.js'
5
+
6
+ /**
7
+ * LI.FI API base URL for reads the user's client makes directly, without the
8
+ * perps backend in the path.
9
+ *
10
+ * @public
11
+ */
12
+ export const LIFI_API_URL = 'https://li.quest/v1'
13
+
14
+ /**
15
+ * Parameters for {@link getGasRecommendation}.
16
+ *
17
+ * @public
18
+ */
19
+ export interface GetGasRecommendationParams {
20
+ /** Chain to hold native gas on — a `firstDepositPipeline` flow's `chainId`. */
21
+ chainId: number
22
+ }
23
+
24
+ /**
25
+ * How much native gas LI.FI suggests holding on `params.chainId` to transact
26
+ * there, for seeding the gas leg of a first-deposit pipeline. Read straight
27
+ * from the LI.FI API by the user's client.
28
+ *
29
+ * @returns The suggestion, with `available: false` and no amounts on a chain
30
+ * LI.FI cannot source gas for.
31
+ * @throws {PerpsError} On API error responses, or network/parsing errors.
32
+ * @public
33
+ */
34
+ export async function getGasRecommendation(
35
+ client: PerpsSDKClient,
36
+ params: GetGasRecommendationParams,
37
+ options?: SDKRequestOptions
38
+ ): Promise<GasRecommendationResponse> {
39
+ return request<GasRecommendationResponse>(
40
+ client.config,
41
+ `${LIFI_API_URL}/gas/suggestion/${params.chainId}`,
42
+ {},
43
+ options
44
+ )
45
+ }
package/src/types/api.ts CHANGED
@@ -3,6 +3,7 @@ import type {
3
3
  AccountResponse,
4
4
  ActionStep,
5
5
  ExecuteActionResponse,
6
+ MarginMode,
6
7
  MarketRef,
7
8
  ModifyOrderInput,
8
9
  OrderSide,
@@ -122,6 +123,12 @@ export interface PlaceOrderParams {
122
123
  size: string
123
124
  price: string
124
125
  leverage?: number
126
+ /**
127
+ * Margin mode the order trades under; omitted falls to the venue's cross
128
+ * default. Lighter's order tx carries the mode directly; Hyperliquid
129
+ * applies it via a prepended leverage update (requires `leverage`).
130
+ */
131
+ marginMode?: MarginMode
125
132
  reduceOnly?: boolean
126
133
  timeInForce?: TimeInForce
127
134
  expiresAt?: string
@@ -209,6 +216,16 @@ export interface GetSetupParams {
209
216
  address: Address
210
217
  }
211
218
 
219
+ /**
220
+ * Parameters for {@link PerpsClient.getDepositFlow}.
221
+ *
222
+ * @public
223
+ */
224
+ export interface GetDepositFlowParams {
225
+ provider: string
226
+ address: Address
227
+ }
228
+
212
229
  /**
213
230
  * Result from {@link PerpsClient.checkSetup}.
214
231
  *
@@ -0,0 +1,75 @@
1
+ import type { ActionType } from '@lifi/perps-types'
2
+ import type { Address } from 'viem'
3
+
4
+ /**
5
+ * A token the SDK declares as part of a deposit flow, by full on-chain
6
+ * identity. Matched by `chainId` + `address`: a symbol is not identity — the
7
+ * Hyperliquid venue chain lists two `USDC` contracts with different decimals.
8
+ *
9
+ * @public
10
+ */
11
+ export interface DeclaredDepositAsset {
12
+ chainId: number
13
+ /** EIP-55 checksummed address; the zero address denotes the chain's native gas token. */
14
+ address: Address
15
+ decimals: number
16
+ }
17
+
18
+ /**
19
+ * Fund the account by swapping whatever the user holds into `destination`
20
+ * through the LI.FI surface. The source token is picked inside that surface, so
21
+ * it is not part of the flow; LI.FI routing owns whether that resolves to a
22
+ * same-chain swap or a bridge.
23
+ *
24
+ * @public
25
+ */
26
+ export interface DepositFlowLifiSwap {
27
+ kind: 'lifiSwap'
28
+ destination: DeclaredDepositAsset
29
+ /**
30
+ * Credited address when it is not the user's own — a venue-provisioned
31
+ * deposit address. Absent means the user's address receives the deposit.
32
+ */
33
+ toAddress?: Address
34
+ }
35
+
36
+ /**
37
+ * Fund an address that has no venue account yet. Collateral and the native gas
38
+ * to broadcast with are both needed on `chainId`, where the venue's
39
+ * {@link ActionType.DEPOSIT} action stages the on-chain legs that open the
40
+ * account.
41
+ *
42
+ * @public
43
+ */
44
+ export interface DepositFlowFirstDepositPipeline {
45
+ kind: 'firstDepositPipeline'
46
+ /** Chain the deposit legs broadcast on; the user's wallet must be switched to it. */
47
+ chainId: number
48
+ gasAsset: DeclaredDepositAsset
49
+ collateral: DeclaredDepositAsset
50
+ bridgeAction: ActionType.DEPOSIT
51
+ }
52
+
53
+ /**
54
+ * The venue cannot name a deposit destination until the listed setup actions
55
+ * are satisfied — Ondo provisions its deposit address behind a signed-in
56
+ * session.
57
+ *
58
+ * @public
59
+ */
60
+ export interface DepositFlowSetupRequired {
61
+ kind: 'setupRequired'
62
+ /** Outstanding `Provider.setup` action types, in the order they must be run. */
63
+ setup: ActionType[]
64
+ }
65
+
66
+ /**
67
+ * The single deposit flow a venue offers one address, resolved from the venue's
68
+ * account and setup state.
69
+ *
70
+ * @public
71
+ */
72
+ export type DepositFlow =
73
+ | DepositFlowLifiSwap
74
+ | DepositFlowFirstDepositPipeline
75
+ | DepositFlowSetupRequired
@@ -10,11 +10,14 @@ import type {
10
10
  ActivityType,
11
11
  FillsResponse,
12
12
  Market,
13
+ MarketRef,
14
+ MarketSettings,
13
15
  Order,
14
16
  OrdersResponse,
15
17
  PerpsMarket,
16
18
  PerpsSigner,
17
19
  Position,
20
+ PositionMarginConstraints,
18
21
  PositionsResponse,
19
22
  ProviderAction,
20
23
  Quote,
@@ -29,6 +32,7 @@ import type {
29
32
  PerpsClientSigner,
30
33
  SDKRequestOptions,
31
34
  } from './config.js'
35
+ import type { DepositFlow } from './deposit.js'
32
36
 
33
37
  /**
34
38
  * Low-level SDK client: resolved config, the optional end-user wallet, and the
@@ -162,6 +166,15 @@ export interface ProviderAccountExistsParams {
162
166
  address: Address
163
167
  }
164
168
 
169
+ /**
170
+ * Read params for {@link PerpsProviderPlugin.getDepositFlow}.
171
+ *
172
+ * @public
173
+ */
174
+ export interface ProviderGetDepositFlowParams {
175
+ address: Address
176
+ }
177
+
165
178
  /**
166
179
  * Read params for {@link PerpsProvider.getPositions}.
167
180
  *
@@ -175,6 +188,18 @@ export interface ProviderGetPositionsParams {
175
188
  cursor?: string
176
189
  }
177
190
 
191
+ /**
192
+ * Read params for {@link PerpsProviderPlugin.getMarketSettings}.
193
+ *
194
+ * @public
195
+ */
196
+ export interface ProviderGetMarketSettingsParams {
197
+ address: Address
198
+ /** The market's `id` and `categoryId`; the category identifies spot
199
+ * markets, which carry no venue leverage state. */
200
+ market: MarketRef
201
+ }
202
+
178
203
  /**
179
204
  * Read params for {@link PerpsProvider.getOrders}.
180
205
  *
@@ -321,11 +346,37 @@ export interface PerpsProviderPlugin {
321
346
  options?: SDKRequestOptions
322
347
  ): Promise<boolean>
323
348
 
349
+ /**
350
+ * The deposit flow this venue offers `params.address`, resolved from the
351
+ * venue's own account and setup state — which collateral token a deposit must
352
+ * land in, whether the address first needs the account-opening pipeline, and
353
+ * whether venue setup gates naming a destination at all.
354
+ *
355
+ * Optional: a provider that cannot be funded through the SDK omits it, and
356
+ * `PerpsClient.getDepositFlow` then resolves `undefined`.
357
+ */
358
+ getDepositFlow?(
359
+ params: ProviderGetDepositFlowParams,
360
+ options?: SDKRequestOptions
361
+ ): Promise<DepositFlow>
362
+
324
363
  getPositions(
325
364
  params: ProviderGetPositionsParams,
326
365
  options?: SDKRequestOptions
327
366
  ): Promise<PositionsResponse>
328
367
 
368
+ /**
369
+ * The user's current venue-side settings for one market — the margin mode
370
+ * and leverage the next order on it will use. Optional because venues
371
+ * expose this unevenly: Hyperliquid reads it directly (`activeAssetData`),
372
+ * Lighter only reports it on an account's position row. `undefined` means
373
+ * the venue has nothing to read for this market.
374
+ */
375
+ getMarketSettings?(
376
+ params: ProviderGetMarketSettingsParams,
377
+ options?: SDKRequestOptions
378
+ ): Promise<MarketSettings | undefined>
379
+
329
380
  getOrders(
330
381
  params: ProviderGetOrdersParams,
331
382
  options?: SDKRequestOptions
@@ -412,6 +463,18 @@ export interface PerpsProviderPlugin {
412
463
  params: LiquidationEstimateParams
413
464
  ): number | undefined
414
465
 
466
+ /**
467
+ * Exact venue-owned constraints for changing `position`'s dedicated margin.
468
+ * Pure — providers normalize raw venue quantities onto the position before
469
+ * returning these inputs.
470
+ *
471
+ * @returns `undefined` when this position has no individual margin
472
+ * adjustment (for example a cross position or a cross-only venue).
473
+ */
474
+ positionMarginConstraints(
475
+ position: Position
476
+ ): PositionMarginConstraints | undefined
477
+
415
478
  /**
416
479
  * Project a typed {@link AccountConfig} against the provider's `setup`
417
480
  * + `options` descriptors into `AccountConfigSetting[]`. Used by
@@ -169,34 +169,6 @@ export function effectiveLeverage(params: {
169
169
  return positionValueUsd / marginUsd
170
170
  }
171
171
 
172
- /**
173
- * Margin that can be removed from a position while keeping its leverage at or
174
- * below the asset's maximum.
175
- *
176
- * The minimum margin to stay within `maxLeverage` is the required margin for
177
- * the position's notional (see {@link calculateRequiredMargin}); anything above
178
- * that is removable.
179
- *
180
- * @param marginUsed - Margin currently backing the position in USD
181
- * @param positionValueUsd - Position notional value in USD
182
- * @param maxLeverage - Maximum leverage allowed for the asset
183
- * @returns Removable margin in USD (never negative); falls back to the full
184
- * `marginUsed` when `maxLeverage` is zero (no constraint available)
185
- * @public
186
- */
187
- export function removableMargin(params: {
188
- marginUsed: number
189
- positionValueUsd: number
190
- maxLeverage: number
191
- }): number {
192
- const { marginUsed, positionValueUsd, maxLeverage } = params
193
- if (maxLeverage === 0) {
194
- return marginUsed
195
- }
196
- const minMargin = calculateRequiredMargin(positionValueUsd, maxLeverage)
197
- return Math.max(0, marginUsed - minMargin)
198
- }
199
-
200
172
  /**
201
173
  * Signed expected PnL for a trigger price — see {@link calculateExpectedPnl}.
202
174
  *
@@ -0,0 +1,77 @@
1
+ import { ChainId } from '@lifi/types'
2
+ import { zeroAddress } from 'viem'
3
+ import type { DeclaredDepositAsset } from '../types/deposit.js'
4
+
5
+ /**
6
+ * USDC on Ethereum mainnet — the collateral leg of Lighter's first-deposit
7
+ * pipeline, and the token Ondo's provisioned deposit address is funded in.
8
+ *
9
+ * @public
10
+ */
11
+ export const ETHEREUM_USDC: DeclaredDepositAsset = {
12
+ chainId: ChainId.ETH,
13
+ address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
14
+ decimals: 6,
15
+ }
16
+
17
+ /**
18
+ * Ether on Ethereum mainnet, to broadcast the first-deposit pipeline's legs
19
+ * with.
20
+ *
21
+ * @public
22
+ */
23
+ export const ETHEREUM_NATIVE_GAS: DeclaredDepositAsset = {
24
+ chainId: ChainId.ETH,
25
+ address: zeroAddress,
26
+ decimals: 18,
27
+ }
28
+
29
+ /**
30
+ * USDC on the Hyperliquid venue chain: the 6-decimal perps contract. The same
31
+ * chain also lists an 8-decimal spot `USDC` at
32
+ * `0x6d1e7cde53bA9467B783Cb7c530CE05400000000`, so a deposit destination
33
+ * resolved by symbol lands on the wrong token and the wrong scale.
34
+ *
35
+ * @public
36
+ */
37
+ export const HYPERLIQUID_USDC: DeclaredDepositAsset = {
38
+ chainId: ChainId.HPL,
39
+ address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
40
+ decimals: 6,
41
+ }
42
+
43
+ /**
44
+ * USDC on the Lighter venue chain. The venue chain reuses the mainnet USDC
45
+ * address, so `chainId` is what distinguishes it from {@link ETHEREUM_USDC}.
46
+ *
47
+ * @public
48
+ */
49
+ export const LIGHTER_USDC: DeclaredDepositAsset = {
50
+ chainId: ChainId.LTR,
51
+ address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
52
+ decimals: 6,
53
+ }
54
+
55
+ /**
56
+ * USDG on Robinhood Chain — the collateral the Lighter Robinhood instance is
57
+ * funded in.
58
+ *
59
+ * @public
60
+ */
61
+ export const ROBINHOOD_USDG: DeclaredDepositAsset = {
62
+ chainId: ChainId.OUT,
63
+ address: '0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168',
64
+ decimals: 6,
65
+ }
66
+
67
+ /**
68
+ * Ether on Robinhood Chain, to broadcast the Robinhood first-deposit pipeline's
69
+ * legs with.
70
+ *
71
+ * @public
72
+ */
73
+ export const ROBINHOOD_NATIVE_GAS: DeclaredDepositAsset = {
74
+ chainId: ChainId.OUT,
75
+ address: zeroAddress,
76
+ decimals: 18,
77
+ }