{ "openapi": "3.1.0", "info": { "title": "Polymarket Webhook API", "description": "", "license": { "name": "" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.struct.to/v1" } ], "paths": { "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Retrieve a paginated list of your webhook subscriptions with optional filtering", "operationId": "list_webhooks", "parameters": [ { "name": "limit", "in": "query", "description": "Results per page (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "status", "in": "query", "description": "Filter by status: active, paused", "required": false, "schema": { "$ref": "#/components/schemas/WebhookStatusBody" } }, { "name": "event", "in": "query", "description": "Filter by event type", "required": false, "schema": { "$ref": "#/components/schemas/PolymarketWebhookEvent" } } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponseBody" } } } }, "401": { "description": "Missing or invalid API key" } }, "security": [ { "api_key": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Create a new webhook subscription for real-time event notifications", "operationId": "create_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequestBody" } } }, "required": true }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Invalid request (malformed URL, invalid filters, etc.)" }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Insufficient credits" }, "429": { "description": "Rate limit exceeded (max 100 webhooks per user)" } }, "security": [ { "api_key": [] } ] } }, "/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "List event types", "description": "Retrieve all available webhook event types with descriptions, categories, credits cost, and applicable filter fields", "operationId": "list_events", "responses": { "200": { "description": "List of available event types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" } } } }, "401": { "description": "Missing or invalid API key" } }, "security": [ { "api_key": [] } ] } }, "/webhooks/{webhook_id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook", "description": "Retrieve details of a specific webhook by its ID", "operationId": "get_webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Webhook not found or not owned by user" } }, "security": [ { "api_key": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update webhook", "description": "Update an existing webhook's URL, filters, or status", "operationId": "update_webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequestBody" } } }, "required": true }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Webhook not found or not owned by user" } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "description": "Permanently delete a webhook subscription", "operationId": "delete_webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookResponse" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Webhook not found or not owned by user" } }, "security": [ { "api_key": [] } ] } }, "/webhooks/{webhook_id}/logs": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook delivery logs", "description": "Returns delivery logs for a webhook (newest first), including the send time and the payload we delivered (large payloads and error messages may be truncated). Retained for 7 days. Keyset-paginated via `pagination_key`.", "operationId": "get_webhook_logs", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook UUID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Results per page (default 10, max 250)", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "from", "in": "query", "description": "Start time, Unix milliseconds (inclusive)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "description": "End time, Unix milliseconds (inclusive)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "pagination_key", "in": "query", "description": "Cursor from a previous response", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery logs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookLogsResponseBody" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Webhook not found or not owned by user" } }, "security": [ { "api_key": [] } ] } }, "/webhooks/{webhook_id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate webhook secret", "description": "Generate a new HMAC secret for a webhook. The new secret is returned once — store it securely", "operationId": "rotate_secret", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "New secret generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateSecretResponse" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Webhook not found or not owned by user" } }, "security": [ { "api_key": [] } ] } }, "/webhooks/{webhook_id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test webhook", "description": "Send a test payload to the webhook URL to verify connectivity", "operationId": "test_webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test delivery completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponseBody" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Webhook not found or not owned by user" } }, "security": [ { "api_key": [] } ] } } }, "components": { "schemas": { "AssertionDisputedEvent": { "type": "object", "description": "V3 UMA OOv3: an assertion was disputed.", "required": [ "id", "hash", "oracle_contract", "assertion_id", "caller", "disputer" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "assertion_id": { "type": "string" }, "caller": { "type": "string" }, "disputer": { "type": "string" }, "condition_id": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "AssertionMadeEvent": { "type": "object", "description": "V3 UMA OOv3: a new assertion (resolution proposal) was made.", "required": [ "id", "hash", "oracle_contract", "assertion_id", "domain_id", "claim", "asserter", "callback_recipient", "escalation_manager", "caller", "expiration_time", "currency", "bond", "identifier" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "assertion_id": { "type": "string" }, "domain_id": { "type": "string" }, "claim": { "type": "string" }, "asserter": { "type": "string" }, "callback_recipient": { "type": "string" }, "escalation_manager": { "type": "string" }, "caller": { "type": "string" }, "expiration_time": { "type": "integer", "format": "int64", "minimum": 0 }, "currency": { "type": "string" }, "bond": { "type": "string" }, "identifier": { "type": "string" }, "condition_id": { "type": [ "string", "null" ] }, "proposed_outcome": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "AssertionSettledEvent": { "type": "object", "description": "V3 UMA OOv3: an assertion liveness period expired and was settled.", "required": [ "id", "hash", "oracle_contract", "assertion_id", "bond_recipient", "disputed", "settlement_resolution", "settle_caller" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "assertion_id": { "type": "string" }, "bond_recipient": { "type": "string" }, "disputed": { "type": "boolean" }, "settlement_resolution": { "type": "boolean" }, "settle_caller": { "type": "string" }, "condition_id": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "AssetPriceTickFilters": { "type": "object", "description": "Subscription filters for the `asset_price_tick` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "asset_symbols": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WebhookAssetSymbol" }, "description": "Restrict to these crypto assets. Empty = all assets." } } }, "AssetPriceTickPayload": { "type": "object", "description": "Webhook payload for an asset price tick.", "required": [ "symbol", "price", "timestamp_ms" ], "properties": { "symbol": { "$ref": "#/components/schemas/WebhookAssetSymbol", "description": "Asset symbol" }, "price": { "type": "number", "format": "double", "description": "Current price from the Chainlink feed" }, "timestamp_ms": { "type": "integer", "format": "int64", "description": "Tick timestamp as reported by the WebSocket feed (milliseconds since epoch)" } } }, "AssetPriceWindowUpdateFilters": { "type": "object", "description": "Subscription filters for the `asset_price_window_update` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "asset_symbols": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WebhookAssetSymbol" }, "description": "Restrict to these crypto assets. Empty = all assets.", "maxItems": 500 }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AssetWindowFilterTimeframe" }, "description": "Restrict to these candle sizes. Empty = all sizes.", "maxItems": 500 } } }, "AssetPriceWindowUpdatePayload": { "type": "object", "description": "Webhook payload for an asset price window open or close.", "required": [ "symbol", "variant", "start_time", "end_time", "open_price", "close_price", "update_type" ], "properties": { "symbol": { "$ref": "#/components/schemas/WebhookAssetSymbol", "description": "Asset symbol" }, "variant": { "$ref": "#/components/schemas/AssetPriceWindowVariant", "description": "Time-window variant" }, "start_time": { "type": "integer", "format": "int64", "description": "Window start timestamp (milliseconds since epoch)" }, "end_time": { "type": "integer", "format": "int64", "description": "Window end timestamp (milliseconds since epoch)" }, "open_price": { "type": "number", "format": "double", "description": "Opening price at start_time" }, "close_price": { "type": "number", "format": "double", "description": "Closing price at end_time (0.0 on an \"open\" update — not yet available)" }, "update_type": { "$ref": "#/components/schemas/AssetPriceWindowUpdateType", "description": "\"open\" when the window starts, \"close\" when the window is complete" } } }, "AssetPriceWindowUpdateType": { "type": "string", "description": "Whether this update is the open or the close of a candle.", "enum": [ "open", "close" ] }, "AssetPriceWindowVariant": { "type": "string", "description": "Time-window variant emitted by the asset price window stream.", "enum": [ "5m", "15m", "1h", "4h", "1d", "24h" ] }, "AssetWindowFilterTimeframe": { "type": "string", "description": "Candle sizes accepted by `asset_price_window_update.timeframes`.", "enum": [ "5m", "15m", "1h", "4h", "1d", "24h" ] }, "CategoryPnlPayload": { "type": "object", "description": "Category PnL webhook payload.", "required": [ "timeframe" ], "properties": { "trader": { "type": [ "string", "null" ], "description": "Trader wallet address." }, "category": { "type": [ "string", "null" ], "description": "Category." }, "timeframe": { "type": "string", "description": "Aggregation timeframe: \"1d\", \"7d\", \"30d\", or \"lifetime\"" }, "realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Realized pnl in USD." }, "markets_in_category": { "type": [ "integer", "null" ], "format": "int64", "description": "Markets in this category." }, "markets_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Markets traded." }, "outcomes_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of outcomes traded." }, "total_buys": { "type": [ "integer", "null" ], "format": "int64", "description": "Total buy count." }, "total_sells": { "type": [ "integer", "null" ], "format": "int64", "description": "Total sell count." }, "total_redemptions": { "type": [ "integer", "null" ], "format": "int64", "description": "Total redemption count." }, "total_merges": { "type": [ "integer", "null" ], "format": "int64", "description": "Total merge count." }, "total_splits": { "type": [ "integer", "null" ], "format": "int64", "description": "Total split count." }, "total_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total volume in USD." }, "buy_usd": { "type": [ "number", "null" ], "format": "double", "description": "Buy in USD." }, "sell_usd": { "type": [ "number", "null" ], "format": "double", "description": "Sell in USD." }, "redemption_usd": { "type": [ "number", "null" ], "format": "double", "description": "Redemption in USD." }, "merge_usd": { "type": [ "number", "null" ], "format": "double", "description": "Merge in USD." }, "convert_collateral_usd": { "type": [ "number", "null" ], "format": "double", "description": "Convert collateral in USD." }, "split_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Split volume in USD." }, "total_fees": { "type": [ "number", "null" ], "format": "double", "description": "Total fees amount." }, "total_shares_bought": { "type": [ "number", "null" ], "format": "double", "description": "Total shares bought." }, "markets_won": { "type": [ "integer", "null" ], "format": "int64", "description": "Markets won." }, "markets_lost": { "type": [ "integer", "null" ], "format": "int64", "description": "Markets lost." }, "market_win_rate_pct": { "type": [ "number", "null" ], "format": "double", "description": "Market win rate percent." }, "avg_hold_time_seconds": { "type": [ "number", "null" ], "format": "double", "description": "Average hold time seconds." }, "best_trade_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Best trade pnl in USD." }, "best_trade_condition_id": { "type": [ "string", "null" ], "description": "Best trade condition id." }, "worst_trade_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Worst trade pnl in USD." }, "worst_trade_condition_id": { "type": [ "string", "null" ], "description": "Worst trade condition id." }, "total_wins_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total wins in USD." }, "total_losses_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total losses in USD." }, "avg_win_usd": { "type": [ "number", "null" ], "format": "double", "description": "Average win in USD." }, "avg_loss_usd": { "type": [ "number", "null" ], "format": "double", "description": "Average loss in USD." }, "profit_factor": { "type": [ "number", "null" ], "format": "double", "description": "Profit factor." }, "first_trade_at": { "type": [ "integer", "null" ], "format": "int64", "description": "First trade timestamp." }, "last_trade_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Last trade timestamp." } } }, "CloseToBondFilters": { "type": "object", "description": "Subscription filters for the `close_to_bond` event. At least one of\n`min_price` or `max_price` is required (enforced at runtime).", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets carrying any of these tags or category names (case-insensitive). Empty = all.", "maxItems": 500 }, "series_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets in any of these series (by slug, case-insensitive). Empty = all.", "maxItems": 500 }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Trigger when the traded position's price is ≥ this value (e.g. 0.95 for a near-certain outcome). At least one of `min_price` or `max_price` must be set.", "maximum": 1, "minimum": 0 }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Trigger when the traded position's price is ≤ this value (e.g. 0.05 for a near-zero outcome).", "maximum": 1, "minimum": 0 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "position_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome token IDs.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets in these events.", "maxItems": 500 }, "outcomes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome names (e.g. \\[\"Yes\", \"No\"\\]).", "maxItems": 500 }, "position_outcome_indices": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Restrict by outcome index. 0 = Yes/Up, 1 = No. Position 0 usually represents the Up/Yes side in binary markets.", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "CloseToBondPayload": { "type": "object", "description": "Close-to-bond webhook payload", "required": [ "trader", "taker", "position_id", "trade_id", "hash", "block", "confirmed_at", "amount_usd", "shares_amount", "fee", "side", "price", "bond_side", "threshold" ], "properties": { "trader": { "type": "string", "description": "Trader address (the limit-order maker)" }, "taker": { "type": "string", "description": "Taker address (the order filler — often the exchange contract)" }, "position_id": { "type": "string", "description": "Position ID (ERC1155 token ID)" }, "condition_id": { "type": [ "string", "null" ], "description": "Condition ID (parent market)" }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name (e.g. \"Yes\", \"No\")" }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index (0 = Yes/Up, 1 = No). Position 0 usually represents Yes/Up.", "minimum": 0 }, "question": { "type": [ "string", "null" ], "description": "Market question" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug" }, "trade_id": { "type": "string", "description": "Trade ID" }, "hash": { "type": "string", "description": "Transaction hash" }, "block": { "type": "integer", "format": "int64", "description": "Block number", "minimum": 0 }, "confirmed_at": { "type": "integer", "format": "int64", "description": "Confirmed timestamp (Unix seconds)", "minimum": 0 }, "amount_usd": { "type": "number", "format": "double", "description": "USD size of the trade" }, "shares_amount": { "type": "number", "format": "double", "description": "Outcome shares traded" }, "fee": { "type": "number", "format": "double", "description": "Fee paid (USD)" }, "side": { "type": "string", "description": "Trade side (\"Buy\" or \"Sell\")" }, "price": { "type": "number", "format": "double", "description": "Price per share (0.0–1.0) — the value that triggered the notification" }, "bond_side": { "type": "string", "description": "Which bond zone was entered: `\"high\"` (price ≥ `min_price`) or `\"low\"` (price ≤ `max_price`)" }, "threshold": { "type": "number", "format": "double", "description": "The price threshold from the subscriber's filter that was breached" } } }, "ConditionHolderMetricsFilters": { "type": "object", "properties": { "condition_ids": { "type": "array", "items": { "type": "string" }, "description": "Market condition IDs to match." }, "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." } } }, "ConditionHolderMetricsPayload": { "type": "object", "required": [ "ts", "block", "condition_id", "holder_count" ], "properties": { "ts": { "type": "integer", "format": "int32", "description": "Unix timestamp in seconds.", "minimum": 0 }, "block": { "type": "integer", "format": "int64", "description": "Block number." }, "condition_id": { "type": "string", "description": "Market condition ID." }, "holder_count": { "type": "integer", "format": "int32", "description": "Number of holders." } } }, "ConditionMetricsPayload": { "type": "object", "description": "Payload delivered when a market's volume or transaction metrics cross a configured threshold", "properties": { "condition_id": { "type": [ "string", "null" ], "description": "Market condition ID" }, "timeframe": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Timeframe values accepted by webhook metric, milestone, spike, and asset-price filters.", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "6h", "1d", "24h", "7d", "30d", "lifetime" ] } ], "description": "Aggregation window" }, "volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total trading volume in USD for this timeframe" }, "shares_volume": { "type": [ "number", "null" ], "format": "double", "description": "Total shares/contracts volume for this timeframe" }, "builder_usd_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed trading volume in USD" }, "builder_shares_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed shares/contracts volume" }, "fees": { "type": [ "number", "null" ], "format": "double", "description": "Total fees collected in USD" }, "builder_fees": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed fees in USD" }, "txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Total number of transactions" }, "builder_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Builder-attributed transaction count" }, "unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique traders" }, "unique_makers": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique makers" }, "unique_takers": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique takers" }, "unique_builder_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique builder-attributed traders" } } }, "ConditionResolutionEvent": { "type": "object", "description": "CTF ConditionResolution: positions become redeemable on the Conditional Tokens contract.", "required": [ "id", "hash", "oracle_contract", "condition_id", "oracle" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "oracle": { "type": "string" }, "proposed_outcome": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "CreateWebhookRequestBody": { "type": "object", "description": "Request body for creating a webhook", "required": [ "url", "event" ], "properties": { "url": { "type": "string", "description": "Destination URL for webhook deliveries (must be HTTPS)" }, "event": { "$ref": "#/components/schemas/PolymarketWebhookEvent", "description": "Event to subscribe to" }, "secret": { "type": [ "string", "null" ], "description": "Optional secret for HMAC signature verification" }, "filters": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebhookFiltersBody", "description": "Optional filters for event matching" } ] }, "description": { "type": [ "string", "null" ], "description": "Optional description/name" } } }, "DeleteWebhookResponse": { "type": "object", "description": "Delete webhook response", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "description": "Whether the webhook was deleted." } } }, "DirtyKind": { "type": "string", "description": "What triggered a position update. Each value is serialised as a\nlowercase string in the `dirty_kinds` array on every payload, and\nthe same values are accepted as a subscribe-time filter on rooms\nthat expose one.\n\n* `trade` — a buy, sell, merge, split, redemption, or NegRisk\n convert landed for the position\n* `price` — the outcome price moved (mark-to-market refresh)\n* `window` — a 1d / 7d / 30d rolling window boundary was crossed\n* `position_resolved` — the market that owns this position resolved\n on this update\n* `market_resolved` — the market itself resolved (stamped on\n `MarketRollup` rows for lifetime holders who never redeemed).\n Carried on the resolution tick stream and on any full-row update\n that bundles a resolution with a trade.", "enum": [ "trade", "price", "window", "position_resolved", "market_resolved" ] }, "DisputePriceEvent": { "type": "object", "description": "V2 UMA OOv2: a proposed price was disputed.", "required": [ "id", "hash", "oracle_contract", "requester", "proposer", "disputer", "identifier", "timestamp", "ancillary_data", "proposed_price" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "requester": { "type": "string" }, "proposer": { "type": "string" }, "disputer": { "type": "string" }, "identifier": { "type": "string" }, "timestamp": { "type": "string" }, "ancillary_data": { "type": "string" }, "proposed_price": { "type": "integer", "format": "int64" }, "condition_id": { "type": [ "string", "null" ] }, "proposed_outcome": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "EventHolderMetricsFilters": { "type": "object", "properties": { "event_slugs": { "type": "array", "items": { "type": "string" }, "description": "Event slugs to match." }, "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." } } }, "EventHolderMetricsPayload": { "type": "object", "required": [ "ts", "block", "event_slug", "holder_count" ], "properties": { "ts": { "type": "integer", "format": "int32", "description": "Unix timestamp in seconds.", "minimum": 0 }, "block": { "type": "integer", "format": "int64", "description": "Block number." }, "event_slug": { "type": "string", "description": "Event slug." }, "holder_count": { "type": "integer", "format": "int32", "description": "Number of holders." } } }, "EventLiquidityFilters": { "type": "object", "description": "Subscription filters for the `event_liquidity` event.\n\nAt least one of `min_liquidity_usd`, `max_liquidity_usd`, or `one_shot` must be set.\nThresholds are edge-triggered: a callback fires when liquidity crosses the threshold,\nthen re-arms once it crosses back (unless `one_shot`).", "required": [ "event_slugs" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery." }, "min_liquidity_usd": { "type": [ "number", "null" ], "format": "double", "description": "Fire when total liquidity crosses up through this USD value." }, "max_liquidity_usd": { "type": [ "number", "null" ], "format": "double", "description": "Fire when total liquidity crosses down through this USD value." }, "event_slugs": { "type": "array", "items": { "type": "string" }, "description": "**Required.** Events to receive liquidity updates for.", "maxItems": 500, "minItems": 1 } } }, "EventLiquidityPayload": { "type": "object", "description": "Event liquidity webhook payload.", "required": [ "event_slug", "liquidity_usd", "threshold_usd", "direction", "liquidity_updated_at" ], "properties": { "event_slug": { "type": "string", "description": "Event slug." }, "liquidity_usd": { "type": "number", "format": "double", "description": "Total order-book liquidity in USD at the time of firing." }, "threshold_usd": { "type": "number", "format": "double", "description": "The threshold (USD) that was crossed." }, "direction": { "type": "string", "description": "`\"above\"` when liquidity crossed up through `min_liquidity_usd`,\n`\"below\"` when it crossed down through `max_liquidity_usd`." }, "liquidity_updated_at": { "type": "integer", "format": "int64", "description": "Update timestamp (Unix millis)." } } }, "EventMetricsFilters": { "type": "object", "description": "Subscription filters for the `event_metrics` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these events. Empty = all events.", "maxItems": 500 }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MetricFilterTimeframe" }, "description": "Restrict to these aggregation windows.", "maxItems": 500 }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when aggregated event volume ≥ this value (USD)." }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maximum volume USD." }, "min_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum transactions." }, "min_unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum unique traders." }, "min_fees": { "type": [ "number", "null" ], "format": "double", "description": "Minimum fees." }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "EventMetricsPayload": { "type": "object", "description": "Payload delivered when an event's aggregated volume or transaction metrics cross a configured threshold", "properties": { "event_slug": { "type": [ "string", "null" ], "description": "Event slug" }, "timeframe": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Timeframe values accepted by webhook metric, milestone, spike, and asset-price filters.", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "6h", "1d", "24h", "7d", "30d", "lifetime" ] } ], "description": "Aggregation window" }, "volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total aggregated volume across all markets in the event (USD)" }, "shares_volume": { "type": [ "number", "null" ], "format": "double", "description": "Total aggregated shares/contracts volume across all markets in the event" }, "builder_usd_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed aggregated volume in USD" }, "builder_shares_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed aggregated shares/contracts volume" }, "fees": { "type": [ "number", "null" ], "format": "double", "description": "Total fees collected in USD" }, "builder_fees": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed fees in USD" }, "txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Total number of transactions" }, "builder_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Builder-attributed transaction count" }, "unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique traders" }, "unique_makers": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique makers" }, "unique_takers": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique takers" }, "unique_builder_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique builder-attributed traders" } } }, "EventVolumeMilestoneFilters": { "type": "object", "description": "Subscription filters for the `event_volume_milestone` event.", "required": [ "timeframes" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "timeframes": { "type": "array", "items": { "$ref": "#/components/schemas/MetricFilterTimeframe" }, "description": "**Required.** Aggregation windows to monitor.", "maxItems": 500, "minItems": 1 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these events.", "maxItems": 500 }, "milestone_amounts": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" }, "description": "Specific USD milestones to trigger on.", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "EventVolumeMilestonePayload": { "type": "object", "description": "Event volume milestone webhook payload", "required": [ "event_slug", "timeframe", "milestone_usd", "current_volume_usd", "fees", "txns" ], "properties": { "event_slug": { "type": "string", "description": "Event slug." }, "timeframe": { "type": "string", "description": "Metric timeframe." }, "milestone_usd": { "type": "number", "format": "double", "description": "Milestone amount reached (USD)" }, "current_volume_usd": { "type": "number", "format": "double", "description": "Current volume (USD) that triggered the milestone" }, "fees": { "type": "number", "format": "double", "description": "Total fees collected in this timeframe" }, "txns": { "type": "integer", "format": "int64", "description": "Total transactions in this timeframe" } } }, "EventVolumeSpikeFilters": { "type": "object", "description": "Subscription filters for the `event_volume_spike` event. `spike_ratio` is required.", "required": [ "spike_ratio" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "spike_ratio": { "type": "number", "format": "double", "description": "**Required.** Multiplier threshold (must be > 1.0). Fires when current volume >= snapshot × ratio.", "exclusiveMinimum": 1 }, "window_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Force snapshot reset after this many seconds (max 600 / 10 minutes).", "maximum": 600, "minimum": 1 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these events.", "maxItems": 500 }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/VolumeSpikeFilterTimeframe" }, "description": "Restrict to these aggregation windows.", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "EventVolumeSpikePayload": { "type": "object", "description": "Event volume spike webhook payload", "required": [ "event_slug", "timeframe", "current_volume_usd", "snapshot_volume_usd", "delta_volume_usd", "spike_pct", "txns", "fees" ], "properties": { "event_slug": { "type": "string", "description": "Event slug." }, "event_title": { "type": [ "string", "null" ], "description": "Event title." }, "image_url": { "type": [ "string", "null" ], "description": "Image URL." }, "timeframe": { "type": "string", "description": "Metric timeframe." }, "current_volume_usd": { "type": "number", "format": "double", "description": "Current aggregated event volume at the time of the spike (USD)" }, "snapshot_volume_usd": { "type": "number", "format": "double", "description": "Volume at the snapshot baseline (USD)" }, "delta_volume_usd": { "type": "number", "format": "double", "description": "New volume since the snapshot that triggered this notification (USD)" }, "spike_pct": { "type": "number", "format": "double", "description": "Volume growth as a percentage of the snapshot (e.g. 200.0 means volume tripled)" }, "txns": { "type": "integer", "format": "int64", "description": "Total transactions in this timeframe" }, "fees": { "type": "number", "format": "double", "description": "Total fees in this timeframe" } } }, "ExitMarkersPayload": { "type": "object", "description": "Exit Markers webhook payload — one position open->closed transition.", "required": [ "trader", "position_id", "condition_id", "event_slug", "market_slug", "title", "question", "image_url", "outcome", "pnl_usd", "pnl_pct", "cost_basis_usd", "reason", "block", "ts" ], "properties": { "trader": { "type": "string", "description": "Trader wallet address." }, "position_id": { "type": "string", "description": "Outcome token ID." }, "condition_id": { "type": "string", "description": "Market condition ID." }, "event_slug": { "type": "string", "description": "Event slug." }, "market_slug": { "type": "string", "description": "Market slug." }, "title": { "type": "string", "description": "Title." }, "question": { "type": "string", "description": "Market question." }, "image_url": { "type": "string", "description": "Image URL." }, "outcome": { "type": "string", "description": "Outcome name." }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index.", "minimum": 0 }, "pnl_usd": { "type": "number", "format": "double", "description": "Pnl in USD." }, "pnl_pct": { "type": "number", "format": "double", "description": "Pnl percent." }, "cost_basis_usd": { "type": "number", "format": "double", "description": "Cost basis in USD." }, "reason": { "type": "string", "description": "resolved_win | resolved_loss | sold_win | sold_loss" }, "block": { "type": "integer", "format": "int64", "description": "Block number." }, "ts": { "type": "integer", "format": "int32", "description": "Exit time, unix seconds.", "minimum": 0 } } }, "FirstTradePayload": { "type": "object", "description": "Payload delivered when a tracked trader executes their first-ever trade on Polymarket", "required": [ "trader", "taker", "trader_info", "position_id", "trade_id", "hash", "block", "confirmed_at", "amount_usd", "shares_amount", "fee", "side", "price", "exchange", "trade_type" ], "properties": { "trader": { "type": "string", "description": "Limit-order maker wallet address (lowercase)" }, "taker": { "type": "string", "description": "Order filler wallet address (lowercase)" }, "trader_info": { "$ref": "#/components/schemas/WebhookTraderInfo", "description": "Maker trader display metadata (address + name / pseudonym / image / x / verified)" }, "position_id": { "type": "string", "description": "ERC-1155 outcome token ID" }, "condition_id": { "type": [ "string", "null" ], "description": "Parent market condition ID (0x-prefixed hex)" }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name (e.g. \"Yes\", \"No\")" }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index: 0 = Yes/Up, 1 = No", "minimum": 0 }, "question": { "type": [ "string", "null" ], "description": "Market question text" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Parent event slug" }, "image_url": { "type": [ "string", "null" ], "description": "Market image URL" }, "trade_id": { "type": "string", "description": "Unique trade identifier" }, "hash": { "type": "string", "description": "Transaction hash" }, "block": { "type": "integer", "format": "int64", "description": "Block number", "minimum": 0 }, "confirmed_at": { "type": "integer", "format": "int64", "description": "Block confirmation timestamp (Unix seconds)", "minimum": 0 }, "amount_usd": { "type": "number", "format": "double", "description": "USD size of the trade (6 decimal places)" }, "shares_amount": { "type": "number", "format": "double", "description": "Outcome shares traded (6 decimal places)" }, "fee": { "type": "number", "format": "double", "description": "Fee paid in USD (6 decimal places)" }, "side": { "oneOf": [ { "type": "string", "description": "Trade direction for trade-fill webhook payloads.", "enum": [ "Buy", "Sell" ] } ], "description": "Trade direction" }, "price": { "type": "number", "format": "double", "description": "Outcome token price (0.0–1.0)", "maximum": 1, "minimum": 0 }, "exchange": { "oneOf": [ { "type": "string", "description": "Polymarket exchange contract types.", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "CTFExchangeV2", "NegRiskExchangeV2", "ComboExchange", "ComboCombinatorialModule", "ComboNegRiskModule", "Unknown" ] } ], "description": "Exchange contract that processed the trade" }, "trade_type": { "oneOf": [ { "type": "string", "description": "Trade type for trade-fill webhook payloads. Webhook events only fire on\nfill-style trades, so the only valid variants are `OrderFilled`,\n`OrdersMatched`, and `ComboExecution`.", "enum": [ "OrderFilled", "OrdersMatched", "ComboExecution" ] } ], "description": "Trade type (webhook events only fire on order fills)" } } }, "GlobalPnlPayload": { "type": "object", "description": "Global PnL webhook payload.", "required": [ "timeframe" ], "properties": { "trader": { "type": [ "string", "null" ], "description": "Trader wallet address." }, "timeframe": { "type": "string", "description": "Aggregation timeframe: \"1d\", \"7d\", \"30d\", or \"lifetime\"" }, "realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Realized PnL for the timeframe (matches REST `/pnl/global`)." }, "events_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Events traded." }, "markets_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Markets traded." }, "total_buys": { "type": [ "integer", "null" ], "format": "int64", "description": "Total buy count." }, "total_sells": { "type": [ "integer", "null" ], "format": "int64", "description": "Total sell count." }, "total_redemptions": { "type": [ "integer", "null" ], "format": "int64", "description": "Total redemption count." }, "total_merges": { "type": [ "integer", "null" ], "format": "int64", "description": "Total merge count." }, "total_splits": { "type": [ "integer", "null" ], "format": "int64", "description": "Total split count." }, "total_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total volume in USD." }, "buy_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Buy volume in USD." }, "sell_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Sell volume in USD." }, "redemption_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Redemption volume in USD." }, "merge_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Merge volume in USD." }, "convert_collateral_usd": { "type": [ "number", "null" ], "format": "double", "description": "Convert collateral in USD." }, "split_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Split volume in USD." }, "maker_rebate_count": { "type": [ "integer", "null" ], "format": "int64", "description": "Maker rebate count." }, "maker_rebate_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maker rebate in USD." }, "reward_count": { "type": [ "integer", "null" ], "format": "int64", "description": "Reward count." }, "reward_usd": { "type": [ "number", "null" ], "format": "double", "description": "Reward in USD." }, "yield_count": { "type": [ "integer", "null" ], "format": "int64", "description": "Yield count." }, "yield_usd": { "type": [ "number", "null" ], "format": "double", "description": "Yield in USD." }, "total_credit_count": { "type": [ "integer", "null" ], "format": "int64", "description": "Total credit count." }, "total_credit_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total credit in USD." }, "markets_won": { "type": [ "integer", "null" ], "format": "int64", "description": "Markets won." }, "markets_lost": { "type": [ "integer", "null" ], "format": "int64", "description": "Markets lost." }, "market_win_rate_pct": { "type": [ "number", "null" ], "format": "double", "description": "Market win rate percent." }, "total_wins_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total wins in USD." }, "total_losses_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total losses in USD." }, "avg_win_usd": { "type": [ "number", "null" ], "format": "double", "description": "Average win in USD." }, "avg_loss_usd": { "type": [ "number", "null" ], "format": "double", "description": "Average loss in USD." }, "profit_factor": { "type": [ "number", "null" ], "format": "double", "description": "Profit factor." }, "avg_hold_time_seconds": { "type": [ "number", "null" ], "format": "double", "description": "Average hold time seconds." }, "total_fees": { "type": [ "number", "null" ], "format": "double", "description": "Total fees amount." }, "best_trade_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Best trade pnl in USD." }, "best_trade_condition_id": { "type": [ "string", "null" ], "description": "Best trade condition id." }, "worst_trade_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Worst trade pnl in USD." }, "worst_trade_condition_id": { "type": [ "string", "null" ], "description": "Worst trade condition id." }, "first_trade_at": { "type": [ "integer", "null" ], "format": "int64", "description": "First trade timestamp." }, "last_trade_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Last trade timestamp." } } }, "ListEventsResponse": { "type": "object", "description": "Response for GET /v1/webhook/events", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventInfo" }, "description": "Supported webhook events." } } }, "MarketCreatedFilters": { "type": "object", "description": "Subscription filters for the `market_created` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets with these tags or category names (case-insensitive match).", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets belonging to these events.", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets (event slugs containing `updown`). Default: `false`." } } }, "MarketCreatedOutcome": { "type": "object", "description": "Outcome entry in the market created payload — mirrors `NewMarketOutcome`", "required": [ "index", "name", "position_id" ], "properties": { "index": { "type": "integer", "format": "int32", "description": "Outcome index (0 = Yes, 1 = No)", "minimum": 0 }, "name": { "type": "string", "description": "Outcome name (e.g. \"Yes\", \"No\")" }, "position_id": { "type": "string", "description": "ERC1155 position token ID" } } }, "MarketCreatedPayload": { "type": "object", "description": "Market created webhook payload — mirrors `NewMarketPayload` field-for-field", "required": [ "condition_id", "market_slug", "outcomes", "question", "description", "tags", "neg_risk" ], "properties": { "condition_id": { "type": "string", "description": "Condition ID (0x-prefixed hex, lowercase)" }, "market_slug": { "type": "string", "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug (parent event)" }, "event_id": { "type": [ "string", "null" ], "description": "Event ID" }, "event_title": { "type": [ "string", "null" ], "description": "Event title" }, "series_slug": { "type": [ "string", "null" ], "description": "Series slug" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/MarketCreatedOutcome" }, "description": "Outcomes with their position IDs, index, and name" }, "question": { "type": "string", "description": "Market question" }, "title": { "type": [ "string", "null" ], "description": "Market title (short display name)" }, "description": { "type": "string", "description": "Market description" }, "category": { "type": [ "string", "null" ], "description": "Market category (e.g. \"Sports\", \"Politics\")" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Market tags" }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL" }, "neg_risk": { "type": "boolean", "description": "Whether this is a neg-risk market" } } }, "MarketDisputedFilters": { "type": "object", "description": "Subscription filters for the `market_disputed` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets in these events.", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "MarketDisputedPayload": { "type": "object", "description": "Market-disputed webhook payload", "required": [ "dispute_kind", "disputer", "hash" ], "properties": { "condition_id": { "type": [ "string", "null" ], "description": "Condition ID (the contested market), when resolvable" }, "dispute_kind": { "type": "string", "description": "Which oracle event produced this dispute: `\"dispute_price\"` or `\"assertion_disputed\"`." }, "disputer": { "type": "string", "description": "Address that filed the dispute" }, "proposer": { "type": [ "string", "null" ], "description": "Address that made the disputed proposal/assertion, when known" }, "proposed_outcome": { "type": [ "string", "null" ], "description": "The proposed outcome that was disputed, when known (e.g. \"Yes\", \"No\")" }, "proposed_price": { "type": [ "number", "null" ], "format": "double", "description": "The proposed price (0.0–1.0) that was disputed (`DisputePrice` only)" }, "question": { "type": [ "string", "null" ], "description": "Market question" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug" }, "image_url": { "type": [ "string", "null" ], "description": "Market image URL" }, "hash": { "type": "string", "description": "Transaction hash of the dispute event" }, "block": { "type": [ "integer", "null" ], "format": "int64", "description": "Block number", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Confirmed timestamp (Unix seconds)", "minimum": 0 } } }, "MarketLiquidityFilters": { "type": "object", "description": "Subscription filters for the `market_liquidity` event.\n\nAt least one of `min_liquidity_usd`, `max_liquidity_usd`, or `one_shot` must be set.\nThresholds are edge-triggered: a callback fires when liquidity crosses the threshold,\nthen re-arms once it crosses back (unless `one_shot`).", "required": [ "condition_ids" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery." }, "min_liquidity_usd": { "type": [ "number", "null" ], "format": "double", "description": "Fire when total liquidity crosses up through this USD value." }, "max_liquidity_usd": { "type": [ "number", "null" ], "format": "double", "description": "Fire when total liquidity crosses down through this USD value." }, "condition_ids": { "type": "array", "items": { "type": "string" }, "description": "**Required.** Markets to receive liquidity updates for.", "maxItems": 500, "minItems": 1 } } }, "MarketLiquidityPayload": { "type": "object", "description": "Market liquidity webhook payload.", "required": [ "condition_id", "liquidity_usd", "threshold_usd", "direction", "liquidity_updated_at" ], "properties": { "condition_id": { "type": "string", "description": "Market condition ID." }, "liquidity_usd": { "type": "number", "format": "double", "description": "Total order-book liquidity in USD at the time of firing." }, "threshold_usd": { "type": "number", "format": "double", "description": "The threshold (USD) that was crossed." }, "direction": { "type": "string", "description": "`\"above\"` when liquidity crossed up through `min_liquidity_usd`,\n`\"below\"` when it crossed down through `max_liquidity_usd`." }, "liquidity_updated_at": { "type": "integer", "format": "int64", "description": "Update timestamp (Unix millis)." } } }, "MarketMetricsFilters": { "type": "object", "description": "Subscription filters for the `condition_metrics` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets. Empty = all markets.", "maxItems": 500 }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MetricFilterTimeframe" }, "description": "Restrict to these aggregation windows. Empty = all windows.", "maxItems": 500 }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when volume ≥ this value (USD)." }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when volume ≤ this value (USD)." }, "min_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Only fire when transaction count ≥ this value." }, "min_unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Only fire when unique trader count ≥ this value." }, "min_fees": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when total fees ≥ this value (USD)." } } }, "MarketPnlPayload": { "type": "object", "description": "Market PnL webhook payload.", "required": [ "timeframe" ], "properties": { "trader": { "type": [ "string", "null" ], "description": "Trader wallet address." }, "condition_id": { "type": [ "string", "null" ], "description": "Market condition ID." }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug." }, "category": { "type": [ "string", "null" ], "description": "Category." }, "timeframe": { "type": "string", "description": "Aggregation timeframe: \"1d\", \"7d\", \"30d\", or \"lifetime\"" }, "realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Realized pnl in USD." }, "current_shares_balance": { "type": [ "number", "null" ], "format": "double", "description": "Current shares balance." }, "outcomes_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of outcomes traded." }, "total_buys": { "type": [ "integer", "null" ], "format": "int64", "description": "Total buy count." }, "total_sells": { "type": [ "integer", "null" ], "format": "int64", "description": "Total sell count." }, "total_redemptions": { "type": [ "integer", "null" ], "format": "int64", "description": "Total redemption count." }, "total_merges": { "type": [ "integer", "null" ], "format": "int64", "description": "Total merge count." }, "total_splits": { "type": [ "integer", "null" ], "format": "int64", "description": "Total split count." }, "buy_usd": { "type": [ "number", "null" ], "format": "double", "description": "Buy in USD." }, "sell_usd": { "type": [ "number", "null" ], "format": "double", "description": "Sell in USD." }, "redemption_usd": { "type": [ "number", "null" ], "format": "double", "description": "Redemption in USD." }, "merge_usd": { "type": [ "number", "null" ], "format": "double", "description": "Merge in USD." }, "convert_collateral_usd": { "type": [ "number", "null" ], "format": "double", "description": "Convert collateral in USD." }, "split_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Split volume in USD." }, "total_fees": { "type": [ "number", "null" ], "format": "double", "description": "Total fees amount." }, "total_shares_bought": { "type": [ "number", "null" ], "format": "double", "description": "Total shares bought." }, "first_trade_at": { "type": [ "integer", "null" ], "format": "int64", "description": "First trade timestamp." }, "last_trade_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Last trade timestamp." } } }, "MarketResolvedFilters": { "type": "object", "description": "Subscription filters for the `market_resolved` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets in these events.", "maxItems": 500 }, "outcomes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only fire when the winning outcome matches one of these (e.g. \\[\"Yes\"\\]).", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "MarketResolvedPayload": { "type": "object", "description": "Market-resolved webhook payload", "required": [ "condition_id", "resolution_kind", "hash" ], "properties": { "condition_id": { "type": "string", "description": "Condition ID (the resolved market)" }, "winning_outcome": { "type": [ "string", "null" ], "description": "Winning outcome name when known (e.g. \"Yes\", \"No\")" }, "settled_price": { "type": [ "number", "null" ], "format": "double", "description": "Settled price (0.0–1.0) when the resolution event carries one\n(`QuestionResolved` only). 1.0 = full YES, 0.0 = full NO, 0.5 = split." }, "resolution_kind": { "type": "string", "description": "Which oracle event produced this resolution: `\"question_resolved\"`,\n`\"question_emergency_resolved\"`, `\"condition_resolution\"`, or `\"neg_risk_outcome_reported\"`." }, "question": { "type": [ "string", "null" ], "description": "Market question" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug" }, "image_url": { "type": [ "string", "null" ], "description": "Market image URL" }, "hash": { "type": "string", "description": "Transaction hash of the resolution event" }, "block": { "type": [ "integer", "null" ], "format": "int64", "description": "Block number", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Confirmed timestamp (Unix seconds)", "minimum": 0 } } }, "MarketVolumeMilestoneFilters": { "type": "object", "description": "Subscription filters for the `market_volume_milestone` event.", "required": [ "timeframes" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "timeframes": { "type": "array", "items": { "$ref": "#/components/schemas/MetricFilterTimeframe" }, "description": "**Required.** Aggregation windows to monitor (e.g. \\[\"1h\", \"24h\"\\]).", "maxItems": 500, "minItems": 1 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets. Empty = all markets.", "maxItems": 500 }, "milestone_amounts": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" }, "description": "Specific USD milestones to trigger on (e.g. \\[10000, 100000, 1000000\\]). Empty = all milestones.", "maxItems": 500 } } }, "MarketVolumeSpikeFilters": { "type": "object", "description": "Subscription filters for the `market_volume_spike` event. `spike_ratio` is required.", "required": [ "spike_ratio" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "spike_ratio": { "type": "number", "format": "double", "description": "**Required.** Multiplier threshold (must be > 1.0). Fires when current volume >= snapshot × ratio. The snapshot is set automatically on first data and resets after each fire.", "exclusiveMinimum": 1 }, "window_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Force snapshot reset after this many seconds (max 600 / 10 minutes).", "maximum": 600, "minimum": 1 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets. Empty = all markets.", "maxItems": 500 }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/VolumeSpikeFilterTimeframe" }, "description": "Restrict to these aggregation windows. Empty = all windows.", "maxItems": 500 } } }, "MarketVolumeSpikePayload": { "type": "object", "description": "Market volume spike webhook payload", "required": [ "condition_id", "timeframe", "current_volume_usd", "snapshot_volume_usd", "delta_volume_usd", "spike_pct", "txns", "fees" ], "properties": { "condition_id": { "type": "string", "description": "Market condition ID." }, "question": { "type": [ "string", "null" ], "description": "Market question." }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug." }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug." }, "image_url": { "type": [ "string", "null" ], "description": "Image URL." }, "timeframe": { "type": "string", "description": "Metric timeframe." }, "current_volume_usd": { "type": "number", "format": "double", "description": "Current window volume at the time of the spike (USD)" }, "snapshot_volume_usd": { "type": "number", "format": "double", "description": "Volume at the snapshot baseline (USD)" }, "delta_volume_usd": { "type": "number", "format": "double", "description": "New volume since the snapshot that triggered this notification (USD)" }, "spike_pct": { "type": "number", "format": "double", "description": "Volume growth as a percentage of the snapshot (e.g. 200.0 means volume tripled)" }, "txns": { "type": "integer", "format": "int64", "description": "Total transactions in this timeframe" }, "fees": { "type": "number", "format": "double", "description": "Total fees in this timeframe" } } }, "MetricFilterTimeframe": { "type": "string", "description": "Aggregation windows emitted by the metrics / milestone streams.", "enum": [ "1m", "5m", "30m", "1h", "6h", "24h", "7d", "30d" ] }, "NegRiskOutcomeReportedEvent": { "type": "object", "description": "NegRisk Adapter: outcome reported for a neg-risk market question.", "required": [ "id", "hash", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "proposed_outcome": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "NewMarketPayload": { "type": "object", "description": "Payload delivered when a trader places their first trade in a specific market (fires once per trader+market pair)", "required": [ "trader", "taker", "trader_info", "position_id", "trade_id", "hash", "block", "confirmed_at", "amount_usd", "shares_amount", "fee", "side", "price", "exchange", "trade_type" ], "properties": { "trader": { "type": "string", "description": "Limit-order maker wallet address (lowercase)" }, "taker": { "type": "string", "description": "Order filler wallet address (lowercase)" }, "trader_info": { "$ref": "#/components/schemas/WebhookTraderInfo", "description": "Maker trader display metadata (address + name / pseudonym / image / x / verified)" }, "position_id": { "type": "string", "description": "ERC-1155 outcome token ID" }, "condition_id": { "type": [ "string", "null" ], "description": "Parent market condition ID" }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name (e.g. \"Yes\", \"No\")" }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index: 0 = Yes/Up, 1 = No", "minimum": 0 }, "question": { "type": [ "string", "null" ], "description": "Market question text" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Parent event slug" }, "image_url": { "type": [ "string", "null" ], "description": "Market image URL" }, "trade_id": { "type": "string", "description": "Unique trade identifier" }, "hash": { "type": "string", "description": "Transaction hash" }, "block": { "type": "integer", "format": "int64", "description": "Block number", "minimum": 0 }, "confirmed_at": { "type": "integer", "format": "int64", "description": "Block confirmation timestamp (Unix seconds)", "minimum": 0 }, "amount_usd": { "type": "number", "format": "double", "description": "USD size of the trade (6 decimal places)" }, "shares_amount": { "type": "number", "format": "double", "description": "Outcome shares traded (6 decimal places)" }, "fee": { "type": "number", "format": "double", "description": "Fee paid in USD (6 decimal places)" }, "side": { "oneOf": [ { "type": "string", "description": "Trade direction for trade-fill webhook payloads.", "enum": [ "Buy", "Sell" ] } ], "description": "Trade direction" }, "price": { "type": "number", "format": "double", "description": "Outcome token price (0.0–1.0)", "maximum": 1, "minimum": 0 }, "probability": { "type": [ "number", "null" ], "format": "double", "description": "Implied probability (0.0–1.0); null when outcome is unknown", "maximum": 1, "minimum": 0 }, "exchange": { "oneOf": [ { "type": "string", "description": "Polymarket exchange contract types.", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "CTFExchangeV2", "NegRiskExchangeV2", "ComboExchange", "ComboCombinatorialModule", "ComboNegRiskModule", "Unknown" ] } ], "description": "Exchange contract that processed the trade" }, "trade_type": { "oneOf": [ { "type": "string", "description": "Trade type for trade-fill webhook payloads. Webhook events only fire on\nfill-style trades, so the only valid variants are `OrderFilled`,\n`OrdersMatched`, and `ComboExecution`.", "enum": [ "OrderFilled", "OrdersMatched", "ComboExecution" ] } ], "description": "Trade type (webhook events only fire on order fills)" } } }, "NewTradeFilterType": { "type": "string", "description": "Trade types accepted by `trader_new_trade.trade_types`. Webhook fires on\nfill-style trades only.", "enum": [ "OrderFilled", "OrdersMatched", "ComboExecution" ] }, "NewTradePayload": { "type": "object", "description": "Payload delivered on every order-filled trade", "required": [ "trader", "taker", "trader_info", "position_id", "trade_id", "hash", "block", "confirmed_at", "amount_usd", "shares_amount", "fee", "side", "price", "exchange", "trade_type" ], "properties": { "trader": { "type": "string", "description": "Limit-order maker wallet address (lowercase)" }, "taker": { "type": "string", "description": "Order filler wallet address (lowercase)" }, "trader_info": { "$ref": "#/components/schemas/WebhookTraderInfo", "description": "Maker trader display metadata (address + name / pseudonym / image / x / verified)" }, "position_id": { "type": "string", "description": "ERC-1155 outcome token ID" }, "condition_id": { "type": [ "string", "null" ], "description": "Parent market condition ID" }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name (e.g. \"Yes\", \"No\")" }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index: 0 = Yes/Up, 1 = No", "minimum": 0 }, "question": { "type": [ "string", "null" ], "description": "Market question text" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Parent event slug" }, "image_url": { "type": [ "string", "null" ], "description": "Market image URL" }, "trade_id": { "type": "string", "description": "Unique trade identifier" }, "hash": { "type": "string", "description": "Transaction hash" }, "block": { "type": "integer", "format": "int64", "description": "Block number", "minimum": 0 }, "confirmed_at": { "type": "integer", "format": "int64", "description": "Block confirmation timestamp (Unix seconds)", "minimum": 0 }, "amount_usd": { "type": "number", "format": "double", "description": "USD size of the trade (6 decimal places)" }, "shares_amount": { "type": "number", "format": "double", "description": "Outcome shares traded (6 decimal places)" }, "fee": { "type": "number", "format": "double", "description": "Fee paid in USD (6 decimal places)" }, "side": { "oneOf": [ { "type": "string", "description": "Trade direction for trade-fill webhook payloads.", "enum": [ "Buy", "Sell" ] } ], "description": "Trade direction" }, "price": { "type": "number", "format": "double", "description": "Outcome token price (0.0–1.0)", "maximum": 1, "minimum": 0 }, "probability": { "type": [ "number", "null" ], "format": "double", "description": "Implied probability (0.0–1.0); null when outcome is unknown", "maximum": 1, "minimum": 0 }, "exchange": { "oneOf": [ { "type": "string", "description": "Polymarket exchange contract types.", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "CTFExchangeV2", "NegRiskExchangeV2", "ComboExchange", "ComboCombinatorialModule", "ComboNegRiskModule", "Unknown" ] } ], "description": "Exchange contract that processed the trade" }, "trade_type": { "oneOf": [ { "type": "string", "description": "Trade type for trade-fill webhook payloads. Webhook events only fire on\nfill-style trades, so the only valid variants are `OrderFilled`,\n`OrdersMatched`, and `ComboExecution`.", "enum": [ "OrderFilled", "OrdersMatched", "ComboExecution" ] } ], "description": "Trade type (webhook events only fire on order fills)" }, "builder_code": { "type": [ "string", "null" ], "description": "CLOB V2 builder code (lower-cased `0x...` bytes32 hex). Absent on V1\ntrades; may be `0x0000…` for V2 trades placed without a builder code.\nCLOB builder code." }, "builder_fee": { "type": [ "number", "null" ], "format": "double", "description": "Builder fee in USDC. Absent when no builder code is attached." } } }, "OracleEventFilterType": { "type": "string", "description": "Oracle event variants accepted by `oracle_events.oracle_event_types`.", "enum": [ "AssertionMade", "AssertionDisputed", "AssertionSettled", "RequestPrice", "ProposePrice", "DisputePrice", "Settle", "QuestionResolved", "QuestionEmergencyResolved", "QuestionReset", "QuestionInitialized", "QuestionPaused", "QuestionUnpaused", "QuestionFlagged", "QuestionUnflagged", "ConditionResolution", "NegRiskOutcomeReported" ] }, "OracleEventTyped": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/AssertionMadeEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "AssertionMade" ] } } } ], "title": "AssertionMade" }, { "allOf": [ { "$ref": "#/components/schemas/AssertionDisputedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "AssertionDisputed" ] } } } ], "title": "AssertionDisputed" }, { "allOf": [ { "$ref": "#/components/schemas/AssertionSettledEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "AssertionSettled" ] } } } ], "title": "AssertionSettled" }, { "allOf": [ { "$ref": "#/components/schemas/RequestPriceEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "RequestPrice" ] } } } ], "title": "RequestPrice" }, { "allOf": [ { "$ref": "#/components/schemas/ProposePriceEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "ProposePrice" ] } } } ], "title": "ProposePrice" }, { "allOf": [ { "$ref": "#/components/schemas/DisputePriceEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "DisputePrice" ] } } } ], "title": "DisputePrice" }, { "allOf": [ { "$ref": "#/components/schemas/SettleEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "Settle" ] } } } ], "title": "Settle" }, { "allOf": [ { "$ref": "#/components/schemas/QuestionResolvedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "QuestionResolved" ] } } } ], "title": "QuestionResolved" }, { "allOf": [ { "$ref": "#/components/schemas/QuestionEmergencyResolvedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "QuestionEmergencyResolved" ] } } } ], "title": "QuestionEmergencyResolved" }, { "allOf": [ { "$ref": "#/components/schemas/QuestionResetEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "QuestionReset" ] } } } ], "title": "QuestionReset" }, { "allOf": [ { "$ref": "#/components/schemas/QuestionInitializedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "QuestionInitialized" ] } } } ], "title": "QuestionInitialized" }, { "allOf": [ { "$ref": "#/components/schemas/QuestionPausedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "QuestionPaused" ] } } } ], "title": "QuestionPaused" }, { "allOf": [ { "$ref": "#/components/schemas/QuestionUnpausedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "QuestionUnpaused" ] } } } ], "title": "QuestionUnpaused" }, { "allOf": [ { "$ref": "#/components/schemas/QuestionFlaggedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "QuestionFlagged" ] } } } ], "title": "QuestionFlagged" }, { "allOf": [ { "$ref": "#/components/schemas/QuestionUnflaggedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "QuestionUnflagged" ] } } } ], "title": "QuestionUnflagged" }, { "allOf": [ { "$ref": "#/components/schemas/ConditionResolutionEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "ConditionResolution" ] } } } ], "title": "ConditionResolution" }, { "allOf": [ { "$ref": "#/components/schemas/NegRiskOutcomeReportedEvent" }, { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "enum": [ "NegRiskOutcomeReported" ] } } } ], "title": "NegRiskOutcomeReported" } ], "description": "Tagged enum for all oracle event types — serializes with `\"event_type\": \"...\"` discriminator\nand only includes fields relevant to each type.", "discriminator": { "propertyName": "event_type" } }, "OracleEventsFilters": { "type": "object", "description": "Subscription filters for the `oracle_events` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "oracle_event_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/OracleEventFilterType" }, "description": "Restrict to these event types (case-insensitive). Empty = all." }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to events for these condition IDs.", "maxItems": 500 } } }, "PaginationMeta": { "type": "object", "description": "Pagination metadata to include in API responses", "required": [ "has_more" ], "properties": { "has_more": { "type": "boolean", "description": "Whether there are more results available" }, "pagination_key": { "type": [ "string", "null" ], "description": "Pagination key for the next page (if has_more is true)" } } }, "PnlFilterTimeframe": { "type": "string", "description": "PnL aggregation windows accepted by `*_pnl.timeframes`.", "enum": [ "1d", "7d", "30d", "lifetime" ] }, "PnlTimeframeFilter": { "type": "string", "description": "PnL timeframe enum for webhook filtering.", "enum": [ "1d", "7d", "30d", "lifetime" ] }, "PolymarketWebhookEvent": { "type": "string", "description": "Polymarket webhook event types", "enum": [ "trader_first_trade", "trader_new_market", "trader_whale_trade", "trader_new_trade", "trader_trade_event", "trader_global_pnl", "trader_market_pnl", "trader_category_pnl", "trader_position_resolved", "trader_exit_markers", "position_holder_metrics", "condition_holder_metrics", "event_holder_metrics", "condition_metrics", "event_metrics", "tag_metrics", "position_metrics", "position_liquidity", "market_liquidity", "event_liquidity", "market_volume_milestone", "event_volume_milestone", "position_volume_milestone", "market_volume_spike", "event_volume_spike", "position_volume_spike", "close_to_bond", "market_created", "asset_price_tick", "asset_price_window_update", "price_spike", "probability_spike", "oracle_events", "price_threshold", "market_resolved", "market_disputed" ] }, "PolymarketWebhookFilter": { "type": "object", "description": "Polymarket-specific webhook filters\n\nDifferent webhook handlers use different subsets of these fields.\nThe trade-driven events `price_spike` and\n`close_to_bond` additionally accept `tags` (matches a market's tags OR its\ncategory) and `series_slugs` (matches the market's parent series); these are\nresolved from the tags/series the crawler enriches onto each trade.\n- first_trade: wallet_addresses, min_usd_value, min_price, max_price, condition_ids, event_slugs, tags\n- new_market: wallet_addresses, condition_ids, event_slugs, min_usd_value, min_price, max_price\n- whale_trade: min_usd_value (required), min_price, max_price, condition_ids, event_slugs\n- global_pnl: traders, min_realized_pnl_usd, max_realized_pnl_usd, min_volume_usd, min_win_rate, min_markets_traded\n- market_pnl: traders, min_realized_pnl_usd, max_realized_pnl_usd, min_buy_usd, condition_ids, event_slugs\n- event_pnl: traders, min_realized_pnl_usd, max_realized_pnl_usd, min_volume_usd, event_slugs, min_markets_traded\n- condition_metrics: condition_ids, min_volume_usd, max_volume_usd, min_fees, min_txns, timeframes\n- event_metrics: event_slugs, min_volume_usd, max_volume_usd, min_fees, min_txns, timeframes\n- tag_metrics: tags, min_volume_usd, max_volume_usd, min_fees, min_txns, timeframes\n- position_metrics: position_ids, condition_ids, outcomes, min_volume_usd, max_volume_usd, min_buy_usd, min_sell_volume_usd, min_fees, min_txns, min_price_change_pct, min_probability_change_pct, timeframes\n- volume_milestone: condition_ids, timeframes, milestone_amounts\n- close_to_bond: min_price (high zone threshold), max_price (low zone threshold), condition_ids, tags, series_slugs, position_ids, outcomes, position_outcome_indices, event_slugs, exclude_shortterm_markets\n- market_created: event_slugs, tags, exclude_shortterm_markets\n- price_spike: condition_ids, event_slugs, tags, series_slugs, outcomes, min_price_change_pct, spike_direction, window_secs, exclude_shortterm_markets\n- trader_new_trade: wallet_addresses, min_usd_value, min_price, max_price, condition_ids, event_slugs, trade_types, exclude_shortterm_markets\n- trader_trade_event: wallet_addresses, min_usd_value, min_price, max_price, condition_ids, event_slugs, trade_types, exclude_shortterm_markets\n- trader_first_trade: wallet_addresses, min_usd_value, min_price, max_price, exclude_shortterm_markets\n- trader_new_market: wallet_addresses, condition_ids, event_slugs, min_usd_value, min_price, max_price, exclude_shortterm_markets\n- trader_whale_trade: min_usd_value (required), min_price, max_price, condition_ids, event_slugs, exclude_shortterm_markets\n- trader_event_pnl: traders, min_realized_pnl_usd, max_realized_pnl_usd, min_volume_usd, event_slugs, min_markets_traded, exclude_shortterm_markets\n- trader_market_pnl: traders, min_realized_pnl_usd, max_realized_pnl_usd, min_buy_usd, condition_ids, event_slugs, exclude_shortterm_markets\n\nImplements Hash + Eq manually (f64 fields use bit representation)", "properties": { "wallet_addresses": { "type": "array", "items": { "type": "string" }, "description": "Filter by wallet addresses (for first_trade, normalized to lowercase). Max 500 entries.\nWallet addresses to match." }, "traders": { "type": "array", "items": { "type": "string" }, "description": "Filter by trader addresses (for PnL webhooks, normalized to lowercase). Max 500 entries.\nTrader wallet addresses to match." }, "condition_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by market/condition IDs. Max 500 entries.\nMarket condition IDs to match." }, "min_usd_value": { "type": [ "number", "null" ], "format": "double", "description": "Filter by minimum USD value (for trades)" }, "event_slugs": { "type": "array", "items": { "type": "string" }, "description": "Filter by event slugs. Max 500 entries.\nEvent slugs to match." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tags or category names (case-insensitive). Matches a market's\ntags or its category label. Max 500 entries.\nTags to match." }, "series_slugs": { "type": "array", "items": { "type": "string" }, "description": "Filter by series slugs (case-insensitive). Matches a market's parent\nseries. Max 500 entries.\nSeries slugs to match." }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Minimum trade price threshold (0.0 - 1.0). Accepts the legacy `min_probability` key." }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Maximum trade price threshold (0.0 - 1.0). Accepts the legacy `max_probability` key." }, "min_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum realized PnL (USD) - for PnL webhooks" }, "max_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maximum realized PnL (USD) - for PnL webhooks" }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum volume (USD) - for PnL and metrics webhooks" }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maximum volume (USD) - for metrics webhooks" }, "min_liquidity_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum order-book liquidity (USD) - for liquidity webhooks.\nFires when liquidity crosses up through this value." }, "max_liquidity_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maximum order-book liquidity (USD) - for liquidity webhooks.\nFires when liquidity crosses down through this value." }, "min_buy_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum buy volume (USD) - for PnL and metrics webhooks" }, "min_win_rate": { "type": [ "number", "null" ], "format": "double", "description": "Minimum win rate (0.0 - 100.0) - for global PnL webhooks" }, "min_markets_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum markets traded - for PnL webhooks" }, "min_net_shares": { "type": [ "number", "null" ], "format": "double", "description": "Minimum net shares - for position PnL webhooks" }, "max_net_shares": { "type": [ "number", "null" ], "format": "double", "description": "Maximum net shares - for position PnL webhooks" }, "position_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by position IDs - for position PnL webhooks. Max 500 entries.\nOutcome token IDs to match." }, "outcomes": { "type": "array", "items": { "type": "string" }, "description": "Filter by outcomes (e.g., \"Yes\", \"No\") - for position PnL webhooks. Max 500 entries.\nOutcome names to match." }, "position_outcome_indices": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Filter by position outcome index — for close_to_bond. Position 0 usually represents Yes/Up, 1 = No.\nWhen non-empty, only trades whose outcome_index is in this list will match. Max 500 entries.\nOutcome indices to match." }, "trade_types": { "type": "array", "items": { "type": "string" }, "description": "Filter by trade type (e.g. \"OrderFilled\", \"Redemption\", \"Merge\", \"Split\"). Empty = default behavior per handler.\nTrade types to match." }, "min_fees": { "type": [ "number", "null" ], "format": "double", "description": "Minimum fees - for metrics webhooks" }, "min_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum transaction count - for metrics webhooks" }, "min_unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum unique traders - for metrics webhooks" }, "min_sell_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum sell volume (USD) - for position metrics webhooks" }, "min_price_change_pct": { "type": [ "number", "null" ], "format": "double", "description": "Minimum price change percentage - for position metrics webhooks" }, "min_probability_change_pct": { "type": [ "number", "null" ], "format": "double", "description": "Minimum probability change percentage - for position metrics webhooks" }, "timeframes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookTimeframe" }, "description": "Timeframes to track - for metrics webhooks (1m, 5m, 30m, 1h, 6h, 24h, 7d, 30d).\nMetric timeframes to match." }, "milestone_amounts": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Milestone amounts to track - for volume milestone webhooks (e.g., 10000, 100000, 1000000). Max 500 entries.\nMilestone amounts to match." }, "spike_ratio": { "type": [ "number", "null" ], "format": "double", "description": "Spike ratio multiplier (must be > 1.0) - for volume spike webhooks\nExample: 2.0 for 2x, 5.0 for 5x, 10.0 for 10x" }, "exclude_shortterm_markets": { "type": "boolean", "description": "When `true`, exclude all short-term \"updown\" markets (event slugs containing \"updown\").\nThese are short-duration crypto price markets (e.g., \"btc-updown-5m-…\", \"eth-updown-1h-…\").\nSupported by: close_to_bond, market_created, price_spike,\ntrader_first_trade, trader_new_market, trader_whale_trade, trader_event_pnl, trader_market_pnl,\nevent_metrics, event_volume_milestone, event_volume_spike." }, "asset_symbols": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAssetSymbol" }, "description": "Filter by crypto asset symbol — for `asset_price_tick` and `asset_price_window_update` webhooks.\nValid values: \"BTC\", \"ETH\", \"SOL\", \"XRP\", \"DOGE\", \"BNB\", \"HYPE\". Empty = all assets.\nAsset symbols to match." }, "spike_direction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpikeDirection", "description": "Direction filter for `price_spike` — only fire for spikes in a specific direction.\nOmit or set to `null` to receive spikes in both directions." } ] }, "window_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Observation window in seconds for `price_spike`.\n\nWhen set, the first trade seen for a position opens a window of this duration.\nThe opening price becomes the baseline, and every subsequent trade within the\nwindow is compared to it. When the window expires the next trade starts a new\nwindow. If omitted, the baseline accumulates indefinitely until a spike fires.\n\nExample: `60` to detect spikes that happen within 60 seconds.", "minimum": 0 }, "oracle_event_types": { "type": "array", "items": { "type": "string" }, "description": "Filter for `oracle_events` by event name (case-insensitive).\nValid values: `AssertionMade`, `AssertionDisputed`, `AssertionSettled`,\n`RequestPrice`, `ProposePrice`, `DisputePrice`, `Settle`,\n`QuestionResolved`, `QuestionEmergencyResolved`, `QuestionReset`,\n`QuestionInitialized`, `QuestionPaused`, `QuestionUnpaused`,\n`QuestionFlagged`, `QuestionUnflagged`, `ConditionResolution`,\n`NegRiskOutcomeReported`. Empty = all types.\nOracle event types to match." }, "one_shot": { "type": "boolean", "description": "Fire-and-delete: when `true`, the subscription is deleted after its first\nsuccessful delivery. Works on any webhook event. (`price_threshold`\nadditionally requires `position_ids` or `condition_ids`.)" }, "fire_if_already_past": { "type": "boolean", "description": "For `price_threshold` — when `true`, fire immediately if the first observed\nprice is already past the target (no prior baseline). Default `false`." } } }, "PositionHolderMetricsFilters": { "type": "object", "properties": { "position_ids": { "type": "array", "items": { "type": "string" }, "description": "Outcome token IDs to match." }, "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." } } }, "PositionHolderMetricsPayload": { "type": "object", "required": [ "ts", "block", "position_id", "holder_count", "total_balance", "total_cost_basis" ], "properties": { "ts": { "type": "integer", "format": "int32", "description": "Unix timestamp in seconds.", "minimum": 0 }, "block": { "type": "integer", "format": "int64", "description": "Block number." }, "position_id": { "type": "string", "description": "Outcome token ID." }, "holder_count": { "type": "integer", "format": "int32", "description": "Number of holders." }, "total_balance": { "type": "number", "format": "double", "description": "Total shares held." }, "total_cost_basis": { "type": "number", "format": "double", "description": "Total holder cost basis in USD." }, "condition_holder_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of market-level holders." }, "event_holder_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of event-level holders." } } }, "PositionLiquidityFilters": { "type": "object", "description": "Subscription filters for the `position_liquidity` event.\n\nAt least one of `min_liquidity_usd`, `max_liquidity_usd`, or `one_shot` must be set.\nThresholds are edge-triggered: a callback fires when liquidity crosses the threshold,\nthen re-arms once it crosses back (unless `one_shot`).", "required": [ "position_ids" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery." }, "min_liquidity_usd": { "type": [ "number", "null" ], "format": "double", "description": "Fire when liquidity crosses up through this USD value." }, "max_liquidity_usd": { "type": [ "number", "null" ], "format": "double", "description": "Fire when liquidity crosses down through this USD value." }, "position_ids": { "type": "array", "items": { "type": "string" }, "description": "**Required.** Outcome token IDs to receive liquidity updates for.", "maxItems": 500, "minItems": 1 } } }, "PositionLiquidityPayload": { "type": "object", "description": "Position liquidity webhook payload.", "required": [ "position_id", "liquidity_usd", "threshold_usd", "direction", "liquidity_updated_at" ], "properties": { "position_id": { "type": "string", "description": "Outcome token (position) ID." }, "liquidity_usd": { "type": "number", "format": "double", "description": "Order-book liquidity in USD at the time of firing." }, "threshold_usd": { "type": "number", "format": "double", "description": "The threshold (USD) that was crossed." }, "direction": { "type": "string", "description": "`\"above\"` when liquidity crossed up through `min_liquidity_usd`,\n`\"below\"` when it crossed down through `max_liquidity_usd`." }, "liquidity_updated_at": { "type": "integer", "format": "int64", "description": "Update timestamp (Unix millis)." } } }, "PositionMetricsFilters": { "type": "object", "description": "Subscription filters for the `position_metrics` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "position_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome token IDs.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to positions within these markets.", "maxItems": 500 }, "outcomes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to positions with these outcome names (e.g. \\[\"Yes\", \"No\"\\]).", "maxItems": 500 }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MetricFilterTimeframe" }, "description": "Restrict to these aggregation windows.", "maxItems": 500 }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when position volume ≥ this value (USD)." }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maximum volume USD." }, "min_buy_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum buy USD." }, "min_sell_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum sell volume USD." }, "min_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum transactions." }, "min_unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum unique traders." }, "min_price_change_pct": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when price change % ≥ this value." }, "min_probability_change_pct": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when probability change % ≥ this value." }, "min_fees": { "type": [ "number", "null" ], "format": "double", "description": "Minimum fees." } } }, "PositionMetricsPayload": { "type": "object", "description": "Payload delivered when a position's volume or transaction metrics cross a configured threshold", "properties": { "position_id": { "type": [ "string", "null" ], "description": "ERC-1155 outcome token ID" }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name (e.g. \"Yes\", \"No\")" }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index" }, "timeframe": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Timeframe values accepted by webhook metric, milestone, spike, and asset-price filters.", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "6h", "1d", "24h", "7d", "30d", "lifetime" ] } ], "description": "Aggregation window" }, "volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total trading volume in USD" }, "buy_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Buy volume in USD" }, "sell_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Sell volume in USD" }, "shares_volume": { "type": [ "number", "null" ], "format": "double", "description": "Total shares/contracts volume" }, "shares_buy_volume": { "type": [ "number", "null" ], "format": "double", "description": "Buy shares/contracts volume" }, "shares_sell_volume": { "type": [ "number", "null" ], "format": "double", "description": "Sell shares/contracts volume" }, "builder_usd_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed volume in USD" }, "builder_usd_buy_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed buy volume in USD" }, "builder_usd_sell_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed sell volume in USD" }, "builder_shares_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed shares/contracts volume" }, "builder_shares_buy_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed buy shares/contracts volume" }, "builder_shares_sell_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed sell shares/contracts volume" }, "fees": { "type": [ "number", "null" ], "format": "double", "description": "Total fees in USD" }, "builder_fees": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed fees in USD" }, "txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Transaction count." }, "buys": { "type": [ "integer", "null" ], "format": "int64", "description": "Buy count." }, "sells": { "type": [ "integer", "null" ], "format": "int64", "description": "Sell count." }, "builder_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Builder-attributed transaction count." }, "builder_buys": { "type": [ "integer", "null" ], "format": "int64", "description": "Builder-attributed buy count." }, "builder_sells": { "type": [ "integer", "null" ], "format": "int64", "description": "Builder-attributed sell count." }, "unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Unique traders." }, "unique_makers": { "type": [ "integer", "null" ], "format": "int64", "description": "Unique makers." }, "unique_takers": { "type": [ "integer", "null" ], "format": "int64", "description": "Unique takers." }, "unique_builder_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Unique builder traders." }, "price_open": { "type": [ "number", "null" ], "format": "double", "description": "Opening price.", "maximum": 1, "minimum": 0 }, "price_close": { "type": [ "number", "null" ], "format": "double", "description": "Closing price.", "maximum": 1, "minimum": 0 }, "price_high": { "type": [ "number", "null" ], "format": "double", "description": "Highest price.", "maximum": 1, "minimum": 0 }, "price_low": { "type": [ "number", "null" ], "format": "double", "description": "Lowest price.", "maximum": 1, "minimum": 0 }, "probability_open": { "type": [ "number", "null" ], "format": "double", "description": "Opening implied probability.", "maximum": 1, "minimum": 0 }, "probability_close": { "type": [ "number", "null" ], "format": "double", "description": "Closing implied probability.", "maximum": 1, "minimum": 0 }, "probability_high": { "type": [ "number", "null" ], "format": "double", "description": "Highest implied probability.", "maximum": 1, "minimum": 0 }, "probability_low": { "type": [ "number", "null" ], "format": "double", "description": "Lowest implied probability.", "maximum": 1, "minimum": 0 }, "avg_trade_shares": { "type": [ "number", "null" ], "format": "double", "description": "Average shares per trade." }, "avg_buy_shares": { "type": [ "number", "null" ], "format": "double", "description": "Average shares per buy." }, "avg_sell_shares": { "type": [ "number", "null" ], "format": "double", "description": "Average shares per sell." } } }, "PositionResolvedPayload": { "type": "object", "properties": { "trader": { "type": "string" }, "position_id": { "type": "string" }, "condition_id": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "description": "Market category slug (e.g. \"politics\", \"sports\") — mirror of\n`PositionRollup.category_id` resolved against the rollup\ninterner. Surfaces on the `/trader/{addr}/positions` API and\nenables direct category-filtered + sorted position lookups\nwithout a cross-grain join." }, "outcome": { "type": [ "string", "null" ] }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32" }, "total_buys": { "type": "integer", "format": "int64" }, "total_sells": { "type": "integer", "format": "int64" }, "total_merges": { "type": "integer", "format": "int64" }, "total_splits": { "type": "integer", "format": "int64" }, "winning_outcome_index": { "type": [ "integer", "null" ], "format": "int32" }, "total_shares_bought": { "type": "number", "format": "double" }, "total_shares_sold": { "type": "number", "format": "double" }, "buy_usd": { "type": "number", "format": "double" }, "sell_usd": { "type": "number", "format": "double" }, "avg_entry_price": { "type": "number", "format": "double" }, "total_fees": { "type": "number", "format": "double" }, "realized_pnl_usd": { "type": "number", "format": "double" }, "total_pnl_usd": { "type": "number", "format": "double" }, "unrealized_pnl_usd": { "type": "number", "format": "double" }, "redemption_usd": { "type": "number", "format": "double" }, "open": { "type": "boolean" }, "won": { "type": [ "boolean", "null" ] }, "first_trade_at": { "type": [ "integer", "null" ], "format": "int64" }, "last_trade_at": { "type": [ "integer", "null" ], "format": "int64" }, "dirty_kinds": { "type": "array", "items": { "$ref": "#/components/schemas/DirtyKind" }, "description": "What kind of activity triggered this update. One or more of\n`\"trade\"`, `\"price\"`, `\"window\"`, `\"position_resolved\"`.\nSubscribers that only care about one kind filter on\n`data.dirty_kinds` containing the value." }, "realized_pnl_pct": { "type": "number", "format": "double", "description": "`realized_pnl_usd / (buy_usd + total_fees) * 100` for the\nwindow. `0.0` when the trader has no cost basis on this row yet." }, "total_pnl_pct": { "type": "number", "format": "double" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug for the parent market of this outcome." }, "title": { "type": [ "string", "null" ], "description": "Market title." }, "question": { "type": [ "string", "null" ], "description": "Market question." }, "image_url": { "type": [ "string", "null" ], "description": "Market image URL." }, "converted_count": { "type": "integer", "format": "int32", "description": "NegRisk conversion count + share deltas for this position.", "minimum": 0 }, "converted_shares_gained": { "type": "number", "format": "double" }, "converted_shares_lost": { "type": "number", "format": "double" }, "total_buy_usd": { "type": "number", "format": "double", "description": "Aggregate buy/sell USD totals for this position across its\nlifetime." }, "total_sell_usd": { "type": "number", "format": "double" }, "merge_usd": { "type": "number", "format": "double", "description": "Merge proceeds (Y+N → collateral)." }, "avg_exit_price": { "type": [ "number", "null" ], "format": "double", "description": "Sell-side average price." }, "avg_price": { "type": [ "number", "null" ], "format": "double", "description": "Volume-weighted average trade price across buys + sells." }, "current_price": { "type": [ "number", "null" ], "format": "double", "description": "Mark-to-market values from the latest price tick." }, "current_shares_balance": { "type": [ "number", "null" ], "format": "double" }, "current_value": { "type": [ "number", "null" ], "format": "double" }, "last_traded_price": { "type": [ "number", "null" ], "format": "double", "description": "Last on-chain trade price for the outcome token." }, "end_date": { "type": [ "integer", "null" ], "format": "int64", "description": "Market resolution deadline as Unix seconds." }, "is_neg_risk": { "type": [ "boolean", "null" ], "description": "NegRisk multi-outcome flag." }, "redeemable": { "type": [ "boolean", "null" ], "description": "`true` when the market is resolved AND the trader still holds\nshares (redeem available)." }, "mergeable": { "type": [ "boolean", "null" ], "description": "`true` when the market is NegRisk, unresolved, and the trader\nholds shares (NegRisk-adapter merge available)." } } }, "PositionVolumeMilestoneFilters": { "type": "object", "description": "Subscription filters for the `position_volume_milestone` event.", "required": [ "timeframes" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "timeframes": { "type": "array", "items": { "$ref": "#/components/schemas/MetricFilterTimeframe" }, "description": "**Required.** Aggregation windows to monitor.", "maxItems": 500, "minItems": 1 }, "position_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome token IDs.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to positions within these markets.", "maxItems": 500 }, "outcomes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome names (e.g. \\[\"Yes\", \"No\"\\]).", "maxItems": 500 }, "milestone_amounts": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int64" }, "description": "Specific USD milestones to trigger on.", "maxItems": 500 } } }, "PositionVolumeMilestonePayload": { "type": "object", "description": "Position volume milestone webhook payload", "required": [ "position_id", "timeframe", "milestone_usd", "current_volume_usd", "buy_volume_usd", "sell_volume_usd", "fees", "txns", "buys", "sells" ], "properties": { "condition_id": { "type": [ "string", "null" ], "description": "Market condition ID." }, "position_id": { "type": "string", "description": "Outcome token ID." }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name." }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index." }, "timeframe": { "type": "string", "description": "Metric timeframe." }, "milestone_usd": { "type": "number", "format": "double", "description": "Milestone amount reached (USD)" }, "current_volume_usd": { "type": "number", "format": "double", "description": "Current volume (USD) that triggered the milestone" }, "buy_volume_usd": { "type": "number", "format": "double", "description": "Buy volume (USD)" }, "sell_volume_usd": { "type": "number", "format": "double", "description": "Sell volume (USD)" }, "fees": { "type": "number", "format": "double", "description": "Total fees collected in this timeframe" }, "txns": { "type": "integer", "format": "int64", "description": "Total transactions in this timeframe" }, "buys": { "type": "integer", "format": "int64", "description": "Buy transactions" }, "sells": { "type": "integer", "format": "int64", "description": "Sell transactions" } } }, "PositionVolumeSpikeFilters": { "type": "object", "description": "Subscription filters for the `position_volume_spike` event. `spike_ratio` is required.", "required": [ "spike_ratio" ], "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "spike_ratio": { "type": "number", "format": "double", "description": "**Required.** Multiplier threshold (must be > 1.0). Fires when current volume >= snapshot × ratio.", "exclusiveMinimum": 1 }, "window_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Force snapshot reset after this many seconds (max 600 / 10 minutes).", "maximum": 600, "minimum": 1 }, "position_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome token IDs.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to positions within these markets.", "maxItems": 500 }, "outcomes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome names.", "maxItems": 500 }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/VolumeSpikeFilterTimeframe" }, "description": "Restrict to these aggregation windows.", "maxItems": 500 } } }, "PositionVolumeSpikePayload": { "type": "object", "description": "Position volume spike webhook payload", "required": [ "position_id", "condition_id", "timeframe", "current_volume_usd", "snapshot_volume_usd", "delta_volume_usd", "spike_pct", "txns", "fees" ], "properties": { "position_id": { "type": "string", "description": "Outcome token ID." }, "condition_id": { "type": "string", "description": "Market condition ID." }, "question": { "type": [ "string", "null" ], "description": "Market question." }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug." }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug." }, "image_url": { "type": [ "string", "null" ], "description": "Image URL." }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name." }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index." }, "timeframe": { "type": "string", "description": "Metric timeframe." }, "current_volume_usd": { "type": "number", "format": "double", "description": "Current position volume at the time of the spike (USD)" }, "snapshot_volume_usd": { "type": "number", "format": "double", "description": "Volume at the snapshot baseline (USD)" }, "delta_volume_usd": { "type": "number", "format": "double", "description": "New volume since the snapshot that triggered this notification (USD)" }, "spike_pct": { "type": "number", "format": "double", "description": "Volume growth as a percentage of the snapshot (e.g. 200.0 means volume tripled)" }, "txns": { "type": "integer", "format": "int64", "description": "Total transactions in this timeframe" }, "fees": { "type": "number", "format": "double", "description": "Total fees in this timeframe" } } }, "PriceSpikeFilters": { "type": "object", "description": "Subscription filters for the `price_spike` event.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "position_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to specific outcome token IDs. Empty = all positions.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to specific market condition IDs. Empty = all markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to specific events. Empty = all events.", "maxItems": 500 }, "outcomes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome names (e.g. \\[\"Yes\", \"No\"\\]).", "maxItems": 500 }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets carrying any of these tags or category names (case-insensitive). Empty = all.", "maxItems": 500 }, "series_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets in any of these series (by slug, case-insensitive). Empty = all.", "maxItems": 500 }, "min_price_change_pct": { "type": [ "number", "null" ], "format": "double", "description": "Minimum price percentage move to trigger (e.g. `10` for a 10% move)." }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Minimum YES probability (0-1).", "maximum": 1, "minimum": 0 }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Maximum YES probability (0-1).", "maximum": 1, "minimum": 0 }, "min_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum trades accumulated in the observation window before firing." }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum USD volume accumulated in the observation window before firing." }, "spike_direction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpikeDirection", "description": "`\"up\"` = price rising only (default when omitted), `\"down\"` = falling only, `\"both\"` = either direction." } ] }, "window_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Observation window in seconds. The first trade in each window sets the reference price; subsequent trades are compared to it. E.g. `60` detects moves that occur within 60 seconds.", "maximum": 600, "minimum": 1 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "PriceSpikePayload": { "type": "object", "description": "Position price spike webhook payload", "required": [ "position_id", "previous_price", "current_price", "spike_direction", "spike_pct" ], "properties": { "position_id": { "type": "string", "description": "Outcome token ID." }, "condition_id": { "type": [ "string", "null" ], "description": "Market condition ID." }, "question": { "type": [ "string", "null" ], "description": "Market question." }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug." }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug." }, "image_url": { "type": [ "string", "null" ], "description": "Image URL." }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name." }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index." }, "previous_price": { "type": "number", "format": "double", "description": "Price at the start of the observation window (the baseline snapshot)" }, "current_price": { "type": "number", "format": "double", "description": "Current price that triggered the spike" }, "spike_direction": { "type": "string", "description": "Direction of the spike: `\"up\"` (price rising) or `\"down\"` (price falling)" }, "spike_pct": { "type": "number", "format": "double", "description": "Detected spike percentage from the snapshot baseline. Positive = rising, negative = falling." } } }, "PriceThresholdFilters": { "type": "object", "description": "Subscription filters for the `price_threshold` event.", "properties": { "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets carrying any of these tags or category names (case-insensitive). Empty = all.", "maxItems": 500 }, "series_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets in any of these series (by slug, case-insensitive). Empty = all.", "maxItems": 500 }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Upward target — fire when the YES price crosses up to ≥ this value (e.g. 0.75 for 75%). At least one of `min_price` or `max_price` must be set.", "maximum": 1, "minimum": 0 }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Downward target — fire when the YES price crosses down to ≤ this value (e.g. 0.25).", "maximum": 1, "minimum": 0 }, "one_shot": { "type": [ "boolean", "null" ], "description": "When `true`, delete the subscription after its first delivery (fire-and-delete). Requires `position_ids` or `condition_ids`. Default: `false`." }, "fire_if_already_past": { "type": [ "boolean", "null" ], "description": "When `true`, fire immediately if the first observed price is already past the target (no prior baseline). Default: `false` (wait for an actual crossing)." }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "position_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome token IDs.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets in these events.", "maxItems": 500 }, "outcomes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these outcome names (e.g. \\[\"Yes\", \"No\"\\]).", "maxItems": 500 }, "position_outcome_indices": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Restrict by outcome index. 0 = Yes/Up, 1 = No. Position 0 usually represents the Up/Yes side in binary markets.", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "PriceThresholdPayload": { "type": "object", "description": "Price-threshold crossing webhook payload", "required": [ "trader", "taker", "position_id", "trade_id", "hash", "block", "confirmed_at", "amount_usd", "shares_amount", "fee", "side", "previous_price", "price", "direction", "threshold" ], "properties": { "trader": { "type": "string", "description": "Trader address (the limit-order maker)" }, "taker": { "type": "string", "description": "Taker address (the order filler — often the exchange contract)" }, "position_id": { "type": "string", "description": "Position ID (ERC1155 token ID)" }, "condition_id": { "type": [ "string", "null" ], "description": "Condition ID (parent market)" }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name (e.g. \"Yes\", \"No\")" }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index (0 = Yes/Up, 1 = No). Position 0 usually represents Yes/Up.", "minimum": 0 }, "question": { "type": [ "string", "null" ], "description": "Market question" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Event slug" }, "trade_id": { "type": "string", "description": "Trade ID" }, "hash": { "type": "string", "description": "Transaction hash" }, "block": { "type": "integer", "format": "int64", "description": "Block number", "minimum": 0 }, "confirmed_at": { "type": "integer", "format": "int64", "description": "Confirmed timestamp (Unix seconds)", "minimum": 0 }, "amount_usd": { "type": "number", "format": "double", "description": "USD size of the trade" }, "shares_amount": { "type": "number", "format": "double", "description": "Outcome shares traded" }, "fee": { "type": "number", "format": "double", "description": "Fee paid (USD)" }, "side": { "type": "string", "description": "Trade side (\"Buy\" or \"Sell\")" }, "previous_price": { "type": "number", "format": "double", "description": "Last observed price before this trade (the baseline the crossing is measured from)" }, "price": { "type": "number", "format": "double", "description": "Price per share (0.0–1.0) that crossed the threshold" }, "probability": { "type": [ "number", "null" ], "format": "double", "description": "Implied probability of the outcome (0.0–1.0)" }, "direction": { "type": "string", "description": "Crossing direction: `\"up\"` (crossed up to the `min_price` target) or\n`\"down\"` (crossed down to the `max_price` target)" }, "threshold": { "type": "number", "format": "double", "description": "The target threshold from the subscriber's filter that was crossed" } } }, "ProposePriceEvent": { "type": "object", "description": "V2 UMA OOv2: a price was proposed (resolution proposal).", "required": [ "id", "hash", "oracle_contract", "requester", "proposer", "identifier", "timestamp", "ancillary_data", "proposed_price", "expiration_timestamp", "currency" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "requester": { "type": "string" }, "proposer": { "type": "string" }, "identifier": { "type": "string" }, "timestamp": { "type": "string" }, "ancillary_data": { "type": "string" }, "proposed_price": { "type": "integer", "format": "int64" }, "expiration_timestamp": { "type": "string" }, "currency": { "type": "string" }, "condition_id": { "type": [ "string", "null" ] }, "proposed_outcome": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "QuestionEmergencyResolvedEvent": { "type": "object", "description": "UMA CTF Adapter: admin emergency resolution.", "required": [ "id", "hash", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "proposed_outcome": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "QuestionFlaggedEvent": { "type": "object", "description": "UMA CTF Adapter: market flagged for emergency resolution.", "required": [ "id", "hash", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "QuestionInitializedEvent": { "type": "object", "description": "UMA CTF Adapter: questionID first initialized on-chain.", "required": [ "id", "hash", "oracle_contract", "condition_id", "creator", "reward_token", "reward", "proposal_bond" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "creator": { "type": "string" }, "reward_token": { "type": "string" }, "reward": { "type": "string" }, "proposal_bond": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "QuestionPausedEvent": { "type": "object", "description": "UMA CTF Adapter: market paused by admin.", "required": [ "id", "hash", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "QuestionResetEvent": { "type": "object", "description": "UMA CTF Adapter: dispute succeeded, market returns to active.", "required": [ "id", "hash", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "QuestionResolvedEvent": { "type": "object", "description": "UMA CTF Adapter: market resolved with definitive outcome.", "required": [ "id", "hash", "oracle_contract", "condition_id", "settled_price" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "settled_price": { "type": "integer", "format": "int64" }, "proposed_outcome": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "QuestionUnflaggedEvent": { "type": "object", "description": "UMA CTF Adapter: flag removed.", "required": [ "id", "hash", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "QuestionUnpausedEvent": { "type": "object", "description": "UMA CTF Adapter: market unpaused.", "required": [ "id", "hash", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "RequestPriceEvent": { "type": "object", "description": "V2 UMA OOv2: a price request was made (market initialization).", "required": [ "id", "hash", "oracle_contract", "requester", "identifier", "timestamp", "ancillary_data", "currency", "reward", "final_fee" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "requester": { "type": "string" }, "identifier": { "type": "string" }, "timestamp": { "type": "string", "description": "UMA request timestamp (seconds, decimal string).\nThe point in time the requester is asking the oracle to resolve the\nprice for — part of the request identity tuple\n`(requester, identifier, timestamp, ancillaryData)`. Not the block\ntimestamp of this event; see `confirmed_at` for that." }, "ancillary_data": { "type": "string" }, "currency": { "type": "string" }, "reward": { "type": "string" }, "final_fee": { "type": "string" }, "condition_id": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "RotateSecretResponse": { "type": "object", "description": "Response for POST /v1/webhook/{id}/rotate-secret", "required": [ "secret", "rotated_at" ], "properties": { "secret": { "type": "string", "description": "The new HMAC secret (only returned once — store it securely)" }, "rotated_at": { "type": "integer", "format": "int64", "description": "Timestamp of rotation (ms since epoch)" } } }, "SettleEvent": { "type": "object", "description": "V2 UMA OOv2: a price request was settled (final resolution).", "required": [ "id", "hash", "oracle_contract", "requester", "proposer", "disputer", "identifier", "timestamp", "ancillary_data", "proposed_price", "payout", "disputed" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "confirmed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "received_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "log_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "block_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "oracle_contract": { "type": "string" }, "requester": { "type": "string" }, "proposer": { "type": "string" }, "disputer": { "type": "string" }, "identifier": { "type": "string" }, "timestamp": { "type": "string" }, "ancillary_data": { "type": "string" }, "proposed_price": { "type": "integer", "format": "int64" }, "payout": { "type": "string" }, "disputed": { "type": "boolean" }, "condition_id": { "type": [ "string", "null" ] }, "proposed_outcome": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "event_slug": { "type": [ "string", "null" ] } } }, "SpikeDirection": { "type": "string", "description": "Direction filter for spike webhooks.", "enum": [ "up", "down", "both" ] }, "TagMetricsFilters": { "type": "object", "description": "Subscription filters for the `tag_metrics` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these tags. Empty = all tags.", "maxItems": 500 }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MetricFilterTimeframe" }, "description": "Restrict to these aggregation windows.", "maxItems": 500 }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when aggregated tag volume >= this value (USD)." }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maximum volume USD." }, "min_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum transactions." }, "min_unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum unique traders." }, "min_fees": { "type": [ "number", "null" ], "format": "double", "description": "Minimum fees." } } }, "TagMetricsPayload": { "type": "object", "description": "Payload delivered when a tag's aggregated volume or transaction metrics cross a configured threshold", "properties": { "tag": { "type": [ "string", "null" ], "description": "Tag label or slug" }, "timeframe": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Timeframe values accepted by webhook metric, milestone, spike, and asset-price filters.", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "6h", "1d", "24h", "7d", "30d", "lifetime" ] } ], "description": "Aggregation window" }, "volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Total aggregated volume for the tag (USD)" }, "shares_volume": { "type": [ "number", "null" ], "format": "double", "description": "Total aggregated shares/contracts volume for the tag" }, "builder_usd_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed aggregated volume in USD" }, "builder_shares_volume": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed aggregated shares/contracts volume" }, "fees": { "type": [ "number", "null" ], "format": "double", "description": "Total fees collected in USD" }, "builder_fees": { "type": [ "number", "null" ], "format": "double", "description": "Builder-attributed fees in USD" }, "txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Total number of transactions" }, "builder_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Builder-attributed transaction count" }, "unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique traders" }, "unique_makers": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique makers" }, "unique_takers": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique takers" }, "unique_builder_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of unique builder-attributed traders" } } }, "TradeEventFilterType": { "type": "string", "description": "Trade-event types accepted by `trader_trade_event.trade_types`. Covers the\nfull set of typed prediction-trade variants.", "enum": [ "OrderFilled", "OrdersMatched", "MakerRebate", "Reward", "Yield", "Redemption", "Merge", "Split", "Cancelled", "PositionsConverted", "ComboCreation", "ComboExecution", "ComboStatusUpdate", "ComboPositionsSplit", "ComboPositionsMerged", "ComboSplitOnCondition", "ComboMergedOnCondition", "ComboExtracted", "ComboInjected", "ComboConvertedToYesBasket", "ComboMergedFromYesBasket", "ComboCompressed", "ComboPositionRedeemed", "ComboWrapped", "ComboUnwrapped", "ComboHorizontalSplit", "ComboHorizontalMerge", "ComboPositionConverted", "ComboPositionMigrated", "Initialization", "Proposal", "Dispute", "Settled", "Resolution", "ConditionResolution", "Reset", "Flag", "Unflag", "Pause", "Unpause", "ManualResolution", "NegRiskOutcomeReported", "RegisterToken" ] }, "TraderCategoryPnlFilters": { "type": "object", "description": "Subscription filters for the `trader_category_pnl` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "traders": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Track only these trader wallet addresses. Empty = all traders.", "maxItems": 500 }, "categories": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these market categories (e.g. `politics`, `sports`).", "maxItems": 500 }, "min_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when per-category realized PnL ≥ this value (USD). Use negative values for loss thresholds." }, "max_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when per-category realized PnL ≤ this value (USD)." }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when total category volume ≥ this value (USD)." }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when total category volume ≤ this value (USD)." }, "min_buy_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when buy volume within the category ≥ this value (USD)." }, "min_sell_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when sell volume within the category ≥ this value (USD)." }, "min_win_rate": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when market win rate ≥ this percentage (0.0–100.0).", "maximum": 100, "minimum": 0 }, "min_markets_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Only fire when the trader has traded in ≥ this many markets within the category." }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PnlFilterTimeframe" }, "description": "Restrict to these PnL windows. Empty = all windows." } } }, "TraderExitMarkersFilters": { "type": "object", "description": "Subscription filters for the `trader_pnl_exits` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "traders": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Track only these trader wallet addresses. Empty = all traders.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to positions in these events.", "maxItems": 500 } } }, "TraderFirstTradeFilters": { "type": "object", "description": "Subscription filters for the `trader_first_trade` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "wallet_addresses": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only fire for trades by these wallet addresses (lowercase). Empty = all traders.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to trades in these markets. Empty = all markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to trades in markets belonging to these events.", "maxItems": 500 }, "min_usd_value": { "type": [ "number", "null" ], "format": "double", "description": "Minimum trade size in USD. Omit to match all sizes." }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when the outcome probability is ≥ this value.", "maximum": 1, "minimum": 0 }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when the outcome probability is ≤ this value.", "maximum": 1, "minimum": 0 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets (event slugs containing `updown`). Default: `false`." } } }, "TraderGlobalPnlFilters": { "type": "object", "description": "Subscription filters for the `trader_global_pnl` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "traders": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Track only these trader wallet addresses. Empty = all traders.", "maxItems": 500 }, "min_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when realized PnL ≥ this value (USD). Use negative values for loss thresholds." }, "max_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when realized PnL ≤ this value (USD)." }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when total trading volume ≥ this value (USD)." }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when total trading volume ≤ this value (USD)." }, "min_buy_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when buy volume ≥ this value (USD)." }, "min_sell_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when sell volume ≥ this value (USD)." }, "min_win_rate": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when market win rate ≥ this percentage (0.0–100.0).", "maximum": 100, "minimum": 0 }, "min_markets_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Only fire when the trader has traded in ≥ this many markets." }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PnlFilterTimeframe" }, "description": "Restrict to these PnL windows. Empty = all windows." } } }, "TraderMarketPnlFilters": { "type": "object", "description": "Subscription filters for the `trader_market_pnl` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "traders": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Track only these trader wallet addresses.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets in these events.", "maxItems": 500 }, "min_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when per-market realized PnL ≥ this value (USD)." }, "max_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when per-market realized PnL ≤ this value (USD)." }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when total volume (buy + sell + redemption + merge) ≥ this value (USD)." }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when total volume ≤ this value (USD)." }, "min_buy_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when buy volume in the market ≥ this value (USD)." }, "min_sell_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when sell volume in the market ≥ this value (USD)." }, "timeframes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PnlFilterTimeframe" }, "description": "Restrict to these PnL windows." }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "TraderNewMarketFilters": { "type": "object", "description": "Subscription filters for the `trader_new_market` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "wallet_addresses": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only fire for these wallet addresses (lowercase). Empty = all traders.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets belonging to these events.", "maxItems": 500 }, "min_usd_value": { "type": [ "number", "null" ], "format": "double", "description": "Minimum trade size in USD. Omit to match all sizes." }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when the outcome probability is ≥ this value.", "maximum": 1, "minimum": 0 }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when the outcome probability is ≤ this value.", "maximum": 1, "minimum": 0 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "TraderNewTradeFilters": { "type": "object", "description": "Subscription filters for the `trader_new_trade` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "wallet_addresses": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only fire for trades by these wallet addresses. Empty = all traders.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets belonging to these events.", "maxItems": 500 }, "min_usd_value": { "type": [ "number", "null" ], "format": "double", "description": "Minimum trade size in USD. Defaults to 0 (matches all trades).", "default": 0.0 }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when outcome probability is ≥ this value.", "maximum": 1, "minimum": 0 }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when outcome probability is ≤ this value.", "maximum": 1, "minimum": 0 }, "trade_types": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Trade types accepted by `trader_new_trade.trade_types`. Webhook fires on\nfill-style trades only.", "enum": [ "OrderFilled", "OrdersMatched", "ComboExecution" ] }, "description": "Only fire for these fill-style trade types. Empty = OrderFilled, OrdersMatched, and ComboExecution only (default).", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "TraderPositionResolvedFilters": { "type": "object", "description": "Subscription filters for the `trader_position_resolved` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "traders": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Track only these trader wallet addresses. Empty = all traders.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to positions in these events.", "maxItems": 500 }, "outcome_indexes": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32" }, "description": "Restrict to these outcome indexes within the resolved market.", "maxItems": 500 }, "won_only": { "type": [ "boolean", "null" ], "description": "Only fire for won (`true`) or lost (`false`) positions. Omit to receive both." } } }, "TraderTradeEventFilters": { "type": "object", "description": "Subscription filters for the `trader_trade_event` event. All fields are optional.\n`event_slugs` and `exclude_shortterm_markets` require explicit `trade_types` that\nexclude `PositionsConverted`, because conversion events do not currently carry\n`event_slug` in the typed webhook payload.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "wallet_addresses": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only fire for events associated with these wallet addresses. Empty = all traders.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets. For `PositionsConverted`, this also matches the NegRisk `market_id`.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets belonging to these events. Requires explicit `trade_types` that exclude `PositionsConverted`.", "maxItems": 500 }, "min_usd_value": { "type": [ "number", "null" ], "format": "double", "description": "Minimum USD amount for the underlying event. Defaults to 0 (matches all events).", "default": 0.0 }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when event probability is ≥ this value. Events without probability data do not match.", "maximum": 1, "minimum": 0 }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when event probability is ≤ this value. Events without probability data do not match.", "maximum": 1, "minimum": 0 }, "trade_types": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Trade-event types accepted by `trader_trade_event.trade_types`. Covers the\nfull set of typed prediction-trade variants.", "enum": [ "OrderFilled", "OrdersMatched", "MakerRebate", "Reward", "Yield", "Redemption", "Merge", "Split", "Cancelled", "PositionsConverted", "ComboCreation", "ComboExecution", "ComboStatusUpdate", "ComboPositionsSplit", "ComboPositionsMerged", "ComboSplitOnCondition", "ComboMergedOnCondition", "ComboExtracted", "ComboInjected", "ComboConvertedToYesBasket", "ComboMergedFromYesBasket", "ComboCompressed", "ComboPositionRedeemed", "ComboWrapped", "ComboUnwrapped", "ComboHorizontalSplit", "ComboHorizontalMerge", "ComboPositionConverted", "ComboPositionMigrated", "Initialization", "Proposal", "Dispute", "Settled", "Resolution", "ConditionResolution", "Reset", "Flag", "Unflag", "Pause", "Unpause", "ManualResolution", "NegRiskOutcomeReported", "RegisterToken" ] }, "description": "Only fire for these trade types. Empty = all supported trade-event variants.", "maxItems": 500 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Requires explicit `trade_types` that exclude `PositionsConverted`. Default: `false`." } } }, "TraderWhaleTradeFilters": { "type": "object", "description": "Subscription filters for the `trader_whale_trade` event. All fields are optional.", "properties": { "one_shot": { "type": [ "boolean", "null" ], "description": "Fire-and-delete: when `true`, delete the subscription after its first\nsuccessful delivery. Applies to any webhook event." }, "wallet_addresses": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only fire for trades by these wallet addresses. Empty = all traders.", "maxItems": 500 }, "condition_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to these markets.", "maxItems": 500 }, "event_slugs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Restrict to markets belonging to these events.", "maxItems": 500 }, "min_usd_value": { "type": [ "number", "null" ], "format": "double", "description": "Minimum trade size in USD. Defaults to 0 (matches all trades).", "default": 0.0 }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when outcome probability is ≥ this value.", "maximum": 1, "minimum": 0 }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Only fire when outcome probability is ≤ this value.", "maximum": 1, "minimum": 0 }, "exclude_shortterm_markets": { "type": [ "boolean", "null" ], "description": "When `true`, suppress webhooks for short-term \"updown\" markets. Default: `false`." } } }, "UpdateWebhookRequestBody": { "type": "object", "description": "Request body for updating a webhook", "properties": { "url": { "type": [ "string", "null" ], "description": "Destination URL for webhook deliveries (must be HTTPS)" }, "event": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PolymarketWebhookEvent", "description": "Event to subscribe to" } ] }, "secret": { "type": [ "string", "null" ], "description": "New secret for HMAC signature verification" }, "filters": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebhookFiltersBody", "description": "Filters for event matching" } ] }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebhookStatusBody", "description": "Webhook status" } ] }, "description": { "type": [ "string", "null" ], "description": "Description/name" } } }, "VolumeMilestonePayload": { "type": "object", "description": "Volume milestone webhook payload", "required": [ "condition_id", "timeframe", "milestone_usd", "current_volume_usd", "fees", "txns" ], "properties": { "condition_id": { "type": "string", "description": "Market condition ID." }, "timeframe": { "type": "string", "description": "Metric timeframe." }, "milestone_usd": { "type": "number", "format": "double", "description": "Milestone amount reached (USD)" }, "current_volume_usd": { "type": "number", "format": "double", "description": "Current volume (USD) that triggered the milestone" }, "fees": { "type": "number", "format": "double", "description": "Total fees collected in this timeframe" }, "txns": { "type": "integer", "format": "int64", "description": "Total transactions in this timeframe" } } }, "VolumeSpikeFilterTimeframe": { "type": "string", "description": "Aggregation windows accepted by `*_volume_spike.timeframes`. Includes `1d`\nin addition to the metric set.", "enum": [ "1m", "5m", "30m", "1h", "6h", "1d", "24h", "7d", "30d" ] }, "WebhookAssetSymbol": { "type": "string", "description": "Crypto asset symbols accepted by `asset_price_tick` and `asset_price_window_update` filters.", "enum": [ "BTC", "ETH", "SOL", "XRP", "DOGE", "BNB", "HYPE" ] }, "WebhookEventInfo": { "type": "object", "description": "Single event type entry for the events list", "required": [ "event", "description", "category", "millicredits_cost", "applicable_filters" ], "properties": { "event": { "type": "string", "description": "Event type identifier (e.g. \"first_trade\")" }, "description": { "type": "string", "description": "Human-readable description" }, "category": { "type": "string", "enum": [ "trader", "trade", "market", "event", "tag", "position", "assets" ], "description": "Category grouping for the event type" }, "millicredits_cost": { "type": "integer", "format": "int64", "description": "Millicredits consumed per webhook delivery (1 credit = 1000 mc)", "minimum": 0 }, "applicable_filters": { "type": "array", "items": { "type": "string" }, "description": "Filter field names that apply to this event type" } } }, "WebhookFiltersBody": { "type": "object", "description": "Webhook filters request body", "properties": { "wallet_addresses": { "type": "array", "items": { "type": "string" }, "description": "Filter by wallet addresses (for first_trade / new_market / whale_trade). Max 500 entries." }, "traders": { "type": "array", "items": { "type": "string" }, "description": "Filter by trader addresses (for PnL webhooks). Max 500 entries." }, "condition_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by market/condition IDs. Max 500 entries." }, "position_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by position IDs (for position metrics / close_to_bond). Max 500 entries." }, "event_slugs": { "type": "array", "items": { "type": "string" }, "description": "Filter by event slugs. Max 500 entries." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tags or category names (case-insensitive). Matches a market's tags or its\ncategory label — for market_created and all market-keyed events. Max 500 entries." }, "series_slugs": { "type": "array", "items": { "type": "string" }, "description": "Filter by series slugs (case-insensitive). Matches a market's parent series — for all\nmarket-keyed events. Max 500 entries." }, "outcomes": { "type": "array", "items": { "type": "string" }, "description": "Filter by outcomes (e.g. \"Yes\", \"No\") — for position metrics / close_to_bond. Max 500 entries." }, "position_outcome_indices": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Filter by position outcome index — for close_to_bond. Position 0 = Yes/Up, 1 = No. Max 500 entries." }, "trade_types": { "type": "array", "items": { "type": "string" }, "description": "Filter by trade type — for `trader_new_trade` and `trader_trade_event`. Max 500 entries." }, "min_usd_value": { "type": [ "number", "null" ], "format": "double", "description": "Minimum USD trade size (for whale_trade / first_trade)" }, "min_price": { "type": [ "number", "null" ], "format": "double", "description": "Minimum price threshold (0.0 - 1.0). Accepts the legacy `min_probability` key." }, "max_price": { "type": [ "number", "null" ], "format": "double", "description": "Maximum price threshold (0.0 - 1.0). Accepts the legacy `max_probability` key." }, "min_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum realized PnL (USD) — for global_pnl / market_pnl / event_pnl" }, "max_realized_pnl_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maximum realized PnL (USD) — for global_pnl / market_pnl / event_pnl" }, "min_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum total volume (USD) — for global_pnl / event_pnl / metrics" }, "max_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Maximum total volume (USD) — for metrics webhooks" }, "min_buy_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum buy volume (USD) — for market_pnl / position metrics" }, "min_sell_volume_usd": { "type": [ "number", "null" ], "format": "double", "description": "Minimum sell volume (USD) — for position metrics" }, "min_win_rate": { "type": [ "number", "null" ], "format": "double", "description": "Minimum win rate (0.0 - 100.0) — for global_pnl" }, "min_markets_traded": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum markets traded — for global_pnl / event_pnl" }, "min_net_shares": { "type": [ "number", "null" ], "format": "double", "description": "Minimum net shares held — for position-level filters" }, "max_net_shares": { "type": [ "number", "null" ], "format": "double", "description": "Maximum net shares held — for position-level filters" }, "min_fees": { "type": [ "number", "null" ], "format": "double", "description": "Minimum fees (USD) — for metrics webhooks" }, "min_txns": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum transaction count — for metrics webhooks" }, "min_unique_traders": { "type": [ "integer", "null" ], "format": "int64", "description": "Minimum unique traders — for metrics webhooks" }, "min_price_change_pct": { "type": [ "number", "null" ], "format": "double", "description": "Minimum price change percentage — for position metrics" }, "min_probability_change_pct": { "type": [ "number", "null" ], "format": "double", "description": "Minimum probability change percentage (legacy spike filter field)" }, "timeframes": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookTimeframe" }, "description": "Timeframes to filter by (e.g. [\"1h\", \"24h\", \"7d\"]) — **required** for volume_milestone\nwebhooks (market/event/position), optional for metrics webhooks.\nValid values: \"1m\", \"5m\", \"30m\", \"1h\", \"6h\", \"24h\", \"7d\", \"30d\"." }, "milestone_amounts": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Milestone amounts to trigger on (USD) — for volume_milestone webhooks. Max 500 entries." }, "spike_ratio": { "type": [ "number", "null" ], "format": "double", "description": "Spike ratio multiplier (must be > 1.0) — for volume_spike. E.g. 2.0 for 2x baseline" }, "spike_direction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpikeDirection", "description": "Direction filter for spike webhooks — \"up\", \"down\", or \"both\"" } ] }, "window_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Observation window in seconds (max 600) — for price_spike, volume_spike", "minimum": 0 }, "exclude_shortterm_markets": { "type": "boolean", "description": "When true, suppress webhooks for short-term \"updown\" markets" }, "asset_symbols": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAssetSymbol" }, "description": "Filter by crypto asset symbol — for `asset_price_tick` and `asset_price_window_update`.\nValid values: \"BTC\", \"ETH\", \"SOL\", \"XRP\", \"DOGE\", \"BNB\", \"HYPE\". Empty = all assets (send everything)." }, "one_shot": { "type": "boolean", "description": "Fire-and-delete: delete the subscription after its first successful\ndelivery. Works on any webhook event. (`price_threshold` additionally\nrequires `position_ids` or `condition_ids`.)" }, "fire_if_already_past": { "type": "boolean", "description": "For `price_threshold` — fire immediately if the first observed price is\nalready past the target. Default `false` (wait for an actual crossing)." } } }, "WebhookListResponseBody": { "type": "object", "description": "List webhooks response", "required": [ "webhooks", "total" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResponse" }, "description": "List of webhooks" }, "total": { "type": "integer", "description": "Total count", "minimum": 0 } } }, "WebhookLogEntry": { "type": "object", "description": "A single webhook delivery log entry (GET /v1/webhooks/{id}/logs)", "required": [ "sent_at", "payload", "event", "delivery_id", "attempt", "success", "status_code", "latency_ms", "url" ], "properties": { "sent_at": { "type": "string", "description": "When the payload was sent (RFC3339, millisecond precision)" }, "payload": { "description": "The full payload we delivered, parsed back to JSON" }, "event": { "type": "string", "description": "Event type (e.g. \"trader_first_trade\")" }, "delivery_id": { "type": "string", "description": "Unique delivery id" }, "attempt": { "type": "integer", "format": "int32", "description": "Final attempt number for this dispatch", "minimum": 0 }, "success": { "type": "boolean", "description": "Whether delivery ultimately succeeded" }, "status_code": { "type": "integer", "format": "int32", "description": "HTTP status code from the endpoint (0 = no response / transport error)", "minimum": 0 }, "latency_ms": { "type": "integer", "format": "int32", "description": "Total dispatch time in milliseconds (including retries)", "minimum": 0 }, "url": { "type": "string", "description": "Destination URL the payload was POSTed to" }, "error": { "type": "string", "description": "Error message when delivery failed (omitted when empty)" } } }, "WebhookLogsResponseBody": { "type": "object", "description": "Response for GET /v1/webhooks/{id}/logs", "required": [ "webhook_id", "total", "logs", "pagination" ], "properties": { "webhook_id": { "type": "string", "description": "The webhook these logs belong to" }, "total": { "type": "integer", "description": "Number of log entries returned", "minimum": 0 }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookLogEntry" }, "description": "Delivery log entries, newest first" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta", "description": "Cursor pagination metadata" } } }, "WebhookResponse": { "type": "object", "description": "Webhook response (returned from API)", "required": [ "id", "url", "event", "status", "created_at", "updated_at", "has_secret" ], "properties": { "id": { "type": "string", "description": "Unique webhook ID" }, "url": { "type": "string", "description": "Destination URL" }, "event": { "$ref": "#/components/schemas/PolymarketWebhookEvent", "description": "Subscribed event" }, "filters": { "$ref": "#/components/schemas/PolymarketWebhookFilter", "description": "Active filters (omitted when no filters are set)" }, "status": { "type": "string", "enum": [ "active", "paused", "disabled", "suspended" ], "description": "Current webhook status" }, "created_at": { "type": "integer", "format": "int64", "description": "Created timestamp (ms)" }, "updated_at": { "type": "integer", "format": "int64", "description": "Updated timestamp (ms)" }, "description": { "type": [ "string", "null" ], "description": "Description/name" }, "has_secret": { "type": "boolean", "description": "Whether an HMAC secret is configured" }, "credits_used_24h": { "type": "integer", "format": "int64", "description": "Credits consumed by this webhook in the last 24 hours" } } }, "WebhookStatusBody": { "type": "string", "description": "Webhook status", "enum": [ "active", "paused" ] }, "WebhookTestResponseBody": { "type": "object", "description": "Test webhook response", "required": [ "success", "duration_ms" ], "properties": { "success": { "type": "boolean", "description": "Whether the test delivery succeeded" }, "status_code": { "type": [ "integer", "null" ], "format": "int32", "description": "HTTP status code from the endpoint", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Error message if failed" }, "duration_ms": { "type": "integer", "format": "int64", "description": "Delivery duration in milliseconds", "minimum": 0 } } }, "WebhookTimeframe": { "type": "string", "description": "Timeframe values accepted by webhook metric, milestone, spike, and asset-price filters.", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "6h", "1d", "24h", "7d", "30d", "lifetime" ] }, "WebhookTraderInfo": { "type": "object", "description": "Trader display metadata nested into trade-fill webhook payloads.\n\nMirrors the shape used by the trade-event and PnL alert payloads. `address`\n(the lower-cased maker wallet) is always present; the remaining fields are\nsourced from the producer-enriched `trader_profile` carried on the trade and\nare omitted until that profile has been resolved.", "required": [ "address", "verified_badge" ], "properties": { "address": { "type": "string", "description": "Maker wallet address (lower-cased)" }, "name": { "type": [ "string", "null" ], "description": "Display name" }, "pseudonym": { "type": [ "string", "null" ], "description": "Polymarket pseudonym" }, "profile_image": { "type": [ "string", "null" ], "description": "Profile image URL (our CDN copy when available)" }, "x_username": { "type": [ "string", "null" ], "description": "Linked X (Twitter) username" }, "verified_badge": { "type": "boolean", "description": "Whether the trader carries a verified badge" } } }, "WhaleTradePayload": { "type": "object", "description": "Payload delivered when a trade exceeds the configured size and probability thresholds", "required": [ "trader", "taker", "trader_info", "position_id", "trade_id", "hash", "block", "confirmed_at", "amount_usd", "shares_amount", "fee", "side", "price", "exchange", "trade_type" ], "properties": { "trader": { "type": "string", "description": "Limit-order maker wallet address (lowercase)" }, "taker": { "type": "string", "description": "Order filler wallet address (lowercase)" }, "trader_info": { "$ref": "#/components/schemas/WebhookTraderInfo", "description": "Maker trader display metadata (address + name / pseudonym / image / x / verified)" }, "position_id": { "type": "string", "description": "ERC-1155 outcome token ID" }, "condition_id": { "type": [ "string", "null" ], "description": "Parent market condition ID" }, "outcome": { "type": [ "string", "null" ], "description": "Outcome name (e.g. \"Yes\", \"No\")" }, "outcome_index": { "type": [ "integer", "null" ], "format": "int32", "description": "Outcome index: 0 = Yes/Up, 1 = No", "minimum": 0 }, "question": { "type": [ "string", "null" ], "description": "Market question text" }, "market_slug": { "type": [ "string", "null" ], "description": "Market slug" }, "event_slug": { "type": [ "string", "null" ], "description": "Parent event slug" }, "image_url": { "type": [ "string", "null" ], "description": "Market image URL" }, "trade_id": { "type": "string", "description": "Unique trade identifier" }, "hash": { "type": "string", "description": "Transaction hash" }, "block": { "type": "integer", "format": "int64", "description": "Block number", "minimum": 0 }, "confirmed_at": { "type": "integer", "format": "int64", "description": "Block confirmation timestamp (Unix seconds)", "minimum": 0 }, "amount_usd": { "type": "number", "format": "double", "description": "USD size of the trade (6 decimal places)" }, "shares_amount": { "type": "number", "format": "double", "description": "Outcome shares traded (6 decimal places)" }, "fee": { "type": "number", "format": "double", "description": "Fee paid in USD (6 decimal places)" }, "side": { "oneOf": [ { "type": "string", "description": "Trade direction for trade-fill webhook payloads.", "enum": [ "Buy", "Sell" ] } ], "description": "Trade direction" }, "price": { "type": "number", "format": "double", "description": "Outcome token price (0.0–1.0)", "maximum": 1, "minimum": 0 }, "probability": { "type": [ "number", "null" ], "format": "double", "description": "Implied probability (0.0–1.0); null when outcome is unknown", "maximum": 1, "minimum": 0 }, "exchange": { "oneOf": [ { "type": "string", "description": "Polymarket exchange contract types.", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "CTFExchangeV2", "NegRiskExchangeV2", "ComboExchange", "ComboCombinatorialModule", "ComboNegRiskModule", "Unknown" ] } ], "description": "Exchange contract that processed the trade" }, "trade_type": { "oneOf": [ { "type": "string", "description": "Trade type for trade-fill webhook payloads. Webhook events only fire on\nfill-style trades, so the only valid variants are `OrderFilled`,\n`OrdersMatched`, and `ComboExecution`.", "enum": [ "OrderFilled", "OrdersMatched", "ComboExecution" ] } ], "description": "Trade type (webhook events only fire on order fills)" }, "builder_code": { "type": [ "string", "null" ], "description": "CLOB V2 builder code (lower-cased `0x...` bytes32 hex). Absent on V1\ntrades; may be `0x0000…` for V2 trades placed without a builder code.\nCLOB builder code." }, "builder_fee": { "type": [ "number", "null" ], "format": "double", "description": "Builder fee in USDC. Absent when no builder code is attached." } } }, "WebhookDeliveryEnvelope": { "type": "object", "description": "Outer envelope for every webhook HTTP POST delivery. The `data` field contains the event-specific payload. Delivery headers sent with every POST: `X-Webhook-ID` (subscription UUID), `X-Delivery-ID` (this attempt's UUID), `X-Event-Type` (event name string, e.g. `trader_first_trade`), `X-Attempt` (attempt number, 1-indexed). When the webhook has a secret configured, `X-Webhook-Signature: sha256=` is also included — compute HMAC-SHA256 over the raw request body using your secret to verify.", "required": [ "id", "event", "data", "timestamp", "webhook_id", "attempt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID of this specific delivery attempt (matches X-Delivery-ID header)" }, "event": { "type": "string", "description": "Event name (e.g. `trader_first_trade`). On test deliveries the suffix `_test` is appended." }, "data": { "type": "object", "description": "Event-specific payload — schema varies by event type; see the individual callback definitions" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds when this delivery was created" }, "webhook_id": { "type": "string", "format": "uuid", "description": "UUID of the webhook subscription that fired (matches X-Webhook-ID header)" }, "attempt": { "type": "integer", "minimum": 1, "description": "Delivery attempt number. 1 = first attempt; increments on each retry." } } }, "WebhookTraderTradeEventPayload": { "description": "Tagged union of trade-type variants delivered to `trader_trade_event` callbacks. Pending-only fields such as `received_at` are absent — callbacks fire only for confirmed trades.", "oneOf": [ { "title": "OrderFilled / OrdersMatched / ComboExecution", "description": "A confirmed buy or sell matched on the exchange.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "order_hash", "trader", "taker", "side", "condition_id", "position_id", "outcome_index", "usd_amount", "shares_amount", "price", "fee", "fee_shares", "fee_pct", "exchange" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "order_hash": { "type": "string" }, "trader": { "type": "object", "required": [ "address", "name", "pseudonym", "profile_image", "x_username", "verified_badge" ], "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "pseudonym": { "type": [ "string", "null" ] }, "profile_image": { "type": [ "string", "null" ] }, "x_username": { "type": [ "string", "null" ] }, "verified_badge": { "type": "boolean" } }, "additionalProperties": false }, "taker": { "type": "string" }, "side": { "type": "string", "enum": [ "Buy", "Sell" ] }, "condition_id": { "type": [ "string", "null" ] }, "position_id": { "type": "string" }, "outcome": { "type": "string" }, "outcome_index": { "type": [ "integer", "null" ] }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "usd_amount": { "type": "number" }, "shares_amount": { "type": "number" }, "price": { "type": "number" }, "probability": { "type": "number" }, "fee": { "type": "number" }, "fee_shares": { "type": "number" }, "fee_pct": { "type": "number" }, "exchange": { "type": "string", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "Unknown" ], "description": "Exchange contract that processed the event" }, "builder_code": { "type": "string", "description": "CLOB V2 builder code (lower-cased `0x...` bytes32 hex). Absent on V1 trades; may be `0x0000…` for V2 trades placed without a builder code." }, "builder_fee": { "type": "number", "description": "Builder fee in USDC. Absent when no builder code is attached." }, "trade_type": { "type": "string", "enum": [ "OrderFilled", "OrdersMatched", "ComboExecution" ] } }, "additionalProperties": false }, { "title": "MakerRebate / Reward / Yield", "description": "pUSD credit paid directly to the trader wallet.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "trader", "usd_amount", "exchange" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "order_hash": { "type": "string" }, "trader": { "type": "object", "required": [ "address", "name", "pseudonym", "profile_image", "x_username", "verified_badge" ], "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "pseudonym": { "type": [ "string", "null" ] }, "profile_image": { "type": [ "string", "null" ] }, "x_username": { "type": [ "string", "null" ] }, "verified_badge": { "type": "boolean" } }, "additionalProperties": false }, "taker": { "type": "string" }, "side": { "type": "string", "enum": [ "Buy", "Sell" ] }, "condition_id": { "type": [ "string", "null" ] }, "position_id": { "type": "string" }, "outcome": { "type": "string" }, "outcome_index": { "type": [ "integer", "null" ] }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "usd_amount": { "type": "number" }, "shares_amount": { "type": "number" }, "price": { "type": "number" }, "probability": { "type": "number" }, "fee": { "type": "number" }, "fee_shares": { "type": "number" }, "fee_pct": { "type": "number" }, "exchange": { "type": "string", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "Unknown" ], "description": "Exchange contract that processed the event" }, "builder_code": { "type": "string", "description": "CLOB V2 builder code (lower-cased `0x...` bytes32 hex). Absent on V1 trades; may be `0x0000…` for V2 trades placed without a builder code." }, "builder_fee": { "type": "number", "description": "Builder fee in USDC. Absent when no builder code is attached." }, "trade_type": { "type": "string", "enum": [ "MakerRebate", "Reward", "Yield" ] } }, "additionalProperties": false }, { "title": "Redemption", "description": "Positions redeemed after market resolution.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "trader", "condition_id", "outcome_index", "usd_amount", "exchange" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "trader": { "type": "object", "required": [ "address", "name", "pseudonym", "profile_image", "x_username", "verified_badge" ], "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "pseudonym": { "type": [ "string", "null" ] }, "profile_image": { "type": [ "string", "null" ] }, "x_username": { "type": [ "string", "null" ] }, "verified_badge": { "type": "boolean" } }, "additionalProperties": false }, "condition_id": { "type": [ "string", "null" ] }, "outcome": { "type": "string" }, "outcome_index": { "type": [ "integer", "null" ] }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "usd_amount": { "type": "number" }, "winning_outcome_index": { "type": "integer" }, "position_details": { "type": "array", "items": { "type": "object", "required": [ "position_id", "outcome_index", "amount" ], "properties": { "position_id": { "type": "string" }, "outcome_index": { "type": "integer" }, "outcome": { "type": "string" }, "amount": { "type": "string" } }, "additionalProperties": false } }, "exchange": { "type": "string", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "Unknown" ], "description": "Exchange contract that processed the event" }, "trade_type": { "type": "string", "enum": [ "Redemption" ] } }, "additionalProperties": false }, { "title": "Merge", "description": "Outcome tokens burned to receive collateral.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "trader", "condition_id", "usd_amount", "exchange" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "trader": { "type": "object", "required": [ "address", "name", "pseudonym", "profile_image", "x_username", "verified_badge" ], "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "pseudonym": { "type": [ "string", "null" ] }, "profile_image": { "type": [ "string", "null" ] }, "x_username": { "type": [ "string", "null" ] }, "verified_badge": { "type": "boolean" } }, "additionalProperties": false }, "condition_id": { "type": [ "string", "null" ] }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "usd_amount": { "type": "number" }, "position_details": { "type": "array", "items": { "type": "object", "required": [ "position_id", "outcome_index", "amount" ], "properties": { "position_id": { "type": "string" }, "outcome_index": { "type": "integer" }, "outcome": { "type": "string" }, "amount": { "type": "string" } }, "additionalProperties": false } }, "exchange": { "type": "string", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "Unknown" ], "description": "Exchange contract that processed the event" }, "trade_type": { "type": "string", "enum": [ "Merge" ] } }, "additionalProperties": false }, { "title": "Split", "description": "Collateral deposited to receive outcome tokens.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "trader", "condition_id", "usd_amount", "exchange" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "trader": { "type": "object", "required": [ "address", "name", "pseudonym", "profile_image", "x_username", "verified_badge" ], "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "pseudonym": { "type": [ "string", "null" ] }, "profile_image": { "type": [ "string", "null" ] }, "x_username": { "type": [ "string", "null" ] }, "verified_badge": { "type": "boolean" } }, "additionalProperties": false }, "condition_id": { "type": [ "string", "null" ] }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "usd_amount": { "type": "number" }, "position_details": { "type": "array", "items": { "type": "object", "required": [ "position_id", "outcome_index", "amount" ], "properties": { "position_id": { "type": "string" }, "outcome_index": { "type": "integer" }, "outcome": { "type": "string" }, "amount": { "type": "string" } }, "additionalProperties": false } }, "exchange": { "type": "string", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "Unknown" ], "description": "Exchange contract that processed the event" }, "trade_type": { "type": "string", "enum": [ "Split" ] } }, "additionalProperties": false }, { "title": "PositionsConverted", "description": "NegRisk NO tokens converted into YES tokens plus collateral.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "trader", "market_id", "index_set", "shares_amount", "exchange" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "trader": { "type": "object", "required": [ "address", "name", "pseudonym", "profile_image", "x_username", "verified_badge" ], "properties": { "address": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "pseudonym": { "type": [ "string", "null" ] }, "profile_image": { "type": [ "string", "null" ] }, "x_username": { "type": [ "string", "null" ] }, "verified_badge": { "type": "boolean" } }, "additionalProperties": false }, "market_id": { "type": "string" }, "index_set": { "type": "string" }, "shares_amount": { "type": "number" }, "fee": { "type": "number" }, "fee_pct": { "type": "number" }, "position_details": { "type": "array", "items": { "type": "object", "required": [ "position_id", "outcome_index", "amount" ], "properties": { "position_id": { "type": "string" }, "outcome_index": { "type": "integer" }, "outcome": { "type": "string" }, "amount": { "type": "string" } }, "additionalProperties": false }, "description": "Per-position conversion amounts." }, "exchange": { "type": "string", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "Unknown" ], "description": "Exchange contract that processed the event" }, "trade_type": { "type": "string", "enum": [ "PositionsConverted" ] } }, "additionalProperties": false }, { "title": "Cancelled", "description": "Order cancelled on-chain.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "order_hash", "exchange" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "order_hash": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "exchange": { "type": "string", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "Unknown" ], "description": "Exchange contract that processed the event" }, "trade_type": { "type": "string", "enum": [ "Cancelled" ] } }, "additionalProperties": false }, { "title": "Initialization", "description": "Question initialized on-chain.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "condition_id", "creator", "reward_token", "reward", "proposal_bond" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "creator": { "type": "string" }, "reward_token": { "type": "string" }, "reward": { "type": "string" }, "proposal_bond": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "Initialization" ] } }, "additionalProperties": false }, { "title": "Proposal", "description": "Resolution proposal submitted to the oracle.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "assertion_id", "domain_id", "claim", "asserter", "callback_recipient", "escalation_manager", "caller", "expiration_time", "currency", "bond", "identifier", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "assertion_id": { "type": "string" }, "domain_id": { "type": "string" }, "claim": { "type": "string" }, "asserter": { "type": "string" }, "callback_recipient": { "type": "string" }, "escalation_manager": { "type": "string" }, "caller": { "type": "string" }, "expiration_time": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "bond": { "type": "string" }, "identifier": { "type": "string" }, "proposed_outcome": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "Proposal" ] } }, "additionalProperties": false }, { "title": "Dispute", "description": "Resolution proposal disputed.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "assertion_id", "caller", "disputer", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "assertion_id": { "type": "string" }, "caller": { "type": "string" }, "disputer": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "Dispute" ] } }, "additionalProperties": false }, { "title": "Settled", "description": "Oracle assertion settled after liveness elapsed.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "assertion_id", "bond_recipient", "disputed", "settlement_resolution", "settle_caller", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "assertion_id": { "type": "string" }, "bond_recipient": { "type": "string" }, "disputed": { "type": "boolean" }, "settlement_resolution": { "type": "boolean" }, "settle_caller": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "Settled" ] } }, "additionalProperties": false }, { "title": "Resolution", "description": "Market resolved with a definitive outcome.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "condition_id", "settled_price" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "settled_price": { "type": "integer", "format": "int64" }, "proposed_outcome": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "Resolution" ] } }, "additionalProperties": false }, { "title": "ConditionResolution", "description": "Conditional Tokens condition resolved and positions became redeemable.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "condition_id", "oracle" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "oracle": { "type": "string" }, "proposed_outcome": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "ConditionResolution" ] } }, "additionalProperties": false }, { "title": "Lifecycle Event", "description": "Simple lifecycle state change with no additional oracle-specific fields.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "Reset", "Flag", "Unflag", "Pause", "Unpause" ] } }, "additionalProperties": false }, { "title": "ManualResolution", "description": "Market resolved via emergency admin action.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "proposed_outcome": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "ManualResolution" ] } }, "additionalProperties": false }, { "title": "NegRiskOutcomeReported", "description": "NegRisk market outcome reported for a question.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "oracle_contract", "condition_id" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "oracle_contract": { "type": "string" }, "condition_id": { "type": "string" }, "proposed_outcome": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "trade_type": { "type": "string", "enum": [ "NegRiskOutcomeReported" ] } }, "additionalProperties": false }, { "title": "RegisterToken", "description": "YES and NO token IDs registered for a condition.", "type": "object", "required": [ "trade_type", "id", "hash", "block", "confirmed_at", "log_index", "block_index", "condition_id", "token0", "token1", "exchange" ], "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "block": { "type": "integer", "format": "int64" }, "confirmed_at": { "type": "integer", "format": "int64" }, "log_index": { "type": "integer", "format": "int64" }, "block_index": { "type": "integer", "format": "int64" }, "condition_id": { "type": "string" }, "token0": { "type": "string" }, "token1": { "type": "string" }, "question": { "type": "string" }, "image_url": { "type": "string" }, "slug": { "type": "string" }, "event_slug": { "type": "string" }, "exchange": { "type": "string", "enum": [ "CTFExchange", "NegRiskExchange", "ConditionalTokens", "NegRiskAdapter", "Unknown" ], "description": "Exchange contract that processed the event" }, "trade_type": { "type": "string", "enum": [ "RegisterToken" ] } }, "additionalProperties": false } ], "discriminator": { "propertyName": "trade_type" } } } }, "tags": [ { "name": "Webhooks", "description": "Webhook subscription management (CRUD operations)" }, { "name": "Webhook Callbacks", "description": "Outgoing HTTP calls to your endpoints when subscribed events occur" } ], "webhooks": { "trader-first-trade": { "post": { "summary": "First trade callback", "description": "Fired when a tracked trader executes their first trade on Polymarket", "operationId": "trader-first-trade", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/TraderFirstTradeFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/FirstTradePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-new-market": { "post": { "summary": "New market entry callback", "description": "Fired when a trader places their first trade in a specific market/condition (fires once per trader+market pair)", "operationId": "trader-new-market", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/TraderNewMarketFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/NewMarketPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-whale-trade": { "post": { "summary": "Whale trade callback", "description": "Fired when a trade meets the configured criteria. Use `min_usd_value` to filter by minimum trade size (optional, defaults to 0 — matches all trades), and `min_price`/`max_price` to restrict to a traded price range.", "operationId": "trader-whale-trade", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/TraderWhaleTradeFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/WhaleTradePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-new-trade": { "post": { "summary": "New trade callback", "description": "Fired on fill-style trades only (`OrderFilled`, `OrdersMatched`, `ComboExecution`). Use `wallet_addresses` to watch specific traders, `min_usd_value` to filter by size, and `min_price`/`max_price` to restrict to a probability range.", "operationId": "trader-new-trade", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/TraderNewTradeFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/NewTradePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-trade-event": { "post": { "summary": "Typed trade-event callback", "description": "Fired on every confirmed prediction trade. Payload is a tagged union of trade-type variants.", "operationId": "trader-trade-event", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/TraderTradeEventFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/WebhookTraderTradeEventPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-global-pnl": { "post": { "summary": "Global PnL callback", "description": "Fired when a trader's global PnL crosses a configured threshold", "operationId": "trader-global-pnl", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/TraderGlobalPnlFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/GlobalPnlPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-market-pnl": { "post": { "summary": "Market PnL callback", "description": "Fired when a trader's market-level PnL crosses a configured threshold", "operationId": "trader-market-pnl", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/TraderMarketPnlFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/MarketPnlPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-category-pnl": { "post": { "summary": "Category PnL callback", "description": "Fired when a trader's category-level PnL crosses a configured threshold", "operationId": "trader-category-pnl", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/TraderCategoryPnlFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/CategoryPnlPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-position-resolved": { "post": { "summary": "Position Resolved callback", "description": "Fired once when a trader's position is resolved (won or lost)", "operationId": "trader-position-resolved", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/TraderPositionResolvedFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/PositionResolvedPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "trader-pnl-exits": { "post": { "summary": "Exit Markers callback", "description": "Fired once per position close, labelled with the exit reason (resolved_win / resolved_loss / sold_win / sold_loss).", "operationId": "trader-pnl-exits", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 25, "x-filters-schema": { "$ref": "#/components/schemas/TraderExitMarkersFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/ExitMarkersPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "position-holder-metrics": { "post": { "summary": "Position holder metrics callback", "description": "Fired when holder metrics change for a position.", "operationId": "position-holder-metrics", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 25, "x-filters-schema": { "$ref": "#/components/schemas/PositionHolderMetricsFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/PositionHolderMetricsPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "condition-holder-metrics": { "post": { "summary": "Condition holder metrics callback", "description": "Fired when holder metrics change for a condition.", "operationId": "condition-holder-metrics", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 25, "x-filters-schema": { "$ref": "#/components/schemas/ConditionHolderMetricsFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/ConditionHolderMetricsPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "event-holder-metrics": { "post": { "summary": "Event holder metrics callback", "description": "Fired when holder metrics change for an event.", "operationId": "event-holder-metrics", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 25, "x-filters-schema": { "$ref": "#/components/schemas/EventHolderMetricsFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventHolderMetricsPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "market-metrics": { "post": { "summary": "Market metrics callback", "description": "Fired when a market's volume or transaction metrics cross a configured threshold. Use `timeframes` to restrict to specific windows (valid values: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `lifetime`).", "operationId": "market-metrics", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/MarketMetricsFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/ConditionMetricsPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "event-metrics": { "post": { "summary": "Event metrics callback", "description": "Fired when an event's volume or transaction metrics cross a configured threshold. Use `timeframes` to restrict to specific windows (valid values: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `lifetime`).", "operationId": "event-metrics", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/EventMetricsFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventMetricsPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "tag-metrics": { "post": { "summary": "Tag metrics callback", "description": "Fired when a tag's volume or transaction metrics cross a configured threshold. Use `timeframes` to restrict to specific windows (valid values: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `lifetime`).", "operationId": "tag-metrics", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/TagMetricsFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/TagMetricsPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "position-metrics": { "post": { "summary": "Position metrics callback", "description": "Fired when a position's volume or transaction metrics cross a configured threshold. Use `timeframes` to restrict to specific windows (valid values: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `lifetime`).", "operationId": "position-metrics", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/PositionMetricsFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/PositionMetricsPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "position-liquidity": { "post": { "summary": "Position liquidity threshold callback", "description": "Fired when a position's USD order-book liquidity crosses a threshold. **`position_ids` is required**, plus at least one of `min_liquidity_usd` (fires when liquidity crosses **up** through the value) or `max_liquidity_usd` (fires when it crosses **down**). Thresholds are edge-triggered and re-arm once liquidity crosses back, unless `one_shot` is set (fire once, then delete).", "operationId": "position-liquidity", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/PositionLiquidityFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/PositionLiquidityPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "market-liquidity": { "post": { "summary": "Market liquidity threshold callback", "description": "Fired when a market's total USD order-book liquidity crosses a threshold. **`condition_ids` is required**, plus at least one of `min_liquidity_usd` (fires when liquidity crosses **up** through the value) or `max_liquidity_usd` (fires when it crosses **down**). Thresholds are edge-triggered and re-arm once liquidity crosses back, unless `one_shot` is set (fire once, then delete).", "operationId": "market-liquidity", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/MarketLiquidityFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/MarketLiquidityPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "event-liquidity": { "post": { "summary": "Event liquidity threshold callback", "description": "Fired when an event's total USD order-book liquidity (summed across its markets) crosses a threshold. **`event_slugs` is required**, plus at least one of `min_liquidity_usd` (fires when liquidity crosses **up** through the value) or `max_liquidity_usd` (fires when it crosses **down**). Thresholds are edge-triggered and re-arm once liquidity crosses back, unless `one_shot` is set (fire once, then delete).", "operationId": "event-liquidity", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/EventLiquidityFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventLiquidityPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "market-volume-milestone": { "post": { "summary": "Market volume milestone callback", "description": "Fired when a market's trading volume crosses a milestone threshold in the specified timeframe. **`timeframes` is required** (e.g. `[\"1h\", \"24h\"]`) — valid values: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `lifetime`. Optional `milestone_amounts` restricts to specific USD thresholds (e.g. `[10000, 100000]`). Optional `condition_ids` restricts to specific markets.", "operationId": "market-volume-milestone", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/MarketVolumeMilestoneFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/VolumeMilestonePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "event-volume-milestone": { "post": { "summary": "Event volume milestone callback", "description": "Fired when an event's trading volume crosses a milestone threshold in the specified timeframe. **`timeframes` is required** (e.g. `[\"1h\", \"24h\"]`) — valid values: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `lifetime`. Optional `milestone_amounts` restricts to specific USD thresholds. Optional `event_slugs` restricts to specific events.", "operationId": "event-volume-milestone", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/EventVolumeMilestoneFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventVolumeMilestonePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "position-volume-milestone": { "post": { "summary": "Position volume milestone callback", "description": "Fired when a position's trading volume crosses a milestone threshold in the specified timeframe. **`timeframes` is required** (e.g. `[\"1h\", \"24h\"]`) — valid values: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `lifetime`. Optional `milestone_amounts` restricts to specific USD thresholds. Optional `position_ids` or `condition_ids` restrict to specific positions/markets.", "operationId": "position-volume-milestone", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/PositionVolumeMilestoneFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/PositionVolumeMilestonePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "price-spike": { "post": { "summary": "Price spike callback", "description": "Fired when a position's price moves significantly. Use `min_price_change_pct` to set the minimum move (e.g. `10` for 10%). Use `window_secs` to observe moves within a specific time window. Use `spike_direction` (`\"up\"` | `\"down\"` | `\"both\"`) — defaults to `\"up\"` when not provided. Filter by `position_ids` or `outcomes` to narrow scope. Scope by market taxonomy with `tags` (matches a market's tags or category) and `series_slugs` (matches its parent series). Optional `min_price`/`max_price` gate the price band, `min_txns`/`min_volume_usd` require a minimum number of trades or USD volume in the observation window.", "operationId": "price-spike", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/PriceSpikeFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/PriceSpikePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "market-volume-spike": { "post": { "summary": "Market volume spike callback", "description": "Fired when a market's trading volume grows by a multiple of `spike_ratio` within a timeframe. Requires `spike_ratio` (> 1.0, e.g. `2.0` fires when volume doubles). Optional `window_secs` sets the observation window in seconds (max 600). Optional `timeframes` — valid values: `1m`, `5m`, `30m`, `1h`, `6h`, `1d`, `24h`, `7d`, `30d`, `lifetime`. Optional `condition_ids` restricts to specific markets.", "operationId": "market-volume-spike", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/MarketVolumeSpikeFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/MarketVolumeSpikePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "event-volume-spike": { "post": { "summary": "Event volume spike callback", "description": "Fired when an event's aggregated trading volume grows by a multiple of `spike_ratio` within a timeframe. Requires `spike_ratio` (> 1.0, e.g. `2.0` fires when volume doubles). Optional `window_secs` sets the observation window in seconds (max 600). Optional `timeframes` and `event_slugs` to narrow scope.", "operationId": "event-volume-spike", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/EventVolumeSpikeFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/EventVolumeSpikePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "position-volume-spike": { "post": { "summary": "Position volume spike callback", "description": "Fired when a position's trading volume grows by a multiple of `spike_ratio` within a timeframe. Requires `spike_ratio` (> 1.0, e.g. `2.0` fires when volume doubles). Optional `window_secs` sets the observation window in seconds (max 600). Optional `position_ids`, `condition_ids`, `outcomes`, and `timeframes` to narrow scope.", "operationId": "position-volume-spike", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/PositionVolumeSpikeFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/PositionVolumeSpikePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "close-to-bond": { "post": { "summary": "Close to bond callback", "description": "Fired when a trade occurs at a near-certain-outcome price. The alert matches on the traded position's own price — so you receive the trade for the exact `position_id` that hit the threshold. **At least one of `min_price` or `max_price` is required.** Use `min_price` (e.g. `0.95`) to trigger when the traded outcome is near-certain (price ≥ threshold); use `max_price` (e.g. `0.05`) for the near-zero side (price ≤ threshold). Optional filters: `position_outcome_indices` — restrict by outcome index (`0` = Yes/Up, `1` = No); `condition_ids` — restrict to specific markets; `position_ids` — restrict to specific outcome tokens; `outcomes` — restrict by outcome name (e.g. `\"Yes\"`, `\"No\"`); `event_slugs` — restrict to specific events. Scope by market taxonomy with `tags` (matches a market's tags or category) and `series_slugs` (matches its parent series).", "operationId": "close-to-bond", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/CloseToBondFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/CloseToBondPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "price-threshold": { "post": { "summary": "Price threshold crossing callback", "description": "Fired when an outcome's price crosses a target level (edge-triggered, fires once per crossing). **At least one of `min_price` or `max_price` is required.** Use `min_price` (e.g. `0.75`) to fire when the price crosses *up* to ≥ that level; use `max_price` (e.g. `0.25`) to fire when it crosses *down* to ≤ that level. Set `one_shot` to delete the subscription after the first delivery (requires `position_ids` or `condition_ids`). Set `fire_if_already_past` to fire immediately when the first observed price is already past the target. Optional scope filters: `condition_ids`, `position_ids`, `outcomes`, `position_outcome_indices` (`0` = Yes/Up, `1` = No), `event_slugs`, `tags` (a market's tags or category), `series_slugs` (parent series).", "operationId": "price-threshold", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 200, "x-filters-schema": { "$ref": "#/components/schemas/PriceThresholdFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/PriceThresholdPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "market-resolved": { "post": { "summary": "Market resolved callback", "description": "Fired once when a market reaches a terminal resolution. Collapses the underlying oracle events (`QuestionResolved`, `QuestionEmergencyResolved`, `ConditionResolution`, `NegRiskOutcomeReported`) into a single notification carrying the winning outcome and, when available, the settled price. Optional filters: `condition_ids`, `event_slugs`, `outcomes` (only fire when the winning outcome matches, e.g. `\"Yes\"`), `exclude_shortterm_markets`.", "operationId": "market-resolved", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/MarketResolvedFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/MarketResolvedPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "market-disputed": { "post": { "summary": "Market disputed callback", "description": "Fired when a proposed market resolution is challenged on-chain (`DisputePrice` or `AssertionDisputed`) — the resolution is now contested and delayed. Carries the disputer, the proposer, and the disputed/proposed outcome when available. Optional filters: `condition_ids`, `event_slugs`, `exclude_shortterm_markets`.", "operationId": "market-disputed", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/MarketDisputedFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/MarketDisputedPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "market-created": { "post": { "summary": "Market created callback", "description": "Fired when a new prediction market is created on Polymarket. Filterable by `tags` and `event_slugs`.", "operationId": "market-created", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/MarketCreatedFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/MarketCreatedPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "oracle-events": { "post": { "summary": "Oracle events callback", "description": "Fired on every on-chain oracle event. Use `oracle_event_types` to restrict to specific kinds — valid values: `AssertionMade`, `AssertionDisputed`, `AssertionSettled`, `RequestPrice`, `ProposePrice`, `DisputePrice`, `Settle`, `QuestionResolved`, `QuestionEmergencyResolved`, `QuestionReset`, `QuestionInitialized`, `QuestionPaused`, `QuestionUnpaused`, `QuestionFlagged`, `QuestionUnflagged`, `ConditionResolution`, `NegRiskOutcomeReported`. Optional `condition_ids` narrows by market.", "operationId": "oracle-events", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/OracleEventsFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/OracleEventTyped" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "asset-price-tick": { "post": { "summary": "Asset price tick callback", "description": "Fired when the price of a tracked crypto asset updates (BTC, ETH, SOL, XRP, DOGE, BNB, HYPE). Use `asset_symbols` to restrict to specific assets (empty = all).", "operationId": "asset-price-tick", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/AssetPriceTickFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/AssetPriceTickPayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } }, "asset-price-window-update": { "post": { "summary": "Asset price window update callback", "description": "Fired at the start and end of each price candle for tracked crypto assets (BTC, ETH, SOL, XRP, DOGE, BNB, HYPE). Payload includes `update_type` (`\"open\"` or `\"close\"`) indicating whether the candle is opening or closing. Use `asset_symbols` to restrict to specific assets. Use `timeframes` to restrict to specific candle sizes — valid values: `\"5m\"`, `\"15m\"`, `\"1h\"`, `\"4h\"`, `\"1d\"`, `\"24h\"`.", "operationId": "asset-price-window-update", "tags": [ "Webhook Callbacks" ], "x-credits-cost": 100, "x-filters-schema": { "$ref": "#/components/schemas/AssetPriceWindowUpdateFilters" }, "parameters": [ { "in": "header", "name": "X-Webhook-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the webhook subscription that fired" }, { "in": "header", "name": "X-Delivery-ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of this specific delivery attempt (matches envelope `id` field)" }, { "in": "header", "name": "X-Event-Type", "required": true, "schema": { "type": "string" }, "description": "Event name string (e.g. `trader_first_trade`)" }, { "in": "header", "name": "X-Attempt", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Delivery attempt number (1 = first attempt)" }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "HMAC-SHA256 of the raw request body: `sha256=`. Present only when the webhook has a secret configured. Verify with: HMAC-SHA256(secret, raw_body_bytes) == hex_part." } ], "requestBody": { "required": true, "description": "Webhook delivery envelope. The `data` field contains the event-specific payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/AssetPriceWindowUpdatePayload" } } } ] } } } }, "responses": { "200": { "description": "Webhook delivery acknowledged" }, "500": { "description": "Server error (will retry)" } } } } } }