@ostium/builder-sdk 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -191,7 +191,7 @@ interface CommonParams {
     slippageBps?: number;
     /**
      * Optional builder fee sharing.
-     * `feeBps` is in basis points — max 50 (0.5%).
+     * `feeBps` in basis points (e.g. 10 = 10 bps / 0.1%, 2.55 = 2.55 bps). Max 50 (0.5%), step 0.01 bps.
      */
     builder?: {
         address: Address;
@@ -624,11 +624,24 @@ interface GetPairsParams {
 interface GetUserParams {
     user: Address;
 }
-interface GetOpenPositionsParams extends GetUserParams {
+interface GetOpenPositionsParams {
+    /**
+     * Trader address — pass `'ALL'` to fetch every trader's open positions
+     * (no trader filter applied to the subgraph query).
+     */
+    user: Address | AllTraders;
     /** Current Arbitrum block number — required for live PnL. Auto-fetched on `OstiumClient`. */
     blockNumber?: bigint;
+    /**
+     * Maximum number of positions to return. Defaults to `Infinity` (all positions).
+     */
+    limit?: number;
+    /**
+     * Number of positions to skip (for pagination). Defaults to `0`.
+     */
+    skip?: number;
 }
-/** Sentinel value for `getFills` / `getFillsByTime` to fetch every trader's fills. */
+/** Sentinel value for `getOpenPositions`, `getFills`, and `getFillsByTime` to fetch across every trader. */
 type AllTraders = 'ALL';
 interface GetFillsParams {
     /**
@@ -1349,6 +1362,11 @@ declare class OstiumClient {
     /**
      * Open positions + margin summary for a user. Defaults to the connected
      * trader. Live prices and the current block number are fetched automatically.
+     *
+     * - `user`: pass an address to scope to a single trader, or `'ALL'` to fetch
+     *   positions across every trader (no trader filter).
+     * - `limit`: cap the number of positions returned (default: all).
+     * - `skip`: offset into the result set for pagination (default: `0`).
      */
     getOpenPositions(params?: Partial<GetOpenPositionsParams>): Promise<OpenPositionsResponse>;
     /**

package/dist/index.d.ts

@@ -191,7 +191,7 @@ interface CommonParams {
     slippageBps?: number;
     /**
      * Optional builder fee sharing.
-     * `feeBps` is in basis points — max 50 (0.5%).
+     * `feeBps` in basis points (e.g. 10 = 10 bps / 0.1%, 2.55 = 2.55 bps). Max 50 (0.5%), step 0.01 bps.
      */
     builder?: {
         address: Address;
@@ -624,11 +624,24 @@ interface GetPairsParams {
 interface GetUserParams {
     user: Address;
 }
-interface GetOpenPositionsParams extends GetUserParams {
+interface GetOpenPositionsParams {
+    /**
+     * Trader address — pass `'ALL'` to fetch every trader's open positions
+     * (no trader filter applied to the subgraph query).
+     */
+    user: Address | AllTraders;
     /** Current Arbitrum block number — required for live PnL. Auto-fetched on `OstiumClient`. */
     blockNumber?: bigint;
+    /**
+     * Maximum number of positions to return. Defaults to `Infinity` (all positions).
+     */
+    limit?: number;
+    /**
+     * Number of positions to skip (for pagination). Defaults to `0`.
+     */
+    skip?: number;
 }
-/** Sentinel value for `getFills` / `getFillsByTime` to fetch every trader's fills. */
+/** Sentinel value for `getOpenPositions`, `getFills`, and `getFillsByTime` to fetch across every trader. */
 type AllTraders = 'ALL';
 interface GetFillsParams {
     /**
@@ -1349,6 +1362,11 @@ declare class OstiumClient {
     /**
      * Open positions + margin summary for a user. Defaults to the connected
      * trader. Live prices and the current block number are fetched automatically.
+     *
+     * - `user`: pass an address to scope to a single trader, or `'ALL'` to fetch
+     *   positions across every trader (no trader filter).
+     * - `limit`: cap the number of positions returned (default: all).
+     * - `skip`: offset into the result set for pagination (default: `0`).
      */
     getOpenPositions(params?: Partial<GetOpenPositionsParams>): Promise<OpenPositionsResponse>;
     /**

package/dist/index.js

@@ -54,6 +54,32 @@ var ERC20_ABI = [
   }
 ];
 
+// src/internal/builder-fee.ts
+var MAX_BUILDER_FEE_BPS = 50;
+var MIN_BUILDER_FEE_BPS_STEP = 0.01;
+var MAX_BUILDER_FEE_CONTRACT = 5e5;
+var BPS_TO_CONTRACT = 1e4;
+function bpsToContractBuilderFee(feeBps) {
+  if (feeBps === 0) return 0n;
+  return BigInt(Math.round(feeBps * BPS_TO_CONTRACT));
+}
+function validateBuilderFeeBps(feeBps) {
+  if (!Number.isFinite(feeBps)) {
+    return "builder.feeBps must be a finite number";
+  }
+  if (feeBps < 0 || feeBps > MAX_BUILDER_FEE_BPS) {
+    return `builder.feeBps must be between 0 and ${MAX_BUILDER_FEE_BPS} (0%\u20130.5%)`;
+  }
+  const centiBps = Math.round(feeBps * 100);
+  if (Math.abs(feeBps * 100 - centiBps) > 1e-6) {
+    return `builder.feeBps must be a multiple of ${MIN_BUILDER_FEE_BPS_STEP} (0.01 bps)`;
+  }
+  if (bpsToContractBuilderFee(feeBps) > MAX_BUILDER_FEE_CONTRACT) {
+    return "builder.feeBps exceeds on-chain maximum (0.5%)";
+  }
+  return null;
+}
+
 // src/internal/decimal.ts
 function parseUsdc(amount) {
   const amountStr = typeof amount === "number" ? amount.toString() : amount;
@@ -212,7 +238,7 @@ function buildBuilderFee(builder) {
   }
   return {
     builder: builder.b,
-    builderFee: BigInt(builder.f)
+    builderFee: bpsToContractBuilderFee(builder.f)
   };
 }
 
@@ -2938,6 +2964,17 @@ query GetTraderOpenTrades($trader: String!, $skip: Int!, $first: Int!) {
     ${PAIR_FULL}
   }
 }`;
+var GetAllOpenTradesQuery = `
+query GetAllOpenTrades($skip: Int!, $first: Int!) {
+  trades(
+    where: { isOpen: true }
+    skip: $skip first: $first
+    orderBy: timestamp orderDirection: desc
+  ) {
+    ${TRADE_CORE}
+    ${PAIR_FULL}
+  }
+}`;
 var ORDER_FIELDS = `
     id tradeID limitID trader
     pair { id from to group { id name } }
@@ -3017,9 +3054,9 @@ query GetTraderActiveLimits($trader: String!, $skip: Int!, $first: Int!) {
 }`;
 
 // src/data/internal/pagination.ts
-async function paginateAll(fetcher, batchSize = 1e3, max = Infinity) {
+async function paginateAll(fetcher, batchSize = 1e3, max = Infinity, initialSkip = 0) {
   const results = [];
-  let skip = 0;
+  let skip = initialSkip;
   while (results.length < max) {
     const remaining = max - results.length;
     const fetchSize = Math.min(batchSize, remaining);
@@ -3948,15 +3985,28 @@ var OstiumSubgraphClient = class _OstiumSubgraphClient {
    *   PnL fields are zeroed.
    */
   async getOpenPositions(params) {
-    const { user, blockNumber } = params;
+    const { user, blockNumber, limit = Infinity, skip: initialSkip = 0 } = params;
+    const isGlobal = user === "ALL";
     const [trades, prices] = await Promise.all([
-      paginateAll(async (skip, first) => {
-        const data = await this.query(
-          GetTraderOpenTradesQuery,
-          { trader: user.toLowerCase(), skip, first }
-        );
-        return data.trades;
-      }),
+      paginateAll(
+        async (skip, first) => {
+          if (isGlobal) {
+            const data2 = await this.query(
+              GetAllOpenTradesQuery,
+              { skip, first }
+            );
+            return data2.trades;
+          }
+          const data = await this.query(
+            GetTraderOpenTradesQuery,
+            { trader: user.toLowerCase(), skip, first }
+          );
+          return data.trades;
+        },
+        1e3,
+        limit,
+        initialSkip
+      ),
       this.fetchLivePricesSafe()
     ]);
     const pairPositions = trades.map((trade) => {
@@ -4324,11 +4374,11 @@ function validateConfig(config) {
       "INVALID_CONFIG" /* INVALID_CONFIG */
     );
   }
-  if (config.builder !== void 0 && (config.builder.feeBps < 0 || config.builder.feeBps > 50)) {
-    throw new OstiumError(
-      "builder.feeBps must be between 0 and 50 (max 0.5%)",
-      "INVALID_CONFIG" /* INVALID_CONFIG */
-    );
+  if (config.builder !== void 0) {
+    const feeError = validateBuilderFeeBps(config.builder.feeBps);
+    if (feeError) {
+      throw new OstiumError(feeError, "INVALID_CONFIG" /* INVALID_CONFIG */);
+    }
   }
   let mode;
   try {
@@ -5124,11 +5174,18 @@ var OstiumClient = class _OstiumClient {
   /**
    * Open positions + margin summary for a user. Defaults to the connected
    * trader. Live prices and the current block number are fetched automatically.
+   *
+   * - `user`: pass an address to scope to a single trader, or `'ALL'` to fetch
+   *   positions across every trader (no trader filter).
+   * - `limit`: cap the number of positions returned (default: all).
+   * - `skip`: offset into the result set for pagination (default: `0`).
    */
   async getOpenPositions(params) {
     return this.subgraph.getOpenPositions({
       user: params?.user ?? this.getTraderAddress(),
-      blockNumber: params?.blockNumber ?? await this.publicClient.getBlockNumber()
+      blockNumber: params?.blockNumber ?? await this.publicClient.getBlockNumber(),
+      limit: params?.limit,
+      skip: params?.skip
     });
   }
   /**