@structbuild/sdk 0.3.1 → 0.3.3

package/README.md

@@ -254,16 +254,16 @@ alerts.on("probability_spike", (payload) => {
 
 | Room | Filters | Event |
 |------|---------|-------|
-| `polymarket_trades` | `condition_ids` | `trade_stream_update` |
-| `polymarket_asset_prices` | `condition_ids?` | `asset_price_tick`, `asset_price_window_update` |
-| `polymarket_asset_window_updates` | `condition_ids` | `asset_window_update` |
+| `polymarket_trades` | `condition_ids?`, `market_slugs?`, `event_slugs?`, `position_ids?`, `traders?`, `trade_types?`, `status?`, `subscribe_all?` | `trade_stream_update` |
+| `polymarket_asset_prices` | `asset_symbols?` | `asset_price_tick`, `asset_price_window_update` |
+| `polymarket_asset_window_updates` | `asset_symbols?`, `timeframes?` | `asset_window_update` |
 | `polymarket_market_metrics` | `condition_ids` | `market_metrics_update` |
 | `polymarket_event_metrics` | `event_slugs` | `event_metrics_update` |
 | `polymarket_position_metrics` | `position_ids` | `position_metrics_update` |
-| `polymarket_trader_pnl` | `addresses` | `trader_global_pnl_update`, `trader_market_pnl_update`, `trader_event_pnl_update` |
-| `polymarket_trader_positions` | `addresses` | `trader_position_update` |
-| `polymarket_accounts` | `wallets` | `accounts_update`, `usdce_update`, `matic_update` |
-| `polymarket_order_book` | `asset_ids` | `order_book_update` |
+| `polymarket_trader_pnl` | `traders` | `trader_global_pnl_update`, `trader_market_pnl_update`, `trader_event_pnl_update` |
+| `polymarket_trader_positions` | `traders` | `trader_position_update` |
+| `polymarket_accounts` | `wallets`, `include_usdce?`, `include_matic?` | `accounts_update`, `usdce_update`, `matic_update` |
+| `polymarket_order_book` | `condition_ids?`, `position_ids?` | `order_book_update` |
 | `polymarket_clob_rewards` | `condition_ids?`, `subscribe_all?` | `clob_rewards_update` |
 
 ### Lifecycle events
@@ -365,6 +365,32 @@ const client = new StructClient({
 });
 ```
 
+## Testing
+
+WebSocket unit tests stay in the default fast suite:
+
+```bash
+bun test
+bun run typecheck
+```
+
+The live websocket soak test is opt-in and env-gated. It first calls the REST API to fetch a recent market, event, position, and trader, then subscribes across the main websocket rooms and keeps the socket alive for 5 minutes by default.
+
+```bash
+STRUCT_RUN_WS_LIVE_TESTS=1 \
+STRUCT_API_KEY=your-api-key \
+bun run test:ws:live
+```
+
+To run longer than 5 minutes, set `STRUCT_WS_SOAK_DURATION_MS`:
+
+```bash
+STRUCT_RUN_WS_LIVE_TESTS=1 \
+STRUCT_API_KEY=your-api-key \
+STRUCT_WS_SOAK_DURATION_MS=420000 \
+bun run test:ws:live
+```
+
 ## License
 
 MIT

package/dist/generated/polymarket.d.ts

@@ -252,7 +252,7 @@ export interface paths {
         };
         /**
          * Get bonds
-         * @description Retrieve a list of bond markets sorted by yield, filtered by probability and time to expiry
+         * @description Retrieve bond markets with sorting, probability range filter, and offset pagination
          */
         get: operations["get_bonds"];
         put?: never;
@@ -412,7 +412,7 @@ export interface paths {
         };
         /**
          * Get market by slug
-         * @description Retrieve a single market by its slug with optional nested tags, event, and metrics
+         * @description Retrieve one or more markets by slug. Supports batch lookups via query params. Returns an array of MarketResponse objects.
          */
         get: operations["get_market_by_slug"];
         put?: never;
@@ -472,7 +472,7 @@ export interface paths {
         };
         /**
          * Get market by condition ID
-         * @description Retrieve a single market by its condition ID with optional nested tags, event, and metrics
+         * @description Retrieve one or more markets by condition ID. Supports batch lookups via query params. Returns an array of MarketResponse objects.
          */
         get: operations["get_market"];
         put?: never;
@@ -623,6 +623,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/polymarket/series/{identifier}/events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get series events
+         * @description Returns a paginated list of events belonging to a specific Polymarket series, with full market data for each event.
+         */
+        get: operations["get_series_events"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/polymarket/tags": {
         parameters: {
             query?: never;
@@ -1045,6 +1065,8 @@ export interface components {
             apy: number;
             /** Format: double */
             volume_24h?: number | null;
+            /** Format: double */
+            liquidity?: number | null;
             outcomes: components["schemas"]["BondOutcome"][];
         };
         BondOutcome: {
@@ -1402,6 +1424,18 @@ export interface components {
              * @default null
              */
             outcome_index: number | null;
+            /**
+             * Format: int64
+             * @description Block of the most recent price update for this outcome.
+             * @default null
+             */
+            latest_block: number | null;
+            /**
+             * Format: int64
+             * @description Unix-seconds timestamp of the most recent price update.
+             * @default null
+             */
+            latest_confirmed_at: number | null;
         };
         /** @enum {string} */
         MarketPnlSortBy: "realized_pnl_usd" | "buy_usd" | "total_buys" | "total_fees" | "outcomes_traded" | "realized_pnl_pct";
@@ -1987,7 +2021,7 @@ export interface components {
             price_close: number;
         };
         /** @enum {string} */
-        PositionPnlSortBy: "realized_pnl_usd" | "buy_usd" | "sell_usd" | "redemption_usd" | "total_buys" | "total_sells" | "total_shares_bought" | "total_shares_sold" | "avg_entry_price" | "avg_exit_price" | "total_fees" | "first_trade_at" | "last_trade_at" | "current_value" | "realized_pnl_pct" | "title";
+        PositionPnlSortBy: "realized_pnl_usd" | "total_buy_usd" | "total_sell_usd" | "redemption_usd" | "total_buys" | "total_sells" | "total_shares_bought" | "total_shares_sold" | "avg_entry_price" | "avg_exit_price" | "total_fees" | "first_trade_at" | "last_trade_at" | "current_value" | "realized_pnl_pct" | "title";
         /**
          * @description Position status filter for open/closed positions.
          * @enum {string}
@@ -2533,6 +2567,8 @@ export interface components {
             first_trade_at?: number | null;
             /** Format: int64 */
             last_trade_at?: number | null;
+            /** Format: double */
+            realized_pnl_pct?: number | null;
         };
         /** @description Trader profile info - backwards compatibility */
         TraderInfo: {
@@ -2546,6 +2582,7 @@ export interface components {
         /** @description Market-level PnL entry */
         TraderMarketPnlEntry: {
             condition_id?: string | null;
+            market_slug?: string | null;
             event_slug?: string | null;
             question?: string | null;
             image_url?: string | null;
@@ -2577,6 +2614,8 @@ export interface components {
             first_trade_at?: number | null;
             /** Format: int64 */
             last_trade_at?: number | null;
+            /** Format: double */
+            realized_pnl_pct?: number | null;
         };
         /** @description Outcome-level PnL entry (per outcome token / position_id) */
         TraderOutcomePnlEntry: {
@@ -2747,12 +2786,12 @@ export interface operations {
                  * @description Asset ticker: BTC, ETH, XRP, SOL, DOGE, BNB, HYPE
                  * @example BTC
                  */
-                asset_symbol: string;
+                asset_symbol: components["schemas"]["AssetSymbol"];
                 /**
                  * @description Time window: 5m, 15m, 1h, 4h, 1d
                  * @example 1h
                  */
-                variant: string;
+                variant: components["schemas"]["AssetVariant"];
                 /** @description Start timestamp in seconds (Unix epoch, inclusive) */
                 from?: number;
                 /** @description End timestamp in seconds (Unix epoch, inclusive) */
@@ -2913,13 +2952,13 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Event metrics for the specified timeframe(s). Returns single object for one timeframe, array for multiple. */
+            /** @description Event metrics. **Note:** returns a single object for one timeframe, or an array of objects for comma-separated timeframes or 'all'. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["EventMetricsResponse"];
+                    "application/json": components["schemas"]["EventMetricsResponse"][];
                 };
             };
             /** @description Invalid timeframe */
@@ -3094,8 +3133,16 @@ export interface operations {
                 condition_id?: string;
                 /** @description Market slug (e.g. `will-trump-win`) */
                 market_slug?: string;
-                /** @description Time range in hours (default: 24, max: 336 = 14 days) */
+                /** @description Start timestamp (Unix seconds). If omitted, derived from `hours` param. */
+                from?: number;
+                /** @description End timestamp (Unix seconds). Defaults to now. */
+                to?: number;
+                /** @description Number of candles to return (default: 500, max: 2500) */
+                count_back?: number;
+                /** @description Fallback time range in hours when `from`/`to` are not provided (default: 24, max: 336 = 14 days) */
                 hours?: number;
+                /** @description Cursor-based pagination key from previous response */
+                pagination_key?: string;
             };
             header?: never;
             path?: never;
@@ -3167,8 +3214,16 @@ export interface operations {
     get_position_holders_history: {
         parameters: {
             query?: {
-                /** @description Time range in hours (default: 24, max: 336 = 14 days) */
+                /** @description Start timestamp (Unix seconds). If omitted, derived from `hours` param. */
+                from?: number;
+                /** @description End timestamp (Unix seconds). Defaults to now. */
+                to?: number;
+                /** @description Number of candles to return (default: 500, max: 2500) */
+                count_back?: number;
+                /** @description Fallback time range in hours when `from`/`to` are not provided (default: 24, max: 336 = 14 days) */
                 hours?: number;
+                /** @description Cursor-based pagination key from previous response */
+                pagination_key?: string;
             };
             header?: never;
             path: {
@@ -3298,12 +3353,16 @@ export interface operations {
             query?: {
                 /** @description Minimum probability threshold (default: 0.85) */
                 min_probability?: number;
+                /** @description Maximum probability threshold (e.g. 0.99) */
+                max_probability?: number;
                 /** @description Maximum hours until market end */
                 max_hours?: number;
+                /** @description Sort by: apy, liquidity, volume, end_date (default: end_date) */
+                sort_by?: string;
                 /** @description Number of results (default: 10, max: 250) */
                 limit?: number;
-                /** @description Cursor for pagination: end_date (unix epoch) of the last item from the previous page */
-                pagination_key?: number;
+                /** @description Offset for pagination (default: 0) */
+                offset?: number;
             };
             header?: never;
             path?: never;
@@ -3311,7 +3370,7 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description List of bond markets sorted by yield */
+            /** @description List of bond markets */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -3335,6 +3394,8 @@ export interface operations {
                 from?: number;
                 /** @description End timestamp (Unix seconds) */
                 to?: number;
+                /** @description Cursor-based pagination key from previous response */
+                pagination_key?: string;
             };
             header?: never;
             path?: never;
@@ -3396,13 +3457,13 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Market metrics for the specified timeframe(s). Returns single object for one timeframe, array for multiple. */
+            /** @description Market metrics. **Note:** returns a single object for one timeframe, or an array of objects for comma-separated timeframes or 'all'. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ConditionMetricsResponse"];
+                    "application/json": components["schemas"]["ConditionMetricsResponse"][];
                 };
             };
             /** @description Invalid timeframe */
@@ -3427,6 +3488,8 @@ export interface operations {
                 from?: number;
                 /** @description End timestamp (Unix seconds) */
                 to?: number;
+                /** @description Cursor-based pagination key from previous response */
+                pagination_key?: string;
             };
             header?: never;
             path?: never;
@@ -3459,13 +3522,13 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Position metrics for the specified timeframe(s). Returns single object for one timeframe, array for multiple. */
+            /** @description Position metrics. **Note:** returns a single object for one timeframe, or an array of objects for comma-separated timeframes or 'all'. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PositionMetricsResponse"];
+                    "application/json": components["schemas"]["PositionMetricsResponse"][];
                 };
             };
             /** @description Invalid timeframe */
@@ -3490,6 +3553,8 @@ export interface operations {
                 from?: number;
                 /** @description End timestamp (Unix seconds) */
                 to?: number;
+                /** @description Cursor-based pagination key from previous response */
+                pagination_key?: string;
             };
             header?: never;
             path?: never;
@@ -3544,6 +3609,24 @@ export interface operations {
     get_market_by_slug: {
         parameters: {
             query?: {
+                /** @description Comma-separated condition IDs (max 50) */
+                condition_ids?: string;
+                /** @description Comma-separated question IDs (max 50) */
+                question_ids?: string;
+                /** @description Comma-separated market IDs (max 50) */
+                market_ids?: string;
+                /** @description Comma-separated market slugs (max 50) */
+                market_slugs?: string;
+                /** @description Comma-separated event slugs (max 50) */
+                event_slugs?: string;
+                /** @description Comma-separated tag filters (max 50) */
+                tags?: string;
+                /** @description Comma-separated position IDs to resolve to markets (max 50) */
+                position_ids?: string;
+                /** @description Search string (3-100 characters) */
+                search?: string;
+                /** @description Metrics timeframe (default: 24h) */
+                timeframe?: components["schemas"]["MetricsTimeframe"];
                 /** @description Include tags array (default: true) */
                 include_tags?: boolean;
                 /** @description Include event object (default: true) */
@@ -3562,7 +3645,7 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Market with metadata, outcomes, tags, event, and metrics */
+            /** @description Array of markets with metadata, outcomes, tags, event, and metrics */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -3615,7 +3698,7 @@ export interface operations {
                         };
                         /** Format: double */
                         relevance_score?: number | null;
-                    };
+                    }[];
                 };
             };
             /** @description Market not found */
@@ -3707,6 +3790,8 @@ export interface operations {
                 from?: number;
                 /** @description End timestamp (Unix seconds) */
                 to?: number;
+                /** @description Cursor-based pagination key from previous response */
+                pagination_key?: string;
             };
             header?: never;
             path?: never;
@@ -3728,6 +3813,24 @@ export interface operations {
     get_market: {
         parameters: {
             query?: {
+                /** @description Comma-separated condition IDs (max 50) */
+                condition_ids?: string;
+                /** @description Comma-separated question IDs (max 50) */
+                question_ids?: string;
+                /** @description Comma-separated market IDs (max 50) */
+                market_ids?: string;
+                /** @description Comma-separated market slugs (max 50) */
+                market_slugs?: string;
+                /** @description Comma-separated event slugs (max 50) */
+                event_slugs?: string;
+                /** @description Comma-separated tag filters (max 50) */
+                tags?: string;
+                /** @description Comma-separated position IDs to resolve to markets (max 50) */
+                position_ids?: string;
+                /** @description Search string (3-100 characters) */
+                search?: string;
+                /** @description Metrics timeframe (default: 24h) */
+                timeframe?: components["schemas"]["MetricsTimeframe"];
                 /** @description Include tags array (default: true) */
                 include_tags?: boolean;
                 /** @description Include event object (default: true) */
@@ -3746,7 +3849,7 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Market with metadata, outcomes, tags, event, and metrics */
+            /** @description Array of markets with metadata, outcomes, tags, event, and metrics */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -3799,7 +3902,7 @@ export interface operations {
                         };
                         /** Format: double */
                         relevance_score?: number | null;
-                    };
+                    }[];
                 };
             };
             /** @description Market not found */
@@ -4012,7 +4115,7 @@ export interface operations {
                 max_spread?: number;
                 /** @description Only return rows where total liquidity (bid + ask) >= this value */
                 min_liquidity?: number;
-                /** @description Number of results (default: 100, max: 1000) */
+                /** @description Number of results (default: 20, max: 200) */
                 limit?: number;
                 /** @description Cursor from previous response's pagination.pagination_key */
                 pagination_key?: string;
@@ -4186,6 +4289,49 @@ export interface operations {
             };
         };
     };
+    get_series_events: {
+        parameters: {
+            query?: {
+                /** @description Filter by active events only (default: false) */
+                active?: boolean;
+                /** @description Include tags array (default: true) */
+                include_tags?: boolean;
+                /** @description Include markets array (default: true) */
+                include_markets?: boolean;
+                /** @description Include metrics (default: true) */
+                include_metrics?: boolean;
+                /** @description Number of events to return (default: 20, max: 250) */
+                limit?: number;
+                /** @description Offset for pagination (default: 0) */
+                pagination_key?: string;
+            };
+            header?: never;
+            path: {
+                /** @description Series slug (e.g. 'btc-weekly-close') or series ID */
+                identifier: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List of events in this series */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PolymarketEvent"][];
+                };
+            };
+            /** @description Series not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     get_tags: {
         parameters: {
             query?: {
@@ -4361,7 +4507,7 @@ export interface operations {
             query?: {
                 /** @description Timeframe: 1d, 7d, 30d, lifetime (default: lifetime) */
                 timeframe?: components["schemas"]["PnlTimeframe"];
-                /** @description Sort: realized_pnl_usd, total_volume_usd, markets_traded, total_fees (default: realized_pnl_usd) */
+                /** @description Sort: realized_pnl_usd, total_volume_usd, markets_traded, total_fees, realized_pnl_pct (default: realized_pnl_usd) */
                 sort_by?: components["schemas"]["EventPnlSortBy"];
                 /** @description Sort direction: asc, desc (default: desc) */
                 sort_direction?: components["schemas"]["SortDirection"];
@@ -4399,7 +4545,7 @@ export interface operations {
             query?: {
                 /** @description Timeframe: 1d, 7d, 30d, lifetime (default: lifetime) */
                 timeframe?: components["schemas"]["PnlTimeframe"];
-                /** @description Sort: realized_pnl_usd, buy_usd, total_buys, total_fees, outcomes_traded (default: realized_pnl_usd) */
+                /** @description Sort: realized_pnl_usd, buy_usd, total_buys, total_fees, outcomes_traded, realized_pnl_pct (default: realized_pnl_usd) */
                 sort_by?: components["schemas"]["MarketPnlSortBy"];
                 /** @description Sort direction: asc, desc (default: desc) */
                 sort_direction?: components["schemas"]["SortDirection"];