@structbuild/sdk 0.2.11 → 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
 ```
 
@@ -45,64 +43,113 @@ const client = new StructClient({
 
 ```typescript
 const markets = await client.markets.getMarkets({ limit: 10 });
-const market = await client.markets.getMarket({ condition_id: "0x..." });
-const marketBySlug = await client.markets.getMarketBySlug({ slug: "will-x-happen" });
-const trades = await client.markets.getTrades({ condition_id: "0x..." });
-const candles = await client.markets.getCandlestick({ condition_id: "0x...", timeframe: "1d", interval: "1h" });
+const market = await client.markets.getMarket({ conditionId: "0x..." });
+const marketBySlug = await client.markets.getMarketBySlug({ marketSlug: "will-x-happen" });
+const trades = await client.markets.getTrades({ condition_ids: "0x..." });
+const candles = await client.markets.getCandlestick({ condition_id: "0x...", resolution: "1h" });
+const chart = await client.markets.getMarketChart({ condition_id: "0x..." });
 const metrics = await client.markets.getMarketMetrics({ condition_id: "0x..." });
 const volumeChart = await client.markets.getMarketVolumeChart({ condition_id: "0x..." });
+const priceJumps = await client.markets.getPriceJumps();
 ```
 
 ### Events
 
 ```typescript
 const events = await client.events.getEvents({ limit: 10 });
-const event = await client.events.getEvent({ id: "123" });
+const event = await client.events.getEvent({ identifier: "123" });
 const eventBySlug = await client.events.getEventBySlug({ slug: "us-election" });
-const eventMetrics = await client.events.getEventMetrics({ event_id: "123" });
+const eventMetrics = await client.events.getEventMetrics({ event_slug: "us-election", timeframe: "24h" });
+const outcomes = await client.events.getEventOutcomes({ event_slug: "us-election" });
+const chart = await client.events.getEventChart({ event_slug: "us-election" });
 ```
 
 ### Trader / Portfolio
 
 ```typescript
-const portfolio = await client.trader.getPortfolio({ address: "0x..." });
-const positions = await client.trader.getPortfolioPositions({ address: "0x..." });
 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 pnlCalendar = await client.trader.getTraderPnlCalendar({ address: "0x..." });
 const volumeChart = await client.trader.getTraderVolumeChart({ address: "0x..." });
+const leaderboard = await client.trader.getGlobalPnl();
 ```
 
 ### Holders
 
 ```typescript
 const marketHolders = await client.holders.getMarketHolders({ condition_id: "0x..." });
-const eventHolders = await client.holders.getEventHolders({ event_slug: "us-election" });
-const positionHolders = await client.holders.getPositionHolders({ position_id: "123" });
+const positionHolders = await client.holders.getPositionHolders({ positionId: "123" });
 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();
 ```
 
-### 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();
+const tag = await client.tags.getTag({ identifier: "politics" });
 const bonds = await client.bonds.getBonds();
 ```
 
+### Trade Types
+
+Trade endpoints (`getTrades`, `getTraderTrades`) return a discriminated union of all on-chain event types. Use the `trade_type` field to narrow:
+
+```typescript
+import type { Trade, MarketTrade, OracleEvent, TradeEventType } from "@structbuild/sdk";
+
+const { data: trades } = await client.markets.getTrades();
+
+for (const trade of trades) {
+  switch (trade.trade_type) {
+    case "OrderFilled":
+    case "OrdersMatched":
+      console.log(trade.price, trade.usd_amount, trade.shares_amount);
+      break;
+    case "Redemption":
+      console.log(trade.winning_outcome_index, trade.position_details);
+      break;
+    case "Merge":
+    case "Split":
+      console.log(trade.usd_amount, trade.position_details);
+      break;
+    case "Resolution":
+      console.log(trade.payout_numerators);
+      break;
+  }
+}
+```
+
+The SDK exports convenience sub-unions for common filtering:
+
+- **`MarketTrade`** — actual on-chain trades: `OrderFilled`, `OrdersMatched`, `Redemption`, `Merge`, `Split`, `PositionsConverted`, `Cancelled`, `RegisterToken`, `Approval`
+- **`OracleEvent`** — protocol lifecycle events: `Initialization`, `Proposal`, `Dispute`, `Settled`, `Resolution`, `ConditionResolution`, `Reset`, `Flag`, `Unflag`, `Pause`, `Unpause`, `ManualResolution`, `NegRiskOutcomeReported`
+- **`TradeEventType`** — string literal union of all `trade_type` values for autocomplete
+
+Individual schemas are also exported: `OrderFilledTrade`, `RedemptionTrade`, `MergeTrade`, `SplitTrade`, `CancelledTrade`, `PositionsConvertedTrade`, `RegisterTokenTrade`, `ApprovalTrade`, and all oracle event types.
+
 ### 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();
@@ -114,30 +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";
+import { StructWebSocket } from "@structbuild/sdk";
 
-function handleWebhook(payload: FirstTradePayload) {
-  console.log(payload.trader, payload.price, payload.side);
-}
+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;
+});
+```
+
+### 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 payload types: `FirstTradePayload`, `GlobalPnlPayload`, `MarketPnlPayload`, `EventPnlPayload`, `PositionPnlPayload`, `ConditionMetricsPayload`, `EventMetricsPayload`, `PositionMetricsPayload`, `VolumeMilestonePayload`, `EventVolumeMilestonePayload`, `PositionVolumeMilestonePayload`, `ProbabilitySpikePayload`.
+### 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
 
@@ -161,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:
@@ -184,7 +339,7 @@ for await (const market of paginate(
 import { HttpError, TimeoutError, NetworkError } from "@structbuild/sdk";
 
 try {
-  await client.markets.getMarket({ condition_id: "0x..." });
+  await client.markets.getMarket({ conditionId: "0x..." });
 } catch (error) {
   if (error instanceof HttpError) {
     console.log(error.status, error.body);