@ostium/builder-sdk 0.1.0 → 0.3.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.
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { Hex, Address } from 'viem';
1
+ import { Address, Hex } from 'viem';
2
2
 
3
3
  declare enum OrderType$1 {
4
4
  Market = "market",
@@ -11,8 +11,11 @@ declare enum CancelOrderType {
11
11
  PendingClose = "pendingClose"
12
12
  }
13
13
  interface OpenTradeParams {
14
- /** Trading pair index (e.g. 0 for BTC/USD). */
15
- pairIndex: number;
14
+ /**
15
+ * Trading pair id — same value as `Pair.pairId` returned by `getPairs()`.
16
+ * Accepts both the numeric string (e.g. `"0"`) and a plain `number`.
17
+ */
18
+ pairId: string | number;
16
19
  /** true = long, false = short. */
17
20
  buy: boolean;
18
21
  /** Entry price as a decimal string (e.g. "65000.50"). */
@@ -158,7 +161,28 @@ interface SubmissionResult {
158
161
  /** Set for gasless submissions — the Safe smart account address that sent the UserOp. */
159
162
  smartAccountAddress?: Address;
160
163
  }
164
+ interface BuiltSafeTxCall {
165
+ to: Address;
166
+ data: Hex;
167
+ value: bigint;
168
+ }
169
+ interface BuiltEoaTxRequest {
170
+ kind: 'eoa';
171
+ to: Address;
172
+ data: Hex;
173
+ value: bigint;
174
+ from: Address;
175
+ traderAddress: Address;
176
+ }
177
+ interface BuiltSafeTxRequest {
178
+ kind: 'safe';
179
+ safeAddress: Address;
180
+ traderAddress: Address;
181
+ calls: [BuiltSafeTxCall];
182
+ }
183
+ type BuiltTxRequest = BuiltEoaTxRequest | BuiltSafeTxRequest;
161
184
 
185
+ type ClientMode = 'self-self' | 'self-gasless' | 'delegated-self' | 'delegated-gasless';
162
186
  /** Shared optional settings available in every mode. */
163
187
  interface CommonParams {
164
188
  /** Use Arbitrum Sepolia testnet. Defaults to false (mainnet). */
@@ -185,47 +209,26 @@ interface CommonParams {
185
209
  */
186
210
  builderApiUrl?: string;
187
211
  }
188
- /**
189
- * **Self + Self** — simplest mode.
190
- *
191
- * Your EOA is the trader: it holds USDC, owns all positions, and pays gas
192
- * for every transaction directly.
193
- *
194
- * ```ts
195
- * const client = await OstiumClient.createSelfAndSelf({
196
- * traderPrivateKey: '0x...',
197
- * rpcUrl: 'https://arb-mainnet.g.alchemy.com/v2/...',
198
- * });
199
- * await client.openTrade({ ... });
200
- * ```
201
- */
202
- interface SelfSelfParams extends CommonParams {
212
+ interface SelfSelfSubmitParams extends CommonParams {
203
213
  /** Private key of the trader's EOA. This account holds USDC, owns all positions, and pays gas. */
204
214
  traderPrivateKey: Hex;
205
215
  /** Arbitrum One (or Sepolia) RPC URL. */
206
216
  rpcUrl: string;
207
217
  }
218
+ interface SelfSelfBuildParams extends CommonParams {
219
+ /** Trader EOA address. Used to build unsigned transactions without SDK submission. */
220
+ traderAddress: Address;
221
+ /** Optional Arbitrum RPC URL for reads/simulation. Defaults to the chain public RPC. */
222
+ rpcUrl?: string;
223
+ }
208
224
  /**
209
- * **Self + Gasless** — your EOA owns everything; a Safe acts as a transparent gasless relay.
210
- *
211
- * Your EOA holds USDC and owns all positions. A Safe smart account is derived
212
- * deterministically from your private key and registered as your delegate.
213
- * After a one-time setup (approve USDC + register Safe via `setupGaslessDelegation()`),
214
- * all subsequent trades are submitted as sponsored UserOperations — no ETH needed.
225
+ * **Self + Self** — simplest mode.
215
226
  *
216
- * ```ts
217
- * const client = await OstiumClient.createSelfAndGasless({
218
- * traderPrivateKey: '0x...',
219
- * pimlicoUrl: 'https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161',
220
- * });
221
- * // One-time setup (EOA pays gas once for each):
222
- * await client.approveUsdc('max');
223
- * await client.setupGaslessDelegation();
224
- * // All subsequent trading is free:
225
- * await client.openTrade({ ... });
226
- * ```
227
+ * Your EOA is the trader: it holds USDC, owns all positions, and pays gas
228
+ * for every transaction directly.
227
229
  */
228
- interface SelfGaslessParams extends CommonParams {
230
+ type SelfSelfParams = SelfSelfSubmitParams | SelfSelfBuildParams;
231
+ interface SelfGaslessSubmitParams extends CommonParams {
229
232
  /** Private key of the trader's EOA. This account holds USDC and owns all positions. A Safe is derived from this key to relay trades gaslessly. */
230
233
  traderPrivateKey: Hex;
231
234
  /** Pimlico-compatible bundler/paymaster RPC URL. Defaults to `https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161`. */
@@ -235,23 +238,22 @@ interface SelfGaslessParams extends CommonParams {
235
238
  /** Pimlico sponsorship policy ID. */
236
239
  sponsorshipPolicyId?: string;
237
240
  }
241
+ interface SelfGaslessBuildParams extends CommonParams {
242
+ /** Trader EOA address that owns USDC and positions. */
243
+ traderAddress: Address;
244
+ /** Safe smart-account address that will submit delegated calls. */
245
+ safeAddress: Address;
246
+ /** Optional Arbitrum RPC URL for reads/simulation. Defaults to the chain public RPC. */
247
+ rpcUrl?: string;
248
+ }
238
249
  /**
239
- * **Delegated + Self** — a dedicated delegate EOA signs and pays gas on behalf of a separate trader address.
240
- *
241
- * The trader account keeps custody of USDC and positions. The delegate account
242
- * only needs ETH for gas. The trader must have called `setDelegate(delegateAddress)`
243
- * on the trading contract before this client can submit trades.
250
+ * **Self + Gasless** — your EOA owns everything; a Safe acts as a transparent gasless relay.
244
251
  *
245
- * ```ts
246
- * const client = await OstiumClient.createDelegatedAndSelf({
247
- * delegatePrivateKey: '0xDelegateKey',
248
- * traderAddress: '0xTraderAddress',
249
- * rpcUrl: 'https://arb-mainnet.g.alchemy.com/v2/...',
250
- * });
251
- * await client.openTrade({ ... }); // submitted as delegatedAction(traderAddress, ...)
252
- * ```
252
+ * Submit-capable clients derive the Safe from `traderPrivateKey`. Build-only
253
+ * clients provide both `traderAddress` and `safeAddress`.
253
254
  */
254
- interface DelegatedSelfParams extends CommonParams {
255
+ type SelfGaslessParams = SelfGaslessSubmitParams | SelfGaslessBuildParams;
256
+ interface DelegatedSelfSubmitParams extends CommonParams {
255
257
  /** Private key of the delegate EOA. This account signs and pays gas for all transactions. */
256
258
  delegatePrivateKey: Hex;
257
259
  /**
@@ -262,30 +264,25 @@ interface DelegatedSelfParams extends CommonParams {
262
264
  /** Arbitrum One (or Sepolia) RPC URL. */
263
265
  rpcUrl: string;
264
266
  }
267
+ interface DelegatedSelfBuildParams extends CommonParams {
268
+ /** Address of the trader this delegate acts for. */
269
+ traderAddress: Address;
270
+ /** Delegate EOA address that will submit the transaction. */
271
+ delegateAddress: Address;
272
+ /** Optional Arbitrum RPC URL for reads/simulation. Defaults to the chain public RPC. */
273
+ rpcUrl?: string;
274
+ }
265
275
  /**
266
- * **Delegated + Gasless** — a Safe derived from the delegate key submits sponsored UserOperations on behalf of the trader.
267
- *
268
- * The trader keeps custody of USDC and positions. The delegate's Safe submits
269
- * trades as UserOperations via Pimlico — no ETH needed after the trader calls
270
- * `setDelegate(safeAddress)` once.
271
- *
272
- * ```ts
273
- * const client = await OstiumClient.createDelegatedAndGasless({
274
- * delegatePrivateKey: '0xDelegateKey',
275
- * traderAddress: '0xTraderAddress',
276
- * pimlicoUrl: 'https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161',
277
- * });
278
- * await client.openTrade({ ... }); // submitted as sponsored delegatedAction UserOp
279
- * ```
276
+ * **Delegated + Self** — a dedicated delegate EOA signs and pays gas on behalf of a separate trader address.
280
277
  */
281
- interface DelegatedGaslessParams extends CommonParams {
278
+ type DelegatedSelfParams = DelegatedSelfSubmitParams | DelegatedSelfBuildParams;
279
+ interface DelegatedGaslessSubmitParams extends CommonParams {
282
280
  /** Private key of the delegate EOA. A Safe smart account is derived from this key and submits UserOperations via Pimlico. */
283
281
  delegatePrivateKey: Hex;
284
282
  /**
285
283
  * Address of the trader this delegate acts for.
286
284
  * The trader must have called `setDelegate(safeAddress)` on the trading contract,
287
285
  * where `safeAddress` is the Safe derived from `delegatePrivateKey`.
288
- * Use `client.getSmartAccountAddress()` to retrieve this address.
289
286
  */
290
287
  traderAddress: Address;
291
288
  /** Pimlico-compatible bundler/paymaster RPC URL. Defaults to `https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161`. */
@@ -295,34 +292,29 @@ interface DelegatedGaslessParams extends CommonParams {
295
292
  /** Pimlico sponsorship policy ID. */
296
293
  sponsorshipPolicyId?: string;
297
294
  }
295
+ interface DelegatedGaslessBuildParams extends CommonParams {
296
+ /** Address of the trader this delegate acts for. */
297
+ traderAddress: Address;
298
+ /** Delegate EOA address that owns the Safe. */
299
+ delegateAddress: Address;
300
+ /** Safe smart-account address that will submit delegated calls. */
301
+ safeAddress: Address;
302
+ /** Optional Arbitrum RPC URL for reads/simulation. Defaults to the chain public RPC. */
303
+ rpcUrl?: string;
304
+ }
298
305
  /**
299
- * Generic config object used by the legacy `OstiumClient.create()` method.
300
- * Prefer the named constructors (`createSelfAndSelf`, `createSelfAndGasless`,
301
- * `createDelegatedAndSelf`, `createDelegatedAndGasless`) for clearer intent.
302
- *
303
- * The SDK infers the operational mode from the shape of this object:
304
- *
305
- * | `traderAddress` | `pimlicoUrl` | Mode |
306
- * |:---:|:---:|:---|
307
- * | ✓ | ✓ | Delegated + Gasless |
308
- * | ✓ | — | Delegated + Self |
309
- * | — | ✓ | Self + Gasless |
310
- * | — | — | Self + Self |
306
+ * **Delegated + Gasless** a Safe derived from the delegate key submits sponsored UserOperations on behalf of the trader.
311
307
  */
312
- interface OstiumClientConfig {
313
- privateKey: Hex;
308
+ type DelegatedGaslessParams = DelegatedGaslessSubmitParams | DelegatedGaslessBuildParams;
309
+ interface OstiumClientConfig extends CommonParams {
310
+ mode?: ClientMode;
311
+ privateKey?: Hex;
314
312
  traderAddress?: Address;
313
+ delegateAddress?: Address;
314
+ safeAddress?: Address;
315
315
  rpcUrl?: string;
316
316
  pimlicoUrl?: string;
317
317
  sponsorshipPolicyId?: string;
318
- testnet?: boolean;
319
- builder?: {
320
- address: Address;
321
- feeBps: number;
322
- };
323
- slippageBps?: number;
324
- subgraphUrl?: string;
325
- builderApiUrl?: string;
326
318
  }
327
319
 
328
320
  /** Mainnet (Arbitrum One) Ostium subgraph endpoint. */
@@ -481,11 +473,11 @@ interface Position {
481
473
  isDayTrade: boolean;
482
474
  /** Max leverage for the trade/pair/group **/
483
475
  maxLeverage: string;
476
+ /** Max collateral removable from this position without breaching min leverage, in USD. */
477
+ maxWithdrawable: string;
484
478
  }
485
479
  interface PairPosition {
486
480
  position: Position;
487
- /** Max collateral removable from this position without breaching min leverage, in USD. */
488
- maxWithdrawable: string;
489
481
  }
490
482
  interface MarginSummary {
491
483
  /** Sum of `(collateral + netPnl)` across all open positions (USD). */
@@ -496,17 +488,16 @@ interface MarginSummary {
496
488
  totalNtlPos: string;
497
489
  /** Sum of unrealized PnL (after rollover) across all open positions (USD). */
498
490
  totalRawPnlUsd: string;
491
+ /** Sum of cumulative rollover across all open positions (USD, negative = trader pays). */
492
+ totalCumRollover: string;
493
+ /** Sum of per-position max-removable collateral across all open positions (USD). */
494
+ totalWithdrawable: string;
499
495
  }
500
496
  interface OpenPositionsResponse {
501
497
  /** All open positions for the requested trader, sorted newest first. */
502
498
  pairPositions: PairPosition[];
503
499
  /** Aggregated margin metrics across all open positions. */
504
500
  marginSummary: MarginSummary;
505
- /**
506
- * Sum of per-position max-removable collateral, computed from the leverage
507
- * constraint: `collateral × (1 − currentLeverage / maxLeverage)`.
508
- */
509
- withdrawable: string;
510
501
  /** Server time (Unix milliseconds). */
511
502
  time: number;
512
503
  }
@@ -633,11 +624,24 @@ interface GetPairsParams {
633
624
  interface GetUserParams {
634
625
  user: Address;
635
626
  }
636
- interface GetOpenPositionsParams extends GetUserParams {
627
+ interface GetOpenPositionsParams {
628
+ /**
629
+ * Trader address — pass `'ALL'` to fetch every trader's open positions
630
+ * (no trader filter applied to the subgraph query).
631
+ */
632
+ user: Address | AllTraders;
637
633
  /** Current Arbitrum block number — required for live PnL. Auto-fetched on `OstiumClient`. */
638
634
  blockNumber?: bigint;
635
+ /**
636
+ * Maximum number of positions to return. Defaults to `Infinity` (all positions).
637
+ */
638
+ limit?: number;
639
+ /**
640
+ * Number of positions to skip (for pagination). Defaults to `0`.
641
+ */
642
+ skip?: number;
639
643
  }
640
- /** Sentinel value for `getFills` / `getFillsByTime` to fetch every trader's fills. */
644
+ /** Sentinel value for `getOpenPositions`, `getFills`, and `getFillsByTime` to fetch across every trader. */
641
645
  type AllTraders = 'ALL';
642
646
  interface GetFillsParams {
643
647
  /**
@@ -719,6 +723,8 @@ interface GetSimOrderbookParams {
719
723
  }
720
724
  /** Live price tick received from the builder API price stream. */
721
725
  interface PriceTick {
726
+ /** Numeric string pair identifier — same as `Pair.pairId`, when resolvable from the SDK cache. */
727
+ pairId?: string;
722
728
  /** Upstream feed identifier. */
723
729
  feedId: string;
724
730
  /** Pair in `"BASE-QUOTE"` format (e.g. `"BTC-USD"`). */
@@ -811,6 +817,8 @@ declare class OstiumPriceStream {
811
817
  private readonly snapshotHandlers;
812
818
  /** pairId (string) → raw "FROM-TO" name for the WS API. */
813
819
  private readonly pairRawNameCache;
820
+ /** raw "FROM-TO" name → pairId (string) for mapping incoming ticks back to SDK ids. */
821
+ private readonly rawNamePairIdCache;
814
822
  private constructor();
815
823
  /**
816
824
  * Open a WebSocket connection to the live price stream.
@@ -863,6 +871,34 @@ declare class OstiumPriceStream {
863
871
  private send;
864
872
  }
865
873
 
874
+ type UpdateHandler = (positions: OpenPositionsResponse) => void;
875
+ type TickSource = Pick<OstiumPriceStream, 'onTick' | 'onSnapshot' | 'onOpen' | 'onError' | 'onClose' | 'close'>;
876
+ declare class OstiumPositionUpdatesStream {
877
+ private readonly priceStream?;
878
+ private readonly updateHandlers;
879
+ private current;
880
+ private readonly trackedPairIds;
881
+ constructor(initial: OpenPositionsResponse, trackedPairIds: string[], priceStream?: TickSource);
882
+ onUpdate(handler: UpdateHandler): () => void;
883
+ onOpen(handler: () => void): this;
884
+ onError(handler: (event: Error) => void): this;
885
+ onClose(handler: (code: number, reason: string) => void): this;
886
+ getCurrent(): OpenPositionsResponse;
887
+ /**
888
+ * Apply a single externally sourced price tick to the tracked positions.
889
+ *
890
+ * Use this when your app already has its own websocket connection and you want
891
+ * the SDK to handle only the position recalculation logic.
892
+ */
893
+ ingestTick(tick: PriceTick): void;
894
+ /**
895
+ * Apply a batch of externally sourced ticks, such as a websocket snapshot.
896
+ */
897
+ ingestSnapshot(ticks: PriceTick[]): void;
898
+ close(): void;
899
+ private emit;
900
+ }
901
+
866
902
  declare class OstiumSubgraphClient {
867
903
  private readonly gql;
868
904
  private readonly builderApiUrl;
@@ -1001,6 +1037,18 @@ declare class OstiumSubgraphClient {
1001
1037
  * `WebSocket` may fail some `https://` upgrades (e.g. CloudFront); use Node if so.
1002
1038
  */
1003
1039
  streamPrices(pairIds?: Array<string | number>): OstiumPriceStream;
1040
+ /**
1041
+ * Stream price-driven updates for an existing `getOpenPositions()` response.
1042
+ *
1043
+ * The SDK subscribes only to the unique pairs present in `initial.pairPositions`,
1044
+ * recalculates price-sensitive fields for affected positions on each tick, and
1045
+ * emits the full updated response.
1046
+ *
1047
+ * Pass an existing `priceStream` to reuse a websocket connection your app has
1048
+ * already opened. Omit it to let the SDK open and manage a dedicated
1049
+ * connection for the tracked pair ids.
1050
+ */
1051
+ streamPositionUpdates(initial: OpenPositionsResponse, priceStream?: OstiumPriceStream): OstiumPositionUpdatesStream;
1004
1052
  private fetchRawPairs;
1005
1053
  private refreshPairIdCache;
1006
1054
  private ensurePairIdCache;
@@ -1013,6 +1061,8 @@ declare class OstiumSubgraphClient {
1013
1061
  declare class OstiumClient {
1014
1062
  private readonly signer?;
1015
1063
  private readonly submitter?;
1064
+ private readonly traderAddress?;
1065
+ private readonly effectiveSender?;
1016
1066
  private readonly contracts;
1017
1067
  private readonly publicClient;
1018
1068
  private readonly defaultSlippageBps;
@@ -1038,7 +1088,7 @@ declare class OstiumClient {
1038
1088
  * });
1039
1089
  * await client.openTrade({ ... });
1040
1090
  * ```
1041
- */
1091
+ */
1042
1092
  static createSelfAndSelf(params: SelfSelfParams): Promise<OstiumClient>;
1043
1093
  /**
1044
1094
  * **Self + Gasless** — your EOA owns everything; a Safe relays trades for free.
@@ -1130,8 +1180,12 @@ declare class OstiumClient {
1130
1180
  * - Self + Gasless: EOA derived from privateKey (NOT the Safe — USDC lives here).
1131
1181
  */
1132
1182
  getTraderAddress(): Address;
1133
- /** True when the client was created via `createReadOnly` and cannot submit transactions. */
1183
+ /** True when the client cannot submit transactions directly. */
1134
1184
  isReadOnly(): boolean;
1185
+ /** True when the client can build mode-correct unsigned transaction requests. */
1186
+ canBuildTransactions(): boolean;
1187
+ /** True when the client has the credentials needed for SDK-managed submission. */
1188
+ canSubmitTransactions(): boolean;
1135
1189
  /**
1136
1190
  * Returns the Safe smart-account address used for gasless submission.
1137
1191
  * Returns undefined when not in gasless mode.
@@ -1161,6 +1215,7 @@ declare class OstiumClient {
1161
1215
  * ```
1162
1216
  */
1163
1217
  setupGaslessDelegation(): Promise<SubmissionResult>;
1218
+ getSetupGaslessDelegationTx(): BuiltTxRequest;
1164
1219
  /**
1165
1220
  * Check whether the trader's USDC allowance covers the required amount.
1166
1221
  * The allowance is always checked against signer.traderAddress (the EOA in
@@ -1187,6 +1242,7 @@ declare class OstiumClient {
1187
1242
  * @param amount USD amount as decimal string (e.g. "1000"), or "max" for MaxUint256.
1188
1243
  */
1189
1244
  approveUsdc(amount: string): Promise<SubmissionResult>;
1245
+ getApproveUsdcTx(amount: string): BuiltTxRequest;
1190
1246
  /**
1191
1247
  * Set a delegate on the trading contract.
1192
1248
  *
@@ -1196,11 +1252,13 @@ declare class OstiumClient {
1196
1252
  * update the trader's delegation on their behalf.
1197
1253
  */
1198
1254
  setDelegate(delegateAddress: Address): Promise<SubmissionResult>;
1255
+ getSetDelegateTx(delegateAddress: Address): BuiltTxRequest;
1199
1256
  /**
1200
1257
  * Remove the current delegate on the trading contract.
1201
1258
  * Follows the same delegation-wrapping rules as setDelegate().
1202
1259
  */
1203
1260
  removeDelegate(): Promise<SubmissionResult>;
1261
+ getRemoveDelegateTx(): BuiltTxRequest;
1204
1262
  /**
1205
1263
  * Open a new trade position.
1206
1264
  *
@@ -1209,6 +1267,8 @@ declare class OstiumClient {
1209
1267
  * the current allowance.
1210
1268
  */
1211
1269
  openTrade(params: OpenTradeParams): Promise<SubmissionResult>;
1270
+ getOpenTradeTx(params: OpenTradeParams): BuiltTxRequest;
1271
+ private getOpenTradeEncoded;
1212
1272
  /**
1213
1273
  * Close an open position (full or partial).
1214
1274
  *
@@ -1222,6 +1282,8 @@ declare class OstiumClient {
1222
1282
  * ```
1223
1283
  */
1224
1284
  closeTrade(params: CloseTradeParams): Promise<SubmissionResult>;
1285
+ getCloseTradeTx(params: CloseTradeParams): BuiltTxRequest;
1286
+ private getCloseTradeEncoded;
1225
1287
  /**
1226
1288
  * Cancel a pending order.
1227
1289
  *
@@ -1243,6 +1305,8 @@ declare class OstiumClient {
1243
1305
  * ```
1244
1306
  */
1245
1307
  cancelOrder(params: CancelOrderParams): Promise<SubmissionResult>;
1308
+ getCancelOrderTx(params: CancelOrderParams): BuiltTxRequest;
1309
+ private getCancelOrderEncoded;
1246
1310
  /**
1247
1311
  * Modify an open trade or a pending limit order.
1248
1312
  *
@@ -1266,6 +1330,8 @@ declare class OstiumClient {
1266
1330
  * - Both `takeProfit` and `stopLoss` without `price` → throws (send two calls).
1267
1331
  */
1268
1332
  modifyOrder(params: ModifyOrderParams): Promise<SubmissionResult>;
1333
+ getModifyOrderTx(params: ModifyOrderParams): BuiltTxRequest;
1334
+ private getModifyOrderEncoded;
1269
1335
  /**
1270
1336
  * Update collateral on an open position (isolated margin).
1271
1337
  *
@@ -1284,6 +1350,8 @@ declare class OstiumClient {
1284
1350
  * Checks USDC allowance before top-up operations.
1285
1351
  */
1286
1352
  updateCollateral(params: UpdateCollateralParams): Promise<SubmissionResult>;
1353
+ getUpdateCollateralTx(params: UpdateCollateralParams): Promise<BuiltTxRequest>;
1354
+ private getUpdateCollateralEncoded;
1287
1355
  /**
1288
1356
  * All trading pairs with computed `minSz`/`maxBSz`/`maxSSz`, live prices, and
1289
1357
  * market-status flags. Pass `pairIds` to restrict to a subset.
@@ -1294,6 +1362,11 @@ declare class OstiumClient {
1294
1362
  /**
1295
1363
  * Open positions + margin summary for a user. Defaults to the connected
1296
1364
  * trader. Live prices and the current block number are fetched automatically.
1365
+ *
1366
+ * - `user`: pass an address to scope to a single trader, or `'ALL'` to fetch
1367
+ * positions across every trader (no trader filter).
1368
+ * - `limit`: cap the number of positions returned (default: all).
1369
+ * - `skip`: offset into the result set for pagination (default: `0`).
1297
1370
  */
1298
1371
  getOpenPositions(params?: Partial<GetOpenPositionsParams>): Promise<OpenPositionsResponse>;
1299
1372
  /**
@@ -1372,15 +1445,27 @@ declare class OstiumClient {
1372
1445
  */
1373
1446
  streamPrices(pairIds?: Array<string | number>): OstiumPriceStream;
1374
1447
  /**
1375
- * Core execution pipeline:
1376
- * 1. signer.prepare() — optionally wraps in delegatedAction.
1377
- * 2. submitter.submit() sends via EOA walletClient or Pimlico UserOp.
1378
- */
1379
- private execute;
1380
- /** Throws if the client is read-only; otherwise returns the signer + submitter. */
1381
- private requireWriter;
1448
+ * Stream price-driven updates for an existing `getOpenPositions()` response.
1449
+ *
1450
+ * Subscribes only to the unique pairs referenced by the response and emits the
1451
+ * full updated positions payload on each relevant price update. Pass an
1452
+ * existing `priceStream` to reuse a websocket your app already owns, or omit
1453
+ * it to let the SDK create a dedicated connection.
1454
+ */
1455
+ streamPositionUpdates(initial: OpenPositionsResponse, priceStream?: OstiumPriceStream): OstiumPositionUpdatesStream;
1456
+ private getSetupGaslessDelegationEncoded;
1457
+ private getApproveUsdcEncoded;
1458
+ private getSetDelegateEncoded;
1459
+ private getRemoveDelegateEncoded;
1460
+ private prepareEncoded;
1461
+ private buildPreparedTx;
1462
+ private buildDirectEoaTx;
1463
+ private toBuiltTxRequest;
1464
+ private submitPrepared;
1382
1465
  /** Direct EOA submission — used only in Self + Gasless for approveUsdc and setupGaslessDelegation. */
1383
- private submitDirectFromEoa;
1466
+ private submitDirectEoa;
1467
+ private requireBuildCapability;
1468
+ private requireSubmitCapability;
1384
1469
  private resolveSlippage;
1385
1470
  }
1386
1471
 
@@ -1446,4 +1531,4 @@ declare class OstiumSubgraphError extends Error {
1446
1531
  constructor(message: string, code: OstiumSubgraphErrorCode, cause?: unknown | undefined);
1447
1532
  }
1448
1533
 
1449
- export { type AllPricesResponse, type AllTraders, type AllowanceStatus, type Balances, type CancelLimitOrderParams, type CancelOrderParams, CancelOrderType, type CancelPendingCloseParams, type CancelPendingOpenParams, type Candle, type CandleResolution, type CloseTradeParams, DEFAULT_BUILDER_API_URL, DEFAULT_SLIPPAGE_PERCENTAGE, DEFAULT_SUBGRAPH_ENDPOINT, DEFAULT_SUBGRAPH_ENDPOINT_TESTNET, type DelegatedGaslessParams, type DelegatedSelfParams, type Fill, type FillFees, type OrderType as FillOrderType, type GetCandlesParams, type GetFillsByTimeParams, type GetFillsParams, type GetOpenPositionsParams, type GetOrdersParams, type GetPairsParams, type GetSimOrderbookParams, type GetSimSlippageParams, type GetUserParams, MAX_COLLATERAL_USD, MIN_COLLATERAL_USD, type MarginSummary, type ModifyOrderParams, type OpenOrder, type OpenPositionsResponse, type OpenTradeParams, type Order, type OrderAction, OrderType$1 as OrderType, OstiumClient, type OstiumClientConfig, OstiumError, OstiumErrorCode, OstiumPriceStream, OstiumSubgraphClient, type OstiumSubgraphClientConfig, OstiumSubgraphError, OstiumSubgraphErrorCode, PRECISION_18, PRECISION_6, type Pair, type PairPosition, type PairsResponse, type Position, type PriceData, type PriceTick, type SelfGaslessParams, type SelfSelfParams, type SimOrderbookLevel, type SimOrderbookResponse, type SimSlippageByPairId, type SimSlippageForPair, type SimSlippageRow, type SubmissionResult, type UpdateCollateralParams, parseLeverage, parsePrice, parseUsdc };
1534
+ export { type AllPricesResponse, type AllTraders, type AllowanceStatus, type Balances, type BuiltEoaTxRequest, type BuiltSafeTxCall, type BuiltSafeTxRequest, type BuiltTxRequest, type CancelLimitOrderParams, type CancelOrderParams, CancelOrderType, type CancelPendingCloseParams, type CancelPendingOpenParams, type Candle, type CandleResolution, type ClientMode, type CloseTradeParams, DEFAULT_BUILDER_API_URL, DEFAULT_SLIPPAGE_PERCENTAGE, DEFAULT_SUBGRAPH_ENDPOINT, DEFAULT_SUBGRAPH_ENDPOINT_TESTNET, type DelegatedGaslessBuildParams, type DelegatedGaslessParams, type DelegatedGaslessSubmitParams, type DelegatedSelfBuildParams, type DelegatedSelfParams, type DelegatedSelfSubmitParams, type Fill, type FillFees, type OrderType as FillOrderType, type GetCandlesParams, type GetFillsByTimeParams, type GetFillsParams, type GetOpenPositionsParams, type GetOrdersParams, type GetPairsParams, type GetSimOrderbookParams, type GetSimSlippageParams, type GetUserParams, MAX_COLLATERAL_USD, MIN_COLLATERAL_USD, type MarginSummary, type ModifyOrderParams, type OpenOrder, type OpenPositionsResponse, type OpenTradeParams, type Order, type OrderAction, OrderType$1 as OrderType, OstiumClient, type OstiumClientConfig, OstiumError, OstiumErrorCode, OstiumPositionUpdatesStream, OstiumPriceStream, OstiumSubgraphClient, type OstiumSubgraphClientConfig, OstiumSubgraphError, OstiumSubgraphErrorCode, PRECISION_18, PRECISION_6, type Pair, type PairPosition, type PairsResponse, type Position, type PriceData, type PriceTick, type SelfGaslessBuildParams, type SelfGaslessParams, type SelfGaslessSubmitParams, type SelfSelfBuildParams, type SelfSelfParams, type SelfSelfSubmitParams, type SimOrderbookLevel, type SimOrderbookResponse, type SimSlippageByPairId, type SimSlippageForPair, type SimSlippageRow, type SubmissionResult, type UpdateCollateralParams, parseLeverage, parsePrice, parseUsdc };