@structbuild/sdk 0.3.0 → 0.3.1

package/README.md

@@ -7,8 +7,6 @@ TypeScript SDK for prediction market data via [api.struct.to](https://api.struct
 ```bash
 npm install @structbuild/sdk
 # or
-pnpm add @structbuild/sdk
-# or
 bun add @structbuild/sdk
 ```
 
@@ -73,11 +71,11 @@ const trades = await client.trader.getTraderTrades({ address: "0x..." });
 const profile = await client.trader.getTraderProfile({ address: "0x..." });
 const profiles = await client.trader.getTraderProfilesBatch({ addresses: "0x...,0x..." });
 const pnl = await client.trader.getTraderPnl({ address: "0x..." });
-const pnlByMarket = await client.trader.getTraderMarketPnl({ address: "0x..." });
-const pnlByEvent = await client.trader.getTraderEventPnl({ address: "0x..." });
+const marketPnl = await client.trader.getTraderMarketPnl({ address: "0x..." });
+const eventPnl = await client.trader.getTraderEventPnl({ address: "0x..." });
+const outcomePnl = await client.trader.getTraderOutcomePnl({ address: "0x..." });
 const pnlCandles = await client.trader.getTraderPnlCandles({ address: "0x..." });
-const calendar = await client.trader.getTraderPnlCalendar({ address: "0x..." });
-const positionPnl = await client.trader.getTraderOutcomePnl({ address: "0x..." });
+const pnlCalendar = await client.trader.getTraderPnlCalendar({ address: "0x..." });
 const volumeChart = await client.trader.getTraderVolumeChart({ address: "0x..." });
 const leaderboard = await client.trader.getGlobalPnl();
 ```
@@ -91,16 +89,20 @@ const history = await client.holders.getMarketHoldersHistory({ condition_id: "0x
 const posHistory = await client.holders.getPositionHoldersHistory({ positionId: "123" });
 ```
 
-### Series
+### Order Book
 
 ```typescript
-const series = await client.series.getSeriesList();
-const outcomes = await client.series.getSeriesOutcomes({ series_slug: "my-series" });
+const orderBook = await client.orderBook.getOrderBook({ asset_id: "0x..." });
+const history = await client.orderBook.getOrderBookHistory();
+const marketBook = await client.orderBook.getMarketOrderBook();
+const spreads = await client.orderBook.getSpreadHistory();
 ```
 
-### Assets, Search, Tags, Bonds
+### Series, Search, Tags, Assets, Bonds
 
 ```typescript
+const series = await client.series.getSeriesList();
+const outcomes = await client.series.getSeriesOutcomes({ series_slug: "my-series" });
 const assetHistory = await client.assets.getAssetHistory({ symbol: "BTC", variant: "1d" });
 const results = await client.search.search({ query: "election" });
 const tags = await client.tags.getTags();
@@ -147,7 +149,7 @@ Individual schemas are also exported: `OrderFilledTrade`, `RedemptionTrade`, `Me
 
 ### Webhooks
 
-Manage webhook subscriptions for real-time event notifications. Webhook endpoints are platform-level (not venue-scoped).
+Manage webhook subscriptions for real-time event notifications:
 
 ```typescript
 const webhooks = await client.webhooks.list();
@@ -159,32 +161,129 @@ const webhook = await client.webhooks.create({
     min_usd_value: 100,
   },
 });
-const detail = await client.webhooks.getWebhook({ webhookId: webhook.data.id });
-await client.webhooks.update({ webhookId: webhook.data.id, events: ["first_trade"] });
 await client.webhooks.test({ webhookId: webhook.data.id });
 await client.webhooks.rotateSecret({ webhookId: webhook.data.id });
 await client.webhooks.deleteWebhook({ webhookId: webhook.data.id });
 const events = await client.webhooks.listEvents();
 ```
 
-#### Webhook Payload Types
+## WebSocket API
 
-The SDK exports typed payload schemas for building webhook receivers:
+Real-time streaming via room-based subscriptions with fully typed filters, responses, and events.
 
 ```typescript
-import type {
-  FirstTradePayload,
-  ProbabilitySpikePayload,
-  GlobalPnlPayload,
-  VolumeMilestonePayload,
-} from "@structbuild/sdk";
-
-function handleWebhook(payload: FirstTradePayload) {
-  console.log(payload.trader, payload.price, payload.side);
-}
+import { StructWebSocket } from "@structbuild/sdk";
+
+const ws = new StructWebSocket({ apiKey: "your-api-key" });
+await ws.connect();
+```
+
+### Subscribing to rooms
+
+Each room has typed filters and a typed subscribe response:
+
+```typescript
+const res = await ws.subscribe("polymarket_trades", {
+  condition_ids: ["0xabc123"],
+});
+
+await ws.subscribe("polymarket_order_book", {
+  asset_ids: ["0xabc123"],
+});
+
+// Some rooms have optional filters
+await ws.subscribe("polymarket_asset_prices");
+await ws.subscribe("polymarket_clob_rewards", { subscribe_all: true });
+```
+
+### Listening for events
+
+```typescript
+ws.on("trade_stream_update", (event) => {
+  event.condition_id;
+  event.price;
+  event.size;
+  event.side;
+});
+
+ws.on("order_book_update", (event) => {
+  event.asset_id;
+  event.bids;
+  event.asks;
+});
+
+ws.on("clob_rewards_update", (event) => {
+  event.event_type;    // "added" | "removed" | "updated"
+  event.condition_id;
+  event.reward;
+});
 ```
 
-Available payload types: `FirstTradePayload`, `GlobalPnlPayload`, `MarketPnlPayload`, `EventPnlPayload`, `ConditionMetricsPayload`, `EventMetricsPayload`, `PositionMetricsPayload`, `VolumeMilestonePayload`, `EventVolumeMilestonePayload`, `PositionVolumeMilestonePayload`, `ProbabilitySpikePayload`.
+### Alerts
+
+Alerts use a separate client with per-event typed filters and payloads:
+
+```typescript
+import { StructAlertsWebSocket } from "@structbuild/sdk";
+
+const alerts = new StructAlertsWebSocket({ apiKey: "your-api-key" });
+await alerts.connect();
+
+await alerts.subscribe("trader_whale_trade", {
+  wallet_addresses: ["0xd91..."],
+  min_usd_value: 10000,
+});
+
+await alerts.subscribe("probability_spike", {
+  spike_direction: "up",
+  min_probability_change_pct: 5,
+});
+
+alerts.on("trader_whale_trade", (payload) => {
+  payload.data.trader;
+  payload.data.amount_usd;
+});
+
+alerts.on("probability_spike", (payload) => {
+  payload.data.spike_direction;
+  payload.data.spike_pct;
+});
+```
+
+### Available rooms
+
+| 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_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_clob_rewards` | `condition_ids?`, `subscribe_all?` | `clob_rewards_update` |
+
+### Lifecycle events
+
+```typescript
+ws.on("connected", () => {});
+ws.on("disconnected", ({ code, reason }) => {});
+ws.on("reconnecting", ({ attempt }) => {});
+ws.on("reconnect_failed", (err) => {});
+ws.on("auth_failed", (err) => {});
+ws.on("warning", (warning) => {});
+ws.on("error", (err) => {});
+```
+
+### Cleanup
+
+```typescript
+ws.unsubscribe("polymarket_trades");
+ws.disconnect();
+```
 
 ## JWT Auth
 
@@ -208,6 +307,15 @@ const ws = new StructWebSocket({
 
 The `pk_jwt_*` key is safe to hardcode in frontend bundles — it is useless without a valid JWT from your configured auth provider.
 
+If your JWT can rotate while a socket stays alive, prefer `getJwt` so reconnects always rebuild the URL with a fresh token:
+
+```typescript
+const ws = new StructWebSocket({
+  apiKey: "pk_jwt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
+  getJwt: () => userAccessToken,
+});
+```
+
 ## Pagination
 
 Use the `paginate` helper to iterate through all results:

package/dist/generated/polymarket.d.ts

@@ -632,7 +632,7 @@ export interface paths {
         };
         /**
          * Get tags
-         * @description Retrieve all available event tags/categories. Uses cursor-based pagination for efficient traversal.
+         * @description Retrieve all available event tags/categories. Supports both cursor-based and offset-based pagination.
          */
         get: operations["get_tags"];
         put?: never;
@@ -892,13 +892,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            confirmed_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            received_at?: number | null;
             /** Format: int64 */
-            block_index: number;
+            log_index?: number | null;
+            /** Format: int64 */
+            block_index?: number | null;
             trader: components["schemas"]["TraderInfo"];
             operator: string;
             approved: boolean;
@@ -913,13 +915,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             assertion_id: string;
             caller: string;
@@ -935,13 +939,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             assertion_id: string;
             domain_id: string;
@@ -967,13 +973,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            confirmed_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            received_at?: number | null;
             /** Format: int64 */
-            block_index: number;
+            log_index?: number | null;
+            /** Format: int64 */
+            block_index?: number | null;
             oracle_contract: string;
             assertion_id: string;
             bond_recipient: string;
@@ -1052,14 +1060,16 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
-            order_hash: string;
+            block_index?: number | null;
+            order_hash?: string | null;
             question?: string | null;
             image_url?: string | null;
             slug?: string | null;
@@ -1137,13 +1147,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             oracle: string;
@@ -1471,13 +1483,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            confirmed_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            received_at?: number | null;
             /** Format: int64 */
-            block_index: number;
+            log_index?: number | null;
+            /** Format: int64 */
+            block_index?: number | null;
             trader: components["schemas"]["TraderInfo"];
             condition_id?: string | null;
             question?: string | null;
@@ -1497,13 +1511,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             proposed_outcome?: string | null;
@@ -1517,16 +1533,18 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
-            order_hash: string;
+            block_index?: number | null;
+            order_hash?: string | null;
             trader: components["schemas"]["TraderInfo"];
-            taker: string;
+            taker?: string | null;
             side: string;
             condition_id?: string | null;
             position_id: string;
@@ -1546,11 +1564,11 @@ export interface components {
             /** Format: double */
             probability?: number | null;
             /** Format: double */
-            fee: number;
+            fee?: number | null;
             /** Format: double */
-            fee_shares: number;
+            fee_shares?: number | null;
             /** Format: double */
-            fee_pct: number;
+            fee_pct?: number | null;
             exchange: components["schemas"]["PolymarketExchange"];
         };
         OrderbookHistoryRow: {
@@ -1907,6 +1925,8 @@ export interface components {
              * @description Outcome index (0 = Yes, 1 = No for binary)
              */
             outcome_index: number;
+            /** @description Outcome name (e.g. "Yes", "No") — enriched from market metadata */
+            outcome?: string | null;
             /** @description Amount of shares created/burned/redeemed for this position */
             amount: string;
         };
@@ -2001,13 +2021,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             trader: components["schemas"]["TraderInfo"];
             /** @description NegRisk umbrella market ID */
             market_id: string;
@@ -2058,13 +2080,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             proposed_outcome?: string | null;
@@ -2078,13 +2102,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            confirmed_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            received_at?: number | null;
             /** Format: int64 */
-            block_index: number;
+            log_index?: number | null;
+            /** Format: int64 */
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             question?: string | null;
@@ -2097,13 +2123,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             creator: string;
@@ -2120,13 +2148,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             question?: string | null;
@@ -2139,13 +2169,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            confirmed_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            received_at?: number | null;
             /** Format: int64 */
-            block_index: number;
+            log_index?: number | null;
+            /** Format: int64 */
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             question?: string | null;
@@ -2158,13 +2190,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             /** Format: int64 */
@@ -2180,13 +2214,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             question?: string | null;
@@ -2199,13 +2235,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            confirmed_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            received_at?: number | null;
             /** Format: int64 */
-            block_index: number;
+            log_index?: number | null;
+            /** Format: int64 */
+            block_index?: number | null;
             oracle_contract: string;
             condition_id: string;
             question?: string | null;
@@ -2218,13 +2256,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             trader: components["schemas"]["TraderInfo"];
             condition_id?: string | null;
             outcome?: string | null;
@@ -2247,13 +2287,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
+            /** Format: int64 */
+            confirmed_at?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            received_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            log_index?: number | null;
             /** Format: int64 */
-            block_index: number;
+            block_index?: number | null;
             condition_id: string;
             token0: string;
             token1: string;
@@ -2310,13 +2352,15 @@ export interface components {
             id: string;
             hash: string;
             /** Format: int64 */
-            block: number;
+            block?: number | null;
             /** Format: int64 */
-            confirmed_at: number;
+            confirmed_at?: number | null;
             /** Format: int64 */
-            log_index: number;
+            received_at?: number | null;
             /** Format: int64 */
-            block_index: number;
+            log_index?: number | null;
+            /** Format: int64 */
+            block_index?: number | null;
             trader: components["schemas"]["TraderInfo"];
             condition_id?: string | null;
             question?: string | null;
@@ -4147,6 +4191,8 @@ export interface operations {
             query?: {
                 /** @description Results limit (default: 10, max: 250) */
                 limit?: number;
+                /** @description Offset-based pagination (number of results to skip). Takes precedence over pagination_key. */
+                offset?: number;
                 /** @description Cursor-based pagination key */
                 pagination_key?: string;
             };